name: subagent-driven-development

description: Use when executing implementation plans with independent tasks. Dispatches fresh delegate_task per task with two-stage review (spec compliance then code quality).

version: 1.1.0

author: Hermes Agent (adapted from obra/superpowers)

license: MIT

metadata:

hermes:

tags: [delegation, subagent, implementation, workflow, parallel]

related_skills: [writing-plans, requesting-code-review, test-driven-development]

Subagent-Driven Development

Overview

Execute implementation plans by dispatching fresh subagents per task with systematic two-stage review.

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

When to Use

Use this skill when:

• - You have an implementation plan (from writing-plans skill or user requirements)
• - Tasks are mostly independent
• - Quality and spec compliance are important
• - You want automated review between tasks

vs. manual execution:

• - Fresh context per task (no confusion from accumulated state)
• - Automated review process catches issues early
• - Consistent quality checks across all tasks
• - Subagents can ask questions before starting work

The Process

1. Read and Parse Plan

Read the plan file. Extract ALL tasks with their full text and context upfront. Create a todo list:

`python

Read the plan

read_file("docs/plans/feature-plan.md")

Create todo list with all tasks

todo([

{"id": "task-1", "content": "Create User model with email field", "status": "pending"},

{"id": "task-2", "content": "Add password hashing utility", "status": "pending"},

{"id": "task-3", "content": "Create login endpoint", "status": "pending"},

])

`

Key: Read the plan ONCE. Extract everything. Don't make subagents read the plan file — provide the full task text directly in context.

2. Per-Task Workflow

For EACH task in the plan:

#### Step 1: Dispatch Implementer Subagent

Use delegate_task with complete context:

`python

delegate_task(

goal="Implement Task 1: Create User model with email and password_hash fields",

context="""

TASK FROM PLAN:

- Create: src/models/user.py

- Add User class with email (str) and password_hash (str) fields

- Use bcrypt for password hashing

- Include __repr__ for debugging

FOLLOW TDD:

1. Write failing test in tests/models/test_user.py

2. Run: pytest tests/models/test_user.py -v (verify FAIL)

3. Write minimal implementation

4. Run: pytest tests/models/test_user.py -v (verify PASS)

5. Run: pytest tests/ -q (verify no regressions)

6. Commit: git add -A && git commit -m "feat: add User model with password hashing"

PROJECT CONTEXT:

- Python 3.11, Flask app in src/app.py

- Existing models in src/models/

- Tests use pytest, run from project root

- bcrypt already in requirements.txt

""",

toolsets=['terminal', 'file']

)

`

#### Step 2: Dispatch Spec Compliance Reviewer

After the implementer completes, verify against the original spec:

`python

delegate_task(

goal="Review if implementation matches the spec from the plan",

context="""

ORIGINAL TASK SPEC:

- Create src/models/user.py with User class

- Fields: email (str), password_hash (str)

- Use bcrypt for password hashing

- Include __repr__

CHECK:

- [ ] All requirements from spec implemented?

- [ ] File paths match spec?

- [ ] Function signatures match spec?

- [ ] Behavior matches expected?

- [ ] Nothing extra added (no scope creep)?

OUTPUT: PASS or list of specific spec gaps to fix.

""",

toolsets=['file']

)

`

If spec issues found: Fix gaps, then re-run spec review. Continue only when spec-compliant.

#### Step 3: Dispatch Code Quality Reviewer

After spec compliance passes:

`python

delegate_task(

goal="Review code quality for Task 1 implementation",

context="""

FILES TO REVIEW:

- src/models/user.py

- tests/models/test_user.py

CHECK:

- [ ] Follows project conventions and style?

- [ ] Proper error handling?

- [ ] Clear variable/function names?

- [ ] Adequate test coverage?

- [ ] No obvious bugs or missed edge cases?

- [ ] No security issues?

OUTPUT FORMAT:

- Critical Issues: [must fix before proceeding]

- Important Issues: [should fix]

- Minor Issues: [optional]

- Verdict: APPROVED or REQUEST_CHANGES

""",

toolsets=['file']

)

`

If quality issues found: Fix issues, re-review. Continue only when approved.

#### Step 4: Mark Complete

`python

todo([{"id": "task-1", "content": "Create User model with email field", "status": "completed"}], merge=True)

`

