subagent-driven-development

What this skill does

# Subagent-Driven Development

## Overview

This skill orchestrates implementation through dedicated subagents with built-in quality gates. Each task is implemented by an implementer subagent, then reviewed by two specialized reviewer agents (spec compliance and code quality) before acceptance. Failed reviews trigger iterative fix cycles with a maximum of 3 retries before escalation. This ensures consistent quality at scale while maximizing parallel throughput.

**Announce at start:** "I'm using the subagent-driven-development skill to dispatch implementation tasks with two-stage review gates."

## Trigger Conditions

- Plan has 3+ tasks that can be implemented independently
- Tasks have well-specified acceptance criteria suitable for delegation
- Speed of execution is a priority
- Tasks have few interdependencies
- Quality gates are needed for delegated work

---

## Phase 1: Task Preparation

**Goal:** Ensure every task is fully specified before dispatching to any subagent.

### Task Specification Requirements (7 Sections)

Every task dispatched to a subagent MUST include ALL of these:

| Section | Content | Example |
|---------|---------|---------|
| 1. Task description | Clear, unambiguous statement | "Implement JWT token generation with RS256 signing" |
| 2. Files to create/modify | Explicit list | `src/auth/jwt.ts`, `tests/auth/jwt.test.ts` |
| 3. Acceptance criteria | Specific, testable conditions | "Tokens expire after 1 hour", "Invalid keys throw AuthError" |
| 4. TDD requirements | Tests to write, behaviors to cover | "Test: valid token generation, expired token rejection, invalid key handling" |
| 5. Quality standards | Code style, patterns, conventions | "Follow existing service pattern in src/services/, use Result type for errors" |
| 6. Context | Relevant code, interfaces, deps | "Logger API: logger.info(msg, meta). Import from ../utils/logger" |
| 7. Constraints | What NOT to do | "Do NOT modify existing auth middleware. Do NOT add new dependencies." |

### Pre-Dispatch Checklist

- [ ] Task spec has all 7 sections filled
- [ ] Task is independent (no unresolved dependencies on in-progress tasks)
- [ ] Acceptance criteria are specific and testable
- [ ] Files to modify are identified and accessible
- [ ] Relevant context has been gathered and included in the spec

### Task Independence Decision Table

| Dependency Type | Can Dispatch? | Action |
|----------------|--------------|--------|
| No dependencies | Yes | Dispatch immediately |
| Depends on completed task | Yes | Include completed task's output as context |
| Depends on in-progress task | No | Wait for dependency to complete |
| Shared file with another task | No | Serialize — one task at a time for that file |
| Shared interface only | Yes | Include interface definition as context |

**STOP — Do NOT dispatch until:**
- [ ] All 7 spec sections are complete
- [ ] Independence is verified
- [ ] Acceptance criteria are testable

---

## Phase 2: Implementation Dispatch

**Goal:** Send the task to an implementer subagent with full context.

1. Prepare the implementer prompt using `implementer-prompt.md` template
2. Include the full task specification (all 7 sections)
3. Include relevant code context (existing files, interfaces, types)
4. Dispatch the implementer subagent
5. Collect the implementation output

> **Dispatch mechanism:** Use the `Agent` tool with `subagent_type="general-purpose"` and include the implementer prompt (from `implementer-prompt.md`) in the `prompt` parameter. Set `description` to a short task label.

### Implementer Expectations

The implementer subagent MUST:
- Follow the TDD cycle (RED-GREEN-REFACTOR)
- Write tests before production code
- Only modify files listed in the task spec
- Follow the quality standards specified
- Report any questions or blockers encountered
- Document all assumptions made

### Question Handling Protocol

| Question Type | During Implementation | Action |
|--------------|----------------------|--------|
| Non-blocking | Can proceed with reasonable assumption | Note assumption, continue, flag in output |
| Blocking | Cannot proceed without answer | STOP immediately, escalate to orchestrator |
| Scope question | Asks about work outside assigned task | Report it, do NOT fix it |

**STOP — Do NOT proceed to review until:**
- [ ] Implementer has returned complete output
- [ ] All listed files have been created/modified
- [ ] Tests exist for every acceptance criterion
- [ ] Any assumptions are documented

---

## Phase 3: Spec Review Gate

**Goal:** Verify the implementation matches the original task specification.

1. Prepare the spec reviewer prompt using `spec-reviewer-prompt.md` template
2. Provide the original task specification AND the implementer's output
3. Dispatch the spec-reviewer subagent
4. Collect the review result

> **Dispatch mechanism:** Use the `Agent` tool with the spec-reviewer prompt (from `spec-reviewer-prompt.md`) in the `prompt` parameter.

### Spec Review Criteria

| Criterion | Assessment | What to Check |
|-----------|-----------|---------------|
| All acceptance criteria met | PASS / FAIL per criterion | Each criterion individually verified |
| Tests cover specified behaviors | PASS / FAIL | Test file contains tests for all behaviors |
| Files modified match spec | PASS / FAIL | No unauthorized file modifications |
| No out-of-scope changes | PASS / FAIL | Only listed files touched |
| Implementation matches intent | PASS / FAIL | Behavior is correct, not just syntactically valid |
| All constraints respected | PASS / FAIL | None of the "do NOT" items violated |

### Gate Decision

| Result | Action |
|--------|--------|
| All PASS | Proceed to Phase 4 (quality review) |
| Any FAIL | Return to implementer with specific failure details |

**STOP — Do NOT proceed to quality review if any spec criterion fails.**

---

## Phase 4: Quality Review Gate

**Goal:** Verify code meets quality standards independent of spec compliance.

1. Prepare the quality reviewer prompt using `code-quality-reviewer-prompt.md` template
2. Provide the implementation code, test code, and project quality standards
3. Dispatch the quality-reviewer subagent
4. Collect the review result

> **Dispatch mechanism:** Use the `Agent` tool with the quality-reviewer prompt (from `code-quality-reviewer-prompt.md`) in the `prompt` parameter.

### Quality Review Areas

| Area | What to Check |
|------|--------------|
| Code quality | Readability, naming, structure, complexity |
| Pattern compliance | Follows project patterns and conventions |
| Security | No injection vulnerabilities, proper validation, safe defaults |
| Performance | No unnecessary allocations, efficient algorithms, no N+1 queries |
| Error handling | All error paths handled, meaningful error messages |
| Test quality | Tests are meaningful, not testing implementation details |

### Issue Severity Classification

| Severity | Definition | Action Required |
|----------|-----------|----------------|
| **Critical** | Security vulnerability, data loss risk, incorrect behavior | MUST fix before acceptance |
| **Important** | Performance issue, maintainability concern, missing error handling | SHOULD fix (escalate to user for decision) |
| **Suggestion** | Style improvement, alternative approach, documentation | MAY fix, at developer's discretion |

### Gate Decision

| Result | Action |
|--------|--------|
| No Critical or Important issues | PASS — proceed to acceptance |
| Any Critical issues | FAIL — must fix and re-review |
| Only Important issues | Conditional — escalate to user for decision |

---

## Phase 5: Fix and Re-Review Cycle

**Goal:** Iteratively fix review failures with a bounded retry limit.

### Fix Cycle Process

```
1. Collect all failure details from the failing review gate
2. Send failures back to implementer subagent with specific instructions
3. Implementer fixes the specific issues (not a full rewrite)
4. Re-run ONLY the failing review gate
5. If still fail