Subagent-Driven Task Execution

Execute specs with proper TDD: tester writes failing tests, implementer makes them pass, reviewers validate.

Core principle: Three-phase batches with fresh subagents. No batch completes without review.

When to Use

Use when:

• Executing an implementation spec (created with spec-create)
• Tasks are mostly independent
• Want TDD enforcement with quality gates

Don't use when:

• No spec exists yet (use spec-validate → spec-create first)
• Tasks are tightly coupled (manual execution better)
• Single small task (just do it directly)
• Initiative spec has failed gates (resolve first via /clarify)

The Three-Phase Pipeline

Each batch executes three phases. A batch is NOT complete until all three phases finish.

┌─────────────────────────────────────────────────────────────────┐
│                         BATCH N                                 │
├─────────────────────────────────────────────────────────────────┤
│  Phase A: TESTERS (parallel)                                    │
│  ├── Dispatch N task-tester subagents (opus)                    │
│  ├── Each writes failing tests (RED)                            │
│  └── Wait for ALL testers                                       │
│                          ↓                                      │
│  Phase B: IMPLEMENTERS (parallel)                               │
│  ├── Dispatch N task-implementer subagents (opus)               │
│  ├── Each receives its tester's report                          │
│  ├── Each makes tests pass (GREEN)                              │
│  └── Wait for ALL implementers                                  │
│                          ↓                                      │
│  Phase C: REVIEWERS (parallel)                                  │
│  ├── Dispatch 1 native Claude reviewer (opus) [required]        │
│  ├── Dispatch 0-N OpenCode reviewers (from validation.yaml)     │
│  ├── Each reviews ALL changes from batch                        │
│  ├── Wait for ALL reviewers                                     │
│  └── Synthesize feedback                                        │
│                          ↓                                      │
│  Gate: Issues found?                                            │
│  ├── Critical/High → Fix before proceeding                      │
│  └── None/Medium → Commit and continue                          │
└─────────────────────────────────────────────────────────────────┘

CRITICAL: All three phases are mandatory. Reviewers are not optional.

Workflow

1. Load Spec and Populate TodoWrite

