contributing

orcr is a Rust workspace (crate orchestratr, binaries orcr and orcr-mock-agent) with a TypeScript SDK under sdk/ts/ and an installable skill under skill/. this page covers building, testing, the codebase map, how to extend each surface, and the conventions a change must hold to.

prerequisites

• Rust >= 1.89 for the CLI and server.
• Node >= 20 for the SDK, its tests, and orcr scaffold.
• herdr on your PATH with the claude and codex integrations, for the e2e suites. the unit and fast tests do not need herdr.

build and test

cargo test                          # unit + fast tests (no herdr needed)
cargo clippy --all-targets          # lint
(cd sdk/ts && npm install && npm test && npm run codegen:check)   # SDK tests + drift check
ORCR_E2E=1 cargo test -- --test-threads=1   # e2e against live herdr + the mock provider

the fast tests (default cargo test) prove the auto-start race resolves to one server, kill -9 gives a clean restart with an intact store, api schema is valid JSON schema with full method coverage, and subscription replay has no gaps or dups.

the SDK's codegen:check fails on drift: src/generated.ts is generated from orcr api schema, so the SDK cannot silently fall behind the protocol. sdk/ts/test/ also proves path-grammar parity with src/path.rs and 100% schema-method coverage.

the e2e gate and the mock provider

end-to-end tests are gated behind ORCR_E2E=1 so cargo test stays fast. they exercise real behavior against live herdr, using the scriptable mock provider (orcr-mock-agent) instead of real claude or codex. the mock self-discovers its herdr pane, reports its own state, writes a claude-format transcript into its data dir (so logs and ask resolve), and parses per-turn directives from the prompt (@turn_ms, @say=<word>, @write=<relpath>, @block, and more) so a test can drive turn shape per agent. it runs only under ORCR_ALLOW_MOCK_PROVIDER=1.

the suites, run one at a time:

ORCR_E2E=1 cargo test --test e2e                                   # driver + harness
ORCR_E2E=1 cargo test --test agent_e2e -- --test-threads=1         # agent core
ORCR_E2E=1 cargo test --test completion_e2e -- --test-threads=1    # turns, wait, logs
ORCR_E2E=1 cargo test --test gc_e2e -- --test-threads=1            # park/reap, attach, reconcile
ORCR_E2E=1 cargo test --test loop_e2e -- --test-threads=1          # scheduler
ORCR_E2E=1 cargo test --test top_e2e -- --test-threads=1           # the TUI
ORCR_E2E=1 cargo test --test recipe_e2e -- --test-threads=1        # SDK, recipes, scaffold

every e2e test creates a throwaway ORCR_HOME tempdir and a disposable herdr session named orcr_test_<rand> (the rand comes from a UUIDv4, because UUIDv7's timestamp prefix collides across near-simultaneous tests), and tears both down in a drop guard. never touch the user's default session and never use ~/.orcr. copy the harness helpers in tests/e2e.rs. non-M4 suites set ORCR_DISABLE_DISCOVERY=1 so unmanaged discovery does not pull your real sessions into the test store.

navigate the codebase

read spec/codebase.md first. it is the living map of the source tree, updated by every milestone, so you can orient without re-reading everything. open the specific file you need to touch for exact signatures; read the per-milestone spec/_impl/*/notes.md for the why (the herdr facts in m0-foundations/notes.md are critical to the driver).

the rough shape:

• src/error.rs: the error enum and exit mapping (single source of truth).
• src/path.rs: the path and glob grammar in one place; every surface derives from it.
• src/api.rs, src/wire.rs: the socket method registry and the wire protocol.
• src/config.rs, src/home.rs, src/cron.rs, src/service.rs, src/scaffold.rs: config, home layout and safety, the cron evaluator, service units, and scaffolding.
• src/server/: the single-writer server: engine.rs (agent core, queue, spawn pipeline, wait/ask/logs), completion.rs (turn state machine), gc.rs (park/reap plus reconciliation), loops.rs (scheduler), discovery.rs (unmanaged discovery).
• src/store/: SQLite (WAL), single writer; schema.rs and the typed DAL in mod.rs.
• src/driver/: the herdr socket driver; contract.rs pins the herdr methods and is checked against live herdr.
• src/top/: the view-only TUI.
• sdk/ts/, skill/: the TypeScript SDK and the skill.

milestones

each milestone is independently buildable, testable, and verifiable; unit tests plus the e2e gate must pass before the next begins. the full spec is at spec/spec.md and per-milestone plans are archived under spec/_impl/.

how to extend

match the spec verbatim where it is precise (grammar, status vocabulary, error and exit codes, JSON shapes, env contract, store schema). where the spec is silent, choose the simplest correct behavior and record it in the milestone notes.md.

conventions

• single writer. the server owns the store. all writes go through BEGIN IMMEDIATE transactions, and events are written in the same transaction as the change they describe.
• clean lint. cargo fmt and cargo clippy --all-targets -- -D warnings must stay clean.
• small, focused commits on main: one module and its tests, one verb, or one fix per commit.
• derive, do not duplicate. nothing derivable is stored (an agent's name is its path's last segment, its home workspace is its first segment or default, data dirs mirror paths). glob matching is anchored and segment-aware, never SQL LIKE.

license

orchestratr is dual-licensed: GNU AGPL-3.0-or-later for open source, and a commercial license for organizations that cannot comply with the AGPL (contact hey@orchestratr.dev). see the LICENSE file in the repo.