parallel-subagent-driven-development

What this skill does

# Parallel Subagent-Driven Development

Execute decomposed plan by dispatching fresh subagent(s) per batch (up to 2 parallel), with code review after each batch.

**Core principle:** Fresh subagent per task + up to 2 parallel when safe + review between batches = high quality, fast iteration

## Overview

**vs. Subagent-Driven Development:**
- Same process, but runs up to 2 subagents in parallel when tasks are independent
- Uses manifest.json to know which tasks can run together
- Reviews both implementations together
- Everything else identical

**vs. Executing Plans:**
- Same session (no context switch)
- Fresh subagent per task (no context pollution)
- Parallel execution when safe (faster)
- Code review after each batch (catch issues early)
- Faster iteration (no human-in-loop between tasks)

**When to use:**
- After running decomposing-plans (which created manifest.json)
- Staying in this session
- Want parallel execution with quality gates

**When NOT to use:**
- Plan not decomposed yet (run decomposing-plans first)
- Need to review plan first (use executing-plans)
- Tasks are tightly coupled (manual execution better)
- Plan needs revision (brainstorm first)

## Prerequisites

**REQUIRED:** Must have run decomposing-plans skill first to create:
- Individual task files: `docs/plans/tasks/<plan-name>/<feature>-task-NN.md`
- Manifest file: `docs/plans/tasks/<plan-name>/<feature>-manifest.json`

Where `<plan-name>` is the full plan filename (e.g., `2025-01-18-user-auth`)

## The Process

### 1. Load Manifest

Read manifest file from `docs/plans/tasks/<feature>-manifest.json`.

Create TodoWrite with all batches:
```
- [ ] Execute batch 1 (tasks X, Y)
- [ ] Review batch 1
- [ ] Execute batch 2 (task Z)
- [ ] Review batch 2
...
```

### 2. Execute Batch with Subagent(s)

For each batch in `parallel_batches` array:

**If batch has 1 task:**

Dispatch fresh subagent (same as original):
```
Task tool (general-purpose):
  description: "Implement Task N: [task name]"
  prompt: |
    You are implementing Task N from the decomposed plan.

    Read the task file: docs/plans/tasks/<plan-name>/<feature>-task-NN.md

    Your job is to:
    1. Read that task file carefully
    2. Implement exactly what the task specifies
    3. Write tests (following TDD if task says to)
    4. Verify implementation works
    5. Commit your work
    6. Report back

    Work from: [directory]

    Report: What you implemented, what you tested, test results, files changed, any issues
```

**If batch has 2 tasks:**

Dispatch TWO fresh subagents IN SINGLE MESSAGE (parallel execution):

```
<function_calls>
  <invoke name="Task">
    <parameter name="subagent_type">general-purpose</parameter>
    <parameter name="description">Implement Task N: [task name]</parameter>
    <parameter name="prompt">
You are implementing Task N from the decomposed plan.

Read the task file: docs/plans/tasks/<plan-name>/<feature>-task-NN.md

Your job is to:
1. Read that task file carefully
2. Implement exactly what the task specifies
3. Write tests (following TDD if task says to)
4. Verify implementation works
5. Commit your work
6. Report back

Work from: [directory]

Report: What you implemented, what you tested, test results, files changed, any issues
    </parameter>
  </invoke>
  <invoke name="Task">
    <parameter name="subagent_type">general-purpose</parameter>
    <parameter name="description">Implement Task M: [task name]</parameter>
    <parameter name="prompt">
You are implementing Task M from the decomposed plan.

Read the task file: docs/plans/tasks/<plan-name>/<feature>-task-MM.md

Your job is to:
1. Read that task file carefully
2. Implement exactly what the task specifies
3. Write tests (following TDD if task says to)
4. Verify implementation works
5. Commit your work
6. Report back

Work from: [directory]

Report: What you implemented, what you tested, test results, files changed, any issues
    </parameter>
  </invoke>
</function_calls>
```

**CRITICAL:** Both Task tools in SINGLE message = true parallel execution.

**Subagent(s) report back** with summary of work.

### 3. Review Subagent's Work

