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 package's own sweep command was the live one.
• When the work depends on an external spec or vendor document, fetch it raw — curl or a real browser, never a summarizing fetch — into a scratchpad cache file, and name that cache path in every dependent charter. All lanes then build from identical bytes; left to fetch it themselves, each agent works from its own paraphrase and the lanes drift apart on the contract they were supposed to share.
• 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. Before launching, check each item's designed fix against its lane's do-not-touch list: an item whose only defensible fix lives in a sibling-owned file moves to the lane that owns the file, or gets an explicit carve-out — left as is, the builder must choose between skipping the item and violating the boundary, and one wave produced a skipped item, a banked residual, and a flagged two-file deviation from exactly this.
• At most one repo-mutating agent per worktree at a time, and an agent that verifies against a builder's live worktree is read-only toward it. A concurrent sibling's git add/commit sweeps the other agent's half-finished files into an unrelated commit, and untangling that means rewriting the branch tip.
• When parallel lanes allocate from a shared identifier pool — seed namespace prefixes, fixture ids, ports, queue names — the orchestrator publishes one canon allocation table in every lane's charter before the first launch, and each lane sub-partitions its allotment across its own flows. Lanes that pick identifiers independently collide, and the collisions surface as another lane's spec failing long after both lanes went green in isolation; one wave shipped three separate collisions (two lanes sharing a phone prefix, two sharing a fixture id, one lane colliding with itself) before the table became standing practice.
• When several lanes will each touch a shared computed constant — a contract fingerprint, a generated schema hash — every charter declares the same resolution protocol up front: on rebase, recompute the value by the mechanism that owns it (its own test's computation), never keep-mine or keep-theirs. Three parallel lanes once rewrote the same fingerprint off stale bases, and every merge needed a hand repin. Each charter also declares whether its own items are expected to move the constant; an unexpected movement is a stop condition to report, never a silent repin — a lane that repins a public contract hash it had no business moving ships the change invisibly under a green suite.
• 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 session ledger, whose actual path the charter must give since it is named for the effort rather than by a fixed convention. 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. The clause covers the charter's designed fix shape and its measured file:line anchors, not only the finding: sibling merges stale both between charter-writing and execution, so a builder that re-verifies the design against its own worktree and deviates with citations is complying — the deviation is adjudicated at merge, never treated as disobedience. 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.
• A charter names the repo's committed engineering conventions (absolute path in the lane's worktree) and instructs the agent to read them before coding and to treat them as binding, naming the repo's designated reference implementation where one exists; a reviewer or skeptic charter names the same conventions as the codified-house-rule source for rubric (b) below. A charter that writes or reshapes tests also names the repo's committed testing doctrine as binding and does not prescribe a test mechanic itself — a charter once offered a patch-based interleave that doctrine forbids, and only the builder's own diligence avoided shipping it.
• A charter that includes a mutation proof (deliberately breaking code to show a test goes red) also specifies the restore protocol: restore byte-identically, verify via git status/git diff, and purge compiled-artifact caches (stale bytecode and the like) under the touched packages — a same-size restore within the same mtime second leaves stale build artifacts that quietly poison every later run in that tree.
• 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.
• Builders never run long gates. A charter ends at commit (or commit + push) and STOP, with only scoped foreground checks before it (the touched module's tests, lint) — "run the full suite in the foreground" does not survive contact with builders: they background it and end their turn terminally stalled, because a workflow agent's turn ending is final. The orchestrator runs full gates itself as its own background shell (its re-invocation on completion costs nothing) and owns push/PR/merge when the charter stops at commit.
• Instruct every agent to deliver its full final report as its last message — never to end the turn "waiting on CI" or any background process: 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 on a scoped check, or hand the wait up. Machine-level waits (a container 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.
• Address every SendMessage by looking up the recipient's task id in the ledger head at send time, never from memory. A charter delivered to the wrong lane's agent reads as an order to abandon its own work and take over another lane's, and only the recipient's own do-not-touch clauses stand between that misdelivery and a corrupted worktree.
• 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 seasoned-skills provision 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 "provision 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.
• Relay a finding at exactly the scope it was measured. "These two named tests survive the mutation" is not "the suite survives the mutation"; widening it on the way into a charter sends the agent to disprove a claim nobody made, and its correction can bury the narrower gap that was real. Quote the finding's own boundary, and mark anything you extrapolated as yours to verify.
• Cross-check a charter's exit assertions against its own items before launching: an exit gate demanding a file show no diff contradicts another item that edits the same file, leaving the agent to choose between violating the gate and dropping the item. Scope byte-identity checks to the exact lines or symbols they protect, never to whole files other items touch.
• 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 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 — an ad hoc query fragment inlined in a view where the repo's committed conventions prescribe a model-owned query method — 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.
• A completeness claim — "every route covered", "every call site migrated", "every consumer updated" — is only checkable against a denominator derived live from the system of record (the URL resolver, the schema, a repo-wide census), never against the plan that produced the work: the plan omits exactly what the work omitted. Establish the denominator before declaring any "every X" objective met, and prefer a gate that recomputes it and fails on drift over a registered list or document describing coverage — registered state duplicates the system and goes stale silently.
• Reconcile numbers exactly: baseline + computed delta = measured, and identical across two runs. A mismatch is a hard stop, not noise. A collect-only reconciliation carries one extra term: registry-parametrized suites expand on their own whenever the registry they parametrize over grows, so account for that expansion before reading a collect-count jump as drift.
• Reconcile a builder's charter item by item against its diff, not only by counts: every charter item ends in exactly one visible state — implemented in the diff, verified-already-correct, or an explicitly reported skip. Builders silently drop items, and numeric reconciliation cannot catch an item whose omission changes no counts (a test reshape, a mechanical conversion) — one such drop shipped unnoticed and only surfaced in a later personal read of the merged diff.
• Reconcile the adjudicated rulings against the union of the lane charters before the wave launches: every ruled fix appears in exactly one lane's items. Orchestrators drop whole rulings the same way builders drop charter items — three ruled fixes once reached no lane at all, caught only by a ruling-by-ruling reconciliation during the final write-up.
• A charter's expected gate numbers are measured on the current base tip at charter-writing time, never carried forward from per-lane history — every sibling merge stales them. When lanes have merged since the last measurement, re-measure the union before chartering anything that asserts a count.
• 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.
• Never block on a running subagent or workflow — a synchronous wait for its output freezes the conversation until the agent finishes, so the user can neither interject nor redirect, and the user has had to interrupt one to say so. Launch in the background, keep the chat free for whatever else is pending, and act when the completion notification arrives. When the harness's task registration is uncertain (after a compaction), arm a background watcher on the task's own artifacts rather than polling in the foreground.

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 (the app's committed nav definition), 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 (the demand's word named a navigation menu entry, not the internal seed section it also matched).
• 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.

Browser and process hygiene

• Every agent that drives a browser ends with its browser session closed, and the orchestrator verifies it — a successful close, or an agent's report that it closed its session, is not evidence that the processes died; only a process listing is. After each browser agent completes, and again between waves, sweep to zero with the shipped command:

  seasoned-skills sweep --browsers          # list survivors with their ages; exits 1 if any are alive
  seasoned-skills sweep --browsers --kill   # kill each survivor by its exact pid, then re-list to prove it
  

• A gate that turns flaky while browser work is in flight is a leak suspect before it is a product bug.

• Every process a lane needs beyond a single turn — a development server, a worker — runs as its own harness background task, never forked with & inside another task's shell; the orchestrator's own long gate runs follow the same rule. Every lane process is swept at session end, and the same sweep is runnable by hand at any time.

• Judge leakage by process count and age, never by reported RSS — paged-out memory hides an order of magnitude (7.6GB visible while roughly 80GB was actually held).

• Leakage comes from sessions accumulating across sequential waves, not from parallel width. Keep lanes parallel; the invariant is verified teardown, not a concurrency cap.

• Kills are the sweep's job precisely because it kills by exact pid after listing what is about to die. Never reach for a pattern kill (pkill -f and relatives) as cleanup or as verification — a pattern that reads as lane-scoped can match unrelated long-running processes on the host, and listing the pids is the inspection step a pattern kill skips. Every kill goes through the shipped sweep, which enforces the rule.

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. Reground with bounded reads — the head block, then targeted slices — never by reading the whole file: a mature ledger runs hundreds of kilobytes, and one full read consumed enough context to force an immediate re-compaction.
• 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. The harness task list can come back empty after a compaction or a host sleep while the underlying shells still run: ps for the actual processes and check whether their log files are still growing before declaring anything 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

• A PR opens as a draft the moment the fast gates pass — so CI overlaps with local verification — and flips to ready for review only after the full pre-merge pipeline completes: builder claims verified, full gates green, the adversarial review run against the draft (it reads the PR's description and discussion alongside the diff, which a bare diff review never sees), and an orchestrator ruling on every confirmed finding. Small diffs are not exempt from the pipeline; they simply overlap it — momentum after green gates is exactly when the review step gets dropped, and on a three-line security fix the almost-skipped review was the one that surfaced a fourth same-class vulnerability.
• 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.
• An umbrella PR's body is a deliverable, not a tracker. While work is landing it may be organized around progress, but the effort is not done — and a goal is not met — until the body is rewritten to read as finished: no tracking framing ("Landed", "updated as areas land", in-flight lists), and no links to the internal PRs that built the branch — sub-PR references are noise to an external reader, who needs the result described, not the delivery.
• When a PR whose title promises no behavior change (test, docs, chore types) actually changes production behavior, the title must say so and the body must lead with a complete list of every behavior change — readers won't expect behavior in that diff. Enumerate the list from the real base-to-tip diff of non-test paths, never from memory of the work.
• A defect fix described only by its new behavior reads as housekeeping. Each behavior-change entry states the problem first — what broke, under what conditions, with what consequence — and then the fix, so its real weight is legible: "event ingestion is idempotent" hides that a routine queue redelivery permanently broke a paying customer's reporting. Write the consequence in the product's terms, not the schema's.
• A before/after contrast in a PR body ("no longer", "used to", "restored", "remains") is only tellable against the PR's base: if the base itself carries the old behavior, the contrast describes the change; if the branch introduced the surface, the contrast narrates the branch's own development history, which the reader never saw — state current truth only. Check each such phrase against the base, not against memory of how the work went. A refute pass does not catch this class on its own — fact-checkers verify claims as stated and confirm a contrast that is factually true but tells internal history — so make base-tellability its own explicit rubric item in any refute pass over a body.

Where lessons go

Project-empirical lessons about this skill land in workflow-content/orchestration.md through a pull request on the project — never by editing this file, which is regenerated on every upgrade. A lesson that turns out to be true of every project travels as an issue on the workflow package instead.