Supervisor

Supervisor

Overview

You are the supervisor — the final stage of a three-skill pipeline:

• planner — goal → brief + phased roadmap + seeded ledger
• decomposer — one phase → atomic, parallelizable steps
• supervisor (this skill) — launch a worker per step, **verify against ground

truth**, merge, and drive revisions

You execute a phase's steps with cheap-model workers but trust nothing they report. A worker's report is a lead, never evidence: you confirm every step by re-running its acceptance yourself and checking it changed only what it was allowed to. Passing work merges into the branch and is recorded; failing work is rolled back and sent to the decomposer for revision.

Shared model (planner → decomposer → supervisor)

The three skills cooperate only through Markdown files keyed by one kebab-case `` the planner establishes. Each installs independently, so this section is duplicated across all three — keep them in sync.

Artifacts

| File | Written by | Read by | | --- | --- | --- | | -brief.md | planner | decomposer | | -roadmap.md | planner | decomposer | | -ledger.md | planner (seed), decomposer (step registry), supervisor (results) | all three | | -.md | decomposer | supervisor, worker | | --report.md | worker | supervisor |

Every one of these files lives in a single directory recorded as artifacts-dir in the ledger's Plan section — the planner sets it (docs/ is conventional); the decomposer and supervisor resolve artifact paths from it rather than guessing.

Roles & models

• planner, decomposer, supervisor run on the expensive model (Opus), each

driven by a person.

• A worker is a subagent the supervisor launches on the cheap model (Sonnet) for one

step. It sees ONLY its step file — none of the brief, roadmap, or sibling steps.

• A step routed judgment (no clean deterministic answer), or one that fails repeatedly,

escalates to the expensive model or a human.

Phases and steps

• A phase is a sequential chunk of the roadmap; phases run in order, a later one

assuming earlier ones are done.

• A step is an atomic unit within a phase, run by one worker. Co-phase steps run in

parallel wherever dependencies and file scopes allow.

Integration model

