Imported from DICEsda/Cypress (.opencode/skills/superpowers/subagent-driven-development/SKILL.md). Install upstream with npx skills add DICEsda/Cypress --skill subagent-driven-development. Copyright stays with the author.

Subagent-Driven Development

Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review. Maximize parallelism by running independent tasks and reviews concurrently.

Core principle: Fresh subagent per task + two-stage review (spec then quality) + parallel where safe = high quality, fast iteration

When to Use

digraph when_to_use {
    "Have implementation plan?" [shape=diamond];
    "Tasks mostly independent?" [shape=diamond];
    "Stay in this session?" [shape=diamond];
    "subagent-driven-development" [shape=box];
    "executing-plans" [shape=box];
    "Manual execution or brainstorm first" [shape=box];

    "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
    "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
    "Tasks mostly independent?" -> "Stay in this session?" [label="yes"];
    "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
    "Stay in this session?" -> "subagent-driven-development" [label="yes"];
    "Stay in this session?" -> "executing-plans" [label="no - parallel session"];
}

vs. Executing Plans (parallel session):

• Same session (no context switch)
• Fresh subagent per task (no context pollution)
• Two-stage review after each task: spec compliance first, then code quality
• Faster iteration (no human-in-loop between tasks)
• Parallel dispatch of independent tasks for maximum throughput

Step 0: Dependency Analysis

Before dispatching any work, analyze all tasks for parallelism.

For each task in the plan:
  1. List the files it creates or modifies
  2. List the agent domain it belongs to (backend, frontend, firmware, etc.)
  3. List explicit dependencies ("Task B needs Task A's output")

Group tasks into parallel batches:
  - Tasks in DIFFERENT domains with NO file overlap = same batch (parallel)
  - Tasks with shared files or explicit dependencies = different batches (sequential)
  - When unsure, default to sequential (safety over speed)

Safe to parallelize:

• backend task + frontend task + firmware task (different domains, different files)
• Two tasks in the same domain that touch completely different files
• Spec review of Task A + implementation of Task B (pipeline parallelism, if no file overlap)

NOT safe to parallelize:

• Two tasks modifying the same files
• Task B depends on code/types/interfaces created by Task A
• Two tasks in the same domain sharing code paths
• Any task that modifies shared configuration (docker-compose, package.json, etc.)

The Process

Sequential Flow (single task or dependent tasks)

digraph process_sequential {
    rankdir=TB;

    subgraph cluster_per_task {
        label="Per Task";
        "Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
        "Implementer subagent asks questions?" [shape=diamond];
        "Answer questions, provide context" [shape=box];
        "Implementer subagent implements, tests, commits, self-reviews" [shape=box];
        "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [shape=box];
        "Spec reviewer subagent confirms code matches spec?" [shape=diamond];
        "Implementer subagent fixes spec gaps" [shape=box];
        "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [shape=box];
        "Code quality reviewer subagent approves?" [shape=diamond];
        "Implementer subagent fixes quality issues" [shape=box];
        "Mark task complete in TodoWrite" [shape=box];
    }

    "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
    "Dependency analysis: group into parallel batches" [shape=box];
    "More tasks remain?" [shape=diamond];
    "Dispatch final code reviewer subagent for entire implementation" [shape=box];
    "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];

    "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dependency analysis: group into parallel batches";
    "Dependency analysis: group into parallel batches" -> "Dispatch implementer subagent (./implementer-prompt.md)";
    "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";
    "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
    "Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)";
    "Implementer subagent asks questions?" -> "Implementer subagent implements, tests, commits, self-reviews" [label="no"];
    "Implementer subagent implements, tests, commits, self-reviews" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)";
    "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" -> "Spec reviewer subagent confirms code matches spec?";
    "Spec reviewer subagent confirms code matches spec?" -> "Implementer subagent fixes spec gaps" [label="no"];
    "Implementer subagent fixes spec gaps" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [label="re-review"];
    "Spec reviewer subagent confirms code matches spec?" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="yes"];
    "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?";
    "Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"];
    "Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="re-review"];
    "Code quality reviewer subagent approves?" -> "Mark task complete in TodoWrite" [label="yes"];
    "Mark task complete in TodoWrite" -> "More tasks remain?";
    "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
    "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
    "Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers:finishing-a-development-branch";
}

