Code Subagents

Spec Subagents

Fresh subagent per task. Two-stage review after each. Parallel when independent, sequential when dependent.

When to Use Subagents

Use when:

• Executing tasks from plan.json with subagent support available
• 2+ independent tasks that don't share state or files
• Each problem can be understood without context from others

Don't use when:

• Tasks are tightly coupled (editing the same files)
• You need to understand full system state across tasks
• Failures are related (fixing one might fix others)
• Exploratory work where the problem isn't well-defined yet

Dispatch Modes

Sequential (dependent tasks)

Tasks with dependencies execute one at a time. Each gets a fresh subagent — no context pollution from previous tasks.

Task 1 (Entity) → review → complete
Task 2 (Repository, depends on T1) → review → complete
Task 3 (Service, depends on T2) → review → complete

Parallel (independent tasks)

Independent tasks dispatch simultaneously. One agent per problem domain.

Task A (auth tests) ──→ review → complete
Task B (billing tests) ──→ review → complete    ← concurrent
Task C (notification tests) ──→ review → complete

Independence check: Would fixing Task A affect Task B? Would they edit the same files? If no to both, dispatch in parallel.

---

Prompt Templates

Use these templates when dispatching subagents. Each template is battle-tested — don't improvise, use them as-is and fill in the variables.

• [references/implementer-prompt.md](references/implementer-prompt.md) — Dispatch an implementer. Includes self-review checklist.
• [references/spec-reviewer-prompt.md](references/spec-reviewer-prompt.md) — Spec compliance review. "Do not trust the report."
• [references/code-quality-reviewer-prompt.md](references/code-quality-reviewer-prompt.md) — Code quality review. Critical/Important/Minor severity.

Prompt quality rules

• Focused — one task, one problem domain
• Self-contained — all context needed is in the prompt. Don't make the subagent

read the plan file; provide the full task text

• Specific about files — exact paths, not "the relevant files"
• Specific about output — what should the subagent return?
• Constrained — what should they NOT touch?

Common mistakes

---

Two-Stage Review

Every completed task gets two reviews in order. Do not skip either. Do not reverse the order.

Stage 1: Spec Compliance

Does the implementation match what was specified?

## Spec Review

Review the implementation against the task specification:

**Task spec:** [paste task from plan.json]

**Files changed:** [list from subagent output]

Check:
1. Are all requirements from the task spec implemented?
2. Is anything implemented that wasn't specified? (over-building)
3. Do tests cover the specified acceptance criteria?
4. Does the implementation match the design in design.md?

Report: List any gaps or extras. Mark ✅ if compliant, ❌ if not.

If the spec reviewer finds issues → the implementer subagent fixes them → spec reviewer reviews again. Repeat until ✅.

Stage 2: Code Quality

Is the implementation well-built?

## Code Quality Review

Review the implementation for code quality:

**Files changed:** [list]

Check:
1. Does the code follow existing patterns and conventions?
2. Are tests meaningful (not just asserting true)?
3. Is there unnecessary complexity?
4. Are edge cases handled?
5. Is the code clean (no dead code, no unnecessary comments)?

Rate issues as Critical (blocks merge), Important (should fix), or Minor (nice to have).

If the quality reviewer finds Critical or Important issues → implementer fixes → reviewer reviews again. Minor issues can be noted and moved past.

Why this order matters

Spec compliance first because there's no point polishing code that doesn't meet the spec. Quality second because compliant code still needs to be well-built.

---

Handling Subagent Questions

Subagents may ask questions before or during implementation. This is good — it means they're thinking rather than guessing.

• Answer clearly and completely
• Provide additional context if needed
• Don't rush them into implementation
• If the question reveals a gap in the plan, that's valuable — note it

---

Integrating Results

After subagents complete (especially parallel dispatch):

1. Read each summary — understand what changed 2. Check for conflicts — did any agents edit the same code? 3. Run full test suite — verify all changes work together 4. Update task tracking — mark tasks complete: beads bd close <id>, or harness todo list

If there are conflicts between parallel results, resolve them manually. Don't dispatch another subagent to merge — that requires too much context.

---

When Subagents Fail

If a subagent fails a task:

• Don't fix it manually — that pollutes your context
• Dispatch a fix subagent with specific instructions about what went wrong
• If it fails twice, stop and escalate to the human. The plan may need revision.

If failure reveals a design problem:

"This task is failing because [reason]. The design in design.md may need to change.

Want me to go back to spec-brainstorm?"

Code Quality Reviewer Prompt Template

Dispatch after the spec compliance review passes (✅). Verifies the implementation is well-built — clean, tested, maintainable.