**Get git SHAs:**
- BASE_SHA: commit before batch started
- HEAD_SHA: current commit after batch

**Dispatch code-reviewer subagent:**

**If batch had 1 task:**
```
Task tool (superpowers:code-reviewer):
  Use template at requesting-code-review/code-reviewer.md

  WHAT_WAS_IMPLEMENTED: [from subagent's report]
  PLAN_OR_REQUIREMENTS: Task N from docs/plans/tasks/<plan-name>/<feature>-task-NN.md
  BASE_SHA: [commit before batch]
  HEAD_SHA: [current commit]
  DESCRIPTION: [task summary]
```

**If batch had 2 tasks:**
```
Task tool (superpowers:code-reviewer):
  Use template at requesting-code-review/code-reviewer.md

  WHAT_WAS_IMPLEMENTED: |
    Task N: [from subagent 1's report]
    Task M: [from subagent 2's report]

  PLAN_OR_REQUIREMENTS: |
    Task N: docs/plans/tasks/<plan-name>/<feature>-task-NN.md
    Task M: docs/plans/tasks/<plan-name>/<feature>-task-MM.md

  BASE_SHA: [commit before batch]
  HEAD_SHA: [current commit]
  DESCRIPTION: Batch with tasks N and M - [summary of both]
```

**Code reviewer returns:** Strengths, Issues (Critical/Important/Minor), Assessment

**Important:** When reviewing 2 tasks, code-reviewer also checks:
- No conflicts between the two implementations
- Proper integration if tasks interact
- Consistent code style across both

### 4. Apply Review Feedback

**If issues found:**
- Fix Critical issues immediately
- Fix Important issues before next batch
- Note Minor issues

**Dispatch follow-up subagent if needed:**

**If issues in 1 task:**
```
Task tool (general-purpose):
  description: "Fix issues from code review in Task N"
  prompt: |
    Fix issues from code review for Task N.

    Issues to fix: [list issues]

    Original task: docs/plans/tasks/<feature>-task-NN.md

    Fix the issues, verify tests pass, commit, report back.
```

**If issues in both tasks:**
```
<function_calls>
  <invoke name="Task">
    <parameter name="subagent_type">general-purpose</parameter>
    <parameter name="description">Fix issues in Task N</parameter>
    <parameter name="prompt">
Fix issues from code review for Task N.

Issues to fix: [list issues for task N]

Original task: docs/plans/tasks/<plan-name>/<feature>-task-NN.md

Fix the issues, verify tests pass, commit, report back.
    </parameter>
  </invoke>
  <invoke name="Task">
    <parameter name="subagent_type">general-purpose</parameter>
    <parameter name="description">Fix issues in Task M</parameter>
    <parameter name="prompt">
Fix issues from code review for Task M.

Issues to fix: [list issues for task M]

Original task: docs/plans/tasks/<plan-name>/<feature>-task-MM.md

Fix the issues, verify tests pass, commit, report back.
    </parameter>
  </invoke>
</function_calls>
```

### 5. Update Manifest and Mark Complete

**Update manifest.json:**
- Set task status to "done"
- Add "completed_at" timestamp

**Mark batch complete in TodoWrite**
- Check off batch execution
- Check off batch review

Move to next batch, repeat steps 2-5.

### 6. Final Review

After all batches complete, dispatch final code-reviewer:
```
Task tool (superpowers:code-reviewer):
  Use template at requesting-code-review/code-reviewer.md

  WHAT_WAS_IMPLEMENTED: [summary of ALL tasks from manifest]
  PLAN_OR_REQUIREMENTS: Original plan file + all task files
  BASE_SHA: [initial commit before all work]
  HEAD_SHA: [current commit after all work]
  DESCRIPTION: Complete implementation of [feature name]
```

**Final reviewer:**
- Reviews entire implementation
- Checks all plan requirements met
- Validates overall architecture
- Checks integration between all tasks

### 7. Complete Development

After final review passes:
- Announce: "I'm using the finishing-a-development-branch skill to complete this work."
- **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch
- Follow that skill to verify tests, present options, execute choice

#