herdr-orchestraherdr-orchestra · AI agent orchestration for Herdr
Your AI agents, working as a team.
herdr-orchestra runs an orchestrated agent workflow for coding. A lead writes the orchestration plan and picks the right level of model for every step. Coders build in parallel, a reviewer checks every diff, and the lead coordinates the run. You get one clean pull request.
In plain words: it is a skill you install into the coding agents you already use (Claude Code, Codex, OpenCode and others), plus a small orch command. Type /orch-plan in one of them and it plans the work, then runs your other agent windows as one team.
npx herdr-orchestra@latestOrchestration plan and orchestration run
One plan you can read. One run that follows it.
You describe the feature and say go. Everything between is planned by the lead and carried out by the team, and the summary shows where the run differed from the plan.
The orchestration plan /orch-plan
The lead reads your codebase and works out what the feature really involves and writes as many milestones as it needs, as issues: one for a small change, more only where a split buys something. For each one the plan says what it depends on, which level of model it needs, which coder will take it, and why.
- Goals and acceptance criteria, never how-to steps
- A reason for every split, and a tier for every milestone
- A normal Markdown file you can edit before anything starts
The orchestration run /orch-run
The lead dispatches the milestones and pauses. A plain script builds, checks, reviews and lands them, and wakes the lead whenever something needs a decision.
- The lead is woken by events; it never polls
- Questions reach you only when only you can answer
- Every event is stored first, so none is missed
The right model for each step
Small models for small work. Strong reasoning where it counts.
The lead does not pick a model by its name. A catalog rates each model on reasoning, coding, architecture, instruction following, tool use, planning, speed and context size, and a model needs enough reasoning for its tier.
Small and fast
- For
- classification, renames, docs, config, mechanical edits. Speed matters more than depth.
- For example
- haiku, gpt-6-luna, qwen3.6-35b-a3b
Medium, for coding
- For
- normal implementation, tests, debugging inside one module. Solid coding and tool use, little design.
- For example
- sonnet, gpt-6-sol, qwen3.8-27b
High reasoning
- For
- the lead, contracts and architecture, cross-module refactors, auth/payments/schema, escalations. A wrong design here is expensive.
- For example
- opus, deepseek-v4-pro, glm-5.3
Explained in the plan
Each milestone carries Tier, Needs, Model why and an Estimate of its time, so you can see and change every choice before the run.
Checked against the run
The summary shows the tier that was planned next to the model that did the work, and the estimated time next to the real time. When something took longer, it says where the time went and who it waited on: fix rounds, the reviewer, your answer, a usage limit.
Yours to change
Use the models your agents already reach. Add or re-rate models in one file. Ultra-premium models (fable, astra) are kept out of runs by default.
Works with your agents
Any installed agent can play any role.
Mix kinds and models freely: a Claude lead on a high-reasoning model, a Codex and a Claude coder, an Antigravity reviewer. Anything that can run shell commands can join. Only have one tool? Open one pane: the lead builds the whole team from it and opens the other panes for you.
Who does what
Clear roles, and clear limits.
Each role has one job and a line it never crosses. The lead decides what, why and which level of model; the coders decide how.
You
- Does
- Describe the feature, approve the plan, answer the questions only you can answer, and review one pull request.
- Never
- Babysit agents or copy work between them.
Lead
- Does
- Researches the codebase, writes the plan, and picks the model tier each milestone needs. Then it dispatches the work, pauses, and is woken to decide what happens next.
- Never
- Writes code, tells coders how to build it, or polls agents.
Coders
- Does
- Own the how: design, code, tests, fixing failed checks and review findings, resolving conflicts. Each runs a model that fits its work, and takes milestones of its tier.
- Never
- Change scope or skip acceptance criteria.
Reviewer
- Does
- Reads every diff and reports problems as BLOCKER: file:line — what — why.
- Never
- Edits code or prescribes the fix.
Parallel by design, clean history
Independent work runs side by side, on one branch.
For each pair of milestones the lead asks: could B be built and pass its checks if A never existed? If yes, two coders build them at the same time in separate git worktrees, each on its own model.
Contract first
Parallel milestones that must fit together depend on a small milestone that defines the shared types or API.
Scaffold first
Routes, nav, package.json and other hotspot files change in one early milestone, so parallel work never collides.
A normal branch and PR
One feature/<name> branch, one commit per milestone with a real message, and orch finish opens the pull request.
Built to keep going
It comes to you only when it needs you.
Failed checks, review findings, conflicts and tired agents are routed to the right place with a round limit. What needs judgment goes to the lead. What only you can decide reaches you, with the reason.
Sends the failure back
The last 60 lines of output go to the coder who built it.
up to 3 roundsQueues a fix job
The problem, not the solution, goes to the next free coder, preferring the author.
up to 2 roundsHands back the merge
A coder merges the branch in its worktree and resolves both sides.
up to 2 roundsBenches the agent
Another coder continues with the work so far.
60 min cooldownMoves the work on
Its task continues on another coder with the work so far; it rejoins when it is back.
10 min benchAlerts you
A desktop notification; every other task keeps running.
no waitingWakes the lead
That task pauses. The lead answers from the plan or asks you, and the same coder carries on.
orch answerSends it to the coder who built it
Tell the lead what to change. One small follow-up job goes to the same coder, with the check and review, and no new plan.
orch fixMoves it up a tier
A milestone a model could not finish gets one fresh round on a stronger model, with the work so far.
onceThe lead decides, a script does
Dispatch, pause, wake, decide.
The run works like a browser's event loop. The lead hands out work and pauses. A plain script does the work in between, queues what happened, and wakes the lead only when it is idle. No AI is spent on waiting or scheduling.
- 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 lead coordinates orch dispatch orch answer
It starts each milestone when its dependencies have landed, answers a coder's question from the plan or asks you, and decides what to do with a milestone that failed.
- Woken once per batch of events, only when idle
- Your answer goes back to the same coder
- A change after the summary goes to the coder who built it
- Never edits code or prompts a coder
The event manager runs it orch autopilot
A plain program hands milestones to coders of the right tier, runs checks and reviews, lands the results, and keeps a queue of everything the lead should hear about.
- One driver per run, safe to kill and restart
- Nothing red is committed; risky changes wait for you
- If the lead is away, ready work still starts
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
Two modes
Parallel worktrees, or one folder in order.
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.
Install and go
One command to install. Three steps to a first run.
Every version stays installed side by side, so switching back is instant.
npx herdr-orchestra@latestRuns in Herdr with Node (for npx), git and python3. No Node? Install with curl. Requirements