orchestration

name

orchestration

description

Run delegated work reliably — writing subagent charters, verifying subagent claims, keeping judgment at the orchestrator tier, ledger discipline, recovering from interruptions, and shipping/merging lane PRs. Use when spawning subagents or workflows, coordinating parallel lanes, resuming after a session limit or compaction, or rebasing and merging a lane's PR. The subagents skill covers task sizing and model choice; this skill covers everything after the spawn.

Orchestration

Delegation only works when the orchestrator treats every subagent claim as unverified and every judgment call as its own. These rules were each paid for by a real incident.

Charters

A charter is the task prompt a subagent receives. Requirements:

• Reference every document by absolute path, and only paths that live in the repository — repo skills under .claude/skills/, repo scripts behind their package commands. A relative path resolves differently (or not at all) in the agent's working directory, and a personal home-directory path can vanish out from under a live agent: ~/.claude/skills was deleted mid-goal to end personal/project skill drift, leaving in-flight charters instructing agents to sweep browsers from a path that no longer existed while the repo's own pnpm run browser:sweep was the live command.
• When parallel lanes could touch the same module, name the sibling lanes and give each an explicit do-not-touch list of files/functions the others own. For genuinely shared append-only files (routes config, nav layout, seeds), say up front that rebase conflicts there resolve keep-both. A fence names artifact classes as well as files — E2E specs, docs articles, and seed sections are the verification stage's territory — because a file-level list cannot fence a file that does not exist yet, and a build stage drifted into writing the spec its verification stage owned.
• Assign each subagent an explicit scratch-file namespace — its lane or task name as a filename prefix — and forbid it from writing any shared scratchpad file, above all the orchestrator's LEDGER.md. Parallel agents that share a scratch filename clobber each other's state, and a fix agent that writes its own notes over the session ledger destroys the orchestrator's recovery record.
• Include a stop-on-contradiction clause: if the charter's factual premise (a claimed bug, a claimed missing feature, a spec citation) doesn't survive verification against the primary source, the agent halts that item and reports with citations instead of inventing. "Verified already correct, no change made" is a valid, expected outcome. Charter-supplied names — slugs, titles, feature labels — fall under the same clause: an agent that discovers the real feature differs from the charter's name must correct the name and flag it, not ship correct content under a stale identifier.
• When two reference sources disagree, the charter names the conflict for adjudication — it never silently picks one. A charter's factual claims are no more trustworthy than a builder's until verified.
• A charter or goal text that enumerates a derivable structure — a dependency graph, a consumer list, a coverage set — instructs the agent to re-derive the complete set from primary sources and treat the enumeration as examples to check against, never as the whole set. Stop-on-contradiction cannot catch an incomplete list: nothing contradicts it, so its gaps ship. A five-edge dependency graph hand-written into a goal text was encoded verbatim as a registry's whole truth, and the guard built on it approved variants that then died mid-transaction on a generic error.
• A charter for any agent that publishes text — an issue, a PR body, review comments — forbids personal data from customer datasets (names, emails) in the published artifact unless strictly necessary, and the orchestrator scans the artifact for it before shipping. A dump-sourced operator email once shipped inside a published investigation issue and had to be redacted after the fact.
• Instruct agents to run slow verification commands (build, tsc, tests) synchronously in the foreground, and to deliver their full final report as their last message — never to end the turn "waiting on CI" or any background process. An agent that backgrounds a check and ends its turn waiting on a notification is terminally stalled — its turn ending is final, and a lane that signed off with "clean, waiting on CI" had to be resumed just to extract the report it never sent. An agent never polls a process it backgrounded either — one foreground wait, or hand the wait up. Machine-level waits (a Docker image pull, an environment stall) belong to the orchestrator, who takes them over machine-side while the agent proceeds; repeated "check the state" turns have eaten a whole stage's context window.
• Write each new charter/script fresh with the Write tool. Deriving one by programmatically splicing a previous one introduces silent syntax errors.
• A parameterized script must parse args defensively (string-or-object) and hard-throw on any missing required field — a silently-undefined interpolation produces a plausible-looking empty result that reads as a clean pass.
• A multi-stage script carries its charter discipline in the shared preamble from the first draft — commit at every milestone, read targeted ranges instead of whole generated files — never patched into one stage after a failure exposes the gap. A stage whose preamble lacked it was stopped at its context threshold with zero commits and eleven uncommitted files; the sibling stage that carried it landed five milestone commits over a comparable span.
• Every build charter carries a classify-the-disk-state-first preamble from its first draft: before building anything, read git status and git log in the lane's worktree, classify every commit and dirty file as done, partial, or untouched, verify-don't-redo whatever is already correct, and run worktree:setup only when the lane's worktree does not exist. A workflow auto-retries a dead agent straight back into the same worktree, so half-finished work on disk is a normal starting state rather than an exception. An API-level event killed a four-lane wave whose charters said only "run worktree:setup if the worktree does not exist yet"; the retries landed in worktrees holding three to five commits and dirty trees apiece and classified them only on their own initiative, and the preamble had to be patched in at relaunch.
• A slice that ships a route, loader, or form must drive that surface live at least once — a minimal browser interaction or a real-Request smoke — before handoff. A unit-only exit bar passes code whose query crashes at runtime or whose form cannot submit (a select with no name attribute).
• A live proof binds only the commits that preceded it. Sequence the browser walkthrough as the charter's last step, after the final commit, and redo it after any later change to the proven surface — a proof that predates a schema or handler commit is evidence of nothing, and a redone proof regularly catches what the suite missed (a coercion regression, a state-update race). The same binding governs specs across stage boundaries: a later stage can invalidate a spec an earlier stage wrote, so the verification stage re-runs every one of the lane's specs after the last build commit — a refusal spec asserting one stage's toast went red the moment the next stage reshaped that refusal, and nothing had re-run across the boundary.
• A skeptic or verifier charter carries TWO acceptance rubrics, not one: a finding stands if either (a) its concrete-input failure scenario occurs at runtime, or (b) it identifies a violation of a codified house rule or doctrine in the work under review. A runtime-only rubric refutes correct doctrine findings — a migration that models a reversible toggle as one action-enum table where the database-design skill prescribes paired event tables — exactly when the fix is cheapest. Doctrine findings against unmerged schema or shape default to fix-now, because schema shapes are effectively permanent once merged.

