herdr-orchestra

How it works

One run, from request to pull request.

A run builds one feature. The lead writes an orchestration plan of 1 to 4 milestones, the orchestration run builds them on one feature branch, and it ends in a pull request. Here is every step, using a CSV import feature as the example.

THE ORCHESTRATION PLAN1. You ask for a feature2. Lead writes the plan3. You say go4. Orchestration runEvery milestone goes round this loopcheck failed: back tothe coder, up to 3 roundsorch autopilota plain script drives the loop;the lead only decidesLead dispatches, pausesorch dispatch M1 M2Coder buildsA model of the milestone's tierChecks runYour test commandReviewer reads the diffBlocker: a fix job, 2 roundsEvent manager queues itWakes the lead when idleapprovedfeature/csv-importone commit per milestoneM1M3M25. You review the PRRead summary.md, test, merge1. You ask for a feature2. Lead writes the plan3. You say go4. Orchestration runLead dispatches, pausesorch dispatch M1 M2Coder buildsA model of the milestone's tierChecks runYour test commandReviewer reads the diffBlocker: a fix job, 2 roundsEvent manager queues itWakes the lead when idlefix ×3approvedCommit on feature/csv-importOne per milestonewhen every milestone is in5. You review the PRRead summary.md, test, merge

Steps 1 to 3 · the orchestration plan

You set the goal. The lead writes the plan.

  1. Open your team

    One pane each: a lead, one or more coders, and an optional reviewer. Coders can run different models. orch agents launch <kind> --model <id> prints each agent's command. Only one tool, or one window? Open just the lead: it builds the team from its own tool (orch team codex) and orch team up opens the other panes when you say go.

  2. Ask the lead for a feature

    Run /orch-plan <feature> in the lead's pane. A good request has Feature, Why, Must, Must not, Already decided, Done when.

  3. The lead researches and plans

    It reads the codebase, finds the files and patterns involved, and writes milestones as issues. Anything it can't decide goes under Open questions, with options.

  4. The lead picks a tier for each milestone

    Small for mechanical work, medium for normal implementation, high where reasoning is the hard part. It reads the model catalog (orch models) and writes the reason next to each choice.

  5. You read the plan and say go

    .orchestrate/plan.md is a normal Markdown file. Change dependencies, a tier, review yes or no, and answer open questions. Nothing starts before you say so.

.orchestrate/plan.md
# Plan: CSV import for transactions
Branch: feature/csv-import
Check command: npm test
Isolation: worktree
Estimate: 1h10m
Lead: lead (claude: opus)
Workers: claude-1 (claude: sonnet), claude-2 (claude: haiku)
Reviewer: reviewer (agy)

## [x] M2: Import endpoint
Depends on: M1 (shared ImportRow type)
Tier: medium
Needs: coding, tool-use
Model why: one module, a clear contract,
  an endpoint to copy; no design decisions
Estimate: 40m
Review: yes
Goal: users upload a bank CSV and get rows back
Acceptance criteria:
- POST /imports returns 400 when the
  amount column is missing
Interfaces:
- ImportRow { date, amount, payee }
Open questions:
- none
Notes from user:
  Use the existing upload limit (10 MB).

Step 4 · the orchestration run

The lead dispatches. The team builds, checks and reviews.

  1. Dispatch, then pause

    The lead runs orch dispatch and stops. Each milestone goes to a free coder whose model serves its tier. In worktree mode, independent milestones run at once.

  2. Check

    When a coder finishes, your check command runs on its work. A failure sends the last 60 lines back, up to 3 rounds. Out of rounds, the milestone gets one go on a stronger model.

  3. Review

    The reviewer reads the diff and reports blockers. Each blocker round becomes a fix job for the next free coder, up to 2 rounds.

  4. Land

    An approved milestone becomes one commit on the feature branch, and the milestones that depended on it unlock.

  5. Wake the lead

    The lead is woken with what happened: a milestone landed, a coder asked a question, something failed or is held. It decides, dispatches what is ready, and pauses again.

A plain script, the event manager (orch autopilot), runs this loop; the lead makes its decisions. The orchestration run →

