Execute Plan

Execute Plan

Execute a wave-grouped plan.md via parallel subagents. The parent orchestrates — dispatching subagents, running review gates, promoting contract-affecting discoveries to the spec, committing — and never writes code itself. Ends by writing the spec's Completion record and freezing the plan.

When to use

YES: meta/specs/NNN-slug/ has a plan.md with wave-grouped [ ] tasks (from write-plan) ready to execute; resuming a partially executed plan.

NO: no waves yet (use write-plan); design undecided (use tech-design); plan Status is already FROZEN.

Protocol

Input

• Spec folder: meta/specs/NNN-slug/ (or a path to either file in it). Reads both plan.md (waves, log) and spec.md (ACs, D-NN decisions, Structure Outline).

Execution model

Parent agent (orchestrator):

• Reads plan + spec, dispatches subagents, runs review gates, commits.
• Never reads source code files or writes code itself.
• Edits spec.md ONLY in Step 2.5 (promotion) and Step 5 (ship gate).

Subagents (implementers):

• Receive: plan file path + their assigned task IDs; the AC-N texts their tasks cite and the relevant Structure Outline excerpt (both copied from spec.md into the dispatch — they don't hunt the spec); any prior [Implementation] log entries touching their files (the outline is frozen — the log is where reality lives).
• Implement the assigned work; read existing code in affected areas.
• Return: { files_changed: [paths], summary: string, discoveries: [{ type: "[Implementation]" | "[AC-affecting]" | "[Future]", note: string }] | null }
• A deviation from the Structure Outline IS an [Implementation] discovery — there is no separate channel. If the task body conflicts with a copied current AC-N text, the AC text is authoritative: implement to the AC and return the conflict as an [AC-affecting] discovery — never silently reconcile it.
• A file assigned to another subagent in the same wave must NOT be edited — return { needs_scope_expansion: true, additional_files: [paths], justification: string } instead; the parent reassigns and re-dispatches. Once per wave: a second needs_scope_expansion in the same wave stops the reshuffle — collapse the colliding tasks into ONE subagent and run them serially (the same escape wave rule 3 uses for declared overlap).
• No file contents in returns — paths and summaries only.

Autonomy gate — resolve before asking

This gate governs any mid-run AskUserQuestion on a reversible code decision. Out of scope (always ask): crash/timeout retry, verification-fail, contract amendment (→ Step 2.5), new-feature placement (→ Step 5.2), any destructive act. Auto-resolve only when the decision is grounded — it traces to a named source (a D-NN, AC-N, cited spec line, or existing code at a file:line), never your reasoning alone — and you are ≥ 0.80 confident it fits this case. Then apply the disposition you'd otherwise recommend — the spec-mandated action (Tier 1) or the solver's fix (Tier 2) — and log it (below). A human-gated or not-diff-provable concern (a visual D-NN) never auto-fixes: log it as a - P2/P3 [deferred]: entry in ## Wave Reviews (the anchor form on the P2/P3 row of Step 2) with the recommendation — Step 5.2 triages it at the ship gate.

Ground the decision in tiers; stop at the first that resolves:

• Tier 1 — Spec (parent, no subagent). The answer sits in a cited AC-N, locked D-NN, plan task, or the frozen Structure Outline. A literal match is ~1.0 confident; applying a principle to this case is a judgment — score it honestly. ≥ 0.80 → proceed; below it, fall to Tier 2, don't ask yet.
• Tier 2 — Investigation (two read-only subagents, serial). Dispatch a finder (Sonnet): "Does a source directly answer this — a D-NN/AC-N, another spec line, or existing code? Return { source, excerpt } only if it directly answers; merely related → source: none." source: none → escalate. Else dispatch a solver (Opus): "From that source + the spec, return { fix, confidence, needs_decision_change } — the simplest fix consistent with the locked decisions. Set needs_decision_change if the fix contradicts the D-NN's rationale, needs a decision changed, re-architects, or invents a default for behavior no source specifies." confidence ≥ 0.80 and not needs_decision_change → proceed; else escalate. The solver only proposes — the fix runs through the normal wave / fix-verify-loop path.
• Tier 3 — Escalate. The step's AskUserQuestion, options with a recommendation, carrying the spec ref + finder/solver notes so the user decides fast.

Log every auto-resolve to ## Execution Log under the wave's ### Wave N — [date] heading: - [auto-resolved]: — per , conf 0.NN. These are code-only and still pass Step 2/4 review — the backstop for a mis-scored proceed.

Step 1 — Wave execution loop

1. Read the plan fresh. Extract PLAN_SLUG from the folder name (meta/specs/014-daily-digest/ → 014-daily-digest). If the plan header's **Base SHA:** is already set (a resume), adopt it as PLAN_BASE_SHA and skip the rest of this item. Fresh start only: check git status --porcelain excluding the spec folder's files (they fold into the Wave 1 commit); if dirty, AskUserQuestion: "Stash and proceed (Recommended)" / "Commit and proceed" / "Abort". Then record PLAN_BASE_SHA=$(git rev-parse HEAD) and set the plan header's **Base SHA:** line.
2. Find the next ### Wave N with any [ ] tasks. Resuming mid-wave → dispatch only unchecked tasks.
3. No unchecked tasks anywhere → pre-finalization checkpoint, then final review (Step 4). Checkpoint — only if mailbox.md exists: (a) Compute this session's context in absolute tokens per the [Context gauge](#context-gauge). (b) If ctx ≥ 150k: append orchestrator | PAUSED after wave N (final wave) | ctx NNNk | HH:MM (N = the last wave) to the mailbox, tell the user in one line that the run paused before final review, and END the session — do not start Step 4. Disk is already a complete checkpoint; the supervisor spawns the next session, which resumes from the checkboxes (all [x]) into Step 4. Otherwise (below 150k, or no mailbox) → proceed to Step 4 in this session.
4. Launch one Opus subagent per task in the wave, in parallel. Must land together with: tasks go to one subagent.
5. Collect results. Crash/timeout → AskUserQuestion: "Retry this item (Recommended)" / "Skip and mark dependents blocked" / "Abort plan". Don't commit a partial wave.
6. Append each returned discovery to the plan's ## Execution Log under a ### Wave N — [date] heading, with its type tag. Any [AC-affecting] discovery → run Step 2.5 now, before committing the wave. Other blocking issues → run the Autonomy gate; on escalation, AskUserQuestion: "Resolve and retry (Recommended)" / "Skip and mark dependents blocked" / "Override and proceed" / "Abort plan".
7. Flip the wave's tasks to [x] — the flip must land IN the wave commit (it's the resume state).
8. Stage and commit: git add [wave files + plan] — plus mailbox.md when it exists (the supervisor reads it from disk, never git — the commit is just a snapshot) — && git commit -m "plan(): Wave N complete — [brief summary]". On Wave 1, also git add any uncommitted spec.md (Step 1.1's fold-in); if git status --porcelain on the spec folder shows anything but spec.md/plan.md/mailbox.md, leave those unstaged and tell the user.
9. Per-wave review (Step 2).
10. Wave-boundary checkpoint — only if mailbox.md exists in the spec folder. Runs after the wave's review chain (Steps 2/3/3.5) finishes. (a) Compute this session's context in absolute tokens per the [Context gauge](#context-gauge). (b) Append orchestrator | wave N complete | ctx NNNk | HH:MM to the mailbox. (c) If ctx ≥ 180k: also append orchestrator | PAUSED after wave N | ctx NNNk | HH:MM, tell the user in one line that the run paused, and END the session — do not start the next wave. Disk is already a complete checkpoint; the supervisor spawns the next session, which resumes from the checkboxes.
11. Return to 1.

Step 2 — Per-wave review + Drift check

Spawn every code-reviewer against the whole wave diff (git diff HEAD~1..HEAD), never per-task slices — so a bug spanning two tasks stays visible. Reviewer count scales with size and risk:

• R1 — contract & correctness — always. Criteria below.
• R2 — cross-task & regression — add when the diff exceeds 4 files or 200 changed lines (git diff HEAD~1..HEAD --stat). Charter: "Find bugs from how this wave's changes interact — a signature, shared state, or config one task changed that another task or an existing caller now depends on. An empty result is valid."
• R3 — data integrity — add whenever the diff touches schema, migrations, or concurrent writes (any size). Charter: transactions, races, partial writes, migration reversibility — mirrors Step 4's data-integrity seat.

Merge findings (dedup by file + line-span + root cause, keep max severity) before the table below; at most three reviewers.

• Criteria (R1): the code-gated AC-N texts cited by this wave's tasks (copied from the spec). [human-gated:] ACs are excluded — they can't be verified against a diff (the ship gate routes them to Post-ship verification). Plus standard correctness/security/edge-case analysis.
• Drift question (posed to R1, whose dispatch also carries the wave's Structure Outline excerpts — the same ones the implementers got): "Does this diff contradict any locked D-NN in spec.md, or deviate from the Structure Outline excerpt? Cite the decision ID or outline element and the contradicting hunk." The outline half is the independent net — implementers self-report only the deviations they notice.
• Scope: this wave's diff only, not the whole plan. Single pass, no verifier; findings have verdict: null.

| Finding | Action | |---|---| | None | Append - Review: 0 findings — clean to ## Wave Reviews. Don't pause — next wave. | | Drift hit (diff contradicts a D-NN) | Run the Autonomy gate. Grounded + reversible (the D-NN is the source) → conform without asking: confirmed P1 → Step 3, log [auto-resolved]. A human-gated/visual D-NN isn't diff-provable → log it as a - P2/P3 [deferred]: entry (P2/P3 row below), don't ask. Only if the gate escalates (not confident, or the reviewer challenges the decision) → AskUserQuestion: "Fix code to conform to D-NN (Recommended)" / "The decision is wrong — supersede it" (→ Step 2.5) / "Accept with risk note in Wave Reviews". | | Outline-drift hit (diff deviates from the outline; no D-NN or AC contradicted) | A detail delta the implementer didn't self-report: append it as an [Implementation] entry to the Execution Log and continue — no pause. (A deviation that also contradicts an AC-N or locked D-NN takes the Drift-hit / Step 2.5 path instead.) | | P0/P1 | Set verdict: "confirmed", evidence: "Orchestrator-confirmed — per-wave review, no verifier pass" → fix-verify-loop (Step 3). | | P2/P3 not fixed | Log in ## Wave Reviews as - P2 [deferred]: ... / - P3 [deferred]: ... with the why — line-leading - required: the ship-gate anchor is ^- P[0-9]+ \[deferred\]: (Plan anchors, skills/write-plan/SKILL.md). |

Append the wave's review block to ## Wave Reviews once Step 3 outcomes are known: findings tally N findings: M fixed, D dropped by pre-gate, E demoted — the dropped/demoted counts come from fix-verify-loop's return buckets — plus Drift result and deferred entries. Only pause where the table says so.

Step 2.5 — Promote an [AC-affecting] discovery (user-gated)

Triggered the moment an [AC-affecting] discovery is logged (Step 1.6) or a Drift hit resolves to "the decision is wrong" (Step 2). Never auto-apply — this amends the contract.

1. Log first: write the [AC-affecting] Execution Log entry if none exists — the Drift path arrives without one, and the marker must have an entry to count against. It states the contradiction and evidence.
2. Present via AskUserQuestion: the contradiction, the evidence, the proposed spec change (revised AC-N text and/or D-NN supersession with new decision block). Also grep plan.md for unchecked - [ ] tasks citing the revised AC-N or the superseded D-0X and list each (title + first body line) in the same question with a disposition: keep / amend / drop — re-pointing a citation updates a label, not the task's instructions. Apply amend/drop edits to plan.md as part of step 6's promotion commit. Options: "Promote to spec (Recommended)" / "Adjust the proposal" / "Abort plan".
3. On approval, edit spec.md (AC line / D-NN block formats are canonical in skills/product-interview/SKILL.md's spec template):

• Revise the AC-N in place, appending *(revised per D-NN)* — ACs are the live contract, one current truth; the why lives in the decision trail.
• Supersede the old D-NN: flip Status: superseded, add Superseded-by: D-0Y. Touch nothing else in the block.
• Append the new D-0Y block (Supersedes: D-0X, rationale citing the evidence and plan Wave N). Heading type marker: inherit the superseded block's [product]/[tech], or [tech] if the change is build-originated (marker is advisory — see the canonical Decisions comment).

1. Re-point stale citations: grep plan.md for per D-0X and re-point to D-0Y.
2. Close the log entry: append promoted-to-spec [date]: AC-N revised, D-0X superseded by D-0Y. — ALWAYS lowercase and hyphenated; this is the ship gate's count-compare anchor (Plan anchors, skills/write-plan/SKILL.md). Never write the hyphenated token outside a real marker (unhyphenated prose is safe — the hyphen is what the gate counts).
3. Commit: git add [spec folder] && git commit -m "plan(): promote [AC-affecting] — D-0X superseded by D-0Y". Resume where execution stopped.

Step 3 — Per-wave fix-verify-loop

P0/P1 findings (incl. confirmed Drift fixes) → invoke the fix-verify-loop skill: findings with verdict: "confirmed" + evidence, artifact paths = this wave's files, criteria = the wave's cited ACs. On a returned escalation, AskUserQuestion: "Retry with guidance (Recommended)" / "Accept and defer" (→ log [deferred] in Wave Reviews) / "Skip finding" / "Abort plan".

Commit fixes separately: plan(): Wave N fixes — [summary].

Step 3.5 — Review fixes commit (regression check)

If Step 3 produced a fixes commit, spawn code-reviewer scoped to that commit's diff. Clean or P2/P3-only → continue (deferred entries logged as in Step 2). P0/P1 → orchestrator-confirm → fix-verify-loop → commit as Wave N regression fixes. Regression-fix commits are not re-reviewed per-wave; Step 4's full-diff review is the backstop.

Step 4 — Final review

All waves done → final review over git diff $PLAN_BASE_SHA..HEAD, all files changed across waves.

Single-wave plan → invoke the two-pass-review skill as a single review: Artifact = the diff; Criteria = every code-gated AC-N, selected mechanically: grep -E '^- \*\*AC-[0-9]+' spec.md | grep -F '[code-gated]'. (The wave's own review just covered this same diff — a panel would re-read the same page twice.)

Multi-wave plan → run the review panel inline. The two-pass-review skill is not invoked (its Pass 1 is hard-wired to one reviewer) but its protocol rules apply: zero P0/P1 across all seats → skip the verifier and present the clean result with checks_run; if the verifier rejects every finding, do NOT treat the review as clean — surface the reviewer/verifier disagreement.

Dispatch in parallel — every seat is a code-reviewer agent receiving the full $PLAN_BASE_SHA..HEAD diff:

• Seat A — contract. Criteria: every code-gated AC-N (mechanical selection grep above) + standard correctness/security/edge-case analysis.
• Seat B — regression / blast radius. Scope: the changed files PLUS t

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: preetamnath
• Source: preetamnath/agent-skills
• License: MIT
• Homepage: https://www.preetamnath.com/blog/agent-skills

Install and usage instructions live in the source repository linked above.