Parallel Flow (independent tasks in same batch)

When dependency analysis identifies independent tasks, dispatch them in the same message:

digraph process_parallel {
    rankdir=TB;

    "Dependency analysis identifies parallel batch" [shape=box];

    subgraph cluster_parallel_impl {
        label="Parallel Implementation (single message, multiple Task calls)";
        rank=same;
        "Implementer: Task A (backend)" [shape=box];
        "Implementer: Task B (frontend)" [shape=box];
        "Implementer: Task C (firmware)" [shape=box];
    }

    "All implementers return" [shape=box];

    subgraph cluster_parallel_spec {
        label="Parallel Spec Review (single message, multiple Task calls)";
        rank=same;
        "Spec review: Task A" [shape=box];
        "Spec review: Task B" [shape=box];
        "Spec review: Task C" [shape=box];
    }

    "All spec reviews return" [shape=box];
    "Any spec issues?" [shape=diamond];
    "Fix issues sequentially (may have conflicts)" [shape=box];

    subgraph cluster_parallel_quality {
        label="Parallel Quality Review (single message, multiple Task calls)";
        rank=same;
        "Quality review: Task A" [shape=box];
        "Quality review: Task B" [shape=box];
        "Quality review: Task C" [shape=box];
    }

    "All quality reviews return" [shape=box];
    "Any quality issues?" [shape=diamond];
    "Fix issues sequentially" [shape=box];
    "Mark batch complete" [shape=box];

    "Dependency analysis identifies parallel batch" -> "Implementer: Task A (backend)";
    "Dependency analysis identifies parallel batch" -> "Implementer: Task B (frontend)";
    "Dependency analysis identifies parallel batch" -> "Implementer: Task C (firmware)";
    "Implementer: Task A (backend)" -> "All implementers return";
    "Implementer: Task B (frontend)" -> "All implementers return";
    "Implementer: Task C (firmware)" -> "All implementers return";
    "All implementers return" -> "Spec review: Task A";
    "All implementers return" -> "Spec review: Task B";
    "All implementers return" -> "Spec review: Task C";
    "Spec review: Task A" -> "All spec reviews return";
    "Spec review: Task B" -> "All spec reviews return";
    "Spec review: Task C" -> "All spec reviews return";
    "All spec reviews return" -> "Any spec issues?";
    "Any spec issues?" -> "Fix issues sequentially (may have conflicts)" [label="yes"];
    "Fix issues sequentially (may have conflicts)" -> "Spec review: Task A" [label="re-review affected"];
    "Any spec issues?" -> "Quality review: Task A" [label="no"];
    "Any spec issues?" -> "Quality review: Task B" [label="no"];
    "Any spec issues?" -> "Quality review: Task C" [label="no"];
    "Quality review: Task A" -> "All quality reviews return";
    "Quality review: Task B" -> "All quality reviews return";
    "Quality review: Task C" -> "All quality reviews return";
    "All quality reviews return" -> "Any quality issues?";
    "Any quality issues?" -> "Fix issues sequentially" [label="yes"];
    "Fix issues sequentially" -> "Quality review: Task A" [label="re-review affected"];
    "Any quality issues?" -> "Mark batch complete" [label="no"];
}

Pipeline Parallelism

Even when tasks are sequential, overlap review with the next implementation:

Timeline:
  Task 1: [Implement]  [Spec Review]  [Quality Review]
  Task 2:              [Implement]     [Spec Review]    [Quality Review]
  Task 3:                             [Implement]       [Spec Review]   [Quality Review]

Rules for pipeline parallelism:

• Only start Task N+1 implementation while Task N is in review (not implementation)
• Task N+1 must NOT depend on Task N
• Task N+1 must NOT touch files Task N modified
• If Task N's review finds issues, pause Task N+1 if there's any risk of conflict

Prompt Templates

• ./implementer-prompt.md - Dispatch implementer subagent
• ./spec-reviewer-prompt.md - Dispatch spec compliance reviewer subagent
• ./code-quality-reviewer-prompt.md - Dispatch code quality reviewer subagent

Example Workflow: Sequential

You: I'm using Subagent-Driven Development to execute this plan.

[Read plan file once: docs/plans/feature-plan.md]
[Extract all 5 tasks with full text and context]
[Dependency analysis: Tasks 1,2 are sequential (shared files), Tasks 3,4 are independent (different domains)]
[Create TodoWrite with all tasks]

