Orchestrator

orchestrator

You hold the goal set, own the durable record, and dispatch sub-agents to execute pieces — reviewing, steering, spot-checking, integrating. The patterns below are different shapes of that one job; pick by the work's dependency structure, not by habit.

Not a board of independent efforts. Here every piece belongs to ONE goal. It reuses whatever machinery your harness already gives you — dispatch profiles, sub-agent messaging, worktrees, a merge queue — rather than defining its own.

Only a top-level session orchestrates. If you are yourself a dispatched sub-agent, you are one of the pieces, not the holder of the goal set — the repo-wide depth cap in AGENTS.local.md applies and you do not dispatch. Execute your scoped task inline and return; if it turns out to be a whole campaign, say so in your return and let your dispatcher run it.

The record you own

One living doc is the effort — goals, architecture, resolved ambiguities with rationale, the to-do, status. Keep it behavior-level; a symbol-pinned to-do rots. Sub-agents get scoped tasks and do not edit it; you reflect each landed piece yourself. (They still merge scoped progress into the thread's own scratch notes — that is the standing exception.)

DIRECTION FROM THE HUMAN GOES INTO THE RECORD IN THE SAME TURN IT ARRIVES. Conversational memory is not a record: it dies at the next compaction and you revert to instinct. Measured — "stop chasing root causes, just grant what they need" was given, acted on for one turn, never written down, and reverted to within hours.

§0 CANON — a persistent, non-editable core at the top

A long effort buries load-bearing direction under accreted findings, and compaction loses it. Give the doc a §0 — CANON section, marked persistent and non-editable.

• In it: the vision only — which products exist and how they differ, non-negotiable properties, the decided mechanism per platform and the requirement that selected it, banned patterns and why, standing invariants, the definition of done. ~100 lines; too long to re-read every cycle means it will not be re-read.
• Not in it: findings, measurements, status, to-dos, history.
• State these rules inside the section so they outlive this skill: nothing in §0 changes except on explicit human instruction; if anything below contradicts §0, §0 wins; re-read §0 after every compaction and before every dispatch; a dispatch prompt whose premise contradicts §0 is a defect in the prompt, not a decision.

The tell you have lost canon: you are about to state something about the design and your confidence comes from recall rather than from having just read it.

Pick the pattern

The rule that decides most of it: EDITS ARE CHEAP AND PARALLELISE; BUILDS ARE EXPENSIVE AND DO NOT. N concurrent builds contend for CPU, disk, and cargo's target lock. Measured here: seven concurrent target dirs drove load to 104 on a 10-core box and one build died No space left on device; separately, lanes each building their own target took free disk from 42 GiB to 14 GiB in an afternoon. Every lane got slower, including the "parallel" ones.

Serialize only the final assembly, never the editing. The file tools reject stale edits, so concurrent edits to one worktree do not silently clobber. What collides is BUILDING (one target lock) and raw destructive git ops (reset/checkout/stash), which no batch agent should run.

The phased batch, in full

1. EDIT (parallel). N agents, one worktree, disjoint file sets. Every prompt carries, in these words or better:

   This is an edit-only phase. Do NOT build, do NOT test, do NOT run cargo at all — not even to check your work. Other agents are editing this same worktree and I run a single shared build after everyone finishes. Concurrent cargo invocations serialise on one target lock, so each of you would wait for the others. Make your edits, make them careful, and stop. Report the files you touched.

   Say why, not just what — a diligent agent builds "just to be sure" unless it understands the cost. The ban is on the target lock: rustfmt --check and anything avoiding cargo is fine.

   • Assign file ownership explicitly; tell each agent to stop and report rather than touching anything outside its own files.
   • You are one of the editors — do not dispatch into a worktree you are editing yourself.
   • Never git add -A in a shared tree — stage only your own paths, or a mid-edit sweep commits another agent's half-written files under your message.
   • Keep the file→agent map. You need it in phase 3.

2. BARRIER. A half-applied tree produces failures that belong to nobody. If an agent dies mid-edit, resume it with SendMessage — its partial work is in the worktree and its reasoning is in its transcript. Run cargo fmt yourself here.

3. BUILD (once, yours). Default to remote-build — an ephemeral GCE spot VM runs the byte-identical CI invocation for cents, and takes the load off the host entirely; a local heavy gate is the exception and needs a reason. Read the tool's own exit code; cargo … ; echo EXIT=$? ; tail makes the shell exit 0 regardless. Gate on what the batch touched: NUB_ALLOW_INCOMPLETE_RUNTIME=1 clippy --all-targets --all-features (a scoped -p without --all-targets misses test-code lints; the env var is what CI's clippy job sets, since --all-features otherwise panics on an incompletely staged runtime/); cd vendor/aube && cargo check --workspace --all-targets with its own target dir if anything reaches aube (a dependent's --all-targets never builds a path dependency's test targets, and that gap has let a broken merge through); cargo check -p <crate> --target x86_64-pc-windows-gnu for cfg(windows) code, confirming from the log that the crate compiled for that target. Read rust-build — clippy and cargo test run on different profiles, so "one build" is two artifact universes, and neither leaves a runnable binary. Triage failures against the phase-1 file map; an error spanning two agents' files is a real interface disagreement — resume BOTH.