Only dispatch after spec compliance is confirmed.

Template

You are reviewing code quality for Task {TASK_ID}: {TASK_NAME}

## What Was Implemented

{From implementer's report — what they built}

## Requirements Reference

Task {TASK_ID} from {PLAN_FILE_PATH}

## Diff Range

Base: {BASE_SHA} (commit before task)
Head: {HEAD_SHA} (current commit)

## Your Job

Review the implementation for quality:

1. Does the code follow existing patterns and conventions in the codebase?
2. Are tests meaningful (not just asserting true or testing mocks)?
3. Is there unnecessary complexity?
4. Are edge cases handled?
5. Is the code clean (no dead code, no unnecessary comments, clear naming)?
6. Are the right things tested at the right boundaries (unit vs integration)?

## Issue Severity

- **Critical** — Blocks merge. Bugs, security issues, broken tests, missing error handling.
- **Important** — Should fix. Magic numbers, unclear naming, missing edge cases, poor test design.
- **Minor** — Nice to have. Style preferences, minor refactors, documentation suggestions.

## Report

- **Strengths:** What was done well
- **Issues:** List with severity (Critical / Important / Minor) and file:line references
- **Assessment:** Approved, Approved with minor issues, or Changes requested

Implementer Prompt Template

Use this template when dispatching an implementer subagent. Paste the full task text from plan.json — don't make the subagent read the plan file.

Template

You are implementing Task {TASK_ID}: {TASK_NAME}

## Task Description

{FULL TEXT of task from plan.json — paste it here}

## Context

{Scene-setting: where this fits in the feature, what was built before this task,
relevant architectural decisions from design.md, existing patterns to follow}

## Before You Begin

If you have questions about:
- The requirements or acceptance criteria
- The approach or implementation strategy
- Dependencies or assumptions
- Anything unclear in the task description

**Ask them now.** Raise any concerns before starting work.

## Your Job

Once you're clear on requirements:
1. Implement exactly what the task specifies
2. Write tests following TDD (failing test → verify fail → implement → verify pass)
3. Verify implementation works
4. Commit your work
5. Self-review (see below)
6. Report back

Work from: {WORKING_DIRECTORY}

**While you work:** If you encounter something unexpected or unclear, ask questions.
It's always OK to pause and clarify. Don't guess or make assumptions.

## Before Reporting Back: Self-Review

Review your work with fresh eyes:

**Completeness:**
- Did I fully implement everything in the spec?
- Did I miss any requirements?
- Are there edge cases I didn't handle?

**Quality:**
- Is this my best work?
- Are names clear and accurate?
- Is the code clean and maintainable?

**Discipline:**
- Did I avoid overbuilding (YAGNI)?
- Did I only build what was requested?
- Did I follow existing patterns in the codebase?

**Testing:**
- Do tests actually verify behaviour (not just mock behaviour)?
- Did I follow TDD?
- Are tests comprehensive?

If you find issues during self-review, fix them before reporting.

## Report Format

When done, report:
- What you implemented
- What you tested and test results
- Files changed
- Self-review findings (if any)
- Any issues or concerns

Spec Compliance Reviewer Prompt Template

Dispatch after the implementer completes a task. Verifies the implementation matches what was specified — nothing more, nothing less.

Dispatch this BEFORE the code quality review.

Template

You are reviewing whether an implementation matches its specification.

## What Was Requested

{FULL TEXT of task requirements from plan.json}

## What Implementer Claims They Built

{From implementer's report}

## CRITICAL: Do Not Trust the Report

The implementer's report may be incomplete, inaccurate, or optimistic. You MUST verify
everything independently.

**DO NOT:**
- Take their word for what they implemented
- Trust their claims about completeness
- Accept their interpretation of requirements

**DO:**
- Read the actual code they wrote
- Compare actual implementation to requirements line by line
- Check for missing pieces they claimed to implement
- Look for extra features they didn't mention

## Your Job

Read the implementation code and verify:

**Missing requirements:**
- Did they implement everything that was requested?
- Are there requirements they skipped or missed?
- Did they claim something works but didn't actually implement it?

**Extra/unneeded work:**
- Did they build things that weren't requested?
- Did they over-engineer or add unnecessary features?
- Did they add "nice to haves" that weren't in spec?

**Misunderstandings:**
- Did they interpret requirements differently than intended?
- Did they solve the wrong problem?
- Did they implement the right feature but the wrong way?

**Verify by reading code, not by trusting the report.**

## Report

- ✅ Spec compliant (if everything matches after code inspection)
- ❌ Issues found: [list specifically what's missing or extra, with file:line references]