agentleFS
wxxb789wxxb789/hoa/skills/subagent-driven-development/SKILL.md

subagent-driven-development

Skill3 starsChanged 53 days agoMITView on GitHub

Execute an implementation plan by dispatching a fresh subagent per task and reviewing each result in two stages — spec compliance first, code quality second — then a final integration review. Use when a plan already exists, tasks are mostly independent, and quality plus spec fidelity must hold between tasks. Not for discovering what to build, and not for one task you can finish in the current context.

189 other projects use a version of this, 12 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use chinese-code-review, chinese-commit-conventions and 9 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • Leodorareluctant259Skill

    chinese-code-review

    中文代码审查规范——在保持专业严谨的同时,用符合国内团队文化的方式给出有效反馈

    Also in 8 projects that use this

  • Leodorareluctant259Skill

    chinese-commit-conventions

    中文 Git 提交规范 — 适配国内团队的 commit message 规范和 changelog 自动化

    Also in 8 projects that use this

  • obraSkill

    diagnosing-superpowers

    Use when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.

    Also in 19 projects that use this

  • Tommy-ywSkill

    webhook-subscriptions

    Create and manage webhook subscriptions for event-driven agent activation, or for direct push notifications (zero LLM cost). Use when the user wants external services to trigger agent runs OR push notifications to chats.

    Also in 5 projects that use this

  • math-incSkill

    minecraft-modpack-server

    Set up a modded Minecraft server from a CurseForge/Modrinth server pack zip. Covers NeoForge/Forge install, Java version, JVM tuning, firewall, LAN config, backups, and launch scripts.

    Also in 5 projects that use this

  • math-incSkill

    pokemon-player

    Play Pokemon games autonomously via headless emulation. Starts a game server, reads structured game state from RAM, makes strategic decisions, and sends button inputs — all from the terminal.

    Also in 5 projects that use this

  • +3 more from Leodorareluctant259
  • +1 more from math-inc

The file

Show its rules and text

We split this skill into the rules it gives an agent

21 rules. 0 are common, 20 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 179 edited versions we read keep these.

  • 20

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Use this skill when:

    line 43
  2. Distinctive:

    Read the plan file. Extract ALL tasks with their full text and context upfront.

    line 77
  3. Distinctive:

    Key: Read the plan ONCE. Extract everything.

    line 86
  4. Distinctive:

    If the plan names a spec file, read it too: the plan says how, the spec says what, and the spec-compliance review in Step 2 measures …

    line 89
  5. Distinctive:

    Use the harness's fresh-subagent dispatch with complete context.

    line 99
  6. Distinctive:

    After the implementer completes, verify against the original spec, using only the spec:

    line 130
  7. Distinctive:

    After spec compliance passes:

    line 150
  8. Distinctive:

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

    line 205
  9. Distinctive:

    Default stays the per-task serial review above.

    line 217
  10. Distinctive:

    Do not merge their findings, reorder findings across axes, or produce a combined score.

    line 230
  11. Very specific:

    No-progress breaker: If the same (axis, rule, file, mechanism) quadruple appears in two consecutive rounds, stop with BLOCKED:no_progress …

    line 245
  12. Distinctive:

    Run the acceptance yourself.

    line 251
  13. Distinctive:

    Start implementation without a plan

    line 283
  14. Distinctive:

    Do not expect the subagent to ask the user — delegated children often have no interactive channel

    line 300
  15. Distinctive:

    Put every needed constraint into the delegated context up front

    line 301
  16. Distinctive:

    If a reviewer finds a missing requirement, update the next delegated task with the clarified requirement explicitly

    line 302
  17. Distinctive:

    Don't skip the re-review

    line 310
  18. Distinctive:

    Don't try to fix manually in the controller session (context pollution)

    line 318
  19. Distinctive:

    No confusion from prior tasks' code or reasoning

    line 326
  20. Distinctive:

    Write failing test first

    line 351
  21. Distinctive:

    If a subagent encounters bugs during implementation:

    line 367

“Common” is measured: kept by at least 6 in 10 of the 179 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Subagent-Driven Development

Overview

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

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

Method adapted from the public superpowers subagent-driven-development flow (MIT); the role names and the transport-neutral dispatch contract are this port's.

Boundary — this is plan execution, not the loop's implement stage

