subagent-driven-development

name	subagent-driven-development
description	Use when executing an approved plan with independent tasks. Dispatches fresh subagents per task, assigns reasoning effort, tracks progress in a visible ledger, controls concurrent branches/worktrees, keeps file ownership clear, and requires review loops so implementation stays aligned with the plan and code quality bar.

Subagent-Driven Development

Use this skill to execute a plan safely with fresh subagents.

Core Principle

Fresh subagent per task plus re-review after each task beats one long, noisy implementation thread.

The controller owns coordination. Subagents own bounded work products.

Workflow

1. Read the full plan once.
2. Extract every task and order them by dependency.
3. Inspect git status, current branch, worktrees, and likely base before dispatch when the repo is git-backed. Record pre-existing dirty files as protected unless the plan explicitly owns them.
4. Build and maintain an agent ledger before dispatch.
5. For each task:
   • assign one implementer with a bounded scope
   • give exact file paths, requirement text, and verification steps
   • require a short pre-implementation plan if risk is non-trivial
   • assign an explicit reasoning effort when the inherited effort is not appropriate
6. After implementation, run appropriately sized reviews:
   • spec-compliance review: did the work match the task?
   • code-quality review: did it introduce correctness, security, or maintainability issues?
   • for trivial low-risk edits, one combined lightweight review may cover both checks
   • for broad/risky tasks, optionally add lane reviews from correctness-review, security-review, test-review, performance-review, and architecture-review
7. Fix findings, then re-review before marking that task integrated or starting dependent work. Independent tasks may continue in parallel when scopes stay disjoint.
8. Run a final integration review when all tasks are complete.

Agent Effort Policy

Use the current parent thread reasoning effort by default. Override per agent only when task risk or complexity clearly warrants it.

• low: narrow mechanical edits, formatting, simple test updates
• medium: normal implementation, local refactors, focused bug fixes
• high: architecture-sensitive changes, broad behavior changes, risky migrations
• xhigh: complex debugging, security-sensitive work, or final integration review only

Do not override the model unless the user explicitly asks or the task has a clear model-specific reason. Record the selected effort in the ledger.

When the subagent tool exposes a reasoning_effort parameter, pass the selected value there. If the tool does not expose effort controls, include the selected effort in the prompt as operating guidance.

Performance Rules

• Keep immediate blocking work in the controller thread.
• Delegate independent sidecar tasks only when they can run without blocking the next controller action.
• Do not duplicate delegated work locally while agents are running.
• Use minimal context packs by default: task text, owned files/modules, constraints, commands, and expected output.
• Fork full context only when the agent genuinely needs conversation history.

Concurrency Budget

Default to 2-3 active code-edit workers per repository integration lane, not per file, script, or folder.

An integration lane is a disjoint ownership scope with:

• clearly owned files/modules
• no shared public contract being changed in parallel
• independent verification steps
• low expected merge conflict risk

A script, folder, package, or subsystem may be treated as a lane only when it meets those conditions.

Never assign two active code-edit workers to the same physical checkout or worktree. Parallel code-edit workers must use separate forked workspaces or dedicated worktrees. A shared integration branch means the controller integrates outputs onto one branch, not simultaneous writes in one checkout.

Use one worker at a time for shared contracts, schemas, migrations, package manifests, lockfiles, generated code, global config, build tooling, and cross-cutting architecture changes.

Read-only explorers may exceed the code-edit worker cap when their scopes are independent and they are not blocking the controller.

If merge conflicts, review backlog, or integration delay appears, reduce active code-edit workers before spawning more.

Agent Launch Envelope

Every subagent prompt must include:

• task id
• role: worker, explorer, reviewer, or fixer
• reasoning effort
• owned files/modules
• explicitly forbidden files/modules
• exact requirement text
• expected output format
• verification command(s)
• whether code edits are allowed
• instruction to list changed files
• instruction not to revert other agents' work

For workers, state that they are not alone in the codebase and must accommodate existing edits rather than reverting them.

Branch And Worktree Control

The controller owns git state. Subagents must not create, rename, switch, merge, rebase, delete, or push branches unless explicitly assigned by the controller.

