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

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.