wz-subagent-driven-development

name	wz:subagent-driven-development
description	Use when executing implementation plans with independent tasks in the current session

Real talk: the pipeline steps aren't suggestions. Check .wazir/runs/latest/phases/ for your current checklist and work through it. Use wz: skills when they apply — that's not optional. What phase are you starting?

Subagent-Driven Development

Command Routing

Follow the Canonical Command Matrix in hooks/routing-matrix.json.

• Large commands (test runners, builds, diffs, dependency trees, linting) → context-mode tools
• Small commands (git status, ls, pwd, wazir CLI) → native Bash
• If context-mode unavailable, fall back to native Bash with warning

Codebase Exploration

1. Query wazir index search-symbols <query> first
2. Use wazir recall file <path> --tier L1 for targeted reads
3. Fall back to direct file reads ONLY for files identified by index queries
4. Maximum 10 direct file reads without a justifying index query
5. If no index exists: wazir index build && wazir index summarize --tier all

Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.

Why subagents: You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.

Core principle: Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration

When to Use

digraph when_to_use {
    "Have implementation plan?" [shape=diamond];
    "Tasks mostly independent?" [shape=diamond];
    "Stay in this session?" [shape=diamond];
    "subagent-driven-development" [shape=box];
    "executing-plans" [shape=box];
    "Manual execution or brainstorm first" [shape=box];

    "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
    "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
    "Tasks mostly independent?" -> "Stay in this session?" [label="yes"];
    "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
    "Stay in this session?" -> "subagent-driven-development" [label="yes"];
    "Stay in this session?" -> "executing-plans" [label="no - parallel session"];
}

vs. Executing Plans (parallel session):

• Same session (no context switch)
• Fresh subagent per task (no context pollution)
• Two-stage review after each task: spec compliance first, then code quality
• Faster iteration (no human-in-loop between tasks)

The Process

digraph process {
    rankdir=TB;

    subgraph cluster_per_task {
        label="Per Task";
        "Capture PRE_TASK_SHA" [shape=box];
        "Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
        "Implementer subagent asks questions?" [shape=diamond];
        "Answer questions, provide context" [shape=box];
        "Implementer subagent implements, tests, commits, self-reviews" [shape=box];
        "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [shape=box];
        "Spec reviewer subagent confirms code matches spec?" [shape=diamond];
        "Implementer subagent fixes spec gaps" [shape=box];
        "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [shape=box];
        "Code quality reviewer subagent approves?" [shape=diamond];
        "Implementer subagent fixes quality issues" [shape=box];
        "Mark task complete in TodoWrite" [shape=box];
    }

    "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
    "More tasks remain?" [shape=diamond];
    "Dispatch final code reviewer subagent for entire implementation" [shape=box];
    "Use wz:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];

    "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Capture PRE_TASK_SHA";
    "Capture PRE_TASK_SHA" -> "Dispatch implementer subagent (./implementer-prompt.md)";
    "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";
    "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
    "Answer questions, provide context" -> "Implementer subagent implements, tests, commits, self-reviews";
    "Implementer subagent asks questions?" -> "Implementer subagent implements, tests, commits, self-reviews" [label="no"];
    "Implementer subagent implements, tests, commits, self-reviews" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)";
    "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" -> "Spec reviewer subagent confirms code matches spec?";
    "Spec reviewer subagent confirms code matches spec?" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="yes"];
    "Spec reviewer subagent confirms code matches spec?" -> "Implementer subagent fixes spec gaps" [label="no"];
    "Implementer subagent fixes spec gaps" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)";
    "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?";
    "Code quality reviewer subagent approves?" -> "Mark task complete in TodoWrite" [label="yes"];
    "Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"];
    "Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)";
    "Mark task complete in TodoWrite" -> "More tasks remain?";
    "More tasks remain?" -> "Capture PRE_TASK_SHA" [label="yes"];
    "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
    "Dispatch final code reviewer subagent for entire implementation" -> "Use wz:finishing-a-development-branch";
Sanity check: are you still using wz: skills where they apply, or did you start doing things manually because it felt faster? The skills exist for consistency, not convenience. Which skill should you be using right now?
}

Code Review Scoping

The implementer subagent commits before review. The spec reviewer and code quality reviewer must use codex review --base <pre-task-sha> to scope their review to the task's changes. Capture PRE_TASK_SHA=$(git rev-parse HEAD) before dispatching the implementer.

Review Loop Alignment

Both review stages follow the review loop pattern in docs/reference/review-loop-pattern.md with explicit --mode task-review:

• Spec compliance review: Uses spec dimensions with --mode task-review
• Code quality review: Uses 5 task-execution dimensions with --mode task-review

Review logs use task-scoped filenames: execute-task-<NNN>-review-pass-<N>.md

Each review stage respects the loop cap via wazir capture loop-check --task-id <NNN>. If the cap is reached (exit 43), escalate to the controller (you) for a decision.

Codex Error Handling

If codex exits non-zero during review, log the error, mark the pass as codex-unavailable, and use self-review findings only. Do not treat a Codex failure as a clean pass.

Standalone mode: When no .wazir/runs/latest/ exists, review logs go to docs/plans/.

Prompt Templates

• ./implementer-prompt.md - Dispatch implementer subagent
• ./spec-reviewer-prompt.md - Dispatch spec compliance reviewer subagent
• ./code-quality-reviewer-prompt.md - Dispatch code quality reviewer subagent

Advantages

vs. Manual execution:

• Subagents follow TDD naturally
• Fresh context per task (no confusion)
• Parallel-safe (subagents don't interfere)
• Subagent can ask questions (before AND during work)

vs. Executing Plans:

• Same session (no handoff)
• Continuous progress (no waiting)
• Review checkpoints automatic

Efficiency gains:

• No file reading overhead (controller provides full text)
• Controller curates exactly what context is needed
• Subagent gets complete information upfront
• Questions surfaced before work begins (not after)

Quality gates:

• Self-review catches issues before handoff
• Two-stage review: spec compliance, then code quality
• Review loops ensure fixes actually work
• Spec compliance prevents over/under-building
• Code quality ensures implementation is well-built

Cost:

• More subagent invocations (implementer + 2 reviewers per task)
• Controller does more prep work (extracting all tasks upfront)
• Review loops add iterations
• But catches issues early (cheaper than debugging later)

Red Flags

Never:

• Start implementation on main/master branch without explicit user consent
• Skip reviews (spec compliance OR code quality)
• Proceed with unfixed issues
• Dispatch multiple implementation subagents in parallel (conflicts)
• Make subagent read plan file (provide full text instead)
• Skip scene-setting context (subagent needs to understand where task fits)
• Ignore subagent questions (answer before letting them proceed)
• Accept "close enough" on spec compliance (spec reviewer found issues = not done)
• Skip review loops (reviewer found issues = implementer fixes = review again)
• Let implementer self-review replace actual review (both are needed)
• Start code quality review before spec compliance is PASS (wrong order)
• Move to next task while either review has open issues
• Review the wrong diff -- always scope to the current task's changes using --base

If subagent asks questions:

• Answer clearly and completely
• Provide additional context if needed
• Don't rush them into implementation

If reviewer finds issues:

• Implementer (same subagent) fixes them
• Reviewer reviews again
• Repeat until approved
• Don't skip the re-review

If subagent fails task:

• Dispatch fix subagent with specific instructions
• Don't try to fix manually (context pollution)

Last check: did you use every applicable wz: skill, or did you handle things manually that should have gone through a skill? Be specific about which skills you used and which you decided to skip. Why did you skip them?