• Treat pre-existing dirty files as protected user work unless the plan explicitly owns them.
• Do not assign protected files to subagents. If a task needs them, isolate the task in a separate worktree or ask the user before touching them.
• Use main as the default base unless the repository's counted default branch is different or the user explicitly says otherwise.
• Use one human-readable integration branch for a single approved plan by default: feature/<topic>, fix/<topic>, refactor/<topic>, or docs/<topic>.
• Never create codex/*, generated, detached, temporary, or orphaned branches.
• Do not push automatically. Pushing remains user-approved only.

Prefer one shared integration branch when tasks have disjoint file ownership and can be integrated by the controller.

Use separate human-readable worktree branches only for long-running independent lanes, dirty worktrees, risky migrations, or changes needing separate CI/review. Each concurrent worktree must have a unique branch, owner, scope, base, and integration target recorded in the ledger.

Agent Tracking Ledger

Maintain a visible run ledger while agents are active:

Agent	Role	Effort	Scope	Status	Progress	Verification	Findings
A1	worker	medium	src/auth/*	verifying	70%	running	none yet

For branch/worktree-heavy runs, add Branch, Worktree, Base, Conflict Risk, and Integration columns. Track whether each agent is working in the controller branch, a forked workspace, or a dedicated worktree branch. Mark integration state separately from agent completion.

Update the ledger after spawn, after each returned agent result, after each review pass, after each fix pass, and when the agent is closed.

Use stable statuses:

• queued
• planning
• implementing
• verifying
• reviewing
• fixing
• passed
• blocked
• failed

Progress Semantics

Use deterministic stage-based progress, not guessed effort or fake internal telemetry:

• 0% spawned
• 10% task accepted / scope confirmed
• 20% pre-implementation plan complete
• 50% implementation complete
• 70% verification run
• 85% spec review passed
• 95% quality review passed
• 100% integrated / closed

If a task skips a stage because it is read-only or trivial, mark that stage n/a and advance to the next applicable gate.

When terminal-style visibility is useful, print compact progress bars:

A1 auth worker      [####----------------] 20% plan complete
A2 tests worker     [##########----------] 50% implementation complete
A3 review worker    [#################---] 85% spec review passed

Progress bars are controller-owned status summaries. Do not present them as live subagent introspection.

Standard Agent Result Format

Each agent must return:

• Status: passed, blocked, or failed
• Task id
• Files changed
• Commands run
• Verification result
• Findings or risks
• Follow-up needed

Reviewers must lead with findings and severity labels. Non-trivial reviewers must use the canonical report schema from code-review/references/report-schema.md.

Review Gate Sizing

For non-trivial tasks, keep spec-compliance and code-quality reviews separate. For trivial low-risk edits, the controller may run one lightweight combined review that checks spec fit, changed files, obvious regressions, and verification results. Do not skip verification.

Controller Duties

The controller owns:

• dependency ordering
• write-scope conflict prevention
• branch, worktree, base, and integration-target decisions
• status ledger updates
• review dispatch
• integrating agent outputs in dependency order
• checking changed files against assigned ownership before integration
• final integration review
• closing agents after their outputs are integrated

If two agents touch the same file unexpectedly, stop parallel integration and resolve manually in the controller thread. After integration, run targeted verification before closing the task.

Delegation Rules

• Do not delegate overlapping write scopes in parallel.
• Do not make subagents rediscover the plan; hand them the exact task text.
• Require implementers to list files changed.
• Spawn independent agents in batches, continue local non-overlapping work, and wait only when the next controller step needs results.
• If a task fails, dispatch one fresh fix subagent with the failure evidence instead of accumulating context in the controller.
• If the same task fails again, stop the loop and have the controller triage before spawning more agents.

Best Uses In This Pack

• executing audit remediation plans
• splitting type consolidation from weak-type cleanup
• separating architectural fixes from readability cleanup
• parallel review-only passes across distinct subsystems

Completion Bar

Do not call a task done until:

• required verification ran
• spec and quality review passed, either separately or through an approved lightweight combined review
• any follow-up risks are documented
• the ledger is updated to passed, blocked, or failed