3. Final Review

After ALL tasks are complete, dispatch a final integration reviewer:

`python

delegate_task(

goal="Review the entire implementation for consistency and integration issues",

context="""

All tasks from the plan are complete. Review the full implementation:

- Do all components work together?

- Any inconsistencies between tasks?

- All tests passing?

- Ready for merge?

""",

toolsets=['terminal', 'file']

)

`

4. Verify and Commit

`bash

Run full test suite

pytest tests/ -q

Review all changes

git diff --stat

Final commit if needed

git add -A && git commit -m "feat: complete [feature name] implementation"

`

Task Granularity

Each task = 2-5 minutes of focused work.

Too big:

• - "Implement user authentication system"

Right size:

• - "Create User model with email and password fields"
• - "Add password hashing function"
• - "Create login endpoint"
• - "Add JWT token generation"
• - "Create registration endpoint"

Red Flags — Never Do These

• - Start implementation without a plan
• - Skip reviews (spec compliance OR code quality)
• - Proceed with unfixed critical/important issues
• - Dispatch multiple implementation subagents for tasks that touch the same files
• - Make subagent read the plan file (provide full text in context instead)
• - Skip scene-setting context (subagent needs to understand where the task fits)
• - Ignore subagent questions (answer before letting them proceed)
• - Accept "close enough" on spec compliance
• - 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

Handling Issues

If Subagent Asks Questions

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

If Reviewer Finds Issues

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

If Subagent Fails a Task

• - Dispatch a new fix subagent with specific instructions about what went wrong
• - Don't try to fix manually in the controller session (context pollution)

Efficiency Notes

Why fresh subagent per task:

• - Prevents context pollution from accumulated state
• - Each subagent gets clean, focused context
• - No confusion from prior tasks' code or reasoning

Why two-stage review:

• - Spec review catches under/over-building early
• - Quality review ensures the implementation is well-built
• - Catches issues before they compound across tasks

Cost trade-off:

• - More subagent invocations (implementer + 2 reviewers per task)
• - But catches issues early (cheaper than debugging compounded problems later)

Integration with Other Skills

With writing-plans

This skill EXECUTES plans created by the writing-plans skill:

1. User requirements → writing-plans → implementation plan

2. Implementation plan → subagent-driven-development → working code

With test-driven-development

Implementer subagents should follow TDD:

1. Write failing test first

2. Implement minimal code

3. Verify test passes

4. Commit

Include TDD instructions in every implementer context.

With requesting-code-review

The two-stage review process IS the code review. For final integration review, use the requesting-code-review skill's review dimensions.

With systematic-debugging

If a subagent encounters bugs during implementation:

1. Follow systematic-debugging process

2. Find root cause before fixing

3. Write regression test

4. Resume implementation

Example Workflow

`

[Read plan: docs/plans/auth-feature.md]

[Create todo list with 5 tasks]

--- Task 1: Create User model ---

[Dispatch implementer subagent]

Implementer: "Should email be unique?"

You: "Yes, email must be unique"

Implementer: Implemented, 3/3 tests passing, committed.

[Dispatch spec reviewer]

Spec reviewer: ✅ PASS — all requirements met

[Dispatch quality reviewer]

Quality reviewer: ✅ APPROVED — clean code, good tests

[Mark Task 1 complete]

--- Task 2: Password hashing ---

[Dispatch implementer subagent]

Implementer: No questions, implemented, 5/5 tests passing.

[Dispatch spec reviewer]

Spec reviewer: ❌ Missing: password strength validation (spec says "min 8 chars")

[Implementer fixes]

Implementer: Added validation, 7/7 tests passing.

[Dispatch spec reviewer again]

Spec reviewer: ✅ PASS

[Dispatch quality reviewer]

Quality reviewer: Important: Magic number 8, extract to constant

Implementer: Extracted MIN_PASSWORD_LENGTH constant

Quality reviewer: ✅ APPROVED

[Mark Task 2 complete]

... (continue for all tasks)

[After all tasks: dispatch final integration reviewer]

[Run full test suite: all passing]

[Done!]

`

Remember

`

Fresh subagent per task

Two-stage review every time

Spec compliance FIRST

Code quality SECOND

Never skip reviews

Catch issues early

`

Quality is not an accident. It's the result of systematic process.