Subagent-Driven Development

superpowers-bd:beads

plan2beads

executing-plans

Quick Start

1. Load epic:

   bd show <epic-id>

   , parse children and Key Decisions
2. Check for

   temp/sdd-checkpoint-{epic_id}.json

   -- if found, restore state (budget_tier, wave_receipts, closed_issues, metrics), print "Resuming epic {id} from wave {N+1}", jump to LOADING (skip step 3)
3. Ask budget tier (max-20x / max-5x / pro-api) -- sets model matrix for session
4. Verify

   temp/

   exists (do NOT run

   mkdir

   )

5. bd ready

   , filter to epic children
6. Check file conflicts, cap wave at 3, serialize wave file map into prompts
7. Dispatch implementers (

   run_in_background: true

   ) -- sub-agents self-read from beads
8. Each returns: spec review -> code review -> verification -> evidence ->

   bd close

9. Post

   [WAVE-SUMMARY]

   to epic comments, cleanup

   temp/<epic>*

   , write checkpoint, retain 2-line receipt
10. Repeat from 5 until all closed
11. Print completion report, run

    finishing-a-development-branch

Budget Tier Selection

complexity:*

Implementer Models

Spec Reviewer Models

Other Roles (unchanged by complexity)

complexity:*

standard

The Process

LOADING: bd ready -> filter to epic -> check file conflicts -> cap at 3
DISPATCH: serialize wave file map -> bd update --status=in_progress -> dispatch async
MONITOR: poll TaskOutput(block=False, timeout=5000) -> route completions
REVIEW: spec review -> code review (N if tier allows) -> gap closure (max 3 attempts)
CLOSE: extract evidence -> bd close --reason -> simplify (if 2+ tasks) -> wave summary
-> loop back to LOADING until all closed -> COMPLETE

Key Rules (GUARDS)

bd update --status=in_progress

bd close

bd ready

bd close

bd ready

bd ready

bd blocked

State Machine

INIT [checkpoint?] -> LOADING (resume at wave N+1)
INIT -> LOADING -> DISPATCH -> MONITOR -> REVIEW -> CLOSE [+checkpoint] -> LOADING (loop)
                                                                        -> COMPLETE [cleanup]
REVIEW -> PENDING_HUMAN (verification >3 attempts)

Context Window Management

temp/sdd-checkpoint-{epic_id}.json

/clear

<sdd-checkpoint-recovery>

temp/sdd-checkpoint-{epic_id}.json

temp/metrics-{epic_id}.json

Prompt Templates

• ./implementer-prompt.md

  --

  {issue_id}

  ,

  {epic_id}

  ,

  {file_ownership_list}

  ,

  {wave_file_map}

  ,

  {dependency_ids}

  ,

  {wave_number}

• ./spec-reviewer-prompt.md

  --

  {issue_id}

  ,

  {wave_number}

• ./code-quality-reviewer-prompt.md

  --

  {issue_id}

  ,

  {base_sha}

  ,

  {head_sha}

  ,

  {wave_number}

  ,

  {code_reviewer_path}

• skills/epic-verifier/verifier-prompt.md

  --

  {epic_id}

  ,

  {base-sha}

  ,

  {head-sha}

  ,

  {test-command}

• ./simplifier-dispatch-guidance.md

  -- post-wave simplification (skip on pro/api, skip single-task waves)

Integration

• plan2beads -- must run first to create epic
• superpowers-bd:finishing-a-development-branch -- after COMPLETE state
• superpowers-bd:test-driven-development -- subagents use for implementation
• superpowers-bd:rule-of-five-code / rule-of-five-tests -- subagents use for artifacts >50 lines (code or test variant)
• superpowers-bd:executing-plans -- alternative for parallel session

Companion Files

• metrics-tracking.md: Wave/epic summary templates, cost formulas
• background-execution.md: Polling pseudocode, review pipeline parallelism
• verification-and-evidence.md: Gap closure loop, evidence extraction
• wave-orchestration.md: TaskCreate/TaskUpdate tracking calls
• example-workflow.md: Complete 3-wave worked example
• failure-recovery.md: Timeout, rejection loop, deadlock, bd errors
• dispatch-and-conflict.md: Dispatch routing, file conflict algorithm, parallel dispatch
• checkpoint-recovery.md: Checkpoint schema, write timing, recovery logic, edge cases
• context-loading.md: Self-read pattern, report tags, orchestrator vs sub-agent responsibilities