/supervise

Goal

Take a written plan (~/.agent/plans/<slug>.md with Wave 1..N sections) and run it end-to-end, dispatching the right specialist agent for each wave, auditing after each wave, and aborting on risk-area violations.

Supporting files here (converge.md, goal-spec.md, race-lanes.md, templates/) write <harness root>; it is ${CLAUDE_PLUGIN_ROOT}.

Modes

Permission friction (plan-scope-allow prerequisite)

/supervise does not grant itself permissions. Whether wave edits hit the native permission prompt is decided by the plan-scope-allow gate (docs/gate-registry.md), which is active only when AGENT_PLAN_ALLOW_MODE=on is exported, or — with the env unset — when the workspace resolves to the personal trust tier (docs/customization.md § Trust tiers). In collab workspaces, expect a prompt per edit; prefer report-first waves there. Coverage is Write/Edit/MultiEdit only — Bash/MCP wave commands always keep their own gates and prompts (extension is backlog LE-1). Hard safeguards (risk-area abort, R4 mutex, gitleaks, test-failure abort) bind in every tier and every mode, including full-auto.

Dispatch pre-flight (before any edit wave leaves the main loop)

A dispatched subagent cannot answer a native permission prompt, and a background dispatch auto-denies any tool call that would prompt — so an edit wave dispatched without cleared permissions doesn't fail loudly, it silently loses its Edit/Write calls and reports garbage. Before dispatching an execution (file-editing) wave, confirm at least one of:

1. The plan-approval flag exists — [[ -f /tmp/agent-plan-approved ]] (written on ExitPlanMode approval; wiped at every SessionStart), which arms the plan-scope-allow gate above, or
2. The project's .claude/settings.local.json carries Edit/Write/ MultiEdit in permissions.allow (project-layer rules are the reliable layer — subagents do not dependably inherit user-level allows).

If neither holds: dispatch the wave foreground (prompts then reach the user) or stop and tell the user which of the two to set up. Never send an edit wave to a background dispatch on an unverified permission surface.

Model policy

Wave-dispatch default effort (advisory — pass effort on the Agent call; model-routing-advisor.py nudges when it is missing; nothing blocks on it):

The risk-area row wins over the other two. Rationale and the full per-stage table: docs/model-routing.md → The effort axis.

The orchestrating session keeps judgment and dispatches hands: when a wave is execution work, dispatch it at the tier the table names instead of doing it inline at the session model. Inline execution at the top tier is the expensive default this rule exists to prevent.

Two placement corollaries (economics: docs/model-routing.md → Intelligence placement & Floors): the audit-after-wave step is this harness's advisor checkpoint — TOP judgment re-ranking MID execution mid-run, which is where advisor value concentrates (not in a single upfront ranking). And a coordination-cost check applies before dispatching: a wave whose delegated volume would not clearly offset its own contract+report boundary (billed twice in each direction) is not a wave — fold it into an adjacent wave or make the edit directly.

The supervise loop itself never overrides a model. core/hooks/supervisor.py is a dispatch-suggestion stub — it matches intent to a specialist from the registry; it does not read or set model. If you add an agent whose role is planning or deep design, leave model: out of its frontmatter.

This table is the enforced (Claude) instance of the cross-runtime tier policy in docs/model-routing.md — see that document for the Codex/Gemini columns, the verify-judge floor, and the fan-out worker default. Prompt-side dispatch guidance for frontier models (anti-wrap-up, evidence-grounded claims, no reasoning replay) is advisory in docs/concepts/fable-5-prompting.md.

Steps

0. Intake restatement

Before touching the plan, restate the ask so dispatch decisions trace to a machine-checkable record rather than to chat prose:

a. Fill ${CLAUDE_PLUGIN_ROOT}/skills/supervise/templates/prompt-restatement.md from the user's invocation text and the plan's objective — all six sections (Original ask verbatim / Interpreted goal / Assumptions / Out of scope / Success criteria / Open questions), plus the Run started: UTC timestamp line (start of the audit window). b. Persist it to .agent/plans/<slug>/RESTATEMENT.md. (RECORD.md stays a mechanical completion ledger — intake interpretation never goes there.) c. If Open questions is non-empty and the run is not full-auto, surface them to the user before Wave 1. Full-auto runs record the resolution used under Assumptions.

/manager-audit grades this file (lane restatement-quality) — a wave serving a goal absent from Interpreted goal is flagged as scope drift.

1. Plan validation

a. Read .agent/plans/<slug>/plan.md (legacy: ~/.agent/plans/<slug>.md). b. Confirm it has Wave 1..N sections. c. Run bash "${CLAUDE_PLUGIN_ROOT}/core/infra/supervisor-goal-audit.sh" score --plan <slug> --wave 1 — on a weak verdict, warn the user and ask whether to proceed. d. If --goal-mode, write .agent/plans/<slug>/goal.json per goal-spec.md, pass ${CLAUDE_PLUGIN_ROOT}/core/infra/goal-spec-check.py on it, then:

bash "${CLAUDE_PLUGIN_ROOT}/core/infra/supervisor-goal.sh" init <slug> <N> [<budget>] "<objective>" --spec <file>

Pattern selection

When reading the plan, name each wave's shape (Pipeline, Fan-out/Fan-in, Expert Pool, Producer-Reviewer; Supervisor is always the outer frame) using docs/concepts/team-patterns.md, which maps each pattern to the lanes and caps in Step 2. A plan that needs Hierarchical Delegation is split into separate plans, not nested. If a wave's shape does not fit any pattern, say so in the restatement's Assumptions rather than inventing a lane.

2. Per-wave loop

For each wave i ∈ {1..N} (N grows under --converge):

a. Read Wave i section of the plan. b. Classify the wave and pick lanes based on its content:

• Judgment work (deciding, synthesizing) stays in the main loop.
• Execution work dispatches with an explicit model per the Model policy (implementation → workhorse tier, mechanical cleanup → low tier), after the dispatch pre-flight above clears the permission surface.
• Wave touches core/hooks/ or general code → code-reviewer after
• Wave touches auth/secrets → security-reviewer
• High-stakes wave where a cross-vendor opinion is worth its cost → /council-review (skills/council-review/SKILL.md; paid, user-approved)
• Never route an execution wave to code-reviewer or security-reviewer — both carry read-only toolsets (Read/Grep/Glob, CI-enforced); they cannot edit a file at all. core/hooks/supervisor.py suggestions name specialists for the review lane, not the execution lane.

Every dispatch is written as a delegation contract — ${CLAUDE_PLUGIN_ROOT}/skills/supervise/templates/delegation-contract.md (goal / output format / tools & scope / boundaries, plus an explicit model field per the Model policy and a skills field naming the skills the worker loads — the supervisor picks them; workers do not search for skills). Five orchestration rules travel with it (details in the template):

• Fan-out cap 3–5 per wave — a wave with more concurrent subtasks splits into consecutive waves (the template shows a worked split).
• Write single-threading — one writer per fileset; review/verify agents carry read-only toolsets, which the CI registry-drift gate enforces.
• Self-contained contracts — subagents inherit no conversation history; the contract carries every needed path, decision, and constraint, with the wave's relevant constraint slice re-stated (not whole rulebooks).
• Verifier isolation — verifiers are fresh spawns with no author context or self-assessment; they grade end-state only.
• Worker reuse (cache) — consecutive subtasks over the same fileset or context continue the same worker rather than fresh-spawning each one (a fresh spawn re-pays the full context write uncached). Verifier isolation is the standing exception: verifiers are always fresh. Liveness (--goal-mode). Register each dispatched agent with a stuck_after budget (600 s for an edit, more for tests) and its write path: bash "${CLAUDE_PLUGIN_ROOT}/core/infra/supervisor-goal.sh" agent-spawn <slug> <agent-id> <i> <stuck-after-s> [scope]. Each tick run stuck-check <slug>: STUCK = no new side effect (commit or file change in scope, or agent-effect <slug> <agent-id> log) past the budget. It prints only on a transition, so a silent tick needs no narration. An agent awaiting the user is not stuck (agent-wait, then agent-resume). On STUCK, read its output and message or re-dispatch it; agent-done when finished.

