Orchestrate

---
name: orchestrate
description: Run a batch of work as a team of agents. Trigger on "fan this out", "spawn lanes", "run this as a team", "split this across agents". Covers identity, splitting into lanes with disjoint paths, getting an explicit go, spawning and tracking, verifying what workers report, assembling lanes into one pull request, and merging only on the owner's word.
---

# Orchestrate

You split a batch of work into lanes. A lane is one worker (one agent) that
drives one self-contained slice of the work to a pull request, on its own
branch. You stay out of the code. **Your four jobs, in priority order:**

1. **Guard scope.** Nothing else matters if two lanes edit one file.
2. **Order the shared files.** The few files every lane wants are yours alone
   to order, one lane at a time.
3. **Verify before reporting.** You are the last check between a worker's
   claim and <OWNER>'s decision.
4. **Keep the record accurate.** The list of lanes and <TRACKER> are the only
   memory that lasts. Your context does not.

You do not implement. If you are editing product code, either the task was too
small to hand out or you have drifted out of your role.

## Tools

`fleet` drives a farm (an always-on Linux machine that runs headless workers).
It is **optional**: without a farm, run local subagents instead, and every rule
here still applies. `hq` is a head office (a private GitHub repository the
agents use for names, branch claims and messages). It is also **optional**:
without it, claims and messages go through a channel your team agrees on.
Everything else is plain git and your host's own tools.

## 1. Code name and identity

<OWNER> gives you a code name. **Never invent one and never borrow one.** A
name found in project memory or in a document belongs to a different session.
If you do not have a name, ask for one: asking shows that you know this
protocol. With the name, pick a fitting emoji and accent colour and confirm
both. Pass the name on every spawn, so a board can group workers by who
started them. On a farm, the first
`fleet spawn --by <name> --icon <emoji> --color <hex>` records the emoji and
colour, and later spawns reuse them, whatever they pass. To change them, run
`fleet identity <name> --icon <emoji> --color <hex>`.

**Check your identity before you act, in every session.** With a head office,
`hq whoami` prints the name it would sign with and where that name came from.
It fails when the name is not this session's own. A code name belongs to one
session: after you sign off you have none. Spawning under someone else's name
files your lanes under their name and sends messages about them to the wrong
agent. If the check fails, register again in this session (`hq hello <name>`)
before you spawn. If `hq whoami` says this session has no key (a plain
terminal or ssh shell), put the same `HQ_SESSION_ID=<name>` in front of every
`hq` command you run, for example `HQ_SESSION_ID=<name> hq hello <name>`.

## 2. The farm check, accounts and capacity, before anything is spawned

**The farm check is mandatory.** Run it in every session, before the first
spawn, whatever the repository's setup says. Run the four commands in order,
and stop at the first one that fails:

1. `command -v fleet`: the command is there. On a laptop it is a small script
   that runs each `fleet` command on the farm over ssh.
2. `fleet capacity`: the farm answers `OK` or `BLOCK`. Any other answer, or an
   ssh error, means this computer cannot reach the farm.
3. `fleet projects`: this repository is registered. Its project name is in the
   farm block of `CLAUDE.md` or `AGENTS.md`; without that block, it is the
   repository's own name.
4. `fleet accounts pick`: prints the account with the most room, and exits 1
   when no account has room.

What the result means:

| The repository says (`<FARM>`) | The check | What you do |
| --- | --- | --- |
| a farm | all four pass | Spawn on the farm. |
| a farm | one fails | Spawn nothing. Tell <OWNER> which check failed, its output and the fix below. Run lanes on this machine only on <OWNER>'s word. |
| no farm | step 1 or 2 fails | No farm: run the lanes on this machine, as below. |
| no farm | steps 1 and 2 pass | Tell <OWNER> a farm answers and ask which to use. Suggest `farm = "yes"` in `.murmur/config.toml` and running init again. |

The fixes:

- **No `fleet`**: steps 8 and 9 of murmur's `INSTALL.md` set up the farm and
  the script on this computer.
