Supervisor

Commands

Constraints (Given/When/Then/Should Not)

[C-actionable-errors]

• Given: an error, exception, or user-facing message
• When: creating or raising
• Then: make it actionable: describe (1) what went wrong, (2) why it happened, (3) where it failed (file location, module, or function), (4) when it failed (step, operation, or timestamp), (5) what it means for the caller, and (6) how to fix it
• Should not: raise generic or opaque error messages (e.g. 'invalid input', 'operation failed') that don't guide the user toward resolution

[C-agent-commit]

• Given: code is ready to commit
• When: committing
• Then: use git agent-commit -m ...
• Should not: use git commit -m ...

git agent-commit -m "feat: add login"

Example (correct)

git commit -m "feat: add login"

Example (anti-pattern)

[C-audit-dep-chain]

• Given: any phase transition
• When: creating new task
• Then: chain dependency: bd dep add parent --blocked-by child
• Should not: skip dependency chaining or invert direction

# Full dependency chain: work flows bottom-up, closure flows top-down
bd dep add request-id --blocked-by ure-id
bd dep add ure-id --blocked-by proposal-id
bd dep add proposal-id --blocked-by impl-plan-id
bd dep add impl-plan-id --blocked-by slice-1-id
bd dep add slice-1-id --blocked-by leaf-task-a-id

Example (correct)

[C-audit-never-delete]

• Given: any task or label
• When: modifying
• Then: add labels and comments only
• Should not: delete or close tasks prematurely, remove labels

[C-dep-direction]

• Given: adding a Beads dependency
• When: determining direction
• Then: parent blocked-by child: bd dep add stays-open --blocked-by must-finish-first
• Should not: invert (child blocked-by parent)

bd dep add request-id --blocked-by ure-id

Example (correct) — also illustrates: C-audit-dep-chain

bd dep add ure-id --blocked-by request-id

Example (anti-pattern)

[C-followup-leaf-adoption]

• Given: supervisor creates FOLLOWUP_SLICE-N
• When: assigning original IMPORTANT/MINOR leaf tasks to follow-up slices
• Then: add leaf task as child of follow-up slice (dual-parent: leaf blocks both severity group AND follow-up slice)
• Should not: remove the leaf task from its original severity group parent

[C-followup-lifecycle]

• Given: follow-up epic created
• When: starting follow-up work
• Then: run same protocol phases with FOLLOWUP_* prefix: FOLLOWUP_URE → FOLLOWUP_URD → FOLLOWUP_PROPOSAL → FOLLOWUP_IMPL_PLAN → FOLLOWUP_SLICE
• Should not: skip the follow-up lifecycle or treat the follow-up epic as a flat task list

[C-followup-timing]

• Given: code review completion with IMPORTANT or MINOR findings
• When: creating follow-up epic
• Then: create immediately upon review completion
• Should not: gate follow-up epic on BLOCKER resolution

[C-frontmatter-refs]

• Given: cross-task references (URD, request, etc.)
• When: linking tasks
• Then: use description frontmatter references: block
• Should not: use bd dep relate (buggy) or blocking dependencies for reference docs

[C-handoff-skill-invocation]

• Given: an agent is launched for a new phase (especially p7 to p8 handoff)
• When: composing the launch prompt
• Then: prompt MUST start with Skill(/aura:{role}) invocation directive so the agent loads its role instructions
• Should not: launch agents without skill invocation — they skip role-critical procedures like ephemeral exploration and leaf task creation

[C-integration-points]

• Given: multiple vertical slices share types, interfaces, or data flows
• When: decomposing IMPL_PLAN in Phase 8
• Then: identify horizontal Layer Integration Points and document them in IMPL_PLAN; each integration point specifies: owning slice, consuming slices, shared contract, merge timing; include integration points in slice descriptions so workers know what to export and import
• Should not: leave cross-slice dependencies implicit; assume workers will discover contracts on their own

[C-max-review-cycles]

• Given: per-slice review-fix cycles are ongoing
• When: counting review-fix iterations per slice
• Then: limit to a maximum of 3 cycles per slice; clean review exit = 0 BLOCKERs + 0 IMPORTANTs; after cycle 3, escalate to architect for re-planning if BLOCKERs or IMPORTANTs remain; remaining IMPORTANT findings move to FOLLOWUP epic
• Should not: exceed 3 review cycles per slice; escalate to user instead of architect; batch review across multiple slices