Decision log. Record each non-trivial decision (dispatch, abort/advance, waiver): bash "${CLAUDE_PLUGIN_ROOT}/core/infra/supervisor-goal-log.sh" append <slug> wave-<i> "<decision>" "<why>" <evidence> <result>. Evidence is a pointer (SHA, path, path:line), never prose. Append-only: fix a wrong row with supersede <slug> <line> …, never edit it.

c. Execute the wave's intended changes — through the dispatched execution lane, not inline at the session model (inline is judgment's lane, not execution's). Under --verify-blocking, the wave's delegation contract (${CLAUDE_PLUGIN_ROOT}/skills/supervise/templates/delegation-contract.md "Completion claim file") must instruct the worker to write .agent/claims/<slug>-w<i>.yml (verify-completion schema) on finishing — completion-gate.sh in step 2d reads it, falling back to the repo-wide .agent/claims/<slug>.yml convention if the wave-suffixed path is absent. No instruction, no claim file: the gate still runs and still blocks in block mode, but on a "claim file missing" it cannot check anything against, not a real refutation — write the instruction so the gate has something to check. d. Audit:

bash "${CLAUDE_PLUGIN_ROOT}/core/infra/supervisor-goal-audit.sh" <slug> <i>

• PASS: continue.
• FAIL: STOP. Report to user. Do not auto-fix and retry — the user decides next action.
• exit 4 (UNVERIFIED: zero runnable checks, a check denied unrun, or no section for the wave): STOP like a FAIL.

