/subagent-development

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:

## 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)?
    -->