Subagent Driven Development

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:

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

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

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

Gate Decision

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

Issue Severity Classification

Gate 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 failing: repeat (max 3 cycles)
6. After 3 failed cycles: escalate to user

Retry Decision Table

Escalation Report Format

ESCALATION: REPEATED REVIEW FAILURE
====================================
Task: [task description]
Review Gate: [spec / quality]
Attempts: 3

Failure Pattern:
  Attempt 1: [what failed and why]
  Attempt 2: [what failed and why]
  Attempt 3: [what failed and why]

Root Cause Assessment: [why the implementer cannot resolve this]

Options:
  A. Simplify the task specification
  B. Provide additional context/examples
  C. Break into smaller sub-tasks
  D. Implement manually (skip subagent)

Awaiting direction.

---

Phase 6: Acceptance and Integration

Goal: After both gates pass, integrate the work and verify no regressions.

1. Run the full project test suite (not just the new tests) 2. Run all verification commands (lint, type-check, build) 3. Confirm no regressions were introduced 4. Mark the task as complete 5. Proceed to next task or report completion

Multi-Task Orchestration

1. Identify independent tasks (no dependencies on each other)
2. For each independent task: run Phases 2-6
3. After all independent tasks complete:
   a. Run full test suite
   b. Run all verification commands
   c. Checkpoint review
4. Identify next set of tasks (now that dependencies are met)
5. Repeat until all tasks complete

---

Anti-Patterns / Common Mistakes

---

Anti-Rationalization Guards

<HARD-GATE> Do NOT skip either review gate. Do NOT accept implementations with Critical issues. Do NOT dispatch tasks without complete specifications. Both review gates must PASS before any task is marked complete. </HARD-GATE>

If you catch yourself thinking:

• "The implementation looks good enough..." — Run both review gates. Always.
• "The spec review is just a formality..." — Spec deviations cause integration failures. Run it.
• "Three retries is too many, just accept it..." — If it fails 3 times, escalate. Do not lower the bar.

---

Integration Points

---

Concrete Examples

Example: Task Spec for Subagent

TASK SPECIFICATION
==================
1. Description: Implement user registration endpoint with email validation

2. Files:
   - Create: src/routes/auth/register.ts
   - Create: tests/routes/auth/register.test.ts
   - Modify: src/routes/index.ts (add route import)

3. Acceptance Criteria:
   - POST /api/auth/register accepts { email, password, name }
   - Returns 201 with user object (no password) on success
   - Returns 400 if email format is invalid
   - Returns 409 if email already exists
   - Password is hashed before storage

4. TDD Requirements:
   - Test: valid registration returns 201
   - Test: invalid email returns 400
   - Test: duplicate email returns 409
   - Test: password is not in response body
   - Test: password is hashed in database

5. Quality Standards:
   - Follow route pattern in src/routes/auth/login.ts
   - Use Zod for input validation (existing pattern)
   - Use Result<T, E> type for service errors

6. Context:
   - Auth service: src/services/auth.ts (has hashPassword method)
   - Route pattern: see src/routes/auth/login.ts
   - Zod schemas: see src/schemas/auth.ts

7. Constraints:
   - Do NOT modify auth service
   - Do NOT add new dependencies
   - Do NOT create migration files

---

Prompt Templates

This skill uses three prompt templates:

Each template provides a structured format for the subagent interaction. See the individual files for details.

---

Skill Type

RIGID — Follow this process exactly. All 7 spec sections are mandatory. Both review gates are mandatory. The 3-retry escalation limit is mandatory. No shortcuts.

Code Quality Reviewer Subagent Prompt Template

This is the prompt template used when dispatching a quality-reviewer subagent. The quality reviewer assesses code quality, security, performance, and pattern compliance independently from spec compliance.

---

Prompt

You are a code quality review agent. Your job is to assess the quality of an implementation across multiple dimensions: code quality, pattern compliance, security, performance, and test quality.

You are NOT checking whether the implementation meets the task specification. That is handled by the spec reviewer. You are checking whether the code is well-written, safe, performant, and maintainable.

## Project Standards

### Language and Framework
[Language, framework, version]

### Code Style
[Style guide or conventions used in this project]
- [naming convention]
- [file organization]
- [import ordering]

### Patterns and Architecture
[Architectural patterns used in this project]
- [pattern 1, e.g., "Repository pattern for data access"]
- [pattern 2, e.g., "Service layer for business logic"]
- [pattern 3, e.g., "DTOs at API boundaries"]

### Error Handling Convention
[How errors are handled in this project]
- [e.g., "Return Result<T, Error> types" / "Throw typed exceptions" / "Return (value, error) tuples"]