4. VERIFY (parallel, warm-resumed). Verification means running the built binary and must stay compilation-free. cargo test and cargo clippy are BUILDS. Give each agent the binary's path and a real fixture per ad-hoc-test, and say cargo is yours. If a change can only be proven by a Rust unit test, that test is an EDIT — written in phase 1. Re-steer the SAME agents, never fresh ones: the agent that wrote the change knows what it rejected and where the risk sits.

Coverage campaigns — the failure that kills them

When the job is to COVER a population (measure N packages, audit N files, migrate N call sites), the thing that kills it is not difficulty. Each unit of coverage surfaces something interesting, and interesting things get investigated. Measured: 20 commits landed after a coverage-measuring harness was built and 2 of them added coverage — the other 18 went to mechanisms, schemas, docs and controls, every one individually defensible.

• A FINDING NEVER GETS A LANE. It gets an entry in whatever the campaign produces — a catalog row, a fix, a backlog line — and you move on. Lanes are for coverage. Two exceptions: work that UNBLOCKS coverage (the harness cannot run on a platform), and a case whose failure indicts the tool rather than the subject.
• Before dispatching anything, name the coverage number it moves. No number, no lane.
• Track that number where you will see it and report it FIRST. If it did not move since the last check-in, that is the headline — not what was discovered.
• Build the terminal fallback EARLY. Where every unit can end with a known-good disposition (grant the whole disk, mark unsupported, accept the default), no finding requires investigation. It converts "this one is strange" from a research prompt into a one-line disposition, and it is what lets a campaign actually finish.

The loop

1. Read the record — reload the goal set and dependency structure.
2. Pick the next piece(s). Judge serialize-vs-parallelize by the dependency structure at this moment: foundational/shared-surface work serializes, disjoint pieces parallelize. No hardcoded concurrency — making that call well is the whole point.
3. Dispatch scoped sub-agents, tiered to the right model/effort, with four standing instructions in every prompt:
   • run the quality loop: build → ad-hoc fixture test → adversarially probe → distill durable checks into committed tests;
   • pause and surface real ambiguity upward rather than guessing on a genuine fork;
   • comments sparse + dense; name any skill it must load (prose-writing, impact-analysis, ad-hoc-test, remote-build — skills are NOT inherited), and say that heavy builds/tests and Linux-answerable fixture sweeps default to the VM (remote-build; --job adhoc for fixture scripts);
   • run builds/tests/waits in the FOREGROUND to completion — never background-a-build-and-rest. A rested agent is not reliably re-woken by its own background task, so it strands itself with work uncommitted.
4. Review every return like you mean it. A sub-agent's "done" is a claim to verify — spot-check it. If work is incomplete, stubbed or off-goal, warm-resume and re-steer rather than accepting it.
5. Facts you assert in a dispatch prompt need the same grounding as facts you tell the human. A fresh-context agent cannot tell a checked claim from a remembered one and will act on both.
6. Update the record and repeat.