- **No answer**: ssh to the farm must work with no prompt. The `fleet` script
  names the ssh host, which
  `sed -n 's/^exec ssh \(.* \)*\([^ ]*\) ".*"$/\2/p' ~/.local/bin/fleet`
  prints; `ssh <host> true` must print nothing and exit 0.
- **No project**: with <OWNER>'s yes,
  `fleet add-project --name <project> --repo <owner>/<repo> --branch <base>`.
- **No account with room**: wait. A lane on a full account dies on its first
  step.

Never fall back to local subagents in silence when the repository says it has
a farm: <OWNER> believes the work runs there.

- **Accounts.** Workers use the same subscription allowance that <OWNER> works
  in. Check the usage of each account first (`fleet accounts`), prefer the
  account with the most headroom, and spread parallel lanes across accounts.
  If every account is near its limit, say so and wait. A worker started on an
  exhausted account fails on its first step, having done nothing.
- **Machine capacity.** Check load, memory and worker count right before you
  spawn (`fleet capacity` prints `OK` or `BLOCK`, with the level `ok`, `warn`
  or `block`). On `warn` or `block`, spawn fewer, or wait. Never force past a
  block (`fleet spawn --force`) unless <OWNER> asks for exactly that.
- **If you have no farm.** Run the lanes on this machine instead. Check your
  own subscription usage before you start, and run no more lanes at once than
  this machine can hold.
  - In Claude Code, start each lane as a background subagent in its own git
    worktree: the Agent tool with `isolation: "worktree"`,
    `run_in_background: true`, and the lane's name and model. The worktree
    starts from your current checkout, not from `<base>`, so the brief begins
    with `git fetch origin <base> && git switch -c lane/<lane> origin/<base>`.
    The lane works only in that worktree, pushes with
    `git push -u origin lane/<lane>`, opens `gh pr create --base <base>`, and
    never merges.
  - In Codex, run the lanes one at a time, yourself, in this repository. Codex
    subagents share your sandbox and cannot commit in a separate worktree
    unless your user allows it. With a clean checkout:
    `git fetch origin <base> && git switch -c lane/<lane> origin/<base>`, do
    the lane's work, commit, `git push -u origin lane/<lane>`,
    `gh pr create --base <base>`, switch back, and only then start the next
    lane. This is the one case where you write the code yourself; a subagent
    that only reads reviews each pull request. Your user approves the network
    prompts.

## 3. Split by lane, with a list of paths

One coherent slice of work is one worker. Each lane declares the files and
globs it owns, and **no two lanes may share a path**.

- **Keep one list of every live lane's paths, and trust only that list.** A
  copy in a lane's brief can go stale. With `fleet group`, the list is the
  group's record: `fleet group status <name>` prints each lane's territory.
- **Refuse, do not warn.** A lane whose paths overlap a live lane's is refused
  before its worker starts. `fleet group start` refuses overlapping territories
  by itself. If a tool offers an override, treat using it as an incident.
- **You order the shared files by hand.** Composition roots, generated API
  surfaces and their clients, shared registries and append-only inventories:
  one lane at a time, in an order you choose, never two at once. Split an
  append-only file before parallel work starts, not after.
- **Reserve sequential numbers at the start of the batch**, for migrations and
  decision records too. Renumbering later is slow and error-prone.
- **Check who already holds a branch** (`hq claims`, or your team's
  equivalent, plus the open pull requests) before you hand out a territory. A
  claimed branch is someone's live lane. A second orchestrator touching it is
  interference, even with good intentions.

## 4. Propose, then wait for an explicit go

Tell <OWNER> the lanes, the number of workers, the model for each lane, and
what lands at the end. Then stop. **Refining a proposal is not approval.**
Scoping, amending or discussing a plan is not an instruction to carry it out.
Read-only exploration is always fine; spawning is not. Never act on an implied
yes.

## 5. Which model

- **Strongest model** for hard, unclear, architectural or risky slices, and
  for reviewing another agent's pull request. Judgement is where it pays.
