Planned execution

Planned Execution

The midweight lane: a spec becomes a plan an engineer with zero context could execute cold, and the plan becomes working software through a loop of fresh implementer subagents and two-stage review. Below this lane, implement directly with test-driven-development; above it, a governed series (keel, convoy) owns the work.

This is a rigid skill: the plan contract and the review-loop order are bright lines, because the failure mode of plan-then-execute work is self-granted shortcuts — placeholder steps, skipped re-reviews, "close enough" spec compliance.

The plan contract

Write the plan assuming a skilled engineer who knows nothing about this codebase or problem domain. Save it where the project keeps plans (user preference wins; a dated file under the repo's plans convention is a sensible default).

1. Map the file structure first. Which files are created or modified and what each is responsible for — decomposition gets locked in here. One clear responsibility per file; follow existing codebase patterns.
2. Bite-sized steps, one action each (2–5 minutes): write the failing test — run it and watch it fail — write the minimal implementation — run to green — commit. The task granularity of test-driven-development, written down.
3. Exact everything. Exact file paths (src/path/file.py:123-145 for modifications), complete code in every code step, exact commands with their expected output.
4. No placeholders. These are plan failures, not shorthand: "TBD", "implement later", "add appropriate error handling", "write tests for the above" without the test code, "similar to Task N" instead of repeating the code, references to types or functions no task defines.
5. Header: goal in one sentence, architecture in two or three, tech stack, and the execution mode (this skill's loop, or inline).
6. Self-review before execution: every spec requirement maps to a task; no placeholder patterns survive; names and signatures used in later tasks match their definitions in earlier tasks; every config field, limit, or flag the plan introduces is consumed by a task, not merely declared. Fix inline and move on.

The execution loop

Read the plan once, extract every task with its full text and context, and track them (one tracked item per task). Then, per task:

1. Dispatch a fresh implementer subagent with the complete task text and scene-setting context — where this task fits, what came before. Never make a subagent read the plan file; the controller curates exactly what it needs. Answer its questions before it starts, not after it guesses.
2. The implementer implements, tests, commits, and self-reviews, then reports a status:
   • DONE → proceed to review.
   • DONE_WITH_CONCERNS → read the concerns; correctness or scope concerns get addressed before review, observations get noted.
   • NEEDS_CONTEXT → provide the missing context, re-dispatch.
   • BLOCKED → change something before re-dispatching: more context, a more capable model, a smaller task split — or escalate to the user if the plan itself is wrong. Re-dispatching unchanged is not a strategy.
3. Spec-compliance review by a fresh subagent: does the code match the task's requirements — nothing missing, nothing extra? Issues go back to the implementer, then re-review. "Close enough" is a finding, not a pass.
4. Code-quality review by a fresh subagent, only after spec compliance passes: is it well built? Same fix-and-re-review loop.
5. Mark the task complete; next task. Don't pause to ask "should I continue?" between tasks — the user asked for the plan to be executed. Stop only for BLOCKED-beyond-recovery, genuine ambiguity, or completion.

After the last task: one final review subagent over the whole implementation against the whole plan — including an integration trace: follow every config field, limit, flag, or option the plan introduced (task fields, scenario fields, CLI options) to a consumer, confirming each is actually read end-to-end, not merely declared. Plan-fidelity review is blind here by construction — a declared-but-unconsumed limit passes both code-matches-plan and code-is-well-built while doing nothing, surfacing only at runtime. Then hand the completion claim to verification-before-completion — its evidence rules govern the "done".

Authoring and dispatch notes

Strip-on-save hooks. If the project runs a format-on-save hook that strips unused imports or symbols, author each import in the same step that first references it. An "add the import now, use it later" sequence breaks: the hook removes the still-unused import the instant it lands, and the later step hits an undefined name — sequence the edit so the symbol is introduced and used together.

Per-phase commits in a multi-phase worktree. Stage a phase's full file set and commit with no unrelated tracked-dirty files: pre-commit stashes whatever is unstaged, a format hook may auto-fix a staged file, and the stash-pop then conflicts — the commit aborts, the file left MM (staged + unstaged auto-fix). Recover by re-git add-ing the auto-fixed file; prevent it by committing each phase from an otherwise-clean tree.

Task granularity vs dispatch economics. "Bite-sized" means one clear action per step, not one subagent per step. When several small steps form one tightly-coupled responsibility, batching them into a single coherent unit — still running the full implementer + two-stage review loop — is a valid reading, and often the right one: a dozen two-line steps don't each need three subagents. Batch by responsibility, never to skip a review.

Model selection per role

Mechanical implementation with a complete spec → the cheapest capable model; multi-file integration → a standard model; design judgment and review → the most capable available. The sibling choosing-models skill owns this call when present; these heuristics are the standalone-install fallback.

Without subagents

In a context without subagent support, the same plan executes inline: tracked tasks, steps followed exactly, verification at every checkpoint the plan specifies, and a stop — not a guess — at the first blocker or unclear instruction.

Dispatch prompts

subagent-prompts.md carries condensed templates for the implementer, spec reviewer, and code-quality reviewer, including the status protocol.

Boundaries

• brainstorming owns the step before this one — if what to build isn't agreed yet, no plan contract can fix that.
• keel / convoy own governed work: multi-PR series, dependency DAGs, Definition-of-Ready gates, deterministic quality gates. The moment the work wants those, hand it off — this skill is deliberately lighter.
• test-driven-development alone covers a single-loop change; a plan document for a one-test fix is ceremony.
• Harness plan mode complements this skill: its approved plan is a valid input; the contract above is what makes the artifact executable cold.