subagent-driven-development

Subagent-Driven Development

Execute a plan with fresh subagents per task and strict review gates.

Required Start

Announce: I'm using subagent-driven-development to execute this plan.

Core Flow

1. Read the plan once and extract all tasks.
2. Create task tracking for all tasks.
3. For each task:

• Dispatch implementer subagent with full task text and minimal required context.
• Resolve implementer questions before coding.
• Require implementer verification evidence.
• Run spec-compliance review.
• If spec fails, return to implementer and re-review.
• Run code-quality review.
• If quality fails, return to implementer and re-review.
• Mark task complete.
  • For complex or high-risk tasks, validate the approach against requirements and consider simpler alternatives before or after the implementer’s work.
  • For tasks centered on frontend/UI, apply frontend-design standards to guide structure, styling, and accessibility.

4. Run final whole-branch review.
5. Invoke finishing-a-development-branch.

Optional Speed Mode: Parallel Waves

Use only when tasks are independent and touch disjoint files.

1. Build a wave of independent tasks.
2. Dispatch implementers in parallel for that wave.
3. Review each task with the same two-stage gate.
4. Run integration verification after the wave.

If any overlap or shared-state risk exists, revert to single-task sequence.

E2E Process Hygiene

When dispatching subagents that start background services (servers, databases, queues):

Subagents are stateless — they do not know about processes started by previous subagents. Accumulated background processes cause port conflicts, stale responses, and false test results.

Include in the subagent prompt for any E2E or service-dependent task:

Unix/macOS:

Before starting any service:
1. Kill existing instances: pkill -f "<service-pattern>" 2>/dev/null || true
2. Verify the port is free: lsof -i :<port> && echo "ERROR: port still in use" || echo "Port free"

After tests complete:
1. Kill the service you started.
2. Verify cleanup: pgrep -f "<service-pattern>" && echo "WARNING: still running" || echo "Cleanup verified"

Windows:

Before starting any service:
1. Kill existing instances: taskkill /F /IM "<process-name>" 2>nul || echo "No existing process"
2. Verify the port is free: netstat -ano | findstr :<port> && echo "ERROR: port still in use" || echo "Port free"

After tests complete:
1. Kill the service you started.
2. Verify cleanup: tasklist | findstr "<process-name>" && echo "WARNING: still running" || echo "Cleanup verified"

Exception: persistent dev servers the user explicitly keeps running — document them in state.md.

Blocked Task Protocol

When an implementer fails on the same task after 2 attempts:

1. Stop. Do not attempt a third implementation.
2. Surface the block to the user with: task name, failure evidence, and what was tried.
3. If the block is architectural or design-level: reassess the approach — validate against requirements, identify edge cases, and consider simpler alternatives before attempting again.
4. If the user is unavailable and the task is non-critical: document the block in state.md and advance to the next independent task. Never silently skip or mark a blocked task complete.

Hard Rules

• Do not execute implementation on main/master without explicit user permission.
• Do not skip spec review.
• Do not skip quality review.
• Do not accept unresolved review findings.
• Do not ask subagents to read long plan files when task text can be passed directly.

Context Isolation

Never forward parent session context or history to subagents. Construct each subagent's prompt from scratch using only:

• Task text
• Acceptance criteria
• Needed file paths
• Relevant constraints

Exclude unrelated prior assistant analysis and old failed hypotheses. Subagents must not receive conversation history, prior reasoning chains, or context from other subagent runs.

Subagent Skill Leakage Prevention

Subagents can discover superpowers-optimized skills via filesystem access and invoke them, causing a focused implementer to behave as a workflow orchestrator. Every subagent prompt MUST include this instruction:

You are a focused subagent. Do NOT invoke any skills from the superpowers-optimized plugin. Do NOT use the Skill tool. Your only job is the task described below.

Model Selection for Agent Tool Calls

Choose model based on task type when dispatching subagents via the Agent tool:

Model	Use for
haiku	File reads, summarization, log scanning, patch verification — output is data, not decisions
sonnet	Default for all implementation tasks
opus	Architecture analysis, complex spec review, multi-system debugging, any task requiring reasoning across many constraints at once

Apply via the model parameter in Agent tool calls. Default to sonnet when uncertain. Only upgrade to opus when the task is genuinely reasoning-heavy — not just large.

Prompt Templates

Use:

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

Integration

• Setup workspace first with using-git-worktrees.
• Use requesting-code-review templates for quality review structure.
• Finish with finishing-a-development-branch.