Verify, never trust

• Re-run the gates yourself before advancing any stage on a subagent's self-report.
• Reconcile numbers exactly: baseline + computed delta = measured, and identical across two runs. A mismatch is a hard stop, not noise.
• A task counts as launched only when its task/run id from the tool result is in the ledger. A written script or a narrated intent is not a running task. Copy every id out of the returned tool result — never from memory or prediction; when a launch and its ledger entry go out in one parallel call, write TBD and fill it in after the result returns. An id written in the same message that launched the task is a prediction, and twice it was wrong.
• Independent lanes launch simultaneously, never in staggered waves. Host contention (CPU, database) slows every lane's gates but never justifies holding a lane back — an idle lane costs more than a slow gate.
• A review or QA returning zero findings is only a clean pass if its agents all completed. Errored finders, an implausibly fast run, or a wrong agent count mean the run is broken — relaunch it.
• Findings about uncommitted working-tree state from a parallel review fan-out are suspect: when finders share one worktree, one finder's in-flight mutation-proof — code deliberately broken to validate a test, then restored — is visible to its siblings and reports as a phantom defect. Verify any working-tree observation against the commit under review (git show HEAD:file), and either require finders to mutation-prove only against committed state and restore immediately, or discount working-tree-only observations at the verify stage.
• Independently probe a shipping agent's claimed git state (git merge-base <lane> origin/main vs origin/main's tip) before merging. Verify mechanical batch edits landed by grepping the expected before/after state, not by exit code.
• A mutation test must sabotage the transformation under test, never the input it reads. When a gate re-derives both sides of its comparison from the same source — a parser diffed against its own re-parse — mutating the source leaves both sides agreeing and the gate green, proving nothing; break the transformation (drop a word inside the parser) and watch every output fail. A wrong-sided mutation test once read as a proven gate when it had exercised nothing.
• Before treating a probe's mismatch as a finding, validate the probe itself against a known-good case — a fidelity spot-check once "failed" solely because the probe's own text flattening left timing lines interleaved with the prose it matched against. And prefer the dumbest direct check over a clever detector: an n-gram loop detector reported zero loops on a file whose raw line counts (sort | uniq -c) showed one line repeated 1,691 times.
• The orchestrator's PR review reads every line of the diff against the binding doctrine of the surfaces it touches — a shaped project's document contracts, the reference implementations it names, and the repo's codified skills — regardless of what the PR body flags. The author's flag is never the safeguard: a page-wide raw-fetch store with bespoke retry and revalidation machinery shipped through review while the shaping document prescribed inheriting the framework's own submission machinery, because everyone read only what the body mentioned — the departure sat unflagged in plain sight in the diff. A goal is never met while its implementation contradicts its shaping document, and conformance is checked at every PR, not discovered at goal close.