gdd runs one goal as one agent run: gdd.py stage --stage implement renders references/stage-templates/implement.md, forbids committing, and leaves the tree for verification. This skill is the other protocol: a multi-task plan, a fresh subagent per task, a commit per task, two reviews between tasks. Load it when writing-plans produced the plan and you are executing it directly; never inside a gdd stage run, where per-task commits break the sealed-scope and single-run budget assumptions of phases 1, 2 and 5.

When to Use

Use this skill when:

  • You have an implementation plan (from writing-plans or equivalent 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
  • Children may lack the parent's interactive tools: state every constraint up front rather than expecting a child to ask

Roles

Names in the source material were agent products; they are roles here.

RoleOwns
controllerreads the plan once, dispatches, tracks status, enforces review order, integrates
implementerone task, full task text, the project's conventions, a report of files/tests/verification
spec reviewerthe original task text only: every requirement present, nothing extra
quality reviewerthe touched files: conventions, error handling, names, coverage, edge cases, security
integration reviewerthe whole change after all tasks: consistency, cross-task seams, full suite

The controller never implements a task itself. Repair belongs to the implementer or a fresh fix subagent, so the controller's context stays clean enough to judge.

The Process

1. Read and Parse Plan

Read the plan file. Extract ALL tasks with their full text and context upfront. Record every task in whatever tracker the work is recorded in, in plan order:

idfull task textstatus
task-1Create the model with email and password-hash fieldspending
task-2Add the password-hashing utilitypending
task-3Create the login endpointpending

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

If the plan names a spec file, read it too: the plan says how, the spec says what, and the spec-compliance review in Step 2 measures against the spec's Acceptance list and Testing seam. A plan that contradicts the spec is a defect in the plan, not a licence to widen scope.

2. Per-Task Workflow

For EACH task in the plan:

Step 1: Dispatch Implementer Subagent

Use the harness's fresh-subagent dispatch with complete context. The brief carries:

TASK FROM PLAN:
- Create: <exact path>
- Add <class/function> with <fields/signature>
- Use <the library named by the plan>
- Include <debug aid>

FOLLOW THE PROJECT'S TEST-FIRST RULE:
1. Write the failing test in <test path>
2. Run: <test command> (verify FAIL)
3. Write the minimal implementation
4. Run: <test command> (verify PASS)
5. Run: <full suite command> (verify no regressions)
6. Commit: <the plan's commit message>

PROJECT CONTEXT:
- Language/runtime: <version>
- App entry point: <path>
- Existing patterns: <paths>
- Test runner and invocation: <command>
- Dependencies already present: <names>

Capabilities are granted explicitly on the dispatch (shell, file read/write, or the adapter's equivalent). A configuration default is not a capability guarantee: if the child needs to run tests, say so, and verify from its report that it did.

Step 2: Dispatch Spec Compliance Reviewer

After the implementer completes, verify against the original spec, using only the spec:

ORIGINAL TASK SPEC:
- <requirements, verbatim from the plan>

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.

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:

FILES TO REVIEW:
- <paths touched by the task>

TRIAGE FIRST:
- Split the touched paths into production code and test code, and say which is which.
- Test files are reviewed, not skipped. They carry their own defects.

TEST CODE — BLOCKING (report as blocking; never downgrade to style):
- Wrong or missing assertions.
- Mocks or fixtures that let the test pass regardless of the behaviour under test.
- Assertions on private internals instead of the public contract.
- Skipped or commented-out tests presented as coverage.
- Tests that depend on execution order or share mutable state.
- A test that would still pass if the behaviour were removed.

FORBIDDEN RECOMMENDATION:
- Never propose sharing a constant, fixture or helper between a test's expected value and the code
  under test, or between a test's input and its expectation. The oracle must be independent or the
  test cannot fail.

DO NOT REPORT:
- Repeated literals inside one test class.
- Short Given/When/Then setup duplication.
- "Primitive Obsession" applied to test data.

Test maintainability is a finding only with a concrete risk: large fixtures duplicated across files
and already drifting, tests bound to private internals that break on legitimate refactors, or data
builders so complex they hide the behaviour being verified. Name that risk in the finding.

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

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

Step 4: Mark Complete

Set the task's status in the tracker. Do not start the next task while either review has an open issue.

3. Final Review

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

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?

Dual-axis mode (opt-in)

Default stays the per-task serial review above. Select dual-axis only when the increment is reviewed as a whole — a goal-driven delivery, or a plan whose tasks are all complete.

Freeze one artifact set for both reviewers: the range (BASE..HEAD), the changed paths, and the spec or plan the work implements. Both reviewers get exactly that set; neither gets the other's report.

Dispatch the two reviewers in parallel, isolated from each other:

  • Standards — repo conventions, the project's own review rules, and the test-code triage from Step 3.
  • Spec — every acceptance clause, one line per clause, marked met or not met.

Do not merge their findings, reorder findings across axes, or produce a combined score. Each axis returns its own verdict line and stable finding IDs — STD-A01… for Standards, SPEC-A01… for Spec — and each finding carries file:line, the rule it breaks, the mechanism, what is false, and the input that breaks it. Verdict per axis:

APPROVE | MUST_FIX (<n>) | DECISION_NEEDED (<question>) | BLOCKED:no_progress

A finding ID the operator already retained, whose evidence has not changed, is not re-asked in the next round.

APPROVE expires the moment the code changes. Any fix invalidates both axes' approvals: re-review the delta against the same frozen set, and never carry a previous approval forward.

No-progress breaker. If the same (axis, rule, file, mechanism) quadruple appears in two consecutive rounds, stop with BLOCKED:no_progress and name that quadruple. Do not spend a third round on it, and do not cap the loop by round count alone.

4. Verify and Commit

Run the acceptance yourself; a child's "tests passed" is a claim.

# Run full test suite
<full suite command>

# Review all changes
git diff --stat

# Final commit if needed
git add <explicit paths> && git commit -m "<the plan's final message>"

Task Granularity

Each task = 2–5 minutes of focused work by default (SDD_TASK_MINUTES_MIN, SDD_TASK_MINUTES_MAX).

Too big:

  • "Implement user authentication system"

Right size:

  • "Create User model with email and password fields"
  • "Add password hashing function"
  • "Create login endpoint"
  • "Add 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 a subagent read the plan file (provide full text in context instead)
  • Skip scene-setting context (the subagent needs to understand where the task fits)
  • Ignore subagent failures or unresolved ambiguity — fix the context and retry with a fresh subagent
  • 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 the next task while either review has open issues

Handling Issues

If Requirements Are Ambiguous

  • Do not expect the subagent to ask the user — delegated children often have no interactive channel
  • Put every needed constraint into the delegated context up front
  • If a reviewer finds a missing requirement, update the next delegated task with the clarified requirement explicitly

If Reviewer Finds Issues

  • Implementer subagent (or a new one) fixes them
  • Reviewer reviews again
  • Repeat until approved
  • Don't skip the re-review
  • Dual-axis mode replaces the fixed round cap with the no-progress breaker: a repeated (axis, rule, file, mechanism) ends the loop at BLOCKED:no_progress. The cap still applies to per-task 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
  • Grant capabilities per dispatch. A global delegation default is documentation, not a guarantee: child access is inherited or narrowed by the transport, so state the tools/capabilities the task needs on the call. Treat an unreported capability as absent.

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-first development

Implementer subagents should follow the project's test-first rule:

  1. Write failing test first
  2. Implement minimal code
  3. Verify test passes
  4. Commit

Include those instructions in every implementer context. If the project has no test-first rule, require a regression test at the seam the task touches.

With code review

The two-stage review process IS the code review. For the final integration review, use the review dimensions the project's own reviewer requires; if it has none, use the quality checklist above plus "does the whole change satisfy the plan?"

With systematic-debugging

If a subagent encounters bugs during implementation:

  1. Follow systematic-debugging
  2. Find root cause before fixing
  3. Write regression test
  4. Resume implementation

Example Workflow

[Read plan: <plan path>]
[Record 5 tasks in the tracker]

--- Task 1: Create User model ---
[Dispatch implementer subagent]
  Implementer: "Should email be unique?"
  Controller: "Yes, email must be unique"      # answered from the plan, then re-dispatched
  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: FAIL — 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

Configuration

KeyEnvDefault
dispatch_commandSDD_DISPATCH_CMDnone — the harness's own fresh-subagent command or adapter
task_minutes_minSDD_TASK_MINUTES_MIN2
task_minutes_maxSDD_TASK_MINUTES_MAX5
child_capabilitiesSDD_CHILD_CAPABILITIESshell, file read/write (pass explicitly per dispatch)
review_orderSDD_REVIEW_ORDERspec,quality — fixed; change only with a documented reason
plan_pathSDD_PLAN_PATHnone — supplied by the caller

Resolution order and the config-file path are defined once in skill-porting-and-publishing § Configuration; this skill does not restate them.

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.