| name | tgd-subagent-driven-development |
| description | Execute implementation plans by dispatching fresh subagents per task with two-stage review. Use when executing a multi-task implementation plan, when context is getting too long for quality output, or when you want maximum isolation between tasks. |
Subagent-Driven Development
Overview
Execute implementation plans by dispatching fresh subagents per task with two-stage review: spec compliance first, then code quality.
Core Principle: Fresh subagent per task + two-stage review = high quality, fast iteration
Why Subagents:
- Each task gets a clean context window — no pollution from prior tasks
- Subagents receive precisely crafted instructions — focus and success
- Your main context is preserved for coordination — you stay in control
- Quality doesn't degrade as context grows — every task starts fresh
When to Use
- Executing a multi-task implementation plan (TASKS.md)
- Context is getting long and output quality is degrading
- Tasks are mostly independent (can be executed sequentially)
- You want the highest quality output per task
When NOT to use:
- Single, small changes (use
tgd-incremental-implementation instead)
- Tasks that are tightly coupled and need constant cross-reference
- Exploration/prototyping where you don't have a plan yet
The Process
Read TASKS.md
│
▼
┌─ For each task ──────────────────────────────────────┐
│ │
│ 1. Dispatch implementer subagent │
│ - Provide: task spec, relevant files, context │
│ - Subagent implements, tests, commits │
│ │
│ 2. Dispatch spec reviewer subagent │
│ - Provide: task spec + subagent's output │
│ - Checks: does code match the spec? │
│ - If NO → fix round (see Review FAIL loop below) │
│ │
│ 3. Dispatch code quality reviewer subagent │
│ - Provide: code diff + quality checklist │
│ - Checks: readability, patterns, test quality │
│ - If NO → fix round (see Review FAIL loop below) │
│ │
│ 4. Flip the task's **Status:** line to `complete` │
│ in TASKS.md (+ backfill Test: fields) │
│ │
└───────────────────────────────────────────────────────┘
│
▼
Final review of entire implementation
Review FAIL loop (bounded): the original implementer subagent is gone —
fresh context is the point. On FAIL, the orchestrator dispatches a NEW
implementer subagent with the same task spec PLUS the reviewer's specific
FAIL list. Maximum two fix rounds per review stage. If the third review
still FAILs, do not keep ping-ponging: set the task's **Status:** blocked: review deadlock — <one-line summary> in TASKS.md, record the disagreement
under ## Risks & Mitigations, and move to the next task. A deadlock usually
means the spec is ambiguous — that's a human call, not a longer loop.
Continuous Execution
Do not pause to check in between tasks. Execute all tasks from the plan without stopping.
Only reasons to stop:
- BLOCKED status you cannot resolve
- Ambiguity that genuinely prevents progress
- All tasks complete
Never: Use "Should I continue?" prompts or progress summaries — waste the user's time.
Subagent Prompts
Implementer Prompt Template
You are implementing a single task from an implementation plan.
WORKING DIRECTORY:
{worktree_path} ← all reads, writes, and commands happen HERE
(the isolated worktree, not the main checkout;
for a [repo-name]-tagged task this is THAT repo's
worktree — ../project-<feature>-<repo-name>)
TASK:
{task_description_including_AC_ids}
RELEVANT FILES:
{file_list}
CONTEXT:
{relevant_context}
RULES:
1. Implement exactly what the task specifies — nothing more, nothing less
2. Write tests before code (TDD Red-Green-Refactor)
3. Every test verifying a criterion MUST mention its AC-<task>.<n> id in
the test name, docstring, or a comment — this is machine-checked later
4. Commit when the task is complete with a clear commit message
5. Do NOT modify files outside your task scope
6. If you encounter ambiguity, state it clearly and stop
7. If you find a bug OUTSIDE your task scope: do NOT fix it — report it
in your output (file, symptom, suspected cause) and keep going. The
orchestrator decides whether it becomes a new task.
EXPECTED OUTPUT:
- Code changes committed
- Tests written and passing
- For EACH acceptance criterion: the AC id and the test file path that
verifies it (the orchestrator records these in TASKS.md Test: fields)
- Out-of-scope bugs found, if any (file + symptom + suspected cause)
- Brief summary of what was done
Orchestrator duty after each implementer completes: take the AC-id → test-path
pairs from the output and backfill the Test: fields in
$TGD_DIR/<feature-name>/TASKS.md, then flip that task's **Status:** line
from in-progress to complete. If the output reports out-of-scope bugs, record
each under ## Risks & Mitigations (or add a new task if it must be fixed this
cycle) — do NOT let the report evaporate. Subagents cannot reliably write
outside the worktree — the orchestrator owns the artifacts directory.
Orchestrator duty after each review stage: record the outcome in the task's
Spec-Review: / Quality-Review: fields in TASKS.md — PASS — <one line> or
FAIL — <one line> (after a FAIL: implementer fixes, the stage re-runs, then
flip to PASS). If you cannot dispatch reviewer subagents, run both review
stages INLINE against their prompt templates — inability to delegate never
skips a stage — and record the fields the same way. /tgd-verify fails closed
on a completed task whose review fields still read pending.
Spec Reviewer Prompt Template
You are reviewing code for spec compliance.
TASK SPEC:
{task_description}
CODE CHANGES:
{diff_or_file_list}
CHECK:
1. Does the code implement everything the spec requires?
2. Are there any spec requirements that were missed?
3. Does the code do anything NOT in the spec? (scope creep)
4. Are edge cases from the spec handled?
OUTPUT:
- PASS: Code matches spec
- FAIL: List specific gaps between spec and implementation
Code Quality Reviewer Prompt Template
You are reviewing code for quality.
CODE CHANGES:
{diff_or_file_list}
CHECK:
1. Readability: Is the code clear and well-structured?
2. Patterns: Does it follow existing codebase conventions?
3. Test quality: Are tests meaningful (not just for coverage)?
4. Error handling: Are failure cases handled?
5. Performance: Any obvious performance issues?
6. Security: Any obvious security issues?
OUTPUT:
- PASS: Code meets quality standards
- FAIL: List specific issues with severity (critical/important/nit)
Integration with tGD
This skill is invoked by /tgd-develop when executing a task plan. It replaces the default single-session execution with subagent-based execution for higher quality.
Trigger conditions:
- TASKS.md exists with multiple tasks
- Tasks are mostly independent
- User wants maximum quality (not maximum speed)
Fallback: If subagent delegation is not available, fall back to tgd-incremental-implementation.
Common Rationalizations
| Rationalization | Reality |
|---|
| "I'll just do it in this session" | Context pollution degrades quality per task |
| "Subagents will mess it up" | Fresh context + clear spec = higher quality |
| "Two-stage review is overkill" | Spec compliance + code quality catch different bugs |
| "It's faster without review" | Faster now, slower when bugs surface later |
Red Flags
- Subagent output claims "done" without showing diff or test results
- Skipping spec review and going straight to code review
- Modifying files outside the task scope
- Implementer and reviewer getting the same overly broad context
- Reviewer passes without listing specific checks performed
Verification
