Tutorial Overview

Series index: Superpowers Tutorial Series

subagent-driven-development is Superpowers’ efficient execution skill. It creates subagents to execute tasks from the implementation plan in parallel. Each subagent works independently, and the main agent then reviews and integrates the results.

What you will learn

• ✅ How the subagent-driven-development workflow works
• ✅ The two-stage review mechanism
• ✅ Task distribution strategies
• ✅ The advantages and limits of parallel execution
• ✅ A practical case study

Why Do We Need Subagent Development?

Limits of single-agent execution

flowchart LR
    A[Task 1] --> B[Task 2]
    B --> C[Task 3]
    C --> D[Task 4]
    D --> E[Task 5]
    E --> F[Done]
    
    style A fill:#ffcccb
    style B fill:#ffcccb
    style C fill:#ffcccb
    style D fill:#ffcccb
    style E fill:#ffcccb
    
    Note over A,E: Serial execution, slower

Parallel execution with subagents

flowchart TD
    M[Main agent - coordination] --> S1[Subagent 1 - database]
    M --> S2[Subagent 2 - backend API]
    M --> S3[Subagent 3 - frontend components]
    
    S1 --> R1[Review 1]
    S2 --> R2[Review 2]
    S3 --> R3[Review 3]
    
    R1 --> I[Integration]
    R2 --> I
    R3 --> I
    
    style M fill:#e1f5ff
    style S1 fill:#e8f5e9
    style S2 fill:#e8f5e9
    style S3 fill:#e8f5e9
    style I fill:#fff3e0
    
    Note over S1,S3: Parallel execution, faster

Comparison

subagent-driven-development Explained

When it triggers

subagent-driven-development triggers automatically in these scenarios:

1. When there is a written implementation plan - after writing-plans completes
2. When there are multiple independent tasks - tasks have no or few dependencies
3. When the work is time-sensitive - you need to finish quickly

Core architecture

flowchart TD
    subgraph "Main session"
        M[Main agent]
        C[Coordinator]
        R[Reviewer]
    end
    
    subgraph "Subagent pool"
        S1[Subagent 1]
        S2[Subagent 2]
        S3[Subagent 3]
        S4[Subagent 4]
    end
    
    M --> C
    C -->|Dispatch task| S1
    C -->|Dispatch task| S2
    C -->|Dispatch task| S3
    
    S1 -->|Complete task| R
    S2 -->|Complete task| R
    S3 -->|Complete task| R
    
    R -->|Review approved| M
    R -->|Review failed| S1
    
    style M fill:#e1f5ff
    style C fill:#e3f2fd
    style R fill:#fff3e0
    style S1 fill:#e8f5e9
    style S2 fill:#e8f5e9
    style S3 fill:#e8f5e9

Two-stage review mechanism

Every task completed by a subagent goes through two review stages:

Stage 1: Compliance review
├── Does it follow the design spec?
├── Does it satisfy the task requirements?
├── Do the tests pass?
└── Are the acceptance criteria met?

Stage 2: Code quality review
├── Is the code clear?
├── Are there potential bugs?
├── Does it follow best practices?
└── Are there any optimization opportunities?

Review flow

flowchart TD
    A[Subagent completes task] --> B[Stage 1: Compliance review]
    B --> C{Compliant?}
    C -->|No| D[Return to subagent for rework]
    C -->|Yes| E[Stage 2: Quality review]
    E --> F{Quality acceptable?}
    F -->|No| G[Return with optimization suggestions]
    G --> D
    F -->|Yes| H[Review passed, submit]
    D --> A
    
    style B fill:#ffebee
    style E fill:#e3f2fd
    style H fill:#e8f5e9

Review examples

Stage 1: Compliance review

## Review Report - Stage 1

**Task**: Task 3 - Create the tag API endpoint

**Compliance requirements**:
- [x] Implement the `GET /api/tags` endpoint
- [x] Return JSON
- [x] Support pagination (`page`, `per_page`)
- [x] Include test cases

**Test results**:
```bash
$ pytest tests/test_tag_api.py -v
✓ test_get_tags_list
✓ test_get_tags_pagination
✓ test_get_tags_empty

Stage 1 conclusion: ✅ Passed - meets the design spec

**Stage 2: Code quality review**

```markdown
## Review Report - Stage 2

**Code quality assessment**:

✅ Strengths:
- Clear code structure
- Accurate function names
- Complete test coverage

⚠️ Improvement suggestions:

