# Supervisor

> >

- **Type:** Skill
- **Install:** `agentstack add skill-jambolo-claude-skills-supervisor`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jambolo](https://agentstack.voostack.com/s/jambolo)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jambolo](https://github.com/jambolo)
- **Source:** https://github.com/jambolo/claude-skills/tree/master/project-management/supervisor

## Install

```sh
agentstack add skill-jambolo-claude-skills-supervisor
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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).
2. **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).
3. 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
  > `files_in_scope`. 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 `files_in_scope` 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):

```markdown
- 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](https://github.com/jambolo)
- **Source:** [jambolo/claude-skills](https://github.com/jambolo/claude-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jambolo-claude-skills-supervisor
- Seller: https://agentstack.voostack.com/s/jambolo
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.