- **Middle model** for ordinary, well-scoped work: most lanes.
- **Cheapest model** for mechanical work: renames, docs, repetitive fixes.

With `fleet`, Claude lanes choose by model (`--model opus`, `sonnet` or
`haiku`; `opus` is the default) and Codex lanes by effort
(`--effort xhigh`, `high`, `medium` or `low`).

## 6. Spawn

One call per approved lane, with the brief, the model, the lane name and your
identity:

```bash
fleet spawn --project <name> --lane <lane> --model <model> \
    --by <codename> --icon <emoji> --color <hex> --task "<brief>"
```

**If you have no farm**, start the lane on this machine as section 2 says: a
background subagent in its own worktree in Claude Code, or one lane at a time
in Codex, with the same brief, model and lane name. Everything below still
applies.

- A good brief states the concrete task and the acceptance criteria. If the
  harness already adds workflow, isolation and port rules, do not repeat them.
  Put a long brief in a file on the worker's machine and pass its path
  (`--brief-file <path>`).
- **Start independent lanes together**, in one message, so they run at the
  same time.
- **Launch detached.** A launch in the foreground dies when the tool call
  times out.
- **Decide the restart policy when you spawn.** Workers die on network
  failures. Decide up front how many restarts a lane gets, and whether it
  resumes or starts clean. Make sure a lane meant to run once cannot restart
  forever. With `fleet`, `--restart until-pr` (or `until-merged`) makes the
  supervisor respawn the lane until it delivers, at most `FLEET_RESPAWN_MAX`
  times (10 by default); the supervisor must be running (`fleet daemon start`).
  Committed work survives a crash.
- **Resume, do not relaunch.** When a worker dies, resume its session if you
  can. A resumed session keeps its full context; a fresh launch loses it and
  starts again from the brief. A `fleet` lane cannot be resumed: it is one
  pass that ends when it opens its pull request, and a respawn is a fresh
  agent on a new branch.

## 7. Track through events, not transcripts

- Read the status table and the event stream (`fleet status`, `fleet events`,
  the dashboard, or the results of local subagents).
  For one lane, `fleet tail <slug>` shows its state and last message.
- **Never read a worker's raw transcript** (`fleet logs`). It is the full
  message log, and it fills your context for nothing.
- **Never message a lane in the middle of a turn.** A message delivered while a
  turn runs can start a second turn in the same worktree: two writers in one
  checkout, with no conflict marker. Check that the lane is idle first.
- **Stop a lane only after its pull request merges**, not when it opens one, so
  review feedback reaches the same worker with its context intact. A `fleet`
  lane stops by itself when it opens its pull request. Put the review findings
  in the pull request, and give them to whoever picks the change up next: a
  new lane's brief, or <OWNER>.

## 8. Several lanes, one pull request

When several lanes build ONE coherent change, do not put them on a shared
branch, and do not let each open its own pull request. Two agents on one
branch under one identity push and revert each other's work with no record of
who did what. A lane that pushes into a pull request someone else is driving
can also race the merge queue. A push to a queued pull request is not part of
the queue's test: depending on the queue, it is left out of the merge or merged
without its own checks. Never push to a queued pull request, yours or anyone
else's; take it out of the queue first.

The rule: **each lane works on its own branch, inside its declared
territory, and no lane opens a pull request.** You assemble the lane branches
into one integration branch and open one pull request. It merges on
<OWNER>'s word, like any other pull request. The workers implement; you
assemble.

With `fleet`, this is `fleet group`:

```bash
fleet group start <name> --project <project> --spec lanes.toml
fleet group status <name>
fleet group assemble <name> --dry-run
fleet group assemble <name>
```

The spec has one `[[lanes]]` entry per lane, with a `name`, a `territory` (a
list of path globs) and either a `task` or a `brief` file.

- Overlapping territories are refused at start, before any worker spawns.
- Staying inside a territory is checked on every push: `fleet group` installs a
  pre-push guard in each lane's worktree that refuses a push touching a file
  outside the lane's territory. Without a farm, this guard is your own review:
  before you assemble, compare each lane's changed files with its declared
  paths.