1. Find most recent spec in ./specs/active/*/
2. Read tasks.yaml from that directory
3. Parse tasks with status: pending or status: in_progress
4. Create TodoWrite with ALL uncompleted tasks:
   • First uncompleted task: "in_progress"
   • Others: "pending"
   • content: task text
   • activeForm: present continuous form

CRITICAL: Always populate TodoWrite before dispatching any subagents.

5. Create/checkout spec branch:
   • Branch name: feat/<spec-directory-name>
   • If branch exists, checkout and pull
   • If not, create from main/master

2. Pre-Implementation Gate Check

Before dispatching any tasks, verify validation.yaml gates:

1. Read validation.yaml from spec directory
2. Check metadata.issue_type
3. If Initiative:
   • Check all gates in gates section
   • If any gate has status: failed:
     • Report which gates failed with reasons
     • Prompt: "Resolve via /clarify or proceed anyway?"
     • If user chooses to proceed: document override in validation.yaml
   • Check markers section for status: open
   • If blocking markers exist:
     • Report marker count and summaries
     • Prompt: "Resolve markers first or proceed?"
4. If Feature/Task: Skip gate check (gates marked n/a)

3. Analyze Task Dependencies

Parse dependencies.yaml to identify execution batches:

Dependency rules:

• Tasks in Phase N depend on Phase N-1 completion
• Tasks with [P] marker AND different file paths can run in parallel
• Tasks with same file path must run sequentially
• Phase boundaries force batch breaks

4. Execute Batches (Three-Phase Pipeline)

For each batch, execute ALL THREE phases:

Phase A: Dispatch Testers

Single task:

Dispatch 1 task-tester (opus) → wait for completion

Parallel batch (N tasks):

Dispatch N task-testers in SINGLE message → wait for ALL

Each tester:

• Invokes code-test skill
• Writes failing tests (RED)
• Reports: test paths, failure output

Phase B: Dispatch Implementers

Single task:

Dispatch 1 task-implementer (opus) with tester report → wait for completion

Parallel batch (N tasks):

Dispatch N task-implementers in SINGLE message → wait for ALL
Each receives its corresponding tester's report

Each implementer:

• Invokes code-implement skill
• Makes tests pass (GREEN)
• Reports: impl files, test pass output

Phase C: Dispatch Reviewers

CRITICAL: Reviewers are mandatory. Every batch gets reviewed.

Get batch diff before dispatching:

# Diff of changes made in this batch (since last batch commit)
git diff <last_batch_commit>..HEAD

Always dispatch ALL reviewers in a SINGLE message for true parallelism:

Dispatch:
  - 1 native Claude reviewer (task-reviewer, opus) [required]
  - 0-N OpenCode reviewers (models from validation.yaml)
→ Wait for ALL reviewers

Each reviewer:

• Invokes code-review --diff (batch diff, not full files)
• Reviews the diff of changes from this batch
• Checks against spec requirements for batch tasks
• Produces YAML report with issues by severity

Review prompt includes:

1. Git diff of batch changes (not full files)
2. Implementer reports (what was done)
3. Task specs from tasks.yaml (what was required)

Reviewer dispatch configuration:

CRITICAL: Dispatch ALL reviewers in a SINGLE message for true parallelism.

# Single message with multiple tool calls:

# 1. Native Claude reviewer (Task tool) [required]
Task(
  subagent_type="task-reviewer",
  model={claude_model},  # from review_config (opus)
  prompt=review_prompt   # includes: batch diff + implementer reports + task specs
)

# 2. OpenCode reviewers (Bash tool, background) [from validation.yaml]
Bash(run_in_background=true):
  timeout 1200 opencode run --model "openai/gpt-5.2-codex" --variant {reasoning_effort}-medium "{review_prompt}"

Bash(run_in_background=true):
  timeout 1200 opencode run --model "google/gemini-3-pro-preview" --variant {reasoning_effort}-medium "{review_prompt}"

All models and reasoning effort are configured in validation.yaml under review_config.

5. Synthesize Review Feedback and Write review.yaml

After ALL reviewers complete:

1. Parse reports - Extract YAML from all reviewer outputs
2. Merge issues:
   • Deduplicate by description similarity
   • Combine issues flagged by multiple reviewers (higher confidence)
   • Note which reviewer(s) found each issue
3. Aggregate severity:
   • Issue severity is the HIGHEST across all reviewers
   • Critical by any reviewer = Critical overall
4. Write review.yaml (append batch review):
   yamlCopy

   # ./specs/active/<spec>/review.yaml
   batch_reviews:
     - batch: <N>
       timestamp: <ISO_TIMESTAMP>
       commit: <SHA>
       tasks: [T001, T002]
       reviewers:
         - id: claude-opus
           status: completed
           gates: { correctness: pass, style: pass, ... }
         - id: opencode-codex
           status: completed | timeout | failed
           gates: { ... }
       synthesized:
         gates: { correctness: pass, style: fail, ... }
         critical_issues: <N>
         high_issues: <N>
         medium_issues: <N>
       outcome: approved | changes_requested
   issues:
     critical: [...]
     high: [...]
     medium: [...]
   deferred_issues: [...]  # medium severity
   

5. Present unified feedback:
   • Gate summary table
   • Issues grouped by severity
   • Show which reviewers found each issue

Gate Summary Table:

| Gate         | Claude | Codex  | Gemini |
|--------------|--------|--------|--------|
| Correctness  | pass   | fail   | pass   |
| Style        | pass   | pass   | pass   |
| Performance  | pass   | pass   | pass   |
| Security     | fail   | pass   | fail   |
| Architecture | pass   | pass   | pass   |

6. Apply Review Feedback

If Critical/High issues found:

1. Dispatch fix subagent(s) (task-implementer, opus)
2. Verify fixes with targeted review
3. Update review.yaml with resolution
4. Only proceed when issues resolved

If only Medium issues:

1. Add to review.yaml deferred_issues
2. Proceed to commit

7. Commit, Checkpoint, and Continue

When batch completes successfully (all phases, review passed):

1. Update TodoWrite (mark tasks as "completed")
2. Edit tasks.yaml: Change status: in_progress to status: completed
3. Write checkpoint.yaml (enables session recovery):
   yamlCopy

   checkpoint:
     spec_name: <spec>
     spec_path: ./specs/active/<spec>
     branch: feat/<spec>
     timestamp: <ISO_TIMESTAMP>
     last_batch: <N>
     last_commit: <SHA>
     tasks:
       completed: [...]
       pending: [...]
     next_batch:
       number: <N+1>
       tasks: [...]
     deferred_issues: [...]  # medium severity, noted for later
     review_config:
       reviewers: [...]  # from validation.yaml
   

4. Commit the batch changes:
   • Stage: implementation + tests + tasks.yaml + checkpoint.yaml + review.yaml
   • Commit message format:
     Copy

     <type>(<scope>): <description>
     
     Tasks: <task-ids>
     Batch: <N>/<total>
     

   • Example: feat(cache): add TTL expiry\n\nTasks: PH2-003, PH2-004\nBatch: 2/5
5. Move to next batch (or use /continue in new session)

8. Final Review

After ALL batches complete, invoke code-review skill in final mode:

/code.review --final <spec-name>

Or dispatch multi-reviewer pass directly:

Dispatch (in same message):
  - 1 native Claude reviewer (opus) [required]
  - 0-N OpenCode reviewers (from validation.yaml)

Final review checks:

• All spec requirements met (cross-reference spec.md)
• All tasks complete (verify tasks.yaml)
• Acceptance criteria satisfied
• Overall architecture sound
• Deferred issues addressed or documented
• Tests passing

Write final_review section in review.yaml:

final_review:
  status: completed
  timestamp: <ISO_TIMESTAMP>
  reviewers: [claude-opus, opencode-codex, ...]
  gates: { correctness: pass, style: pass, ... }
  spec_compliance:
    all_tasks_complete: true
    acceptance_criteria_met: true
    edge_cases_handled: true
  issues: [...]
  strengths: [...]
  overall_assessment: "Implementation complete and verified"
  recommendation: ready_to_merge | changes_requested
readiness:
  all_batches_reviewed: true
  critical_issues_resolved: true
  high_issues_resolved: true
  final_review_passed: true
  tests_passing: true

Subagent Configuration

CRITICAL: Always specify model: opus for testers, implementers, and reviewers.

Quality Gates

Red Flags

Never:

• Skip the tester phase (implementer must receive failing tests)
• Skip the reviewer phase (every batch must be reviewed)
• Use sonnet for subagents (always opus)
• Dispatch parallel subagents on same file
• Let implementer write tests (tester's job)
• Ignore failed pre-impl gates for Initiatives
• Batch commits across multiple batches

If tester can't write tests:

• Don't skip to implementer
• Handle the gap (consult spec, ask user)
• Re-dispatch tester with clarification

If reviewers timeout:

• Continue with available reviews (minimum 1)
• Note partial results in output
• Consider re-running batch

Example Workflow

[Load spec, create TodoWrite, checkout branch]

Batch 1: Task 1 (single task)
├── Phase A: Dispatch tester (opus)
│   └── Tester: Wrote 3 tests, all failing (RED)
├── Phase B: Dispatch implementer (opus) + tester report
│   └── Implementer: Made tests pass (GREEN)
├── Phase C: Dispatch reviewers (3 in parallel)
│   ├── Claude: approved, no issues
│   ├── Codex: approved, 1 minor issue
│   └── Gemini: approved, no issues
├── Synthesize: 1 minor issue (note for later)
└── Commit: feat(cache): add caching layer

Batch 2: Tasks 2, 3, 4 ([P] parallel batch)
├── Phase A: Dispatch 3 testers (single message)
│   └── All testers complete with failing tests
├── Phase B: Dispatch 3 implementers (single message)
│   └── All implementers complete, tests passing
├── Phase C: Dispatch reviewers (3 in parallel)
│   ├── Claude: changes_requested, 1 critical
│   ├── Codex: changes_requested, 1 critical (same issue)
│   └── Gemini: approved
├── Synthesize: 1 critical issue (found by 2 reviewers)
├── Fix: Dispatch fix subagent → verify
└── Commit: feat(api): add endpoints for tasks 2, 3, 4

...

[Final review - 3 reviewers in parallel]
All requirements met

Integration

Use with:

• spec-validate → spec-create - Create spec before dispatch
• clarify - Resolve markers/gates before dispatch
• code-test - Tester invokes for TDD methodology
• code-implement - Implementer invokes for language guidelines
• code-review - Reviewer invokes for review methodology
• task-completion-verify - Verify before claiming done

Reference

• subagent-workflow.md - Dispatch templates and YAML reports
• report.md - YAML report schemas
• checkpoint-format.md - Session checkpoint schema
• review.md - Implementation review schema (review.yaml)
• roles/tester.md - Test-writing subagent
• roles/implementer.md - Implementation subagent
• roles/reviewer.md - Review subagent