Task 1: Hook installation script

[Get Task 1 text and context (already extracted)]
[Dispatch implementation subagent (general) with full task text + context]

Implementer: "Before I begin - should the hook be installed at user or system level?"

You: "User level (~/.config/superpowers/hooks/)"

Implementer: "Got it. Implementing now..."
[Later] Implementer:
  - Implemented install-hook command
  - Added tests, 5/5 passing
  - Self-review: Found I missed --force flag, added it
  - Committed

[Dispatch spec compliance reviewer]
Spec reviewer: ✅ Spec compliant - all requirements met, nothing extra

[Get git SHAs, dispatch code quality reviewer]
Code reviewer: Strengths: Good test coverage, clean. Issues: None. Approved.

[Mark Task 1 complete]

Task 2: Recovery modes (depends on Task 1)

[Get Task 2 text and context (already extracted)]
[Dispatch implementation subagent (general) with full task text + context]

Implementer: [No questions, proceeds]
Implementer:
  - Added verify/repair modes
  - 8/8 tests passing
  - Self-review: All good
  - Committed

[Dispatch spec compliance reviewer]
Spec reviewer: ❌ Issues:
  - Missing: Progress reporting (spec says "report every 100 items")
  - Extra: Added --json flag (not requested)

[Implementer fixes issues]
Implementer: Removed --json flag, added progress reporting

[Spec reviewer reviews again]
Spec reviewer: ✅ Spec compliant now

[Dispatch code quality reviewer]
Code reviewer: Strengths: Solid. Issues (Important): Magic number (100)

[Implementer fixes]
Implementer: Extracted PROGRESS_INTERVAL constant

[Code reviewer reviews again]
Code reviewer: ✅ Approved

[Mark Task 2 complete]

Example Workflow: Parallel Batch

[Dependency analysis identified Tasks 3,4,5 as independent batch]
[Task 3: backend API endpoint (backend agent)]
[Task 4: dashboard widget (frontend agent)]
[Task 5: coordinator telemetry (firmware agent)]

--- PARALLEL IMPLEMENTATION (single message, 3 Task calls) ---

[Dispatch backend implementer with Task 3 text]
[Dispatch frontend implementer with Task 4 text]
[Dispatch firmware implementer with Task 5 text]

[All three return:]
Backend implementer: Implemented endpoint, 4/4 tests pass (output shown)
Frontend implementer: Implemented widget, 6/6 tests pass (output shown)
Firmware implementer: Implemented telemetry, 3/3 tests pass (output shown)

--- PARALLEL SPEC REVIEW (single message, 3 Task calls) ---

[Dispatch backend spec reviewer for Task 3]
[Dispatch frontend spec reviewer for Task 4]
[Dispatch firmware spec reviewer for Task 5]

[All three return:]
Spec reviewer (backend): ✅ Spec compliant
Spec reviewer (frontend): ❌ Missing: responsive breakpoint for tablet
Spec reviewer (firmware): ✅ Spec compliant

--- FIX ISSUES (sequential - only Task 4 needs fixes) ---

[Resume frontend implementer to fix tablet breakpoint]
Frontend implementer: Added tablet breakpoint, 7/7 tests pass

[Re-dispatch frontend spec reviewer]
Spec reviewer (frontend): ✅ Spec compliant now

--- PARALLEL QUALITY REVIEW (single message, 3 Task calls) ---

[Dispatch quality reviewer for Task 3 (backend)]
[Dispatch quality reviewer for Task 4 (frontend)]
[Dispatch quality reviewer for Task 5 (firmware)]

[All three return: ✅ Approved]

[Mark Tasks 3, 4, 5 complete]

Example Workflow: Pipeline Parallelism

[Tasks 6,7 are sequential but Task 7 doesn't touch Task 6's files]

--- PIPELINE: overlap review with next implementation ---

[Dispatch implementer for Task 6]
Task 6 implementer returns: Done, 5/5 tests pass

[In SAME message: dispatch spec reviewer for Task 6 AND implementer for Task 7]
Task 6 spec reviewer returns: ✅ Spec compliant
Task 7 implementer returns: Done, 3/3 tests pass

