// Epic-level task supervisor — owns an epic from decomposition through the review surface. Survives interruption. All state lives in the task file.
[HINT] Download the complete skill directory including SKILL.md and all related files
| id | supervisor-c41c35d6 |
| name | supervisor |
| description | Epic-level task supervisor — owns an epic from decomposition through the review surface. Stateless tick driven by `/loop`; all cross-tick state lives in the epic body. |
| triggers | ["supervise","supervisor","shepherd","coordinate epic","get these done"] |
| modifies_files | true |
| needs_task | true |
| mode | iterative |
| domain | ["operations"] |
Canonical invocation: /loop 30m /supervisor <epic-id>
Each tick gets a fresh main-agent context. The supervisor's job is to advance one epic by one decision, then exit. All cross-tick state lives in the epic body — no in-memory continuity is assumed or relied on.
The main agent runs this loop once and exits:
mcp_pkb_get_task(<epic-id>). Read the body only.## Pattern Memory and ## Work Items from the body and apply the Emergency Brake table. If any rule fires, halt the epic and exit.That is the whole loop. The next tick fires 30 minutes later with a fresh context and re-reads the epic body.
If any of these appear in a supervisor transcript, the loop instructions need fixing — file via /learn:
grep / find / repo scanspolecat ping-pkb, A8 scan)Pre-flight, verification, and reaction are subagent work. The main agent reads structured verdicts and acts.
The main agent calls exactly one subagent per tick.
Use for every decision the supervisor would otherwise inline: "what should I dispatch next?", "a worker exited without a deliverable", "the verifier said fail."
Brief shape: epic ID + role (preflight | react) + (for react) one-line context (work item ID, exit signal).
Pauli owns:
project= / Next link in chain) — see [[instructions/worker-dispatch#gate-3-pre-flight-confirmation-summary-task-4cea5008-aops-e2d639e2]]Pauli returns exactly one of:
{action: "dispatch", task_id, worker, project, command}
{action: "file_fix_task", parent, title, body}
{action: "halt", status: "blocked"|"review", reason}
The main agent does not interpret pauli's reasoning — it executes the action. If the verdict is shaped wrong, append "pauli verdict malformed" to Pattern Memory and exit; do not improvise.
Use when a worker has just exited and the work item is in in_progress. Marsha is the QA reviewer; her contract is unchanged from her standard role.
Brief shape: work item ID, PR URL (or "none"), acceptance criteria from the work item.
Marsha returns exactly one of:
{verdict: "PASS"}
{verdict: "FAIL", reason}
{verdict: "REVISE", reason} # treated as indeterminate by the supervisor
| Marsha verdict | Main agent action |
|---|---|
| PASS | Mark item ready_for_user_review; checkpoint |
| FAIL | Call pauli with role=react, context=marsha-fail: <reason> |
| REVISE | File a verification subtask (depends_on PR); checkpoint |
Marsha never dispatches, never edits, never files tasks. The supervisor consumes her verdict.
Before calling any subagent, apply this table against ## Pattern Memory (capped to the last 8 rows) and ## Work Items:
| Rule | Trigger condition | Action |
|---|---|---|
| Recurring failure | Same failure class appears ≥3× in last 8 Pattern Memory rows | Halt epic; status review; reason recurring: <class> |
| Stalled workers | ≥2 work items in_progress with last activity > 4h ago | Halt epic; status review; reason stalled workers |
| Reactor exhaustion | Pauli react returned halt ≥2× since last brake reset | Halt epic; status review; reason repeated react halt |
| Preflight halt | Pauli preflight returned halt this tick | Halt epic; status from pauli; reason from pauli |
Halt protocol: append the reason as a Pattern Memory row, set the epic status, emit a one-line user summary, exit. Never substitute a different worker, repo, or scope. Brake reset happens only when a human explicitly clears the epic (status → queued).
The main agent appends one row per tick. Capped at 16 rows (drop the oldest when over). Lives in the epic body under ## Pattern Memory:
## Pattern Memory
| Tick (ISO) | Decision | Class | Notes |
| -------------------- | --------------------------- | ----------- | ------------------- |
| 2026-05-08T02:14:00Z | dispatch task-abc to claude | dispatch_ok | preflight clean |
| 2026-05-08T02:43:11Z | marsha FAIL on task-abc | verify_fail | tests red on docker |
Class values used by the brake: dispatch_ok, dispatch_halt, verify_pass, verify_fail, react_filed_fix, react_halt, brake_fired. Keep class names stable — the brake matches on them.
The main agent never inspects work items by reading their task bodies; the Work Items table inside the epic body is the authoritative summary.
No external state files, no environment-specific paths, no "check the log." The next supervisor instance (possibly a different machine, possibly a different agent) reads the epic body and knows exactly what's happening.
Supervisor appends to the epic body — ## Pattern Memory, ## Work Items, ## Supervisor Log — are part of the supervisor contract. Downstream enforcers must not flag them as P#5 violations.
The supervisor never silently substitutes a different worker, deliverable type, or scope. It halts, records infeasibility in the epic body, and waits for explicit human direction. Whether the substitution would be "use Gemini instead of Claude," "ship a partial draft instead of the full section," or "write a stub instead of the requested fix" — same rule.
In autonomous (loop) sessions, halts set the epic to blocked or review; the next interactive supervisor invocation picks it up.
Failing tests, broken tools, and incompatible environments are bugs the supervisor's plan must fix — never categories the supervisor's plan triages around. The verbatim list of prohibited prose patterns (drift candidate, skip-on-env, "fix vs skip", etc.) is canonical at [[instructions/decomposition-and-review#a8-prose-scan-mandatory-before-posting-any-decomposition]] and is enforced by pauli during preflight and decomposition. Casual user phrasing such as "we may need to adjust some tests" does NOT authorise A8 exemption — A8 is universal (per A7) and only an explicit user directive to skip a specific test counts.
A8 generalises beyond code: a failing claim-evidence audit, citation check, or methodology review is a bug to fix, never a category to route around.
Tasks tagged high-risk or meeting blast-radius criteria (irreversible operations, external system modifications, actions that close recovery paths) require independent critic review before dispatch. Pauli's preflight verdict includes the critic check; see [[instructions/worker-dispatch#critic-gate-for-high-blast-radius-tasks]] for the protocol.
The supervisor delegates execution but never delegates judgment. Methodology choices, citation accuracy, and anything published under the user's name require human decision points, surfaced in the epic body as pending decisions.
The supervisor is a loop, not a pipeline. Each tick enters one phase and exits.
| Phase | Subagent | What happens |
|---|---|---|
| Orient | (none) | Main agent reads epic body; runs brake; chooses subagent role |
| Decompose | pauli | Pauli proposes subtasks. See [[instructions/decomposition-and-review]] |
| Review | (none) | Plan-review halt — decomposition synthesised; awaits human promotion to queued |
| Dispatch | pauli | Pauli returns dispatch action; main agent fires it. See [[instructions/worker-dispatch]] |
| Verify | marsha | Marsha returns PASS/FAIL/REVISE on a worker exit |
| React | pauli | Pauli returns file_fix_task or halt after a FAIL |
| Halt | (none) | All work items at review surface or escalated; emit final summary; exit |
Review and Halt are real terminal states, not transient phases. The supervisor never finalises the deliverable itself — it hands off at the review surface. Async ownership transfers to whatever review pipeline the deliverable subworkflow defines.
The supervisor loop is deliverable-agnostic. The same orient → decompose → review → dispatch → verify → react → halt cycle applies whether the deliverable is a code change, a methodology section, or an analysis report. What changes is the dispatch shape, the review surface, and the completion signal.
| Deliverable type | Subworkflow | Status |
|---|---|---|
| Code change | [[instructions/code-deliverable]] | active |
| Research / writing | (would live alongside, not in scope here) | not yet |
The supervisor's job ends when each work item has reached its review surface (open PR for code; equivalent surface for other deliverable types). Set the epic to ready_for_user_review once every child is at the surface or escalated/blocked with a recorded reason. The async review pipeline takes over; the supervisor produces its final summary and exits. See [[instructions/code-deliverable#handoff-contract-task-212f1c82]] for the code case.
| Hook | Trigger | What it does |
|---|---|---|
queue-drain | cron / manual | Checks queue, starts supervisor session |
stale-check | cron / manual | Resets tasks stuck beyond threshold |
pr-merge | GitHub Action | (Code deliverable) PR merged → mark task done; not driven by supervisor |
Configuration: See [[WORKERS.md]] for runner types, capabilities, and sizing defaults — pauli reads these at dispatch time.
polecat for code) or unassigned.nic unless the task reduces to a genuine binary human choice ("Pattern A or Pattern B?").nic.Always leave a loose thread. Every agent that completes work as part of a chain MUST leave at least one PKB task that says what comes next — unless the work is fully complete with no follow-ups. Use mcp_pkb_append mid-flow and mcp_pkb_release_task at terminal states.
If dispatch is blocked → file a refinement task. If a phase is complete but the epic remains → ensure the next subtask is ready or queued. Never assume the user knows the graph; link to the next task explicitly.