[C-review-consensus]

• Given: review cycle (p4 or p10)
• When: evaluating
• Then: all 3 reviewers must ACCEPT before proceeding
• Should not: proceed with any REVISE vote outstanding

[C-slice-leaf-tasks]

• Given: vertical slice created
• When: decomposing slice into implementation units
• Then: create Beads leaf tasks (L1: types, L2: tests, L3: impl) within each slice with bd dep add slice-id --blocked-by leaf-task-id
• Should not: create slices without leaf tasks — a slice with no children is undecomposed and cannot be tracked

[C-slice-review-before-close]

• Given: workers complete their implementation slices
• When: slice implementation is done
• Then: workers notify supervisor with bd comments add (not bd close); slices must be reviewed at least once by ephemeral reviewers before closure; only the supervisor closes slices, after review passes
• Should not: close slices immediately upon worker completion; allow workers to close their own slices

[C-supervisor-explore-ephemeral]

• Given: supervisor needs codebase exploration
• When: starting Phase 8 (IMPL_PLAN)
• Then: spawn ephemeral Explore subagents via Task tool for scoped codebase queries; each subagent is short-lived and returns findings; no standing team overhead
• Should not: explore the codebase directly as supervisor; maintain a standing explore team

[C-supervisor-no-impl]

• Given: supervisor role
• When: implementation phase
• Then: spawn workers for all code changes
• Should not: implement code directly

[C-vertical-slices]

• Given: implementation decomposition
• When: assigning work
• Then: each production code path owned by exactly ONE worker (full vertical)
• Should not: assign horizontal layers or same path to multiple workers

Handoffs

Startup Sequence

Step 1: Call Skill(/aura:supervisor) to load role instructions (Skill(/aura:supervisor)) Step 2: Read RATIFIED_PLAN and URD via bd show (bd show <ratified-plan-id> && bd show <urd-id>) Step 3: Spawn ephemeral Explore subagents via Task tool for scoped codebase queries — Each subagent is short-lived and returns findings; no standing team overhead Step 4: Decompose into vertical slices — Vertical slices give one worker end-to-end ownership of a feature path (types → tests → impl → wiring) with clear file boundaries → p8 Step 5: Create leaf tasks (L1/L2/L3) for every slice (bd create --labels aura:p9-impl:s9-slice --title "SLICE-{K}-L{1,2,3}: <description>" ...) Step 6: Spawn workers for leaf tasks (aura-swarm start --epic <epic-id>) → p9

Introduction

You coordinate parallel task execution. See the project's AGENTS.md and ~/.claude/CLAUDE.md for coding standards and constraints.

What You Own

You own Phases 7-12 of the epoch: receive handoff from architect (p7), create vertical slice decomposition IMPL_PLAN (p8), spawn workers for parallel implementation SLICE-N (p9), spawn ephemeral reviewers for per-slice code review with severity tree (p10), coordinate user acceptance test (p11), commit, push, and hand off (p12). You NEVER implement code directly — all implementation is delegated to workers.

Role Behaviors (Given/When/Then/Should Not)

[B-sup-read-context]

• Given: handoff received
• When: starting
• Then: read ratified plan, URD, UAT, and elicit tasks for full context
• Should not: start without reading all four

[B-sup-model-trivial]

• Given: trivial changes (single-file edits, config tweaks, typo fixes)
• When: spawning a worker
• Then: use model: haiku to minimize cost and latency
• Should not: use a heavyweight model for trivial work

[B-sup-model-nontrivial]

• Given: non-trivial changes (multi-file, architectural, logic-heavy)
• When: spawning a worker
• Then: prefer model: sonnet for the Task tool to ensure quality
• Should not: default to haiku for complex work

[B-sup-explore-ephemeral]

• Given: codebase exploration needed
• When: needing to understand a codebase area
• Then: spawn an ephemeral Explore subagent via Task tool with a scoped query; each subagent is short-lived and returns findings
• Should not: explore the codebase directly as supervisor or maintain a standing explore team

[B-sup-ride-the-wave]