1. 🟡 Minor: Extract pagination logic into a standalone function
   
   Current:
   ```python
   def get_tags(request):
       page = request.GET.get('page', 1)
       per_page = request.GET.get('per_page', 20)
       # 30 lines of pagination logic...

Suggestion:

def get_tags(request):
    pagination = get_pagination_params(request)
    # business logic

2. 🟡 Minor: Add type hints

   def get_tags(request: HttpRequest) -> JsonResponse:
   

Stage 2 conclusion: ✅ Passed - improvements are recommended but not blocking

## Task Distribution Strategy

### Task grouping principles

Group by layer: ├── Database task group │ ├── Create migrations │ └── Run migrations ├── Backend task group │ ├── Create model │ ├── Create repository │ └── Create controller └── Frontend task group ├── Create components └── Write styles

### Dependency-aware dispatch

```mermaid
graph TD
    T1[Task 1: Database migration] --> T2[Task 2: Model]
    T2 --> T3[Task 3: Repository]
    T3 --> T4[Task 4: Controller]
    T3 --> T5[Task 5: Service]
    
    T4 --> T6[Task 6: API tests]
    T5 --> T6
    
    subgraph "Batch 1 - Parallel"
        T1
    end
    
    subgraph "Batch 2 - Parallel"
        T2
    end
    
    subgraph "Batch 3 - Parallel"
        T3
    end
    
    subgraph "Batch 4 - Parallel"
        T4
        T5
    end
    
    subgraph "Batch 5"
        T6
    end
    
    style T1 fill:#e1f5ff
    style T2 fill:#e8f5e9
    style T3 fill:#fff3e0
    style T4 fill:#f3e5f5
    style T5 fill:#f3e5f5

Dispatch configuration

subagent:
  # Concurrency control
  concurrency:
    max_parallel: 3  # At most 3 subagents in parallel
    max_retries: 2   # Retry count for failures
    timeout_minutes: 30  # Timeout for a single task
  
  # Task assignment strategy
  assignment:
    # Group by dependency
    group_by_dependencies: true
    
    # Assign similar tasks to the same subagent to preserve context
    sticky_assignment: true
  
  # Resource limits
  resources:
    max_memory_mb: 512
    max_tokens: 50000

Practical Workflow

Full example: tag system development

Step 1: Prepare the plan

# Implementation Plan - Tag System

## Phase 1: Database
- Task 1: Create tags table migration
- Task 2: Create article_tags table migration
- Task 3: Run migrations

## Phase 2: Backend
- Task 4: Create Tag model
- Task 5: Create TagRepository
- Task 6: Create TagController
- Task 7: Define API routes

## Phase 3: Frontend
- Task 8: Create TagList component
- Task 9: Create TagSelect component
- Task 10: Integrate into the article editor

## Phase 4: Testing
- Task 11: Unit tests
- Task 12: Integration tests
- Task 13: E2E tests

Step 2: Dispatch tasks

The main agent analyzes dependencies and dispatches:

Batch 1:
└── Subagent A: Task 1, Task 2 (database migrations, parallel)

Batch 2:
└── Subagent B: Task 3 (run migrations, depends on Task 1 and 2)

Batch 3:
├── Subagent A: Task 4, Task 5 (model and repository)
└── Subagent B: Task 11 (unit tests, can be prepared early)

Batch 4:
├── Subagent A: Task 6, Task 7 (controller and routes)
└── Subagent C: Task 8, Task 9 (frontend components)

Batch 5:
├── Subagent A: Task 12 (integration tests)
├── Subagent C: Task 10 (frontend integration)
└── Subagent B: Task 13 (E2E test preparation)

Step 3: Subagent execution

Subagent A executes Task 1:

## Subagent Execution Report

**Agent**: Agent-A
**Task**: Task 1 - Create tags table migration
**Start time**: 10:00
**End time**: 10:03

**Execution details**:

1. Created migration file
   - Path: `database/migrations/20260228_create_tags_table.sql`
   - Content: `CREATE TABLE tags (...)`

2. Verification
   - SQL syntax check passed
   - File existence confirmed

**Submitted for review**:
- File: `database/migrations/20260228_create_tags_table.sql`
- Test: `sqlint migrations/20260228_create_tags_table.sql`

Reviewer checks Task 1:

## Review Result

**Task 1**: ✅ Passed

Stage 1 - Compliance review:
- [x] Migration file created
- [x] SQL syntax is correct
- [x] All fields included

Stage 2 - Code review:
- [x] Naming follows convention
- [x] Comments included
- [x] Indexes are reasonable

**Status**: Committed to Git

Step 4: Parallel progress

Timeline:

10:00 - Subagent A starts Task 1
10:00 - Subagent B starts Task 2
10:03 - Subagent A completes Task 1, passes review
10:04 - Subagent B completes Task 2, passes review
10:04 - Subagent A starts Task 4
10:05 - Subagent B starts Task 3
10:07 - Subagent A completes Task 4, under review...
10:08 - Subagent B completes Task 3, under review...
...