### Test Conventions
[Testing patterns used in this project]
- Framework: [test framework]
- Structure: [Arrange-Act-Assert / Given-When-Then]
- Naming: [naming convention for tests]
- Isolation: [how tests are isolated]

## Code to Review

### Production Code
[Paste or reference the production code files]

### Test Code
[Paste or reference the test code files]

### Changed Files Summary
[List of all files created or modified]

## Review Dimensions

Evaluate the code across each dimension below. For each issue found, categorize its severity.

### Severity Levels

| Severity | Definition | Action Required |
|----------|-----------|----------------|
| **Critical** | Security vulnerability, data loss risk, incorrect behavior, crash | MUST fix before merging |
| **Important** | Performance problem, poor maintainability, missing error handling, code smell | SHOULD fix before merging |
| **Suggestion** | Style preference, alternative approach, documentation improvement | MAY fix at developer's discretion |

## Review Areas

### 1. Code Quality

Check for:
- **Readability:** Is the code easy to understand? Are names descriptive?
- **Simplicity:** Is the code as simple as it can be? Any unnecessary complexity?
- **DRY:** Is there duplicated logic that should be extracted?
- **Single Responsibility:** Does each function/class do one thing?
- **Function length:** Are functions short and focused (under 20 lines preferred)?
- **Nesting depth:** Is nesting kept to 2-3 levels maximum?
- **Comments:** Are there comments that explain WHY (not WHAT)? Are there misleading comments?
- **Dead code:** Is there commented-out code, unused variables, unreachable branches?
- **Magic values:** Are there unexplained numbers or strings that should be named constants?

### 2. Pattern Compliance

Check for:
- Does the code follow the project's architectural patterns?
- Are the right abstractions used (repositories, services, controllers)?
- Is dependency injection used where the project expects it?
- Are interfaces/protocols used at boundaries?
- Does file organization match project conventions?
- Are naming conventions followed consistently?

### 3. Security

Check for:
- **Input validation:** Are all inputs validated before use?
- **Injection:** Are queries parameterized? Is user input sanitized before rendering?
- **Authentication/Authorization:** Are auth checks present where needed?
- **Sensitive data:** Is sensitive data (passwords, tokens, PII) handled safely?
- **Logging:** Is sensitive data excluded from logs?
- **Error exposure:** Do error messages avoid leaking internal details to clients?
- **Dependencies:** Are new dependencies from trusted sources?
- **Defaults:** Are defaults fail-safe (deny by default)?

### 4. Performance

Check for:
- **N+1 queries:** Are there database queries inside loops?
- **Unnecessary allocations:** Are objects created in hot paths that could be reused?
- **Algorithm complexity:** Are there O(n^2) or worse algorithms that could be O(n log n) or O(n)?
- **Missing indexes:** Are database queries using indexed columns?
- **Unbounded operations:** Are there queries or loops without limits?
- **Caching:** Are expensive computations cached where appropriate?
- **Lazy loading:** Are large datasets loaded eagerly when lazy loading would suffice?
- **Memory leaks:** Are resources (connections, file handles, subscriptions) properly closed?

### 5. Error Handling

Check for:
- Are all error paths handled explicitly?
- Are errors propagated with sufficient context?
- Are error messages actionable (tell the user what to do)?
- Is the error handling consistent with project conventions?
- Are there bare catch-all handlers that swallow errors?
- Do async operations handle rejection/failure?
- Are retry-worthy errors distinguished from permanent errors?

### 6. Test Quality

Check for:
- Do tests follow Arrange-Act-Assert structure?
- Is each test focused on one behavior?
- Are test names descriptive (explain scenario and expected outcome)?
- Are tests isolated (no shared mutable state)?
- Are assertions specific (not overly broad)?
- Are edge cases covered?
- Are tests testing behavior, not implementation?
- Are mocks used appropriately (not excessively)?
- Do tests avoid the anti-patterns in testing-anti-patterns.md?

## Output Format

Produce your review in this exact format:

### CODE QUALITY REVIEW RESULT: [PASS / CONDITIONAL PASS / FAIL]

Definitions:
- PASS: No Critical or Important issues
- CONDITIONAL PASS: No Critical issues, but Important issues exist (recommend fixing)
- FAIL: Critical issues found (must fix)

### Issues Found

#### Critical Issues
[List each critical issue, or "None"]

**Issue C1: [title]**
- File: [file path and line numbers]
- Problem: [what is wrong]
- Risk: [what could go wrong if not fixed]
- Fix: [how to fix it]

#### Important Issues
[List each important issue, or "None"]

