hermes-skills/subagent-driven-development/SKILL.md

---
name: subagent-driven-development
description: "Execute plans with fresh subagents per task and review."
version: 1.0.0
author: Hermes Agent (adapted from obra/superpowers)
license: MIT
platforms: [linux]
metadata:
  hermes:
    tags: [subagent, delegation, review, execution, sdd]
    related_skills: [create-plan, brainstorming, verification-before-completion]
---

# Subagent-Driven Development

Execute plan 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

**Continuous execution:** Do not pause to check in with your human partner between tasks. Execute all tasks from the plan without stopping. The only reasons to stop are: BLOCKED status you cannot resolve, ambiguity that genuinely prevents progress, or all tasks complete.

## When to Use

- You have an implementation plan with independent tasks
- Tasks can be worked on without shared state
- You want review gates between tasks
- Same session execution (vs dispatching to separate sessions)

## The Process

### Setup

- Read the plan once, note its context and Global Constraints
- Create a todo per task
- Before dispatching Task 1, scan the plan for conflicts: tasks that contradict each other, anything the plan mandates that the review would flag as a defect
- Present conflicts to the user as one batched question before execution begins

### Model Selection

Use the least powerful model that can handle each role:

- Mechanical implementation (isolated functions, clear specs, 1-2 files): cheap model
- Integration and judgment (multi-file coordination, pattern matching): standard model
- Architecture and design: most capable model
- Review tasks: scaled to diff size, complexity, and risk
- Fix-loop rounds 4-5: model at least one tier above the implementer

Always specify the model explicitly when dispatching a subagent.

### 1. Dispatch the Implementer

- Task brief: extract the task's full text, make it the single source of requirements
- Compose dispatch with: (1) one line on where this task fits, (2) the brief path, (3) interfaces from earlier tasks, (4) resolution of any ambiguity, (5) report-file path
- Never make a subagent read the whole plan file
- Never dispatch multiple implementation subagents in parallel (conflicts)

### 2. Handle the Report

Implementer subagents report one of four statuses:

- DONE: Generate review package, dispatch task reviewer
- DONE_WITH_CONCERNS: Read concerns before proceeding. If about correctness/scope, address before review. If observations, note and proceed.
- NEEDS_CONTEXT: Provide missing context and re-dispatch
- BLOCKED: Assess — context problem (re-dispatch), needs more reasoning (more capable model), too large (break into pieces), plan wrong (escalate to user)

### 3. Review the Task

Per-task reviews are task-scoped gates. Two verdicts required: spec compliance AND task quality.

- Hand the reviewer a diff file (never paste diffs into context)
- Reviewer inputs: brief file, report file, review package, global constraints
- Do not pre-judge findings — never instruct a reviewer to ignore a specific issue
- The reviewer may report "Cannot verify from diff" items — resolve these yourself

### 4. The Fix Loop

Triggers when review reports spec failure, Critical, or Important findings. Five rounds maximum per task:

- Rounds 1-3: Resume the original implementer with open findings verbatim
- Rounds 4-5: Fresh implementer on a more capable model
- Every round: implementer fixes, re-runs tests, appends fix report
- Re-review is scoped: only verify findings were addressed, flag new breakage in fix diff
- Minor findings go to the ledger, never enter the loop

**The breaker (round 5):** Adjudicate each open finding:
- Reviewer wrong or contestable: park with ruling
- Real but nothing downstream builds on it: park with ruling
- Real and load-bearing: STOP, report BLOCKED to user

### 5. Complete the Task

When review is clean or all open findings are parked at the cap, mark complete and move to next task.

## Final Review

After all tasks: dispatch final whole-branch review on the most capable model. If findings: ONE fix subagent with complete findings list, then ONE scoped re-review. Adjudicate residuals. No second fix wave.

## Common Rationalizations

| Excuse | Reality |
|--------|---------|
| "Close enough on spec compliance" | Reviewer found spec gaps = not done |
| "I'll fix it myself" | Controller fixes pollute context and skip review |
| "One more round will converge" | Past the cap, rounds don't converge — failure is structural |
| "This finding is obviously wrong, I'll drop it" | Adjudicate only at the cap, every ruling is a ledger entry |
| "The fix was small, skip the re-review" | Unreviewed fixes are how regressions land |