Step 5: Integration complete

When all tasks are complete:

✅ Phase 1: Database - done
✅ Phase 2: Backend - done
✅ Phase 3: Frontend - done
✅ Phase 4: Testing - done

Main agent integration:
- Merge all commits
- Run the full test suite
- Prepare `finishing-a-development-branch`

Error Handling and Recovery

Subagent failure handling

flowchart TD
    A[Subagent executes task] --> B{Success?}
    B -->|Yes| C[Review]
    B -->|No| D{Retry count?}
    D -->|< max| E[Retry]
    E --> A
    D -->|>= max| F[Mark as failed]
    F --> G[Main agent intervenes]
    G --> H{Critical task?}
    H -->|Yes| I[Main agent completes it directly]
    H -->|No| J[Skip or defer]
    
    style A fill:#e8f5e9
    style C fill:#e8f5e9
    style F fill:#ffebee
    style I fill:#e3f2fd

Failure example

## Subagent Execution Failure

**Task**: Task 7 - Define API routes

**Failure reason**:
- Route file locked by another process
- Still failed after 2 retries

**Main agent intervention**:
1. Check file lock status
2. Found IDE preview was the cause
3. Closed the preview and retried
4. Task 7 completed

**Lessons learned**:
- Check file locks before editing route files
- Be careful with IDE integrations

Partial failure handling

Scenario: 8 out of 10 tasks succeed, 2 fail

Handling strategy:
1. Continue the review flow for the 8 successful tasks
2. Retry the 2 failed tasks or let the main agent intervene
3. Do not block overall progress
4. Integrate everything at the end

Performance Tuning

Optimization 1: Smart batching

subagent:
  batching:
    # Merge small tasks
    merge_small_tasks: true
    merge_threshold_minutes: 2
    
    # Example:
    # Task 1: Create file A (1 minute)
    # Task 2: Create file B (1 minute)
    # → Merge and assign to one subagent

Optimization 2: Context caching

subagent:
  context:
    # Shared context to reduce repeated loading
    shared_context:
      - design_document
      - coding_standards
      - project_structure
    
    # Subagent-specific context
    per_agent_context:
      - current_task
      - related_files

Optimization 3: Result prediction

The main agent predicts task duration:
- Database migration: 3 minutes
- Model creation: 5 minutes
- Test writing: 10 minutes

Optimize dispatch based on prediction:
- Prioritize long tasks
- Merge short tasks
- Give priority to critical-path tasks

Working with Other Skills

With writing-plans

`writing-plans` outputs a structured plan
    ↓
`subagent-driven-development` parses the plan
    ↓
Tasks are dispatched by dependency

With TDD

Subagent starts task
    ↓
`test-driven-development` triggers
    ↓
Subagent writes tests first, then implementation
    ↓
Review includes test coverage checks

With code review

Subagent completes task
    ↓
`requesting-code-review` triggers
    ↓
Two-stage review
    ↓
Submit after review passes

Best Practices

1. Task independence

✅ Good: tasks do not share state
❌ Bad: tasks wait on each other

Example:
✅ Task 1: Create model (independent)
   Task 2: Create component (independent)

❌ Task 1: Write lines 1-10 of file A
   Task 2: Write lines 11-20 of file A (will conflict)

2. Reasonable concurrency

Adjust based on resources:
- Local development: 2-3 subagents
- Cloud server: 5-10 subagents
- Resource-constrained: 1 subagent (degrade to serial)

3. Clear acceptance criteria

✅ Good: concrete acceptance criteria
❌ Bad: vague completion criteria

Example:
✅ "Test pass rate 100%"
   "API response time < 100ms"
   "Coverage >= 85%"

❌ "The feature works"
   "The code quality is good"

Summary

subagent-driven-development improves efficiency through parallel execution and two-stage review:

1. Parallel execution - Multiple subagents work at the same time
2. Two-stage review - Compliance and quality checks
3. Dependency awareness - Intelligent task dispatch
4. Error recovery - Failed tasks are retried automatically

Key takeaways

• ✅ Task independence is a prerequisite for parallelism
• ✅ Two-stage review ensures quality
• ✅ Dependencies determine execution order
• ✅ Failed tasks have a recovery path

Performance gains

Series Navigation:

• ← Previous: Tutorial 7: Code Review Skills Guide
• → Next: Tutorial 9: verification-before-completion and finishing-a-branch
• Back: Series Index

Reference Resources

• Multi-Agent Systems
• Parallel Computing Concepts
• Distributed Task Execution