sp-subagent-driven-development

name	sp-subagent-driven-development
description	Executes implementation plans by dispatching a fresh subagent per task with two-stage review after each (spec compliance, then code quality). Use when executing a plan with independent tasks in the current session.
tags	["workflow","subagents","implementation","code-review","planning"]
version	1.0.0
risk	guarded
triggers	["execute this plan with subagents","subagent-driven development","dispatch subagents for each task","implement plan with review","fresh subagent per task"]
requirements	{"cli":[],"env":[]}
upstream_ref	skills/subagent-driven-development/SKILL.md
author	AlphaComposite
license	MIT
dependencies	["sp-writing-plans","sp-test-driven-development","sp-requesting-code-review","sp-finishing-a-development-branch","sp-using-git-worktrees","sp-brainstorming","sp-executing-plans"]

Subagent-Driven Development

Execute a plan by dispatching a fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.

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

Dependency notes:

• sp-requesting-code-review has not yet been ported. When unavailable, apply the code review prompt inline using the templates in this skill.
• sp-finishing-a-development-branch has not yet been ported. When unavailable, handle branch completion manually (final review, merge/PR creation).
• This skill requires an isolated worktree prepared by sp-using-git-worktrees before starting.

When to Use

Decision tree:

Have implementation plan?
  ├── No  → Brainstorm first (sp-brainstorming → sp-writing-plans)
  └── Yes → Tasks mostly independent?
              ├── No (tightly coupled) → Manual execution
              └── Yes → Stay in this session?
                          ├── Yes → Use sp-subagent-driven-development (this skill)
                          └── No  → Use sp-executing-plans (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)

The Process

Setup

1. Read the plan file once
2. Extract ALL tasks with full text and context
3. Create a task list (e.g. via TodoWrite or equivalent) with all tasks

Per-Task Loop

For each task:

1. Dispatch implementer subagent — provide full task text + scene-setting context (where does this fit in the overall plan?)
2. Handle questions — if the subagent asks questions before starting, answer fully before letting it proceed
3. Implementer implements, tests, commits, self-reviews
4. Dispatch spec compliance reviewer — provide task spec + git SHAs of commits made
5. If spec reviewer finds issues — implementer (same subagent) fixes them; re-review until ✅
6. Dispatch code quality reviewer — provide git SHAs; review code quality
7. If quality reviewer finds issues — implementer fixes; re-review until ✅
8. Mark task complete

Completion

After all tasks:

1. Dispatch a final code reviewer for the entire implementation
2. Invoke sp-finishing-a-development-branch

Spawning Subagents (OpenClaw)

In OpenClaw, subagents are spawned via the orchestration pattern in AGENTS.md. Use exec with PTY + background for builder subagents:

# Spawn an implementer subagent
exec pty:true background:true command:"<builder-cli> '<full task text + context>'"

Note: The specific CLI command depends on the configured coding agent (e.g. Claude Code, Aider, etc.). Check AGENTS.md or project config for the builder CLI.

For reviewer subagents, spawn similarly but pass the review prompt instead of the implementation prompt.

Key rules:

• Always set workdir to the project/worktree directory
• Always use background:true for long tasks
• Monitor with process action:log sessionId:<id>
• Never spawn multiple implementer subagents in parallel (causes git conflicts)

Prompt Templates

Implementer Prompt

You are implementing Task N of M in <project-name>.

**Scene:** <Where this task fits in the overall plan — 1-2 sentences>

**Task:** <Full task text from the plan, verbatim>

**Context:**
- Worktree: <path>
- Branch: <branch-name>
- Relevant files: <list any files the implementer needs>
- Related tasks already done: <summary of completed tasks>

**Requirements:**
- Use TDD: write failing test first, verify it fails, then implement (sp-test-driven-development)
- Commit after each logical unit
- Self-review before reporting done
- Ask questions BEFORE starting if anything is unclear

Report when done: what you implemented, tests passing, commits made, any self-review findings.

Spec Compliance Reviewer Prompt

You are a spec compliance reviewer. Your job: confirm the implementation matches the spec exactly — no more, no less.

**Task Spec:**
<Full task text from the plan, verbatim>

**Commits to review:**
<git SHAs>

**Review criteria:**
- Every requirement in the spec is implemented
- Nothing extra was added that wasn't requested
- Edge cases mentioned in spec are handled

Output:
✅ Spec compliant — list what was verified
OR
❌ Issues found:
  - Missing: <requirement not implemented>
  - Extra: <thing added that wasn't requested>

Code Quality Reviewer Prompt

You are a code quality reviewer. The spec compliance reviewer has already confirmed the implementation matches spec. Your job: assess code quality.

**Commits to review:**
<git SHAs>

**Review criteria:**
- Code is readable and well-named
- No unnecessary duplication (DRY)
- No over-engineering (YAGNI)
- Tests are meaningful (not testing mocks, not testing implementation details)
- Error handling is appropriate
- No obvious performance issues

Output:
✅ Approved — brief summary of strengths
OR
⚠️ Issues (label each as Critical / Important / Minor):
  - <issue description and suggested fix>

Example Workflow

[Read plan: docs/plans/2024-01-15-auth.md]
[Extract 5 tasks with full text]
[Create task list: Task 1-5]

Task 1: Hook installation script

[Dispatch implementer 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: abc1234, def5678

[Dispatch spec compliance reviewer with task spec + SHAs]
Spec reviewer: ✅ Spec compliant — all requirements met, nothing extra

[Dispatch code quality reviewer with SHAs]
Code reviewer: ✅ Approved. Good test coverage, clean naming.

[Mark Task 1 complete]

Task 2: Recovery modes

[Dispatch implementer with full task text + context]
Implementer: [No questions, proceeds]
Implementer:
  - Added verify/repair modes
  - 8/8 tests passing
  - Committed: 9ab0123

[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. Committed: cd23456

[Spec reviewer re-reviews]
Spec reviewer: ✅ Spec compliant now

[Dispatch code quality reviewer]
Code reviewer: ⚠️ Issues (Important): Magic number (100) — extract as constant

[Implementer fixes]
Implementer: Extracted PROGRESS_INTERVAL constant. Committed: ef34567

[Code reviewer re-reviews]
Code reviewer: ✅ Approved

[Mark Task 2 complete]
...
[After all tasks: final review → sp-finishing-a-development-branch]

Advantages

vs. Manual execution:

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

vs. Executing Plans:

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

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 well-built implementation

Red Flags

Never:

• Start implementation on main/master branch without explicit user consent
• Skip reviews (spec compliance OR code quality)
• Proceed with unfixed issues
• Dispatch multiple implementer subagents in parallel (git conflicts)
• Make subagent read the plan file (provide full task text directly)
• 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 (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

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 subagent fails task:

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