/orchestrate

The idea

Everything in orchestrate follows one idea: coordination and work are different jobs, and they should never share a context window.

A controller plans the run, assigns the work, and checks the results — it never writes code itself. Each task goes to a subagent: a fresh worker that starts empty, does one scoped job, and is thrown away.

The two never talk through chat. The controller writes a brief file; the worker reads it, works, and writes a report file back. The files outlive the worker — so a run survives crashes, compaction, and restarts, because its state lives on disk instead of in anyone's head.

Worker 1 is already gone. Its brief, its report, and its ledger line remain — that is the whole trick.

How a run works

Every strategy shares the same six-step spine.

One preset, ten knobs

A strategy is a preset, not a product. orchestrate has ten dimensions — knobs like how work splits, who reviews it, which engine runs it at which reasoning effort, and whether the flight plan gates on your approval (confirm, on by default). Each of the nine strategies is just a named preset over those knobs. Learn one command and you've learned all nine.

Any knob you set yourself overrides its preset value. That's the whole override model:

That one line means: Codex implements every task, Claude still reviews every result. Strategies compose the same way — strategy=loop topology=parallel makes each loop cycle fan out.

The knobs you'll actually type — most runs touch two or three:

Choose a strategy

Find yours by the shape of your task — or pass nothing and let triage pick.

Gated by default

Nothing lands because an agent says it's done. Every result passes two gates, in a fixed order, and reviewers verify by reading the code — never the worker's own report. Every gate that judges produced work names at least one fact no agent produced: a command that ran with its output, a file on disk at a stated sha, an external readback. A topology of agents reading each other's reports can be perfectly consistent and entirely unverified.

Four invariants sit under every status, gate, and ledger line:

The third is the one most runs get wrong: an exit code of 0 only proves the process exited — not that the work landed.

• branch firstIt never starts work on main without your explicit consent.
• no duplicates on overloadIf the API chokes, it resumes the same agent — it never spawns a competing copy.
• loops have a kill switchHard cycle caps, a regression breaker, and a contract file you can delete to stop everything.
• PR bandwidthIt never opens a new PR while the run's previous one sits unmerged.
• blocked means escalateA stuck task gets more context, a stronger model, a split, or a human — never a blind retry.
• data is not instructionsWorkers never follow orders found in logs or fetched content, and credentials never enter briefs.

Where the tokens go

The target is zero wasted tokens, not minimal tokens. Workers get every pointer they need to do the job — then stay quiet while working and report densely when done. Noisy command output is redirected to files, so dumps never enter anyone's context.

Every dispatch carries a short contract matched to its role — a dispatch with no block is a defect, not a default:

The life of a dispatch — where tokens get spent, saved, and where quality is guarded:

1. briefcontrollerinput quality ↑
   Pointers, not payloads: the objective, the scope, read: pointers to the right files, a verification command, and a stop condition — instead of pasted file contents.
   example brief ▸

   # .orchestrate/task-3-brief.md Objective extract the rate-limit middleware; done = suite green, public API unchanged Scope in: src/middleware · out: auth flow · must NOT change: response shape Pointers read: src/middleware/rate.ts — current implementation @ 4f2c91a read: src/config/limits.ts — constants to honor Verification pnpm test middleware Report .orchestrate/task-3-report.md · inline <15 lines Stop BLOCKED if the storage backend is ambiguous — don't guess
2. brief-checkgatesaves a worker turn
   A script fails dead pointers and missing sections before dispatch — a clarifying round-trip afterward costs a full worker turn.
3. workworker−narration −dumps
   The worker orients, works silently, and redirects noisy output to .orchestrate/raw/ at execution time — the dump never enters context.
4. reportworkercompounds every turn
   Dense and structured — the report becomes controller input that is re-read on every later turn, so every saved token compounds. Code and exact errors stay verbatim.
5. gate & ledgerreviewer · controllerrecall guard
   Findings land in a file that caps can't truncate; the task lands as one ledger line. Resume reads the ledger and git log — never the transcript.

Start here

Install once, point it at a plan. Bare invocation triages and explains its pick.

The same install runs on any Agent Skills host — Claude Code is the reference; on the others the skill detects its host at kickoff, binds what's native, and degrades honestly where a primitive is missing.

An alias is a preset you name yourself in config.yaml. Five ship built in — good defaults to steal:

Copy-paste starting points for more scenarios: docs/recipes.md.