subagent-driven-development

Files (6)

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

SKILL.md (first lines)

# Subagent-Driven Development

## Purpose

The core value of subagents is context isolation: bounded implementation work
can proceed without loading the main session's accumulated history, while the
main agent keeps the long-horizon picture coherent. Use this workflow for a
plan whose deliverables benefit from that separation, not as a mandatory wrapper
around every edit.

## Controller and worker ownership

The main agent owns long-horizon continuity, overall construction progress,
dependency and integration state, semantic acceptance ownership, and high-level
architecture communication with the user. It normally coordinates rather than
performing the worker's detailed implementation itself.

Workers own their bounded construction, focused validation, and durable report.
The main agent should not duplicate worker implementation merely to stay busy.
Direct main-agent investigation is appropriate only when separate verification
is required, a worker report cannot serve as ground truth, or repeated failure
on the same problem calls for deeper diagnosis.

## Choose or resume a worker

Before each dispatch, ask whether the harness supports resuming a relevant prior
worker and whether that worker's context still materially helps the next
deliverable. When available, resume a relevant prior worker when it retains
useful task-specific knowledge, unresolved evidence, or local implementation
state.

Use a fresh worker when clean context isolation, an independent perspective, or
unrelated work makes the earlier context a liability. Do not hardcode a single
harness API: express the resume-or-dispatch decision, then use the active
harness's supported worker mechanism.

## Durable handoffs

Keep the controller context small and the work recoverable through files:

- Create a task brief with `scripts/task-brief PLAN_FILE N`; it is the
  worker's authoritative requirement source.
- Give the worker a report path beside the brief. The report preserves project
  meaning, architecture impact, semantic evidence, concerns, commit_authority,
  and commits when authorized or working-tree diff, changed files, and evidence
  without commit authority.
- Create a review package only when independent review is warranted. For committed
  work use `scripts/review-package BASE HEAD`; without commit authority use
  `scripts/review-package --worktree BASE [OUTPUT]`. Pass the resulting DIFF_FILE,
  brief, and report paths to the reviewer instead of requiring a SHA or pasting
  bulk history.
- Maintain `.superpowers/sdd/progress.md` as the progress ledger. Record each
  accepted deliverable, commit_authority, commits when authorized or its
  working-tree diff/files/evidence, acceptance evidence, open concerns, and next
  dependency. After context compaction, resume from the ledger and `git
  log`, not recollection.

The brief, report, review package, and progress ledger are continuity tools, not
ceremony: each preserves information a new controller or worker would otherwise
need to reconstruct.

## Review placement

Place independent review at a meaningful semantic or risk boundary: a behavior
that changes user-visible outcomes, crosses module ownership, introduces a
security or data-integrity concern, alters permissions, affects concurrency, or
creates a compatibility boundary. Substantive work receives a final whole-change
review that checks integration and semantic acceptance across deliverables.

Repeated low-risk mechanical work following an already-reviewed pattern may use
a grouped review. Short changes still receive independent review when they are
security-sensitive, data-integrity, permission, concurrency, or cross-module
changes. A reviewer evaluates semantic behavior and integration, not a hunt for
style findings or an excuse to add process.

If a review finds an issue, decide whether a fix needs independent verification:
request it for material semantic, risk, or integration findings; record a
low-risk mechanical correction and verify it through the appropriate acceptance
evidence when another review would not change confidence.

## Execution loop

1. Read the plan, stable references, repository-operation preferences, and any
   progress ledger. Resolve only blockers that change construction.
2. Identify the next meaningful deliverable and its dependencies. Select a
   resumed or isolated worker using the rule above.
3. Dispatch with the task brief, any non-inferable interface decisions, the
   report path, and the required semantic acceptance evidence. Choose model
   capability proportional to the task's ambiguity, risk, and integration load.
4. Read the worker status and report. Preserve its evidence in the ledger; do
   not treat a summary as proof when separate verification is required.
5. Place review at the meaningful semantic or risk boundary. Resolve material
   findings through a worker or direct investigation only under the ownership
   rule above.
6. Update the ledger with accepted state, commit_authority, commits when
   authorized or working-tree diff/files/evidence without commit authority,
   concerns, and the next dependency. At the end of substantive work, request a final whole-change
   review before closeout.

## Worker status

- **DONE:** Confirm the report contains project meaning, architecture impact,
  semantic evidence, and concerns; then select the appropriate acceptance or
  review path.
- **DONE_WITH_CONCERNS:** Read and record the concern before deciding whether it
  requires independent verification or a follow-up worker.
- **NEEDS_CONTEXT:** Supply the missing decision or stable reference and resume
  the relevant worker when that context remains useful.
- **BLOCKED:** Change the task context, worker capability, decomposition, or
  escalate the real blocker. Do not repeat the same dispatch without new
  information.

## Model selection

Use the least costly worker that can safely handle the task: inexpensive models
for determined isolated edits, stronger models for cross-module integration or
debugging, and the strongest available judgment for substantive whole-change
review. Explicitly choose a model where the harness allows it; do not inherit a
high-cost default accidentally.

From BB-84C/superpowers-lite, MIT.

More from BB-84C/superpowers-lite