subagent-driven-development

Files (7)

• SKILL.md
• examples.md
• implementer-prompt.md
• review-package · scripts/
• sdd-workspace · scripts/
• task-brief · scripts/
• task-reviewer-prompt.md

SKILL.md (first lines)

# Subagent-Driven Development

Execute TSP by dispatching a fresh implementer subagent per task, a task review (spec compliance + code quality) after each, and a broad whole-branch review at the end.

**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 + task review (spec + quality) + broad final review = high quality, fast iteration

See [examples.md](examples.md#narration) for narration-style guidance.

**Continuous execution:** Do not pause to check in with your human partner between tasks. Execute all tasks from the TSP without stopping. The only reasons to stop are: BLOCKED status you cannot resolve, ambiguity that genuinely prevents progress, or all tasks complete. "Should I continue?" prompts and progress summaries waste their time — they asked you to execute the TSP, so execute it.

See [examples.md](examples.md#when-to-use) for the decision diagram on when
to use this skill vs. executing-plans vs. manual execution.

See [examples.md](examples.md#the-process) for the full per-task workflow
diagram.

See [examples.md](examples.md#pre-flight-tsp-review) for the Pre-Flight TSP
Review scan-for-conflicts step.

See [examples.md](examples.md#model-selection) for model-tier selection
guidance across implementer and reviewer roles.

Resolve `SDD_SCRIPTS` to this installed skill's absolute `scripts` directory.
Run helpers from the **target worktree**, not the plugin directory: they use
the current Git repository to locate the plan's records. Resolve `PLAN_FILE`
against that target worktree.

## Handling Implementer Status

Implementer subagents report one of four statuses. Handle each appropriately:

**DONE:** Generate the review package (`bash "$SDD_SCRIPTS/review-package" PLAN_FILE BASE HEAD` — stdout is the file path; BASE is the commit you recorded before dispatching the implementer — never `HEAD~1`, which silently drops all but the last commit of a multi-commit task), then dispatch the task reviewer with that path. A rejected range is a finding to investigate, not a clean review.

See [examples.md](examples.md#done_with_concerns) for handling DONE_WITH_CONCERNS.

**NEEDS_CONTEXT:** The implementer needs information that wasn't provided. Provide the missing context and re-dispatch.

**BLOCKED:** The implementer cannot complete the task. Assess the blocker:
1. If it's a context problem, provide more context and re-dispatch with the same model
2. If the task requires more reasoning, re-dispatch with a more capable model
3. If the task is too large, break it into smaller pieces
4. If the TSP itself is wrong, escalate to the human

**Never** ignore an escalation or force the same model to retry without changes. If the implementer said it's stuck, something needs to change.

## Handling Reviewer ⚠️ Items

The task reviewer may report "⚠️ Cannot verify from diff" items — requirements
that live in unchanged code or span tasks. These do not block the rest of the
review, but you must resolve each one yourself before marking the task
complete: you hold the TSP and cross-task context the reviewer
lacks. If you confirm an item is a real gap, treat it as a failed spec
review — send it back to the implementer and re-review.

## Bounded Fix Rounds

Keep the implementer's identity in the plan ledger. A fix round is one repair
and its re-review. Resume that implementer with the open findings and named
covering tests; when resuming is unavailable, give a fresh worker the task
brief, existing report, and findings. A worker that is stuck needs new context,
a smaller task, or a capability escalation, not the same request repeated.

Record `FIX_BASE` as the revision the reviewer last saw. Review the new
`FIX_BASE..HEAD` package against the open findings and check for breakage caused
by the fix, including affected callers. Carry unrelated observations to the
final review; do not reopen unchanged code as a new full task review. Existing
test evidence for unchanged code remains usable; changed code needs new evidence.

After each round, record:

`Task N: fix round R/3 | commits | addressed findings | open findings | test evidence`

After **three unsuccessful rounds**, stop automatic fix dispatches. Keep the
task **blocked/incomplete**, record the remaining findings and attempted fixes,
and present the next proposed approach to your human partner. Resume only with
a resolved blocker or a new agreed approach; record that decision before a new
bounded attempt. A retry limit never makes an unresolved Critical/Important
finding complete, and dependent tasks stay blocked. Minor observations are
recorded for final review rather than extending this loop.

Apply the same bound to final-review repairs, grouping substantive findings
into one fix dispatch per round. Preserve every unresolved finding in the
handoff; do not present the branch as ready to merge while any remain.

## Constructing Reviewer Prompts

Per-task reviews are task-scoped gates. The broad review happens once, at the
final whole-branch review. When you fill a reviewer template:

- Do not add open-ended directives like "check all uses" or "run race tests
  if useful" without a concrete, task-specific reason
- Do not ask a reviewer to re-run tests the implementer already ran on the
  same code — the implementer's report carries the test evidence
- Do not pre-judge findings for the reviewer — never instruct a reviewer to
  ignore or not flag a specific issue. If you believe a finding would be a
  false positive, let the reviewer raise it and adjudicate it in the review
  loop. If the prompt you are writing contains "do not flag," "don't treat X
  as a defect," "at most Minor," or "the TSP chose" — stop: you are
  pre-judging, usually to spare yourself a review loop.
- See [examples.md](examples.md#global-constraints-block) for guidance on
  the global-constraints block.
- Hand the reviewer its diff as a file: run this skill's
  `bash "$SDD_SCRIPTS/review-package" PLAN_FILE BASE HEAD` and pass the reviewer the file path
  it prints (or, without bash: `git log --oneline`, `git diff --stat`,
  and `git diff -U10` for the range, redirected to one uniquely named
  file). The output never enters your own context, and the reviewer sees
  the commit list, stat summary, and full diff with context in one Read
  call. Use the BASE you recorded before dispatching the implementer —
  never `HEAD~1`, which silently truncates multi-commit tasks.
- A dispatch prompt describes one task, not the session's history. Do not
  paste accumulated prior-task summaries ("state after Tasks 1-3") into
  later dispatches — a real session's dispatch hit 42k chars of which 99%
  was pasted history. A fresh subagent needs its task, the interfaces it
  touches, and the global constraints. Nothing else.
- Dispatch fix subagents for Critical and Important findings. Record Minor
  findings in the progress ledger as you go, and point the final
  whole-branch review at that list so it can triage which must be fixed

From HundredBillion/dmi_superpowers, MIT.

More from HundredBillion/dmi_superpowers