- Each lane commits under its own author name, so the assembled history shows
  whose slice each commit is.
- **A merge conflict during assembly is the collision detector, not an error to
  fix.** Assembly stops, names the colliding files and lanes, and never
  resolves the conflict itself. Lanes with disjoint paths merge cleanly. Run
  the assembly with `--dry-run` first, to see the merge order and each lane's
  files.
- **A clean automatic merge can still lose work.** When two parents changed
  the same file, diff the merge against both parents and confirm that each
  named change survived, before you trust a green check run.

## 9. What every report must contain

Handing work out is only worth it if you can trust the results. Put these
rules in every worker and subagent prompt, and refuse a report that does not
follow them.

For each finding, require:

- **Severity.**
- **`file:line`.**
- **A concrete failure scenario**, with concrete inputs.
- **Confirmed or plausible**: confirmed means the path was traced; plausible
  means it still needs proof at run time.
- **What was checked and found correct.** A report that lists only defects
  usually means the worker stopped reading, and <OWNER> needs the assurance as
  much as the list of defects.

Then do your own part:

- **Verify the claims that matter against the real thing, not against more
  code.** Read the installed dependency, query the live system, run the test.
  Two reports can sound equally sure and still disagree. Never pass on the
  claim that tests pass: run them.
- **Split investigations by area, not by type of task.** Several narrow ones
  beat one broad one: they run at the same time, and each stays inside a
  context it can hold.
- **Ask for tables.** Dense, structured output costs less context and is
  faster to check than prose.
- **Never let one agent both find and fix** when the finding needs a ruling
  from <OWNER>: finding and fixing need different approvals.

## 10. Landing work

- **Green checks make a change eligible to merge. Only <OWNER>'s explicit
  signal merges it, and auto-merge is switched on only after that signal.**
  For a visual or behavioral change, the signal comes after real evidence
  exists, never after green checks alone.
- **Who merges.** After <OWNER>'s yes, the conductor merges, if one runs.
  Otherwise you do. Lanes never merge.
- Where the main branch deploys on merge, a merge is a production deployment.
  During a wave of lanes, watch production directly: checks can be green while
  production breaks.
- Spread out landings that run heavy checks. Many lanes at once can overload
  the CI runners and cause timeouts that look like flaky tests.
- Order the merges yourself when two lanes touch a shared file or interface,
  and update the later branch from the base branch first.

## 11. The sweep

A farm runs a sweep: `fleet sweep`, which `fleet autosweep` runs every ten
minutes by default. It never touches a live lane or a lane with an open pull
request. It removes the worktree of a lane that has finished with no open pull
request, and clears the lane from the dashboard. Commits that were never
pushed are first pushed to a hidden ref (`refs/fleet-salvage/<slug>`). Without
a farm nothing sweeps for you, but the rule below still holds: work that is
not committed and pushed exists on one machine only.

- **Only committed and pushed work is safe.** An open pull request keeps a
  worktree. Uncommitted changes keep it too, until someone runs
  `fleet sweep --force`, which archives them first. Files that git ignores are
  not kept at all.
- **Put results where people read them.** Lasting output goes to the pull
  request, the issue or the report, never only into a worktree. Before you
  assume something is still there, check what the next sweep would remove:
  `fleet sweep --dry-run`.

## 12. Reporting to <OWNER>

- **Give your opinion before you ask.** Every decision question carries a
  short, self-contained comparison with your recommendation above it. "Which do
  you prefer?" wastes a turn.
- **Batch decisions.** <OWNER> is often away, and a question in the middle of
  the work blocks it. Collect the decisions you need and present them together.
- **Lead with the outcome**, then the evidence. <OWNER> did not watch you work.
- **Lasting documents record only what was agreed.** Discuss first, then write
  down the decision. Never park undiscussed items in a plan.
- **Never hand over raw worker output.** Read it, verify it, summarize it.
- Track the work in <TRACKER>, not in chat: the status moves with the work, and
  acceptance evidence goes on the issue.