Judgment stays at the top

• Never trade the mainline for an edge case: a fix whose cost lands on the bulk of use cases to close a rare corner is the wrong shape, however clean the mechanism looks. Accept the residual and record it, or scope the mitigation to the edge itself. Shipping the full route manifest up front (routeDiscovery: 'initial') to close one offline corner — a submit to a never-visited write route — was denied for exactly this: it reverses lazy route discovery, which exists because full manifests scale badly, and charges every session to fix a case almost nobody hits.
• Every demand gets an architecture round before any delegation: zoom out and map the mechanism behind the ask, where else that mechanism lives, and the repercussions of candidate fixes — then design at the level the root cause lives. A defect surfacing in one route but rooted in a shared primitive gets the primitive fixed, never a route-local workaround; a batch of demands gets grouped by mechanism, not by surface, before lanes are cut. Zoom in only with full domain over the systemic impact. A route-local patch of a polling defect owned by a framework hook would have left the same bug live in fifteen sibling routes; fixing the hook also surfaced a second latent defect in it.
• A stakeholder's demand names what they see. Before designing or interviewing against it, translate every term through the navigation the requester actually uses (app/routes/app/nav.ts), never through internal section, module, or schema names — an analysis framed on internals reads as wrong to the user even when technically coherent, and one design interview had to be restarted after the user caught the frame ("recipes" meant the Production menu's entry, not the seed section).
• Answer any question about repo machinery only after reading the primary source completely: every file in .github/workflows/ before stating what CI does — one check name can live in two workflows, a per-PR job and a scheduled twin — and real run history (gh run list) before stating what a job costs in time, since a job's timeout is a ceiling and never an estimate. When the user's question hints that something is missing, it is a diligence probe, not a request for a guess: assemble the complete factual picture from the sources, then answer once. Seven consecutive user messages on one thread went into forcing a workflow-file read that should have preceded the first answer, every probe meeting a fresh inference instead — and in delegated work nobody is there to supply that correction.
• Design and adjudication are orchestrator-tier work. When the evidence under a design changes (stale reference, corrected spec), redo the design at the orchestrator tier — never hand the stale design down with a "re-verify your citations" instruction.
• Synthesizing a multi-agent review's findings into an adjudicated register is itself adjudication, not mechanical distillation. Read every report yourself and build the register personally — a synthesis delegated to a subagent launders the miners' claims into rulings nobody made, and the fix program built on it inherits judgments the orchestrator never exercised.

Ledger discipline

• Structure the ledger as a STANDING DIRECTIVES head (settled policy, kept current) plus a chronological log. Reground after compaction from the head AND the tail — a tail-only reground lets settled directives fade.
• The ledger keeps exactly one live head. When a new head goes in, move the superseded one to an archive file beside the ledger instead of stacking it below — stacked dead heads push the file past what a single read returns and tax every reground with prose no longer true. One goal's ledger reached ~390KB carrying eleven stacked superseded heads, and by the end every update to it needed byte-offset reads and count-asserted scripted edits.
• Record launches with their task/run ids, lanes with their base commits, and verdicts with their evidence.
• When a long effort concludes, externalize the durable record (decisions, divergences, audit results) to a permanent artifact — a GitHub issue or PR body — before the scratchpad is cleaned up.

Recovery after an interruption

