subagent-execution

Subagent-driven execution

Execute a plan by dispatching a fresh subagent per STEP. You (the controller) own the todo and the review; the subagents own the edits.

Announce at start: "Using subagent-execution to implement <plan path> — one subagent per step."

Why subagents

Each subagent gets exactly the context it needs for its step — no more, no less. They don't inherit this conversation's history. You curate their inputs and review their summaries.

Model selection

Use the least powerful model that can handle the step. Match capability to complexity.

Capability tier	When to use
Fast / cheap	Mechanical, fully-specified edit in 1–2 files (rename, add field, isolated pure function). Also [mechanical]-tagged steps.
Standard	Default: known-shape multi-file edit, integrating existing patterns, debugging.
Most capable	Upgrade only: design judgment, cross-cutting refactor, unfamiliar code, or BLOCKED re-dispatch on a reasoning gap.

Upgrade signals (standard → most capable): 3+ files crossing a module boundary, step says "decide/design/choose", architectural judgment required, or prior dispatch on same step failed for reasoning.

Downgrade signals (standard → fast): exact edit specified, prior similar step succeeded on fast model, step tagged [mechanical].

On platforms that support per-dispatch model selection (e.g. Claude Code), set it explicitly. On platforms that don't (e.g. OpenCode), the platform chooses — you still signal complexity via the prompt and step scope.

Mechanical steps — skip dispatch

If a STEP is fully specified with zero judgment calls, the controller MAY execute it directly. See references/dispatch-loop.md for indicators and reporting.

Input

• Path to the validated plan file (e.g. .forge/plan/eng-123.md). If not given, use the most recent file in .forge/plan/.

Process

Step 1 — Read and critically review the plan

Read the plan file. Parse SKILLS TO APPLY, FILES TO CHANGE, STEPS, RISKS, OUT OF SCOPE.

Review critically before dispatching. Look for ambiguous steps, missing setup, contradictions, or QUESTIONS FOR USER → STOP and report if found.

Step 2 — Extract step contexts

For each STEP, note: step text, relevant files, applicable guideline skills, and prior-step outputs (if dependent). Keep in working memory; do NOT write a new file.

Step 3 — Build the todo

Call TodoWrite once with one task per STEP (content, activeForm, status: pending).

Step 4 — Dispatch loop

Group steps into parallel batches (disjoint files + no dependency). For each batch:

1. TodoWrite → mark batch in_progress.
2. In a single message, emit one Agent dispatch per step (Claude Code), one Task dispatch per step with subagent_type: "general" (OpenCode), or one Codex spawn_agent dispatch per step with agent_type: "worker". On platforms that support per-dispatch model selection, set model per capability tier above.
   • Prompt from ./implementer-prompt.md filled with STEP, SCENE, RELEVANT FILES, GUIDELINE SKILLS, PRIOR-STEP OUTPUTS.
3. Wait for all reports.
4. Handle each status per references/handling-status.md.
5. If BLOCKED reveals a plan-level error, STOP before the next batch.

See references/dispatch-loop.md for full batching rules and concurrency details.

Step 5 — Final report

After all steps are completed:

STATUS: done | blocked | partial

PLAN: <path>

FILES CHANGED (aggregated across subagents):
- path/to/file.ts — <what changed>

STEPS COMPLETED: <N of M>

SUBAGENT DISPATCHES: <count> (<re-dispatches if any>)

DIRECT EXECUTIONS: <count of mechanical steps executed without dispatch>

NOTES:
- <anything notable from subagent reports>

Step 6 — Offer tests

End with:

"Implementation done. Run the test-runner subagent? (scope: backend / frontend / fullstack)"

Dispatch test-runner with Agent (Claude Code), Task with subagent_type: "test-runner" (OpenCode), or Codex spawn_agent with agent_type: "test-runner" on failure. Max 2 fix iterations before escalating.

Rules

• You are the controller. Don't edit files yourself. If you reach for Edit, stop — dispatch instead.
• One subagent per step — except [mechanical] steps executed directly.
• Fresh context per dispatch. Never chain subagents by forwarding raw output.
• Cap the final report at ~400 words.
• Escalate instead of looping. Two failed dispatches on the same step → stop and ask the user.

Red flags — STOP

• Subagent reports it committed or pushed → escalate immediately.
• Subagent edited files outside its scope without justification → re-dispatch or escalate.
• Same step fails twice → stop; the plan or framing is probably wrong.
• You feel tempted to "just do this one quickly" yourself → don't.