[In SAME message: dispatch quality reviewer for Task 6 AND spec reviewer for Task 7]
Task 6 quality reviewer returns: ✅ Approved
Task 7 spec reviewer returns: ✅ Spec compliant

[Mark Task 6 complete, dispatch quality reviewer for Task 7]
Task 7 quality reviewer returns: ✅ Approved

[Mark Task 7 complete]

Time saved: review of Task 6 overlapped with implementation of Task 7

Advantages

vs. Manual execution:

• Subagents follow TDD naturally
• Fresh context per task (no confusion)
• Parallel-safe (subagents don't interfere when in different domains)
• Subagent can ask questions (before AND during work)

vs. Executing Plans:

• Same session (no handoff)
• Continuous progress (no waiting)
• Review checkpoints automatic

Efficiency gains:

• No file reading overhead (controller provides full text)
• Controller curates exactly what context is needed
• Subagent gets complete information upfront
• Questions surfaced before work begins (not after)
• Parallel batches reduce wall-clock time proportional to batch size
• Pipeline parallelism overlaps review with next implementation

Quality gates:

• Self-review catches issues before handoff
• Two-stage review: spec compliance, then code quality
• Review loops ensure fixes actually work
• Spec compliance prevents over/under-building
• Code quality ensures implementation is well-built
• Verification evidence required - no unverified claims

Cost:

• More subagent invocations (implementer + 2 reviewers per task)
• Controller does more prep work (dependency analysis + extracting all tasks upfront)
• Review loops add iterations
• But catches issues early (cheaper than debugging later)
• Parallel dispatch amortizes the cost across concurrent tasks

Red Flags

Never:

• Start implementation on main/master branch without explicit user consent
• Skip reviews (spec compliance OR code quality)
• Proceed with unfixed issues
• Parallelize tasks that touch the same files (conflicts)
• Parallelize tasks with explicit dependencies (Task B needs Task A's output)
• Skip dependency analysis before dispatching
• Make subagent read plan file (provide full text instead)
• Skip scene-setting context (subagent needs to understand where task fits)
• Ignore subagent questions (answer before letting them proceed)
• Accept "close enough" on spec compliance (spec reviewer found issues = not done)
• Skip review loops (reviewer found issues = implementer fixes = review again)
• Let implementer self-review replace actual review (both are needed)
• Start code quality review before spec compliance is ✅ (wrong order)
• Move to next task while either review has open issues
• Accept claims without verification evidence (no "tests pass" without output)

Parallelism safety:

• Different domains, different files = safe to parallelize
• Same domain, different files = usually safe (verify no shared code paths)
• Same files = NEVER parallelize
• Shared config files (docker-compose, package.json, etc.) = NEVER parallelize
• When unsure = default to sequential (safety over speed)
• Fix loops after parallel batch = always sequential (fixes may conflict)

If subagent asks questions:

• Answer clearly and completely
• Provide additional context if needed
• Don't rush them into implementation

If reviewer finds issues:

• Implementer (same subagent) fixes them
• Reviewer reviews again
• Repeat until approved
• Don't skip the re-review
• If fixing in a parallel batch, fix sequentially (not in parallel)

If subagent fails task:

• Dispatch fix subagent with specific instructions
• Don't try to fix manually (context pollution)

Integration

Required workflow skills:

• superpowers:using-git-worktrees - REQUIRED: Set up isolated workspace before starting
• superpowers:writing-plans - Creates the plan this skill executes
• superpowers:requesting-code-review - Code review template for reviewer subagents
• superpowers:finishing-a-development-branch - Complete development after all tasks
• superpowers:dispatching-parallel-agents - Principles for safe parallel dispatch

Subagents should use (inlined in agent definitions):

• Test-Driven Development - Write test first, watch fail, implement minimal, verify green
• Systematic Debugging - Root cause investigation before fixes
• Verification Before Completion - Run commands, read output, then claim results

Domain-specific agents (use instead of generic "general"):

• backend - ASP.NET Core / API / MQTT bridge
• frontend - Angular / dashboard / UI
• firmware - ESP32 coordinator/node
• mongodb - Schema, indexes, queries
• ml - ML models, features, inference
• integration - Cross-layer / contract testing
• devops - Docker, CI/CD, infrastructure

Alternative workflow:

• superpowers:executing-plans - Use for parallel session instead of same-session execution