---
name: subagent-development
description: "Executes plans via fresh subagents per task with two-stage review (spec → quality). Triggers: subagent execution, execute plan, fresh agent per task, spec compliance review."
user-invocable: true
effort: high
argument-hint: "[plan file or task description]"
allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent, TaskCreate, TaskList, TaskUpdate, TaskGet
---
# Subagent Development
$ARGUMENTS
Execute implementation plans by dispatching fresh subagents per task, then running a two-stage review gate: spec compliance first, code quality second. Fresh context per subagent prevents accumulated confusion. Two-stage review catches different failure modes: spec review catches wrong behavior, quality review catches bad structure.
## Usage
```
/subagent-development [plan file or task description]
```
## Why This Works
| Property | Benefit |
|----------|---------|
| Fresh subagent per task | No accumulated context drift or confusion |
| Spec review first | Catches wrong behavior before quality review wastes time on wrong code |
| Quality review second | Catches structural issues after behavior is confirmed correct |
| Sequential tasks | No merge conflicts, each task builds on verified previous work |
## Process Flow
```
Read plan
|
v
Extract ordered task list
|
v
For each task:
|
+---> [1] Dispatch IMPLEMENTER subagent
| |
| v
| Handle status (see Status Protocol)
| |
| v
+---> [2] Dispatch SPEC REVIEWER subagent
| |
| v
| APPROVED? --no--> fix issues, re-review
| |
| yes
| |
| v
+---> [3] Dispatch QUALITY REVIEWER subagent
| |
| v
| Critical issues? --yes--> fix, re-review
| |
| no
| v
| Mark task complete
|
v
Next task (or done)
```
## Step 1 -- Read and Parse Plan
Read the plan file. Extract:
1. **Ordered task list** -- each task with description, acceptance criteria, file scope
2. **Global constraints** -- what must NOT change, architecture rules, shared conventions
3. **Dependencies** -- which tasks depend on which (execute in dependency order)
Present the task list to the user. Wait for approval before proceeding.
## Step 2 -- Execute Tasks Sequentially
For each task in order:
### 2a. Gather Context
Before dispatching the implementer, gather:
- Relevant source files the task will read or modify
- Related test files
- Any output/artifacts from previously completed tasks
- Global constraints from the plan
### 2b. Dispatch Implementer
Use the `Agent` tool with the [implementer prompt template](reference/implementer-prompt.md).
Select model based on task complexity:
| Task Type | Model | Examples |
|-----------|-------|---------|
| Mechanical | Cheapest available | Rename, move, config change, 1-2 files with clear spec |
| Integration | Standard | Wire up existing components, add endpoint using established patterns |
| Design/Complex | Most capable | New architecture, complex algorithms, cross-cutting concerns |
### 2c. Handle Implementer Status
The implementer reports one of four statuses:
| Status | Handling |
|--------|----------|
| **DONE** | Proceed to spec review |
| **DONE_WITH_CONCERNS** | Read concerns. If they relate to correctness or scope violations, address them before review. If observational only (style preference, future improvement), note them and proceed to spec review |
| **NEEDS_CONTEXT** | Provide the missing context the implementer identified. Re-dispatch with the same task plus the additional context |
| **BLOCKED** | Assess the blocker. Context problem: re-dispatch with better context. Task too complex for selected model: re-dispatch with more capable model. Plan is wrong or ambiguous: escalate to user for clarification |
### 2d. Spec Review (Stage 1)
Use the `Agent` tool with the [spec reviewer prompt template](reference/spec-reviewer-prompt.md).
The spec reviewer checks:
- All requirements from the task are implemented
- Nothing extra was added beyond the spec
- Nothing is missing
- Behavior matches acceptance criteria
If **APPROVED**: proceed to quality review.
If **issues found**: fix the issues (re-dispatch implementer with specific fix instructions or fix inline if trivial), then re-run spec review. Do not proceed to quality review until spec review passes.
### 2e. Quality Review (Stage 2)
Use the `Agent` tool with the [quality reviewer prompt template](reference/code-quality-reviewer-prompt.md).
The quality reviewer categorizes findings:
| Category | Action |
|----------|--------|
| **Critical** | Must fix before proceeding. Re-dispatch implementer or fix inline |
| **Important** | Should fix. Fix now unless time-boxed, then document for follow-up |
| **Suggestions** | Nice to have. Note for future improvement, do not block progress |
After fixing any Critical issues, re-run quality review to confirm.
### 2f. Mark Task Complete
Record:
- Task ID and description
- Files modified
- Commit SHA (if commits were made)
- Any concerns or suggestions deferred for later
## Step 3 -- Summary Report
After all tasks complete, produce:
```markdown
## Subagent Development Report
### Plan
[Plan file or description]
### Tasks Completed
| # | Task | Files Modified | Status | Notes |
|---|------|---------------|--------|-------|
| 1 | ... | ... | Done | ... |
| 2 | ... | ... | Done | ... |
### Deferred Items
- [Any "Important" or "Suggestion" issues not addressed]
### Verification
- [ ] All tasks implemented
- [ ] All spec reviews passed
- [ ] All quality reviews passed (no Critical issues remaining)
- [ ] Tests pass
```
## Model Selection Guidance
Before dispatching each subagent, assess the task:
```
Is the task mechanical (rename, config, boilerplate)?
--> Use cheapest model
Does the task integrate existing patterns (1-3 files)?
--> Use standard model
Does the task require design decisions or span 4+ files?
--> Use most capable model
Is it a review task?
--> Always use most capable model (reviews catch what implementers miss)
```
## Review Order Rule
```
Spec compliance review MUST pass BEFORE quality review starts.
```
Rationale: quality-reviewing code that does the wrong thing wastes everyone's time. Confirm the code does what was asked first, then confirm it does it well.
## Red Flags -- STOP Immediately
If you observe any of these, stop and correct course:
- **Skipping reviews**: Every task gets both reviews. No exceptions, regardless of task size
- **Proceeding with unfixed Critical issues**: Critical means critical. Fix before moving on
- **Dispatching multiple implementers in parallel**: Tasks are sequential. The next implementer needs to see the previous task's completed state
- **Implementer modifying files outside its scope**: Re-dispatch with explicit constraints
- **Review rubber-stamping**: If a reviewer approves in under 10 seconds with no specifics, the review is suspect. Re-dispatch with instructions to be thorough
- **Accumulated context**: If you find yourself passing growing context between tasks, you are doing it wrong. Each subagent gets fresh context relevant to its task only
## Checklist Per Task
```
[ ] Context gathered for this specific task
[ ] Implementer dispatched with correct model
[ ] Implementer status handled per protocol
[ ] Spec review passed (all requirements met, nothing extra, nothing missing)
[ ] Quality review passed (no Critical issues)
[ ] Task marked complete with file list and notes
```