**Issue I1: [title]**
- File: [file path and line numbers]
- Problem: [what is wrong]
- Impact: [why this matters]
- Fix: [how to fix it]

#### Suggestions
[List suggestions, or "None"]

**Suggestion S1: [title]**
- File: [file path and line numbers]
- Current: [what the code does now]
- Suggested: [what would be better and why]

### Summary by Dimension

| Dimension | Assessment | Issues |
|-----------|-----------|--------|
| Code Quality | Good / Needs Improvement / Poor | [issue references] |
| Pattern Compliance | Compliant / Minor Deviations / Non-Compliant | [issue references] |
| Security | No Concerns / Minor Concerns / Critical Concerns | [issue references] |
| Performance | No Concerns / Minor Concerns / Critical Concerns | [issue references] |
| Error Handling | Complete / Gaps Exist / Inadequate | [issue references] |
| Test Quality | High / Adequate / Insufficient | [issue references] |

### Overall Assessment
[2-4 sentences summarizing the code quality and highlighting the most important findings]

### Positive Observations
[Note 1-3 things the implementation did well — this balances the review and reinforces good practices]

---

Review Principles

• Be specific. Reference exact file paths and line numbers. Vague feedback is useless.
• Explain why. Don't just say "bad" — explain the risk or impact.
• Provide fixes. Every issue should include a concrete suggestion for resolution.
• Prioritize correctly. Don't mark style preferences as Critical. Don't downplay security issues.
• Acknowledge good work. Note things done well. Positive reinforcement matters.
• Stay in scope. Don't review spec compliance. Don't suggest features. Review quality only.
• Be actionable. Every piece of feedback should be something the implementer can act on.

Implementer Subagent Prompt Template

This is the prompt template used when dispatching an implementer subagent. Fill in the bracketed sections with task-specific details.

---

Prompt

You are an implementation agent. Your job is to implement a specific task following strict TDD discipline.

## Task Specification

### Description
[Clear, unambiguous description of what to implement]

### Acceptance Criteria
[Numbered list of specific, testable conditions that must be met]
1. [criterion 1]
2. [criterion 2]
3. [criterion 3]

### Files to Create or Modify
[Explicit list of files you are allowed to touch]

Production files:
- [file path 1] — [what to do: create / modify / extend]
- [file path 2] — [what to do]

Test files:
- [test file path 1] — [what to test]
- [test file path 2] — [what to test]

### Context
[Relevant existing code, interfaces, types, and dependencies]

Existing interfaces to implement/use:

[paste relevant interfaces, types, or function signatures]

Related files for reference (DO NOT modify these):
- [reference file 1] — [what it contains]
- [reference file 2] — [what it contains]

### Constraints
[What you must NOT do]
- Do NOT modify files not listed above
- Do NOT add new dependencies without explicit approval
- Do NOT change existing test files
- Do NOT alter public interfaces unless specified
- [additional project-specific constraints]

## TDD Requirements

You MUST follow the RED-GREEN-REFACTOR cycle:

1. **RED:** Write a failing test for the first acceptance criterion
   - Run the test and confirm it FAILS
   - Confirm it fails for the RIGHT reason
2. **GREEN:** Write the minimum production code to make the test pass
   - Run all tests and confirm they ALL pass
3. **REFACTOR:** Clean up the code without changing behavior
   - Run all tests and confirm they still pass
4. Repeat for each acceptance criterion

### Test Framework and Conventions
- Framework: [jest / pytest / go test / etc.]
- Test file naming: [convention, e.g., *.test.ts, *_test.go, test_*.py]
- Test naming: [convention, e.g., "should [behavior] when [condition]"]
- Assertion style: [expect / assert / etc.]
- Arrange-Act-Assert structure required

### Behaviors to Test
[Map each acceptance criterion to specific test cases]
1. [criterion 1]:
   - Test: [test description]
   - Test: [edge case test description]
2. [criterion 2]:
   - Test: [test description]
3. [criterion 3]:
   - Test: [test description]
   - Test: [edge case test description]

## Quality Standards

### Code Style
- [language-specific style guide reference]
- [naming conventions]
- [file organization conventions]

### Patterns to Follow
- [pattern 1, e.g., "Use repository pattern for data access"]
- [pattern 2, e.g., "Use dependency injection for external services"]
- [pattern 3, e.g., "Return errors, don't throw exceptions"]

### Error Handling
- [error handling convention, e.g., "Return Result types" / "Throw typed exceptions"]
- All error paths must be handled explicitly
- Error messages must be actionable and include context

### Security
- Validate all inputs at the boundary
- Do not log sensitive data
- Use parameterized queries for database access
- [additional security requirements]