~/app · run log
lead $ orch dispatch M1
DISPATCH M1 -> claude-1 (tier high)
started the event manager (`orch autopilot`, log: .orchestrate/autopilot.log)
[14:02:11] autopilot started: worktree mode, max 2 parallel, workers ['claude-1 (sonnet)', 'claude-2 (haiku)']; events go to the lead (lead)
[14:02:12] M1 -> claude-1
[14:08:40] M1 done by claude-1 -> running checks
[14:09:05] M1 checked and merged into feature/csv-import
[14:09:06] woke the lead (lead): 2 event(s) — merged M1, ready
[14:09:31] M2 -> claude-1
[14:09:31] M3 -> claude-2
[14:17:48] M3 done by claude-2 -> running checks
[14:18:20] M3 checks failed -> fix round 1
[14:21:02] M2 paused: skip empty rows or reject the file?
[14:21:03] woke the lead (lead): 1 event(s) — paused M2
[14:24:40] M2 -> claude-1
[14:26:51] M3 checked and merged into feature/csv-import
[14:33:15] M2 review: 1 blocker(s) -> fix job queued (first free coder)
[14:33:16] M2 fix job -> claude-1
[14:41:10] M2 review passed
[14:41:11] M2 checked and merged into feature/csv-import
[14:41:12] woke the lead (lead): 2 event(s) — merged M2, ready
[14:41:40] M4 -> claude-2
[14:52:30] M4 checked and merged into feature/csv-import
[14:53:04] woke the lead (lead): 1 event(s) — all_done
[14:53:05] ALL_DONE on feature/csv-import — final check PASS. See .orchestrate/summary.md

$ orch finish
CLEAN feature/csv-import is the only branch this run made (4 hidden ref(s) removed)
PUSHED feature/csv-import to origin
PR https://github.com/you/app/pull/42

Inside step 4 · the event manager

The lead is woken like a browser's event loop.

In a browser, a click doesn't run straight away: its callback waits in a queue, and the event loop runs it only when the call stack is empty. A run works the same way. Agents finish work or ask questions in the background, each event is stored in a queue, and the event manager wakes the lead once with the whole batch when it is idle. The lead decides, and an answer goes back to the coder that asked.

Leadlike the call stackbusywokentalking to you about the plan…orch events → 4 eventsorch dispatch M4orch answer M2 "skip empty rows"orch dispatch M3 --tier highAgentslike Web APIs: work in the backgroundclaude-1building M1M1 checked and mergedcodex-1building M2M2 paused: a questionopencode-1building M3M3 still failing after its roundsgot the answer, building M2answerto thesame coderevery event is stored firstEvent queuelike the callback queue · kept in state.json, so none is missedmergedM1readyM4pausedM2failedM3empty: the lead read them allwakes it once per batch,only when it is idleEvent managerorch autopilotlike the event loopLead away? Nothing is lost: it is woken again after 5 minutes (3 times), then you are told,and ready work starts by itself after 15 minutes.
In a browser
Web APIs run a timer or a fetch in the background.
In a run
Coders and the reviewer work in their own panes.
In a browser
When one finishes, its callback waits in the queue.
In a run
When one finishes or asks, an event waits in the queue.
In a browser
The event loop runs a callback only when the call stack is empty.
In a run
The event manager wakes the lead only when it is idle, with the whole batch.

The event kinds and commands are the real ones. The lead and the event manager →

Step 5

One branch, one pull request.

The run never adds bookkeeping branches or commits to your repo. You get a feature/<name> branch with a real commit per milestone and a summary in .orchestrate/summary.md, including the tier planned for each milestone next to the model that really did it, and the estimated time next to the real time, with the reasons when something took longer. Run orch finish and it re-checks the branch, pushes it and opens the pull request.

mainrun startsM1M2M3M4feature/<name>: one branch per run, a real commit per milestonemergeM1 contractShared typesM2 backendclaude-1, own worktreeM3 frontendcodex-1, own worktreeM4 integrationWires both sidesOpen PRyou merge

When it needs you

You answer, the same coder carries on.

If a coder asks something the plan and the code don't answer, the lead is woken and asks you in its pane. Your answer goes into the plan with orch answer and back to the coder that asked, which continues from its saved work. Other milestones keep running, and no event is lost while anyone is away. When a run needs you →

After the summary, ask the lead for any change you want. It runs orch fix M1 "the login button should be blue": one small follow-up job goes straight to the coder who built M1, the check and review run as usual, and the summary is written again. The lead and the event manager →

Modes

Pick per run.

Worktree Isolation: worktree

Each coder works in its own git worktree. Independent milestones run at the same time, and each one lands when it passes checks and review.

~/code/app            # your folder, on feature/csv-import
~/code/app-wt/claude-1  # M2 backend, medium tier
~/code/app-wt/claude-2  # M3 frontend, small tier
  • Pick it when milestones can be built independently.
  • Review is pipelined: coders move on while the reviewer reads.

Shared Isolation: shared

Everyone works in your folder, one milestone at a time. Two agents in one folder would overwrite each other, so this mode is strictly sequential.

~/code/app            # M1, then M2, then M3
  • Pick it when every milestone depends on the one before.
  • The lead uses it automatically when you have one coder.