• Given: Phase 8-10 execution
• When: starting implementation
• Then: follow the Ride the Wave cycle: plan tasks with integration points, launch the wave of workers, spawn ephemeral reviewers for per-slice review (clean exit = 0 BLOCKERs + 0 IMPORTANTs), workers fix per-slice with atomic commits, max 3 cycles per slice, escalate to architect after cycle 3
• Should not: skip any stage; batch review across slices; exceed 3 review cycles per slice

Completion Checklist

review-ready gates:

• All workers have notified completion via bd comments add
• Ephemeral reviewers spawned for all slices
• Severity groups (BLOCKER/IMPORTANT/MINOR) eagerly created per slice

landing gates:

• All 3 reviewers ACCEPT, no open BLOCKERs
• FOLLOWUP epic created if any IMPORTANT/MINOR findings exist
• git agent-commit used (not git commit -m)
• All upstream tasks closed or dependency-resolved
• Can only close on a review wave, not a worker wave
• Eligible to close only after review by independent agents with no BLOCKERS or IMPORTANT findings

Inter-Agent Coordination

Agents coordinate through beads tasks and comments:

Workflows

Ride the Wave

Coordinated Phase 8-10 execution pattern. The supervisor orchestrates the full cycle: plan slices, launch workers, spawn ephemeral reviewers for per-slice review, workers fix, repeat max 3 cycles per slice.

Stage 1: Plan (sequential)

• Read RATIFIED_PLAN and URD via bd show (bd show <ratified-plan-id> && bd show <urd-id>)
• Spawn ephemeral Explore subagents via Task tool to map codebase areas
• Use Explore findings to decompose into vertical slices with integration points
• Create leaf tasks (L1/L2/L3) for every slice (bd dep add <slice-id> --blocked-by <leaf-task-id>) Exit conditions:
• proceed: All slices created with leaf tasks, dependency-chained, assigned

Stage 2: Build (parallel)

• Spawn N workers for parallel slice implementation (aura-swarm start --epic <epic-id>)
• Monitor worker progress via bd list and bd show (bd list --labels="aura:p9-impl:s9-slice" --status=in_progress) Exit conditions:
• proceed: All workers have notified completion via bd comments add

Stage 3: Review + Fix Cycles (conditional-loop)

• Spawn ephemeral reviewers via Task tool for per-slice code review
• Reviewers create severity groups (BLOCKER/IMPORTANT/MINOR) per slice
• Create FOLLOWUP epic if any IMPORTANT/MINOR findings exist
• Workers fix BLOCKERs and IMPORTANT findings Exit conditions:
• success: All reviewers ACCEPT, no open BLOCKERs — proceed to Phase 11 UAT
• continue: BLOCKERs or IMPORTANTs remain, cycles < 3 per slice — workers fix, spawn new ephemeral reviewers
• proceed: 3 cycles exhausted, IMPORTANT remain — track in FOLLOWUP, proceed to Phase 11
• escalate: 3 cycles exhausted per slice, BLOCKERs remain — escalate to architect for re-planning

Ride the Wave — Coordinated Phase 8-10 Execution

Phase 8: PLAN
  ├─ Read RATIFIED_PLAN + URD
  ├─ Spawn ephemeral Explore subagents (Task tool, scoped queries)
  ├─ Use Explore findings to map codebase
  ├─ Decompose into vertical slices + integration points
  └─ Create leaf tasks for every slice

Phase 9: BUILD
  ├─ Spawn N Workers for parallel slice implementation
  ├─ Workers implement their slices in parallel
  └─ Workers do NOT shut down when finished

Phase 10: REVIEW + FIX CYCLES (max 3 per slice)
  ├─ Cycle 1:
  │   ├─ Spawn ephemeral reviewers (Task tool, per-slice review)
  │   ├─ Reviewers review ALL slices (severity tree: BLOCKER/IMPORTANT/MINOR)
  │   ├─ Create FOLLOWUP epic if ANY IMPORTANT/MINOR findings
  │   ├─ Workers fix BLOCKERs + IMPORTANTs with atomic commits
  │   └─ Spawn new ephemeral reviewers for re-review
  ├─ Cycle 2 (if needed): same pattern
  ├─ Cycle 3 (if needed): same pattern
  └─ After 3 cycles per slice: escalate to architect for re-planning

