菜单
Implement a feature by executing its wave-grouped plan.md. TRIGGER when: user says 'run the plan', 'execute the plan', or 'implement it'; a plan.md has unchecked waves ready to build.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/preetamnath/agent-skills --skill execute-plan命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
| name | execute-plan |
| description | Implement a feature by executing its wave-grouped plan.md. TRIGGER when: user says 'run the plan', 'execute the plan', or 'implement it'; a plan.md has unchecked waves ready to build. |
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. Freezes the plan with the spec's Completion record.
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.
meta/specs/NNN-slug/ (or a path to either file in it). Reads both plan.md (waves, log) and spec.md (ACs, D-NNN-XX decisions, Structure Outline).Parent agent (orchestrator):
spec.md ONLY in Step 2.5 (promotion) and Step 6 (ship gate).Use the model the user requests. Otherwise, choose the implementer model per logical task:
Subagents (implementers):
AC-NNN-XX 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).D-NNN-XX/AC-NNN-XX ids may label a comment beside its fact.test_acNNN_XX_....{ files_changed: [paths], summary: string, discoveries: [{ type: "[Implementation]" | "[AC-affecting]" | "[Future]", note: string }] | null }[Implementation] discovery — there is no separate channel. If the task body conflicts with a copied current AC-NNN-XX text, the AC text is authoritative: implement to the AC and return the conflict as an [AC-affecting] discovery — never silently reconcile it.{ 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).git stash, git checkout -- ., git reset, or another command that changes the whole tree.git show HEAD:<path>.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 6.2), any destructive act. Auto-resolve only when the decision is grounded — it traces to a named source (a D-NNN-XX, AC-NNN-XX, 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-NNN-XX) never auto-fixes: log it as a - P2/P3 [deferred]: F-NNN-XX — ... entry in ## Wave Reviews (the anchor form on the P2/P3 row of Step 2) with the recommendation — Step 6.2 triages it at the ship gate.
Ground the decision in tiers; stop at the first that resolves:
AC-NNN-XX, locked D-NNN-XX, 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.D-NNN-XX/AC-NNN-XX, 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-NNN-XX'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.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]: <decision> — per <source>, conf 0.NN. These are code-only and still pass Step 2/4 review — the backstop for a mis-scored proceed.
The orchestrator chooses each review unit without asking. A review unit changes review timing, not execution state — every wave keeps its own dispatch, checkbox flips, and commit.
Before dispatch:
- Review pending: Waves N–M — base <SHA> under ## Wave Reviews; use N–N for one wave.HEAD before the unit's first implementation commit.After each wave in a two-wave unit:
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: first the staleness check — LAST=$(git log -1 --format=%H -- meta/specs/<slug>/plan.md); skip it if LAST is empty (plan never committed), else run git diff $LAST -- meta/specs/<slug>/spec.md (working tree included, so uncommitted spec edits count); any output means the plan was sequenced against an older spec — stop and route to write-plan. Then 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.Review pending: marker before new implementation:
AskUserQuestion: "Resume from the partial changes (Recommended)" / "Stash them and restart the wave" / "Abort plan". On Resume, dispatch one recovery implementer with the unchecked task IDs and existing diff to reconcile and finish the wave; use the user-requested model, or Opus by default.### Wave N with any [ ] tasks. Resuming mid-wave → dispatch only unchecked tasks. No unchecked tasks anywhere → resolve any pending review, then run Step 4.Must land together with: tasks go to one subagent and are classified together.AskUserQuestion: "Retry this item (Recommended)" / "Skip and mark dependents blocked" / "Abort plan". Don't commit a partial wave.## Execution Log under a ### Wave N — [date] heading, with its type tag ([Future] entries take the next F-NNN-XX — Plan anchors, skills/write-plan/SKILL.md). 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".[x] — the flip must land IN the wave commit (it's the resume state).git add [wave files + plan] && git commit -m "plan(<PLAN_SLUG>): 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, leave those unstaged and tell the user.Read REVIEW_BASE from the pending marker, set REVIEW_HEAD=$(git rev-parse HEAD), and spawn every code-reviewer against git diff $REVIEW_BASE..$REVIEW_HEAD. Review the whole unit, never task or commit slices, so cross-task and cross-wave bugs stay visible. Reviewer count scales with the unit's actual size and risk:
Merge findings (dedup by file + line-span + root cause, keep max severity) before the table below; at most three reviewers.
AC-NNN-XX texts cited by the unit'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.D-NNN-XX 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.verdict: null.| Finding | Action |
|---|---|
| None | Record 0 findings — clean beside the pending marker; continue to Step 3.5. |
Drift hit (diff contradicts a D-NNN-XX) | Run the Autonomy gate. Grounded + reversible (the D-NNN-XX is the source) → conform without asking: confirmed P1 → Step 3, log [auto-resolved]. A human-gated/visual D-NNN-XX 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 the D-NNN-XX (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-NNN-XX 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-NNN-XX or locked D-NNN-XX takes the Drift-hit / Step 2.5 path instead.) |
| P0/P1 | Set verdict: "confirmed", evidence: "Orchestrator-confirmed — review-unit pass, no verifier" → fix-verify-loop (Step 3). |
| P2/P3 not fixed | Log in ## Wave Reviews as - P2 [deferred]: F-NNN-XX — ... / - P3 [deferred]: F-NNN-XX — ... with the why — line-leading - required: the ship-gate anchor is ^- P[0-9]+ \[deferred\]:, and the F id follows the colon (Plan anchors, skills/write-plan/SKILL.md). |
Write the unit's findings tally and Drift result beside its pending marker once Step 3 outcomes are known. Step 3.5 replaces that marker with the completed review record. Only pause where the table says so.
Triggered the moment an [AC-affecting] discovery is logged (Step 1.7) or a Drift hit resolves to "the decision is wrong" (Step 2). Never auto-apply — this amends the contract.
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.
Present via AskUserQuestion: the contradiction, the evidence, the proposed spec change (revised AC-NNN-XX text and/or D-NNN-XX supersession with new decision block). Also grep plan.md for unchecked - [ ] tasks citing the revised AC-NNN-XX or the superseded old id 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 the promotion commit. Options: "Promote to spec (Recommended)" / "Adjust the proposal" / "Abort plan".
On approval, edit the spec(s) (AC line / decision block formats are canonical in skills/product-interview/SKILL.md's spec template). Worked example: old id D-014-03, new id D-014-11.
AC-NNN-XX in place, appending *(revised per D-NNN-XX)* — ACs are the live contract, one current truth; the why lives in the decision trail.Status: superseded, add Superseded-by: <new id>. Touch nothing else in the block.NNN and the next XX (highest existing XX in this spec + 1) — Supersedes: <old id>, 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).Classify the supersession, then re-point. Additive = every claim under the old id stays true; behavior-changing = some claim is now false. Either way, grep plan.md for the old id and re-point citations to the new id. A behavior-changing supersession also sweeps the repo: grep the old id across code and docs, dispatch ONE subagent with the hit list and the implementers' comment rules; per hit —
The subagent returns files_changed to stage in the promotion commit.
Close the log entry: append promoted-to-spec [date]: AC-NNN-XX revised, <old id> superseded by <new id>. — 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).
Commit: git add [spec folder(s)] [swept files] && git commit -m "plan(<PLAN_SLUG>): promote [AC-affecting] — <old id> superseded by <new id>". Resume where execution stopped.
P0/P1 findings (incl. confirmed Drift fixes) → invoke the fix-verify-loop skill: findings with verdict: "confirmed" + evidence, artifact paths = this unit's files, criteria = the unit'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(<PLAN_SLUG>): Waves N-M fixes — [summary] (use Wave N for a one-wave unit).
If Step 3 produced a fixes commit, spawn code-reviewer scoped to its diff when the fix reached outside the review unit's files (git show --name-only --format= HEAD vs the unit file-set) or the diff is sizeable — directionally 2+ files or ~50 lines; otherwise skip the review. Clean or P2/P3-only → continue (deferred entries logged as in Step 2). P0/P1 → orchestrator-confirm → fix-verify-loop → commit as Waves N-M regression fixes (Wave N for one wave). Regression-fix commits are not re-reviewed here; Step 4 therefore selects Full.
Set Fix coverage to none when Step 3 made no commit, reviewed through <SHA> when every fix commit received this regression check, and unreviewed when any fix or regression-fix commit did not.
Close the unit by replacing its pending marker and adjacent provisional lines with:
### Review unit: Waves N–M
- Range: <REVIEW_BASE>..<REVIEW_HEAD>
- Seats: R1[, R2, R3]
- AC evidence: <AC-NNN-XX PASS — file:line; ... | none>
- Findings: <N findings: M fixed, D dropped by pre-gate, E demoted | 0 findings — clean>
- Drift: <none | disposition>
- Fix coverage: <none | reviewed through <SHA> | unreviewed>
Keep every anchored deferred entry directly below the completed block; marker replacement never removes deferred findings.
All waves done and no pending review remains → select code-gated ACs with grep -E '^- \*\*AC-[0-9]+' spec.md | grep -F '[code-gated]', then choose the final mode over git diff $PLAN_BASE_SHA..HEAD:
Use Integration only when all conditions hold:
Use Full when any Integration condition fails or its evidence is unclear.
Integration review: spawn one code-reviewer over the full diff, licensed to inspect unchanged callers and consumers. Give it every code-gated AC-NNN-XX, every D-NNN-XX block, and the Structure Outline. Charter: "Return per-AC PASS/FAIL evidence, then find cross-wave or caller regressions and whole-build decision/outline drift that review-unit passes could not see. Do not repeat isolated implementation commentary already settled in completed review units. An empty finding set is valid."
Full review: run the panel below. For either mode, the two-pass-review 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, record the disagreement and AskUserQuestion: "Accept the verifier's rejection and continue" / "Run one sanity check (Recommended when the evidence is unclear)" / "Abort plan"; final review remains incomplete until that choice or sanity check resolves it.
Dispatch in parallel — every seat is a code-reviewer agent receiving the full $PLAN_BASE_SHA..HEAD diff:
AC-NNN-XX (mechanical selection grep above) + standard correctness/security/edge-case analysis.D-NNN-XX blocks from spec.md (including superseded, to catch reversion) + the frozen Structure Outline. Criteria: "Does the whole diff contradict any locked D-NNN-XX or deviate from the frozen Structure Outline? Cite the decision or outline element and the contradicting hunk. A contract-level contradiction is a Step 2.5 promotion, not just a fix. An empty result is a valid result."Merge (parent): dedup by file + line-span + root cause; keep the max severity; note which seats flagged each finding.
Verify: ONE verifier agent over the merged finding set — never one per seat. If the deduped P0/P1 findings exceed 4, batch the verification by relatedness (shared files, symbols, or call chains — never split findings that reference the same code path) and stitch the verdicts back into one envelope.
Confirmed P0/P1 → fix-verify-loop. A finding that contradicts an AC-NNN-XX or locked D-NNN-XX (not just fails it) is a contract break: log it as an [AC-affecting] Execution Log entry and run Step 2.5 — final review has no wave commit, but promotion works the same.
AskUserQuestion: "Run another final review (Recommended)" / "Abort plan".Verification run (conditional). After the selected review's fixes land, the parent runs the project's test/verification command once over the final state, if one exists — reading PASS/FAIL only, never source.
verification: passed.AskUserQuestion: "Fix" / "Accept (pre-existing or intended)" / "Abort". You classify; the parent never reads the test to guess why. "Fix" → fix-verify-loop as a confirmed finding, then return to the final-review re-run rule before running verification again; "Accept" → log an accepted risk in the ### Final review block, carried into the completion record.Record the selected mode, per-AC PASS/FAIL evidence, and the verification-run outcome in a ### Final review block appended to ## Wave Reviews — file-backed so it survives a session boundary; Step 6.3 copies it into the spec.
Invoke the durable-docs-update skill via the Skill tool inline. It sweeps the comments, syncs the docs, and reports both. Pass:
$PLAN_BASE_SHA..HEAD (Mode B);spec.md path, so it mines the locked D-NNN-XX decisions as candidates.Commit only the files durable-docs-update changed: git add [those paths] && git commit -m "plan(<PLAN_SLUG>): durable docs sync" — plan.md may hold unstaged Wave-Review text that must not ride along. Runs before the ship gate so the freeze stays the last act on the plan.
Run the plan's ## Ship Gate checklist; every box must be resolved before freezing.
sed -n '/^## Execution Log/,/^## Wave Reviews/p' plan.md | grep -c '^- \[AC-affecting\]' must equal the same slice piped to grep -ci 'promoted-to-spec'. Any shortfall → run Step 2.5 for the unmarked entries now; an unpromoted contract break fails the gate.[Future] and [deferred] entry (walk them via AskUserQuestion, batched): hole in the shipped thing → spec "Deferred / what this does NOT close"; new feature → surface to the user to place manually — no automatic destination exists; it must not die silently; noise → dies with the plan. The promoted text's new home opens with promoted from F-NNN-XX; the finding id never appears in code.skills/product-interview/SKILL.md's spec template; copy, don't move — the plan keeps its log):
Shipped: [date], Status Complete/Partial.## UX section + ACs, each an unchecked - [ ] line written steps → expected result. Every human-gated AC-NNN-XX MUST appear as a steps → expected line led by AC-NNN-XX: — owed, not orphaned (the diff never verified them). Confirm coverage mechanically: grep -E '^- \*\*AC-[0-9]+' spec.md | grep -F '[human-gated:' (grep the open [human-gated: form — it carries the inline "how" text; a closed bracket matches nothing and silently drops every human-gated AC) — every hit needs a matching AC-NNN-XX: line. If nothing is human-observable: write None — nothing manually observable.tighten-instruction and structure-prose skills via the Skill tool, then relay both lenses to one Sonnet subagent. Run this pass once, after all parent-authored prose exists and before changing ship state.
## Execution Log and ## Wave Reviews (including ### Final review), plus the spec's new Completion record.[Implementation], [AC-affecting], [Future], and [auto-resolved] entries must still start - [Tag].[deferred] entries must still start - P<severity> [deferred]:.promoted-to-spec.Status: → Shipped. Check the plan's Ship Gate boxes, set plan Status: FROZEN [date].git add [spec folder] && git commit -m "plan(<PLAN_SLUG>): ship — completion record, plan frozen".After this commit the plan is frozen — the shipped record.
The Completion record in spec.md is the durable summary — don't duplicate it. Report in this exact shape — a scan of this block is how the user learns what happened, so give substance to what they're knowingly carrying and counts to what was routinely handled:
**Build complete: [NNN-slug]**
- Built: [what shipped, one line]
- Tests: [passed | failed — accepted: why | no command]
- ACs: [n] PASS, [m] FAIL/PARTIAL — [name each non-pass | all pass]
- Spec changed mid-build: [old id → new id — what changed, one line each | none]
- Accepted risks (carried, not fixed): [one line each — see Wave Reviews | none]
- Deferred debt: [one line each, with severity | none]
- Handled autonomously: [N] outline deviations, [M] auto-resolved decisions (see Execution Log)
- Docs: [files touched | none needed]
- Post-ship verification (you verify): [each item, one per line | none]
(Counts write 0 when empty — a zero is information, not noise. A field with two or more items nests them as sub-bullets.)
[x] checkboxes — on resume, find the first wave with [ ] tasks, dispatch only those.PLAN_BASE_SHA recovers from the plan header's **Base SHA:** line; fallback: take the first plan(<PLAN_SLUG>): Wave commit (git log --format=%H --grep="plan(<PLAN_SLUG>): Wave" --reverse | head -1), then walk to its parent, skipping past any plan(<PLAN_SLUG>): promote commits — a Wave-1 promotion lands BEFORE the Wave-1 commit, and the base is the commit before all of them.- [Implementation], - [AC-affecting], - [Future], or - [auto-resolved]; deferred Wave Review entries start - P<severity> [deferred]:. Exact forms live under Plan anchors in skills/write-plan/SKILL.md. Never log a discovery untagged or start a narrative line with a bracketed tag.[Implementation] entries that later-wave dispatches carry so subagents trust the log over the outline.*(revised per D-NNN-XX)* is a human-readable convention, not a gate anchor — nothing greps it; don't build checks on it.