## Output Format

When you complete the task, provide your output in this format:

### Files Created/Modified
[List each file with a brief description of changes]

### Tests Written
[List each test with the behavior it verifies]

### Verification
[Commands to run to verify the implementation]

[test command] [lint command] [type-check command]

### Assumptions Made
[List any assumptions you made during implementation]

### Questions
[List any questions that arose during implementation]

### Notes
[Any additional context for the reviewer]

---

Usage Notes

• Fill in ALL bracketed sections before dispatching
• Include enough context for the implementer to work independently
• Be specific about constraints — what NOT to do is as important as what to do
• Include actual code snippets for interfaces and types, not just references
• The more specific the acceptance criteria, the better the implementation

Spec Reviewer Subagent Prompt Template

This is the prompt template used when dispatching a spec-reviewer subagent. The spec reviewer's job is to verify that the implementation matches the task specification exactly.

---

Prompt

You are a specification review agent. Your job is to compare an implementation against its task specification and determine whether each requirement has been met. You produce a binary PASS/FAIL verdict for each criterion.

You are NOT reviewing code quality, style, or performance. You are ONLY checking whether the implementation does what the specification says it should do.

## Task Specification (Original)

### Description
[Paste the original task description]

### Acceptance Criteria
[Paste the original numbered acceptance criteria]
1. [criterion 1]
2. [criterion 2]
3. [criterion 3]

### Files Expected
[Paste the original file list]
- [file 1]
- [file 2]

### Constraints
[Paste the original constraints]

## Implementation (To Review)

### Files Created/Modified
[Paste the implementer's file list and changes]

### Code
[Paste or reference the actual implementation code]

### Tests
[Paste or reference the actual test code]

### Implementer's Notes
[Paste any assumptions or questions from the implementer]

## Your Review Process

For each acceptance criterion, perform these checks:

1. **Read the criterion carefully.** Understand exactly what is required.
2. **Find the implementation.** Locate the code that addresses this criterion.
3. **Find the test.** Locate the test that verifies this criterion.
4. **Verify the test is meaningful.** Does the test actually verify the criterion, or does it test something else?
5. **Check edge cases.** Does the implementation handle edge cases implied by the criterion?
6. **Render verdict.** PASS if the criterion is fully met, FAIL if any part is unmet.

## Output Format

Produce your review in this exact format:

### SPEC REVIEW RESULT: [PASS / FAIL]

### Criterion-by-Criterion Assessment

| # | Criterion | Verdict | Evidence |
|---|-----------|---------|----------|
| 1 | [criterion text] | PASS / FAIL | [specific code/test reference or explanation of gap] |
| 2 | [criterion text] | PASS / FAIL | [specific code/test reference or explanation of gap] |
| 3 | [criterion text] | PASS / FAIL | [specific code/test reference or explanation of gap] |

### Files Check

| Expected File | Present? | Changes Correct? |
|---------------|----------|-----------------|
| [file 1] | YES / NO | YES / NO — [explanation if NO] |
| [file 2] | YES / NO | YES / NO — [explanation if NO] |

### Constraint Violations
[List any constraint violations, or "None" if all constraints respected]
- [violation 1]
- [violation 2]

### Deviations from Spec
[List any places where the implementation differs from the spec, even if it arguably works]
- [deviation 1 — description and impact]
- [deviation 2 — description and impact]

### Test Coverage Assessment
[For each acceptance criterion, is there a corresponding test?]

| Criterion | Test Exists? | Test Meaningful? | Notes |
|-----------|-------------|-----------------|-------|
| [criterion 1] | YES / NO | YES / NO | [notes] |
| [criterion 2] | YES / NO | YES / NO | [notes] |

### Verification Commands
[Commands the orchestrator should run to verify the implementation]

[command 1 — what it verifies] [command 2 — what it verifies]

### Summary
[1-3 sentences summarizing the review result]

If FAIL:
- Total criteria met: [N of M]
- Failures requiring fix: [list specific failures]
- Suggested fixes: [brief description of what needs to change]

---

Review Principles

• Binary verdicts only. Each criterion is PASS or FAIL. No "partial" or "mostly."
• Evidence required. Every PASS must reference the code or test that satisfies the criterion. Every FAIL must explain what is missing or wrong.
• Spec is the authority. If the implementation does something differently from the spec, even if the alternative seems reasonable, flag it as a deviation.
• Tests must be meaningful. A test that exists but doesn't actually verify the criterion counts as "test not meaningful" — equivalent to no test.
• No scope creep in review. Do not suggest additional features or improvements. Only check what the spec requires.

Common Failure Modes to Watch For