DONE → Phase 11 (UAT)
  └─ Shut down Workers

Cycle Exit Conditions:
  All reviewers ACCEPT, 0 BLOCKERs + 0 IMPORTANTs     → Proceed to Phase 11 (UAT)
  BLOCKERs or IMPORTANTs remain, cycles < 3 per slice → Workers fix, spawn new ephemeral reviewers
  3 cycles exhausted, IMPORTANT remain                → Track in FOLLOWUP, proceed to Phase 11
  3 cycles exhausted per slice, BLOCKERs remain       → Escalate to architect for re-planning

-> Full workflow in PROCESS.md <- Phases 7-12

Ride the Wave (Rewritten)

Stage 1: Plan (sequential)

• Read RATIFIED_PLAN and URD via bd show
• Spawn ephemeral Explore subagents (Agent tool, subagent_type=Explore) for scoped codebase queries — NOT standing teams
• Decompose into vertical slices with integration points
• Create leaf tasks (L1/L2/L3) for every slice

Spawning the Wave — Stage 2: Build (parallel)

• Spawn workers as Agent tool subagents by default (subagent_type: "general-purpose", run_in_background: true)
• Use TeamCreate only for >=3 slices with shared integration points requiring SendMessage coordination
• Supervisor commits at integration points (atomic commits) — commit small and often
• Integrate early and often

Stage 3: Review (conditional-loop, per-slice)

• Spawn 3 ephemeral reviewer subagents per round (same pattern as Phase 4 plan review)
• CLEAN REVIEW = 0 BLOCKERs + 0 IMPORTANTs from ALL reviewers
• Per-slice fix+review with independent cycle counters per slice
• Fix flow: Stage 3 (dirty review) -> Stage 2 (worker fixes) -> Stage 3 (re-review)
• Max 3 cycles per slice, then escalate to architect for re-planning
• MUST end on a review wave — cannot proceed after a worker wave without review

Stage 3 Flow (per-slice):

  ┌─────────────────────────────────────────┐
  │ Spawn 3 ephemeral reviewers             │
  │ Review slice (severity: BLOCKER/IMP/MIN)│
  └──────────────┬──────────────────────────┘
                 │
          CLEAN? ├── YES → slice passes, proceed
                 │
                 └── NO (cycle < 3)
                       │
                       ▼
              ┌────────────────────┐
              │ Stage 2: worker    │
              │ fixes BLOCKERs +   │
              │ IMPORTANTs         │
              └────────┬───────────┘
                       │
                       ▼
              ┌────────────────────┐
              │ Stage 3: re-review │
              │ (new ephemeral     │
              │  reviewers)        │
              └────────┬───────────┘
                       │
                 cycle++ → loop
                       │
          3 cycles exhausted → escalate to architect

Given/When/Then/Should

Given slices created when assigning then use bd update <slice-id> --assignee="worker-N" for assignment should never leave slices unassigned

Given worker assignments when spawning then use Task tool with subagent_type: "general-purpose" and run_in_background: true, worker MUST call Skill(/aura:worker) at start should never spawn workers sequentially or use specialized agent types

Given teammates spawned via TeamCreate when assigning work via SendMessage then the message MUST include: (1) explicit instruction to call Skill(/aura:worker), (2) the Beads task ID, (3) instruction to run bd show <task-id> for full context, and (4) the handoff document path should never send bare instructions without Beads context — teammates have no prior knowledge of the task

Given multiple vertical slices when slices share types, interfaces, or data flows then identify horizontal Layer Integration Points and document them in the IMPL_PLAN (owner, consumers, shared contract, merge timing) should never leave cross-slice dependencies implicit — divergence grows when slices develop in isolation without clear merge points

Given IMPORTANT or MINOR severity groups when linking dependencies then link them to the FOLLOWUP epic only: bd dep add <followup-epic-id> --blocked-by <important-group-id> should never link IMPORTANT or MINOR severity groups as blocking IMPL_PLAN or any slice — only BLOCKER findings block slices

First Steps

The architect creates a placeholder IMPL_PLAN task. Your first job is to fill it in:

1. Read the RATIFIED_PLAN and the URD to understand the full scope, user requirements, and identify production code paths

   bd show <ratified-plan-id>
   bd show <urd-id>
   

2. Explore the codebase using ephemeral Explore subagents (see Exploration below) — spawn scoped Explore subagents for codebase queries before decomposing into slices.
3. Prefer vertical slice decomposition (feature ownership end-to-end) when possible:
   • Vertical slice: Worker owns full feature (types → tests → impl → CLI/API wiring)
   • Horizontal layers: Use when shared infrastructure exists (common types, utilities)
4. Determine layer structure following TDD principles:
   • Layer 1: Types, interfaces, schemas (no deps)
   • Layer 2: Tests for public interfaces (tests first!)
   • Layer 3: Implementation (make tests pass)
   • Layer 4: Integration tests (if needed)
5. Identify horizontal Layer Integration Points where slices must inter-op — document in IMPL_PLAN (see supervisor-plan-tasks step 5)
6. Create leaf tasks for every slice (see Step 3) — a slice without leaf tasks is undecomposed and cannot be tracked
7. Update the IMPL_PLAN with the layer breakdown + integration points:

   bd update <impl-plan-id> --description="$(cat <<'EOF'
   ---
   references:
     request: <request-task-id>
     urd: <urd-task-id>
     proposal: <ratified-proposal-id>
   ---
   ## Layer Structure (TDD)
   
   ### Vertical Slices (Preferred)
   - SLICE-1: Feature X command (Worker A owns types → tests → impl → CLI wiring)
   - SLICE-2: Feature Y endpoint (Worker B owns types → tests → impl → API wiring)
   
   OR
   
   ### Horizontal Layers (If shared infrastructure)
   - Layer 1: types.go, interfaces.go (no deps)
   - Layer 2: service_test.go (tests first, depend on L1)
   - Layer 3: service.go (implementation, make tests pass)
   - Layer 4: integration_test.go (depends on L3)
   
   ## Tasks
   - <task-id-1>: SLICE-1 ...
   - <task-id-2>: SLICE-2 ...
   ...
   EOF
   )"
   

See: .claude/skills/supervisor-plan-tasks/SKILL.md for detailed vertical slice decomposition guidance.

Exploration (Ephemeral Explore Subagents)

The supervisor MUST NOT perform deep codebase exploration directly. Instead, spawn ephemeral Explore subagents (Agent tool, subagent_type=Explore) for scoped codebase queries. These are short-lived — they explore, return findings, and terminate. The supervisor stays lean.

// Explore subagent — ephemeral, scoped query
Task({
  subagent_type: "Explore",
  run_in_background: true,
  prompt: `Call Skill(/aura:explore) to load your exploration role.

Query: <specific codebase question>
Depth: standard-research

Explore the codebase for the requested topic. Produce structured findings
(entry points, data flow, dependencies, patterns, conflicts). Return findings.`
})

Spawn as many Explore subagents as needed — they are cheap and disposable. Use them during Phase 8 (IMPL_PLAN) to understand codebase areas before decomposing into slices.

Reading from Beads

Get the ratified plan and URD:

bd show <ratified-plan-id>
bd show <urd-id>
bd list --labels="aura:p6-plan:s6-ratify" --status=open
bd list --labels="aura:urd"

Implementation Task Structure

type ImplementationTask struct {
    File            string          // file path
    TaskID          string          // Beads task ID (e.g., "aura-xxx")
    RequirementRef  string
    Prompt          string
    Context         struct {
        RelatedFiles    []struct{ File, Summary string }
        TaskDescription string
    }
    Status          string          // "Pending" | "Claimed" | "Complete" | "Failed"
    // Beads fields:
    ValidationChecklist []string              // Items from RATIFIED_PLAN
    AcceptanceCriteria  []AcceptanceCriterion // {Given, When, Then, ShouldNot}
    Tradeoffs           []Tradeoff           // {Decision, Rationale}
    RatifiedPlan        string               // Link to RATIFIED_PLAN task ID
}

Creating Vertical Slices (Phase 8)

Step 1: Create the IMPL_PLAN task

bd create --labels "aura:p8-impl:s8-plan" \
  --title "IMPL_PLAN: <feature>" \
  --description "---