All work accumulates as commits on one dedicated local working branch (its starting commit is in the ledger's Plan section) — usually unpushed, not necessarily the repo default. Every worker worktree bases on that branch's current local HEAD, never a remote or default ref like origin/HEAD. The supervisor creates and verifies all worktrees itself.

Artifact style

Only models read these artifacts — some weak, low-context — never humans. Write for machine consumption: structured over prose (fields, tables, fenced blocks); explicit over elegant (exact paths, commands, expected strings — no "see above"); self-contained sections. Cut anything only a human needs — intros, transitions, summaries. Completeness first, compactness second, polish never.

Worker report & commit protocol

A step ends in exactly ONE commit containing every changed files_in_scope path — the report included, so the worker writes --report.md BEFORE committing. Report fields: status: pass | fail | missing-base · base (the SHA the work started from) · changes (what was actually done) · acceptance (each command with its verbatim output) · deviations (anything done other than as instructed, else "none"). A report never contains its own commit SHA, branch, or anything else self-referential — the supervisor reads commit identity from git, and a SHA recorded inside the commit it names cannot be written.

Step fields you act on (the decomposer authors them): depends_on (ordering) · route (mechanical → worker, judgment → escalate) · files_in_scope (the only paths that may change) · acceptance (command + exact expected result — you re-run it) · rollback (how to undo) · objective/context/actions (handed to the worker).

Verification protocol — the core discipline

For every step, independently of the worker's report:

1. Re-run every acceptance command yourself against the tree the worker produced,

and confirm the result matches the step's exact expected result. Check the check: a result satisfied by content manufactured for the check rather than by the step's real work (a hidden comment inserted to hit a grep count) is a FAIL even though the command passes — and usually a sign the acceptance was mis-specified (see Decide, option b).

1. Confirm scope: git -C diff --name-only ..HEAD — where BASE is

the wave base the worktree was created at — must be a subset of files_in_scope. Any out-of-scope change fails the step, as does any commit that isn't this step's own single commit (the contract mandates exactly one; a cherry-picked sibling or dependency commit signals a stale base or a wandering worker).

1. Treat --report.md as a hint about what the worker believes it did,

never as proof. Ground truth is the acceptance result and the diff.

Operation — supervise a phase

You are given a ` and a **phase number**. This runs inside a **git repository** (steps commit; parallel workers use worktrees). First confirm the checked-out branch equals the ledger's working-branch`; if it differs, stop and reconcile with the user — every worktree base is computed from this branch's HEAD.

1. Ensure the phase is decomposed

If the phase's -.md step files don't exist yet, invoke the decomposer skill via the Skill tool for this phase, then continue.

2. Build the dependency graph

Read all step files for the phase and the ledger. Form the DAG from each step's depends_on. A step is ready when every dependency is marked done in the ledger.

3. Run each ready set — in parallel

Repeat until the phase is done:

• Compute the ready set (ready, not-yet-done steps). Their files_in_scope are

pairwise disjoint (the decomposer guarantees this), so they are safe to run concurrently.

• Gate on prerequisites: before launching anything, confirm every depends_on step's

ledger commit is already on the current branch — git merge-base --is-ancestor HEAD must succeed for each. You create every worktree at this HEAD, so a missing prerequisite would hand the worker a stale base. If a dependency is marked done but its SHA is not an ancestor of HEAD, stop and repair the merge/ledger state before launching.

• Resolve references: replace any "files changed in step `" in a step's context`

with the concrete paths from the ledger, so the worker gets real paths.

• Create the wave's worktrees yourself — NEVER via the Agent tool's

isolation: "worktree" option (see Worktree & merge mechanics for why). Record BASE = git rev-parse HEAD, then for each step: git worktree add -> -b wt/- .

• Base gate — fail fast, mechanism-agnostic: for each worktree W before launch,

git -C rev-parse HEAD must equal BASE, and every dependency's ledger commit must satisfy git merge-base --is-ancestor . On any mismatch do NOT launch — remove and recreate the worktree at BASE. This must hold no matter how a worktree came to exist; it is what catches a harness or tooling regression.

• Launch the ready set concurrently — one worker per step, as ordinary subagents via

the Task/Agent subagent tool with model: sonnet and no isolation option (a worker's shell starts in the main repo — the contract's path discipline is what keeps it inside its worktree). Hand each worker its worktree's absolute path plus the step's objective, context, actions, files_in_scope, and this contract:

> Work ONLY inside `, on the branch already checked out there. Use > absolute paths for every file edit, run every git command as > git -C …, and prefix every build/test command with > cd && . Do only this step's actions. Change only files in > filesinscope. If your starting tree seems to be missing prerequisite work (e.g. the > step's first assertion fails), STOP and say so in your report — never fetch, pull, > merge, rebase, cherry-pick, or switch branches to repair it. Run the acceptance > command yourself and fix within scope until it passes; if a check looks unsatisfiable > by honest work (it contradicts the step's own instructions or required content), STOP > and report the discrepancy — never add content whose only purpose is to make a check > pass. Then write --report.md in the worktree — terse and structured, a > model reads it, not a human — with exactly these fields: status: pass | fail | > missing-base; base: the SHA you started from; changes: what you actually did; > acceptance: each command with its verbatim output; deviations: anything done other > than as instructed, else "none". Do NOT record your own commit SHA or branch — the > supervisor reads those from git. Finish with exactly ONE commit containing every > changed filesinscope` path including this report, message naming the step id — no > follow-up commits, no amending. Touch nothing else.

A judgment step is not given to a cheap worker — handle it on the expensive model or escalate to a human (see Routing). A lone ready step (no parallel siblings) may run directly in the working tree with no worktree — hand it the repo root as its working path, same contract — but first commit any pending plan-artifact edits so git status --porcelain is clean at launch: a worker must never meet supervisor-owned uncommitted state (it wastes worker attention and poisons status-based checks).

• As each worker returns, apply the Verification protocol in that worker's worktree.

4. Decide per step

• PASS (acceptance matches, scope clean) → merge the worktree's branch into the

current branch (clean, because scopes are disjoint), record the resulting commit SHA and the produced files in the ledger, remove the worktree and its wt/ branch, and mark the step done. Commit the ledger update — per step is cheapest to reason about, and it is mandatory before any in-tree launch; an uncommitted ledger is lost state after a crash and visible dirt to the next in-tree worker.

• FAIL → choose:
• (a) Retry — for a transient or worker-level miss on a mechanical step: hand a

corrected packet and re-run the same step, bounded (≤2 retries).

• (b) Correct in flight — when the work is right but the step's spec is defective

(typically an acceptance check honest output cannot satisfy): hand the worker a corrected packet directly, skipping the decomposer round-trip — but treat it as a real revision: append a Revisions row AND commit the corrected step file, so the artifact history matches what actually ran.

• (c) Revise — for a wrong step or wrong plan (scope overlap, missing context, step

too large — the step itself, not just its check): run the step's rollback and discard the worktree, write a revision note (below), invoke the decomposer (its revise operation) via the Skill tool with that note and the phase number, then re-run the affected steps once corrected steps land.

• (d) Escalate — for a judgment step, or repeated failure after retry + revision:

hand it to a human or resolve it on the expensive model.

Independent in-flight siblings still finish and merge — only the failed step's dependents wait.

5. Phase Definition of Done

When every step is done, verify the phase's Definition of Done from the roadmap. A gate step's report, if the phase has one, is a lead for which items to scrutinize — never a substitute for running the checks yourself. If the DoD holds: mark the phase complete in the ledger, advance current-phase, then commit all outstanding plan-artifact changes — git add /-*.md (ledger, brief, roadmap, plus any step or report files not already committed) — message supervise(): phase complete. Only then hand back to the user for the next phase. If it doesn't hold, the phase wasn't fully covered — write a revision note and send it to the decomposer.

Worktree & merge mechanics

• **Create every worktree yourself, at an exact SHA — never via the Agent tool's

isolation: "worktree".** That mode bases the worktree on the remote default branch (origin/HEAD), not your session HEAD — so every local-only commit, i.e. the pipeline's entire accumulated work, is absent — and it picks opaque agent- paths and branches you can neither verify, merge, nor clean up deterministically. Use git worktree add -b wt/- with a path OUTSIDE the main working tree (e.g. ../worktrees/-) so the main tree's status and scope checks stay clean.

• Create worktrees per ready set, immediately before launch — after every prior step's

merge has landed, so BASE (the working branch's HEAD at wave launch) already contains all depends_on commits. Never create later waves' worktrees in advance.

• Fresh worktrees do not inherit installed dependencies. Before a phase's first wave,

confirm the build/test toolchain runs in a fresh worktree (pnpm, for one, relinks from its store in seconds); if a bootstrap command is needed, run it in every worktree before handing it to the worker — workers must never improvise setup.

• Verify in the worktree (acceptance + scope diff against BASE) before merging.
• Merge passing wt/- branches into the current branch one at a time.

Disjoint scopes ⇒ no conflicts. A merge conflict is not something to hand-resolve — it means two co-parallel steps overlapped in scope, a decomposition bug: roll back and send a revision note to the decomposer.

• After a parallel wave merges, re-verify any facts one step recorded ABOUT files a

sibling edited — line-number links, counts, quoted signatures. Disjoint scopes keep merges clean but do not keep embedded facts true. Fix drift in a supervisor integration commit and note the coupling in a Revisions row so the decomposer serializes those steps next time.

• Clean up deterministically, pass or fail: git worktree remove the worktree, then delete

its branch (git branch -d wt/- after a merge, -D when discarding).

Routing & escalation

• mechanical → cheap Sonnet worker.
• judgment → expensive model or human; never a cheap worker.
• Bound retries (≤2). Revision → retry once more. Still failing → escalate. Never loop

indefinitely on the same step.

Ledger updates

Keep -ledger.md authoritative — it is what makes the run resumable and what the decomposer reads when revising.

• Steps rows: set status to done (or failed/superseded), fill files (the

merged paths) and commit (the SHA on the current branch).

• Plan: update current-phase as phases complete.
• Revisions: append phase | failed step | revision note | outcome whenever you send a

step back to the decomposer.

Revision note (what you pass to the decomposer):

- failed step: 
- acceptance: 
- expected: 
- observed: 
- root cause: 
- suggested fix: 

Pitfalls

• Never trust the self-report — always re-run acceptance and diff the scope yourself.
• Never use isolation: "worktree" — it bases the worktree on origin/HEAD, so

workers start without the pipeline's own prior work (see Worktree & merge mechanics). Create worktrees yourself at BASE, and run the base gate regardless of how any worktree was created.

• Launch only on a complete base — a base missing prerequisite commits makes workers

self-reconcile (cherry-pick / merge sibling work), corrupting scope checks and merges. Run the step-3 gates (dependency ancestry + worktree HEAD == BASE) before every wave.

• Enforce scope hard — out-of-scope changes fail the step

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jambolo
• Source: jambolo/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.