Subagent-Driven Development

Overview

Execute implementation plans by dispatching fresh subagents per task with systematic two-stage review.

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

When to Use

Use this skill when:

• You have an implementation plan (from writing-plans skill or user requirements)
• Tasks are mostly independent
• Quality and spec compliance are important
• You want automated review between tasks

vs. manual execution:

• Fresh context per task (no confusion from accumulated state)
• Automated review process catches issues early
• Consistent quality checks across all tasks
• Subagents can ask questions before starting work

The Process

1. Read and Parse Plan

Read the plan file. Extract ALL tasks with their full text and context upfront. Create a todo list:

# Read the plan
read("docs/plans/feature-plan.md")

# Create todo list with all tasks
todo([
    {"id": "task-1", "content": "Create User model with email field", "status": "pending"},
    {"id": "task-2", "content": "Add password hashing utility", "status": "pending"},
    {"id": "task-3", "content": "Create login endpoint", "status": "pending"},
])

Key: Read the plan ONCE. Extract everything. Don't make subagents read the plan file — provide the full task text directly in context.

2. Per-Task Workflow

For EACH task in the plan:

Step 1: Dispatch Implementer Subagent

Use sessions_spawn with complete context. In OpenAEON, pass the full assignment in task; keep each spawned session bounded and give it clear ownership.

{
  "task": "Implement Task 1: create src/models/user.py with a User class containing email and password_hash fields. Follow TDD: add tests/models/test_user.py first, run the focused test to see it fail, implement the minimal code, rerun the focused test, then run the relevant suite. Project context: Python 3.11 Flask app, existing models under src/models, pytest from repo root, bcrypt already available. Own only src/models/user.py and tests/models/test_user.py.",
  "label": "task-1-user-model",
  "runTimeoutSeconds": 900
}

Step 2: Dispatch Spec Compliance Reviewer

After the implementer completes, verify against the original spec:

{
  "task": "Review whether the implementation matches this exact spec: create src/models/user.py with User class, fields email and password_hash, bcrypt password hashing, and __repr__. Check file paths, signatures, behavior, and scope creep. Output PASS or a short list of concrete spec gaps.",
  "label": "task-1-spec-review",
  "runTimeoutSeconds": 600
}

If spec issues found: Fix gaps, then re-run spec review. Continue only when spec-compliant.

Step 3: Dispatch Code Quality Reviewer

After spec compliance passes:

{
  "task": "Review code quality for src/models/user.py and tests/models/test_user.py. Check project conventions, error handling, naming, test coverage, bugs, edge cases, and security issues. Return Critical Issues, Important Issues, Minor Issues, and Verdict: APPROVED or REQUEST_CHANGES.",
  "label": "task-1-quality-review",
  "runTimeoutSeconds": 600
}

If quality issues found: Fix issues, re-review. Continue only when approved.

Step 4: Mark Complete

todo([{"id": "task-1", "content": "Create User model with email field", "status": "completed"}], merge=True)

3. Final Review

After ALL tasks are complete, dispatch a final integration reviewer:

{
  "task": "Review the entire implementation for consistency and integration issues. Check whether all completed tasks work together, whether tests pass, and whether anything blocks merge readiness.",
  "label": "final-integration-review",
  "runTimeoutSeconds": 1200
}

4. Verify and Commit

# Run full test suite
pytest tests/ -q

# Review all changes
git diff --stat

# Final commit if needed
git add -A && git commit -m "feat: complete [feature name] implementation"

Task Granularity

Each task = 2-5 minutes of focused work.

Too big:

• "Implement user authentication system"

Right size:

• "Create User model with email and password fields"
• "Add password hashing function"
• "Create login endpoint"
• "Add JWT token generation"
• "Create registration endpoint"

Red Flags — Never Do These

• Start implementation without a plan
• Skip reviews (spec compliance OR code quality)
• Proceed with unfixed critical/important issues
• Dispatch multiple implementation subagents for tasks that touch the same files
• Make subagent read the plan file (provide full text in context instead)
• Skip scene-setting context (subagent needs to understand where the task fits)
• Ignore subagent questions (answer before letting them proceed)
• Accept "close enough" on spec compliance
• 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 PASS (wrong order)
• Move to next task while either review has open issues

Handling Issues

If Subagent Asks Questions

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

If Reviewer Finds Issues

• Implementer subagent (or a new one) fixes them
• Reviewer reviews again
• Repeat until approved
• Don't skip the re-review

If Subagent Fails a Task

• Dispatch a new fix subagent with specific instructions about what went wrong
• Don't try to fix manually in the controller session (context pollution)

Efficiency Notes

Why fresh subagent per task:

• Prevents context pollution from accumulated state
• Each subagent gets clean, focused context
• No confusion from prior tasks' code or reasoning

Why two-stage review:

• Spec review catches under/over-building early
• Quality review ensures the implementation is well-built
• Catches issues before they compound across tasks

Cost trade-off:

• More subagent invocations (implementer + 2 reviewers per task)
• But catches issues early (cheaper than debugging compounded problems later)

Integration with Other Skills

With writing-plans

This skill EXECUTES plans created by the writing-plans skill:

1. User requirements → writing-plans → implementation plan
2. Implementation plan → subagent-driven-development → working code

With test-driven-development

Implementer subagents should follow TDD:

1. Write failing test first
2. Implement minimal code
3. Verify test passes
4. Commit

Include TDD instructions in every implementer context.

With requesting-code-review

The two-stage review process IS the code review. For final integration review, use the requesting-code-review skill's review dimensions.

With systematic-debugging

If a subagent encounters bugs during implementation:

1. Follow systematic-debugging process
2. Find root cause before fixing
3. Write regression test
4. Resume implementation

Example Workflow

[Read plan: docs/plans/auth-feature.md]
[Create todo list with 5 tasks]

--- Task 1: Create User model ---
[Dispatch implementer subagent]
  Implementer: "Should email be unique?"
  You: "Yes, email must be unique"
  Implementer: Implemented, 3/3 tests passing, committed.

[Dispatch spec reviewer]
  Spec reviewer: ✅ PASS — all requirements met

[Dispatch quality reviewer]
  Quality reviewer: ✅ APPROVED — clean code, good tests

[Mark Task 1 complete]

--- Task 2: Password hashing ---
[Dispatch implementer subagent]
  Implementer: No questions, implemented, 5/5 tests passing.

[Dispatch spec reviewer]
  Spec reviewer: ❌ Missing: password strength validation (spec says "min 8 chars")

[Implementer fixes]
  Implementer: Added validation, 7/7 tests passing.

[Dispatch spec reviewer again]
  Spec reviewer: ✅ PASS

[Dispatch quality reviewer]
  Quality reviewer: Important: Magic number 8, extract to constant
  Implementer: Extracted MIN_PASSWORD_LENGTH constant
  Quality reviewer: ✅ APPROVED

[Mark Task 2 complete]

... (continue for all tasks)

[After all tasks: dispatch final integration reviewer]
[Run full test suite: all passing]
[Done!]

Remember

Fresh subagent per task
Two-stage review every time
Spec compliance FIRST
Code quality SECOND
Never skip reviews
Catch issues early

Quality is not an accident. It's the result of systematic process.