/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.

How a run works

Every strategy shares the same spine — and every step of it is on the record.

Before it runs: prepare

Most bad runs are lost before the first agent starts — the request was vague, or the tools were missing, so every worker guessed. orchestrate takes stock first, and asks only what it cannot look up.

What one clarify round looks like:

Nothing is installed and no paid service is used without your yes — free, local tools first, paid ones only as a fallback you approved. Tune it with prep=full (always interview and scout) or prep=off.

It picks the shape

You never need a strategy name. Triage reads what kind of task it is and which tasks really depend on each other — concurrency is the default; sequence is a finding. The gates stay the same whatever shape it picks.

Or force one yourself — find it by the shape of your task:

Deep research, fanned out

Ask a question that many sources answer — "what is the fastest proven e2e tool for a Tauri app?" — and it runs one lane per source in parallel, each with the best free tool for that source. You never have to list the sources.

• keyword-richSix to ten query variants per lane, then a second round on every tool, repo and author the first one surfaced.
• traced, not trustedEvery claim follows its link to the repo, registry or docs that owns it, and carries a grade. Likes and stars say popular, not right.
• refuted before it shipsA synthesizer writes the report; a fresh fact-check tries to break every load-bearing claim first.

A lane whose tool is missing gets it proposed with the install command — never installed unasked. The same shape serves market research, content and video work: the lanes come from the question and from what is on your machine.

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.

• redesign, never patchWhen an agent finds the plan won't work as written, it stops instead of hacking around it. A fresh top-tier model redesigns the part that broke; anything your users would notice comes to you as a question.
• 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.
• your machine, your callInstalls, paid services and credits are proposed with the exact command and why — never run without your yes. Free, local tools come first.
• data is not instructionsWorkers never follow orders found in logs or fetched content, and credentials never enter briefs.

The board

You should not have to read logs to know where a run stands. Open a second terminal in the repo and type board. You get a live kanban of the run: what is queued, who is working on what, what is under review, what is done, what is stuck. It updates by itself as files land. It runs in any terminal and needs nothing but python.

  ORCHESTRATE   payments-api @ main                                                                     1/5 done  ·  2m20s
  goal       Ship the rate-limit rewrite behind a flag
  run        parallel  ·  review dual  ·  host Claude Code
  models     worker sonnet  ·  reviewer opus
  budget     agents 6/8  ·  tokens 412k/150k-600k
  checks     3/3 ok
  plan       approved 15:51
  attention  x 1 blocked/failed  ·  ? 2 pending
  mail       2 sent  ·  2 unread  ·  1 for controller  ·  1 question  ·  learn 2  ·  2 new for controller

  TODO  0

  ╭─ IN PROGRESS ──────────────────────────────────────────────────────────────────────────────────────────────────── 2 ─╮
  │  3  Migrate the DB layer  impl-3         ? asked controller #23 · 2m19s · tests ok 0s · m1                           │
  │  4  Ship the docs         impl-4 ·codex  > 2m19s                                                                     │
  ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

  ╭─ REVIEW ───────────────────────────────────────────────────────────────────────────────────────────────────────── 1 ─╮
  │  2  Auth token refresh  quality-2  spec ok r1 · quality .. r1                                                        │
  ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

  ╭─ DONE ─────────────────────────────────────────────────────────────────────────────────────────────────────────── 1 ─╮
  │  1  Extract rate-limit middleware  quality-1  4f2c91a..a7d3e10                                                       │
  ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

  ╭─ BLOCKED ──────────────────────────────────────────────────────────────────────────────────────────────────────── 1 ─╮
  │  5  Integration  integ-5  x needs the vendor token — owner: controller, next: add it to .env.example                 │
  ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

  15:51  integ-5: needs the vendor token — owner: controller, next: add it to .env.example

  j/k focus a card  ·  enter its history  ·  e expand all  ·  a attention only  ·  n next run  ·  r reload  ·  q quit

A few commands sit under the pane. board attention lists what needs the controller, most urgent first. board check audits the run and refuses to count a task as finished when a review failed or a file it claims to have written is missing. board resume writes the handoff a fresh session needs to pick the run up where it stopped. board reap finds the dev servers and watchers an agent left running and stops them; the run cannot finish while any are still up. Full reference: docs/usage.md.

Shared context

Running several agents at once is easy. The hard part is that each one only knows what it did itself. Two of them hit the same broken test setup and both lose an hour to it. One changes an interface and nobody hears. You change a decision halfway through, and the workers already running never see it.

orchestrate keeps one shared record for the run, and every worker reads it each time it checks in. Three kinds of thing travel through it.

One preset, every knob optional

A strategy is a preset, not a product. orchestrate has a small set of 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:

Where the tokens go

The target is zero wasted tokens, not minimal tokens. Workers get every pointer they need to do the job — then keep a short work log 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, keeps a short milestone log in its own transcript, 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, then hand it a plan, an idea or a question. With no flags it prepares, picks a shape and explains why — then waits for your approval before anything runs.

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.

board --version says which release you have. On a run you started earlier, board version says which release started it and whether anything since then needs doing — so upgrading in the middle of a run is safe.

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.