Then, the completion-claim gate (docs/gate-registry.md completion-gate row — the first blocking consumer of completion-verify.py's verdict, docs/scoring-convention.md):

bash "${CLAUDE_PLUGIN_ROOT}/core/infra/completion-gate.sh" <slug> <i> [claim-path]

• --verify-blocking (or --converge) on the /supervise invocation sets AGENT_VERIFY_BLOCKING=block for this call (unset/other flags leave the script's own default, dryrun — logs the verdict, never blocks).
• block mode + REFUTED (exit 1): STOP, same protocol as a 2d audit FAIL — report the printed refutations to the user verbatim, do not auto-fix and retry. The user decides next action.
• --converge + REFUTED: follow ${CLAUDE_PLUGIN_ROOT}/skills/supervise/converge.md instead of STOP.
• block mode + exit 4 (UNVERIFIED: no checkable evidence): STOP; run /verify-completion.
• exit 2 (the gate's own liveness canary failed — a dead completion-verify.py, not a refuted claim) is also a STOP: the gate cannot be trusted, report it as a harness defect, not a wave failure. e. Advance (if --goal-mode; refuses exit 3 if not active or the wave's audit failed):

bash "${CLAUDE_PLUGIN_ROOT}/core/infra/supervisor-goal.sh" advance-wave <slug> <i>

f. Wrap (if --auto-push or --auto-merge):

• Invoke /wrap with the appropriate flag.

2b. Race lanes (opt-in: wave annotated race: true)

Before running a race: true wave, read ${CLAUDE_PLUGIN_ROOT}/skills/supervise/race-lanes.md — it holds the one-writer and patch-only rules.

3. Safeguards (immediate abort)

Stop the supervise loop immediately on any of these:

1. User says "stop" / "halt" / "cancel" / "pause".
2. Risk-area violation detected (rules/policy/security-guards.md 5 areas).
3. R4.1 file mutex blocked.
4. gitleaks failure at any stage.
5. Test suite failure.
6. Type-check / lint failure.
7. A dispatched review/verify agent died (session limit, API error) — treat the wave's audit as FAIL even if the aggregate reports 0 findings; a dead reviewer is not a clean review (re-dispatch or verify in the main loop).

On safeguard: emit blocked broadcast (R13), report state to user.

4. Token budget (--goal-mode)

If --goal-mode with a budget, after each tool call:

bash "${CLAUDE_PLUGIN_ROOT}/core/infra/supervisor-goal.sh" track-tokens <slug> <delta>

When status transitions to budget_limited, the helper auto-writes a graceful-wrap stub at wiki/synthesis/<slug>-budget-limited-<date>.md and the supervise loop exits gracefully.

5. Completion

When wave N passes audit, cross-check the decision log against the run record before declaring the run complete:

bash "${CLAUDE_PLUGIN_ROOT}/core/infra/supervisor-goal-log.sh" check <slug>    # prints "## Attention"
bash "${CLAUDE_PLUGIN_ROOT}/core/infra/supervisor-goal.sh" complete <slug>     # if --goal-mode (re-runs the check on stderr)

Copy ## Attention into the report below (pending/failed decisions, dead evidence pointers, waves with no decision row, open agents, unfilled RECORD.md). Resolve what you can; leave the rest listed — never report "complete" over it unmentioned.

Report:

Plan <slug>: COMPLETE
Waves: N/N
PRs opened: <list>
PRs merged: <list>
Outstanding: <deferred items from the plan>
## Attention
<paste from supervisor-goal-log.sh check>

Also write the same facts to .agent/plans/<slug>/RECORD.md — the repo-native execution ledger (waves / PRs / audit verdicts / carried items). The ledger is mechanical facts only; session narrative belongs to the global recording layer, so the two never duplicate. On --goal-mode runs the complete command drops a RECORD.md stub automatically (the deterministic guarantee the file exists — it never overwrites one you already wrote); on non-goal runs writing it is this step's discipline. This keeps an execution record on runtimes that have no global recording layer at all.

Finally, auto-run the two model-economics lanes: bash "${CLAUDE_PLUGIN_ROOT}/core/infra/manager-audit.sh" <slug> --json --since <Run started ts from RESTATEMENT.md>, then filter its findings array to lane == "routing-waste" or lane == "token-spend" (the script has no per-lane flag — the JSON lane field on each finding IS the selection interface; the other two lanes' findings are simply ignored in this pass). First check whether .agent/logs/model-routing.jsonl exists and has at least one record scoped to this run — if it's missing or empty (the routing-log-missing WARN finding, or a routing-waste/token-spend finding set with zero RECORDS), the correct summary is routing: skip (no routing log), NOT routing: clean — a missing observer log makes the two lanes trivially FAIL/WARN-free (manager-audit.sh short-circuits to an empty RECORDS set and reports lane-clean PASS), so "clean" would misrepresent "never measured" as "measured and good." Only write routing: clean when records actually exist and both lanes are FAIL/WARN-free. Otherwise write routing: N WARN/FAIL — top: <subagent_type> [<tier>] rel_cost=<n> (from the token-spend lane's top-spend-sources finding). This is non-blocking — a bad verdict never blocks completion, it only informs the ledger.

Then offer to run the FULL /manager-audit <slug> (from agent-harness-extras; all four lanes — restatement quality, model-routing waste, relative token spend, role compliance), passing --since <Run started ts from RESTATEMENT.md> so the audit scopes to this run's dispatches. It reads the logs this run already produced; it never blocks completion.

Hard rules

• Never skip the audit step. A wave isn't done until the audit passes.
• Never auto-retry a failed audit (except the capped --converge loop). Hand off to the user.
• Never bypass safeguards even if the user said "full auto". "Full auto" = no clarifying-Q at decision forks; it doesn't disable safety gates.
• Always emit broadcasts at started / decision / committed / pr_opened / done / blocked (R12 / R13).