Questions and how-tos
Short answers to the questions people ask most. Each one ends with a link to the page that has every detail.
Planning and small changes
Section titled “Planning and small changes”How is a small change handled? Does it skip planning?
Section titled “How is a small change handled? Does it skip planning?”Not fully, but planning is much lighter. Start your request with quick::
/orch-plan quick: make the Save button blue- The lead still reads the code first. It checks that the change is small and safe. Then it writes a short plan with one milestone and one coder, plus its reason for calling it quick (
Quick because: ...). - It waits for your “go”. That takes a few seconds, and you can catch a wrong guess before any code changes.
- One coder builds it, with no reviewer. The check (lint, types, tests) runs 2 times instead of 4.
Risky changes, like a database migration, CI, secrets or package files, are never quick. They are refused as quick runs and get full planning instead. Normal feature planning has not changed. See Quick runs for small changes.
Can I choose quick or full myself?
Section titled “Can I choose quick or full myself?”Yes, with the first word of your request:
| You type | What you get |
|---|---|
quick: make the Save button blue |
One coder, no reviewer |
quick review: reject an empty email on signup |
One coder, and the reviewer reads the diff |
full: add createdAt to GET /orders |
The full process: milestones, roles, a reviewer |
| nothing | The lead decides after reading the code, and tells you why |
If you write quick: but the lead finds the change is not small (for example it needs a new database column), it tells you which point failed and plans it in full, unless you insist.
Can I put several small changes in one quick run?
Section titled “Can I put several small changes in one quick run?”Yes. Write them in one request, and each one gets its own line in the plan to check:
/orch-plan quick: make the Save button blue, and add a spinner on the dashboardHow does the lead split a big feature?
Section titled “How does the lead split a big feature?”It sizes the milestones to the feature, with no fixed count. Each milestone says Why separate: (why it is not part of another one), the Role: its coder should work as (for example “senior frontend engineer with a designer’s eye”), a tier (small, medium or high model) and an Estimate:. You read the plan, change anything in .orchestrate/plan.md, and say go. See The orchestration plan.
How long will it take?
Section titled “How long will it take?”The plan has an estimate for each milestone and for the whole feature. Milestones that run side by side count once. For example M1 30m, then M2 40m and M3 30m side by side, makes Estimate: 1h10m. At the end, the summary and orch report show the estimate next to the real time, and when it took longer, why and who it waited on. See Estimate vs actual time.
During a run
Section titled “During a run”A coder has a question. How do I answer it?
Section titled “A coder has a question. How do I answer it?”You answer the lead, not the coder. The lead asks you in its pane, then runs:
orch answer M2 "skip empty rows"The answer is written under that milestone’s “Notes from user”, and the same coder carries on. Other milestones keep running meanwhile. See When a run needs you.
Part of a milestone can’t be built yet. Can I ship the rest?
Section titled “Part of a milestone can’t be built yet. Can I ship the rest?”Yes. Say a milestone has two criteria: AC1 “the watch shows the steps” and AC2 “the watch syncs with the phone API”, and that API doesn’t exist yet. The coder asks, the lead asks you, and you say “build the rest, AC2 later”. The lead runs:
orch answer M7 --defer AC2 "build the rest; sync when the API exists"Now when the coder reports AC2 as not met, it is not sent back to fix it, and it is not moved to a stronger model. The reviewer doesn’t block on AC2 either. The summary has a “Deferred: not done, follow-ups” section that says AC2 was not built, gives your reason, and suggests orch fix M7 "..." for later. If the milestone already failed, the lead runs orch defer M7 AC2 "<your reason>", then orch dispatch M7.
Only you can agree to leave something out. Writing it in the plan as a note is not enough: the check reads --defer.
A milestone says held. What do I do?
Section titled “A milestone says held. What do I do?”orch holds a milestone when its change looks risky: it deletes files, touches a migration, CI or secrets, changes packages, or is very large. You get a desktop notification. Look at the reasons in orch status, then:
orch approve M3 # let it landorch set M3 paused # or stop it for nowHow do I see what is going on?
Section titled “How do I see what is going on?”orch status # every coder and milestone, and why something waitsorch events --peek # what is waiting for the lead, without marking it readA worker line shows herdr=ok or NO AGENT, and state=free, coding M3, stopping M3, benched 42m or OFF. stopping M3 means M3 was paused or moved while that coder worked: orch pressed Esc and told it to stop, and it gets no new work until herdr shows it idle.
Can I make a milestone go to one particular coder?
Section titled “Can I make a milestone go to one particular coder?”Yes. Ask the lead, or run:
orch dispatch M2 --to claude-1--to locks that milestone to that coder, which is useful for UI work you want one agent to own. The plan’s Prefer: line is weaker: it only breaks ties. --to refuses a coder that has no agent open in herdr, or one you benched. See Agents and roles.
I don’t want one coder today (for example, no Claude). How?
Section titled “I don’t want one coder today (for example, no Claude). How?”orch bench claude-1 off "no Claude today"orch bench claude-1 on # later, to bring it backIt stays out until you turn it back on, even across restarts. Its milestones go to the other coders. To bench it for a while only, use orch cooldown claude-1 60 (60 minutes).
How do I swap a coder for another one?
Section titled “How do I swap a coder for another one?”orch stop # stop the event manager cleanly; nothing is lost# change the Workers: line in .orchestrate/plan.mdorch sync # read the plan againorch team up # open the new coder's paneorch resume # carry onHow do I stop a run?
Section titled “How do I stop a run?”orch stop stops the event manager after the step it is on (a check, a merge). Every event is kept, and orch resume starts it again. orch stop --now also stops the step it is on. To stop one milestone and keep its work, use orch park M2 paused "why".
After the run
Section titled “After the run”I read the summary and want one more change. Do I plan again?
Section titled “I read the summary and want one more change. Do I plan again?”No. Tell the lead, and it sends the change straight to the coder who built that part:
you → "the login button should be blue"lead → orch fix M1 "the login button should be blue"orch adds a small follow-up milestone (for example M5 “Fix for M1”), the same coder makes the change, the check (and the review, if M1 had one) runs as usual, and the summary is written again. It works on quick runs too. You can run orch fix yourself, and --to <worker> gives it to another coder. If you type into a coder’s pane instead, nothing checks the change and it is not in the summary. See The lead and the event manager.
How do I get the pull request?
Section titled “How do I get the pull request?”Do the short manual checklist at the end of .orchestrate/summary.md (only what needs your eyes, like how the UI looks), then:
orch finishIt runs the final check (or reuses it when the files are exactly the same), removes the coders’ folders and the <repo>-wt folder, pushes the feature branch and opens the PR. See Git, commits and the PR.
Why is there a <repo>-wt folder next to my repo?
Section titled “Why is there a <repo>-wt folder next to my repo?”That is where coders work side by side, one folder each, so they don’t touch each other’s files. orch finish removes it when every milestone has landed. A stopped or crashed run keeps it on purpose, so orch resume can carry on. Quick runs never make one. A folder with real changes no milestone has is kept, and finish prints the command that deletes it.
Restarts and crashes
Section titled “Restarts and crashes”My computer restarted, or herdr closed. What now?
Section titled “My computer restarted, or herdr closed. What now?”Open herdr and run one command in the repo:
orch resumeIt leaves the time orch was down out of every time budget, gives the agents their names back, saves any unsaved work, sends each task in progress to its agent again, and starts the event manager. You don’t type “continue” in each pane. It is safe to run more than once. See After a restart.
A coder’s pane closed, or only a shell is left.
Section titled “A coder’s pane closed, or only a shell is left.”The lead tells you (WORKER-LOST) with the exact fix. Usually:
orch team up # opens every missing agent in its folder, on its modelThe milestone waits with its work so far.
Why did the run stop?
Section titled “Why did the run stop?”orch doctor --crashIt shows why the event manager last stopped, for example the computer’s memory guard closing the terminal, and the last screen of any agent that quit. See Why did it stop?.
Team and agents
Section titled “Team and agents”I only have one tool (for example Codex). Can I still run a team?
Section titled “I only have one tool (for example Codex). Can I still run a team?”Yes. Open just the lead’s pane. The lead sees it is alone and builds the team from that one tool: coders on its small, medium and high models, and a reviewer. When you say go, it opens the other panes for you with orch team up. See One tool, whole team.
Which models can it use?
Section titled “Which models can it use?”Whatever your agents already reach. The lead picks a small, medium or high model for each milestone. Only ultra-premium models are blocked. orch models lists them all. See Models and tiers.
Updates
Section titled “Updates”How do I update?
Section titled “How do I update?”orch update # install the latest release and show what is neworch update --check # only lookorch update --version v5.7.1 # install one exact version, also how you go backOn 5.7 or older, run npx herdr-orchestra@latest once. After that, orch tells you when a new version is out (herdr-orchestra 5.8.1 is out (you have 5.8.0). Run orch update.).
Can it update itself?
Section titled “Can it update itself?”Yes, it is on by default. When you start a new plan, orch installs a newer release first. It never updates in the middle of a run, for a major version, or in a repo pinned with .orch-version. Turn it off or on with:
orch config auto-update offSee Updates.
Every command is listed in Commands.