Step 0 is always to positively enumerate what is alive (task list, workflow roster) — a missing state file or empty output file usually means still-running, not dead. Declaring a live task dead and relaunching into its worktree corrupts both. Then, for tasks with positive evidence of death:

• Audit the worktree first: git status/git log. Clean tree at a known commit → relaunch the charter unedited. Dirty tree → launch a continuation agent on the same worktree whose first step is diffing working tree vs last commit to classify done/partial/untouched, then finishing — never a blind restart. A continuation charter lists the remainder and says explicitly that when the listed remainder is done, STOP: a continuation that finishes early otherwise runs on into the next stage's ground, and one built two of a later stage's commits plus a half-written file nobody had chartered.
• Audit the remote before writing any continuation charter: git ls-remote for the lane's branch and gh pr list --head <branch> for its PR. A dead agent may have finished — one continuation was chartered on a "nothing pushed" premise while the original agent's PR was already open with green CI, and the charter sent the new agent to redo completed work.
• A QA agent killed mid-mutation-proof can leave deliberately broken code on disk — check for a live mutation before anything else runs there.
• An agent that is still addressable resumes by message from its last checkpoint, keeping its context, instead of restarting cold — but NEVER message an agent a live workflow still owns. The message forks the transcript into two live instances sharing one worktree: each sees the other's edits as a foreign actor's, and one fork's honorable stop can strand half the work. Deliver mid-flight course corrections to a workflow-owned agent only through the workflow (edit the script and resume the run), or wait for the run to end and relaunch with an amended charter.
• Probe returned capacity by attempting real work. Never idle-wait.

Shipping and merging a lane

• Write every PR title and description for an external reader: someone with zero knowledge of the execution that produced the change must understand what it is and why it matters. No orchestration vocabulary (goals, lanes, charters, sanctioned allowances, finder/verifier counts, workspace skills or tooling-repo names), and no superseded project state — describe what the change IS in the product's own terms, and rewrite the body as the work evolves so it always reads as current truth, not history.
• When the user shares another organization's work (a PR, a repo, a pattern) as the model for a change here, that source never appears in anything visible in this repo — PR bodies, commit messages, code, comments, or issues. Describe the change entirely on its own terms; the reference lives only in the conversation.
• Merge PRs with a merge commit (gh pr merge --merge) — the repo's convention. Never squash or rebase-merge.
• Never chain the merge with branch or worktree teardown. A merge can be rejected transiently (after a force-push, GitHub recomputes mergeability for ~30s and gh pr merge fails with "not mergeable"), and a chained cleanup then runs anyway — deleting the remote branch auto-closes the open PR. Merge, confirm the merged state with a fresh read, then tear down, each step checked. If a branch deletion does close a PR, the commits survive at pull/<n>/head: restore the branch (or repush the surviving local one), gh pr reopen, and merge properly.
• Before every teardown, positively enumerate the live-agent roster and confirm none is pointed at that worktree. Read-only scouts and auditors carry worktree paths in their charters and leave no trace in the lane's own PR state, so a merged-and-shipped lane is not evidence its worktree is free — one had to be restored mid-flight as a plain checkout because a live agent's charter cited the path.
• The repo requires a PR's head branch to be up to date with its base before merging. When gh pr merge is rejected with "the head branch is not up to date", run gh pr update-branch <n>, wait for the new check run to register (~45s), watch it, then take a fresh gh pr checks read and merge on that.
• Verify a large PR's scope with git diff --stat against the merge base — gh pr view --json files silently caps at 100 files, and a scope check that only sees the first 100 blesses whatever hides past the cap.
• Before rebasing, predict the conflict surface: intersect the lane's touched files with what main gained since the lane's base. Empty intersection → expect a clean rebase; non-empty → you know exactly which files need care.
• On a non-empty intersection, a conflict-free rebase is not evidence of correctness. Git auto-merges a lane's hunks around a sibling's rewrite of the same function, leaving code that references symbols the lane deleted — and the lane's analysis, written against pre-merge main, can assert facts the sibling has since made false. Re-derive the lane's claims about the intersecting files against post-merge main, and resolve the rebase semantically — take the sibling's merged shape as authoritative and re-apply the lane's intent on top — never by accepting whatever auto-merge produced.