Imported from trieuluan/codemap (.claude/skills/codemap-subagent-driven-development/SKILL.md). Install upstream with npx skills add trieuluan/codemap --skill codemap-subagent-driven-development. Copyright stays with the author.

Subagent-Driven Development

Overview

For plans with multiple independent tasks: delegate each to a fresh implementer subagent, then run two-stage review before proceeding.

Core principle: Fresh context per task. Two-stage quality gate. Continuous execution without pausing.

When to Use

Use when:

• You have an approved plan with 2+ independent implementation tasks
• Each task can be specified clearly enough for a subagent to implement without parent context
• You want to parallelize or keep implementation context clean

Do NOT use when:

• Tasks are tightly sequential (each depends on the output of the previous)
• The task is a single coherent change best done in one pass
• You're in a debugging session (use codemap-systematic-debugging instead)

The Continuous Execution Rule

DO NOT pause between tasks to update the user.
DO NOT pause between review stages.
DO NOT ask permission to proceed to the next task.
CONTINUE autonomously until all tasks are complete or blocked.
Only stop at genuine blockers: NEEDS_CONTEXT or BLOCKED status.

The user approved the plan. Execute it.

Workflow Per Task

FOR each task in the approved plan:
  1. Write implementer prompt (see template below)
  2. Dispatch implementer subagent (forked: false — self-contained context)
  3. Receive DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED status
  4. IF DONE or DONE_WITH_CONCERNS:
       → Run spec compliance review (Stage 1)
       → Run code quality review (Stage 2)
       → If clean: continue to next task
       → If issues: fix, re-review if substantial
  5. IF NEEDS_CONTEXT:
       → Provide missing context
       → Re-dispatch implementer
  6. IF BLOCKED:
       → Stop on this task
       → Surface blocker to user
       → Continue other unblocked tasks if any

Implementer Statuses

Implementer Prompt Template

## Task

[TASK_TITLE]

## Objective

[1-3 sentences: what this task should accomplish]

## Relevant Files

[List of file paths from explore_task / search_codebase]
OR: "Use explore_task('[task keyword]') to find relevant files"

## Context

[Any specific constraints, patterns to follow, interfaces to match]

## Specification

[Exact behavior expected — inputs, outputs, edge cases]

## Definition of Done

- [ ] [Specific verifiable criterion]
- [ ] Tests pass (or behavior verified if no test suite)
- [ ] TypeScript compiles clean

## Instructions

1. Start with explore_task or search_codebase to understand current code
2. Read relevant files with get_file before editing
3. Implement the minimum to satisfy the spec
4. Verify with the smallest relevant build/test
5. End your response with one of:
   - STATUS: DONE
   - STATUS: DONE_WITH_CONCERNS — [brief description]
   - STATUS: NEEDS_CONTEXT — [what you need]
   - STATUS: BLOCKED — [what blocks you]

Stage 1: Spec Compliance Review

Dispatch BEFORE code quality review. This checks: "Did we build the right thing?"

## Spec Compliance Review

Review the following implementation against the spec.

## Spec

[Copy the exact spec and definition of done from the implementer prompt]

## Implementation

[Summary or diff of what was implemented]

## Review Questions

1. Does the implementation satisfy every item in the spec?
2. Are the Definition of Done criteria met?
3. Is anything missing or out of scope?

Return: COMPLIANT or list of spec gaps (not style/quality issues).

Stage 2: Code Quality Review

Dispatch AFTER spec compliance is confirmed. This checks: "Did we build it well?"

Use codemap-requesting-code-review for the prompt template.

Key checks for this stage:

• Logic errors and edge cases
• Error handling
• Type safety
• No regressions (use symbol(action="callers") to verify)
• Tests adequate

Model Selection

When your runtime supports model selection:

If no model selection: use the same model for all roles.

Parallelization

Independent tasks with no shared state can be dispatched in parallel:

IF task_A and task_B touch different files AND have no shared state:
  Dispatch both implementers simultaneously
  Collect both results before running reviews
  Review each independently

Do NOT parallelize if tasks touch the same files or depend on each other's output.

Example Session Flow

Plan: [Task A, Task B, Task C]

→ Dispatch implementer for Task A
← STATUS: DONE
→ Stage 1: Spec review → COMPLIANT
→ Stage 2: Quality review → LGTM
→ Dispatch implementer for Task B
← STATUS: DONE_WITH_CONCERNS — "Changed interface signature, may affect callers"
→ Stage 1: Spec review → COMPLIANT
→ Stage 2: Quality review → IMPORTANT: verify callers
→ Fix caller update, re-verify
→ Dispatch implementer for Task C
← STATUS: NEEDS_CONTEXT — "Which config format to use?"
→ Provide context: "Use JSON, matching existing .codemap/mcp.json"
→ Re-dispatch implementer for Task C
← STATUS: DONE
→ Stage 1 + Stage 2 → LGTM

→ codemap-verification-before-completion
→ codemap-finishing-a-development-branch

Related Skills

• codemap-executing-plans — for single-agent sequential plan execution (simpler)
• codemap-requesting-code-review — the quality review template
• codemap-receiving-code-review — how to handle review feedback
• codemap-verification-before-completion — final gate after all tasks complete
• codemap-finishing-a-development-branch — branch completion after all tasks done