Execute Plan
Overview
Execute a pre-approved plan with strict adherence to scope, sequence, and verification. Treat the plan as a living document that records progress, findings, decisions, and outcomes as execution proceeds.
The input is typically: execute-plan docs/.plans/YYMMDD-HHmm-<plan-slug>/SUMMARY.md
Do not redesign the plan during execution. If ambiguity or blockers appear, stop and ask.
Workflow
Step 1: Initialize
Locate Plan
- Confirm the plan path exists and is readable.
- If a directory is provided, locate
SUMMARY.md inside it.
Load Execution Context
- Load only the project context relevant to the plan:
- If
docs/SUMMARY.md exists, read it first.
- Load only task-relevant detail docs.
- Prioritize
Code Standard docs for implementation conventions.
- If docs conflict with code or user intent, use the available input/question before broad changes.
- Review the plan’s phase files, context/orientation notes, dependencies, acceptance criteria, idempotence/recovery notes, decision log, and open questions.
- If an older plan is missing living-plan sections (
Progress, Surprises & Discoveries, Decision Log, Outcomes & Retrospective), add those sections before execution when the plan is otherwise clear.
Select Execution Mode (Explicit Rule)
- Default mode: Batch
- Use Interactive when any of the following is true:
- High-risk changes (auth, payments, migrations, security-critical logic)
- Irreversible operations (data migrations, destructive scripts)
- Unclear acceptance criteria
- User explicitly requests checkpoints
- If mode is unclear, ask once and proceed with user choice.
Find Next Pending Phase
- First
[ ] phase
- If none, first
[-] phase
- If no pending/in-progress phases remain, go to final verification.
Critical Plan Sanity Check
- Ensure each phase has:
- clear objective
- file targets
- verification commands
- observable acceptance criteria
- If observable acceptance criteria are missing but can be inferred from explicit phase verification and exit criteria, add them to the phase before execution.
- If essential details are missing or contradictory, stop and request clarification.
Step 2: Execute Per-Phase Loop
For each phase in order:
Skip Completed
- If status is
[x], continue to next phase.
Mark In Progress
- Update phase status to
[-] before making changes.
- Add a timestamped
Progress entry in SUMMARY.md describing the phase start.
Execute Exactly
- Implement only the tasks defined in that phase.
- Do not expand scope without approval.
- Write the minimum code that satisfies the phase. No speculative features, no abstractions for single-use code, no error handling for impossible scenarios. See Simplicity first and Surgical changes rules below.
- If implementation reveals a material surprise, record it under
Surprises & Discoveries in SUMMARY.md.
- If a decision is needed to stay within scope, record the decision and rationale under
Decision Log before continuing.
Verify Phase
- Run the phase-specific verification commands from the plan.
- At minimum, run relevant tests/checks tied to touched files.
- Record concise verification evidence in
SUMMARY.md under Progress or the phase's requested evidence location.
Handle Failures
- If verification fails:
- Attempt focused fixes within phase scope.
- Re-run verification.
- If still failing or root cause is outside scope, stop and report blocker.
Mark Complete
- Update phase status to
[x] only after verification passes.
- Add a timestamped
Progress entry with the verification result and changed files for that phase.
Progress Report
- Interactive mode: report and wait for confirmation before next phase.
- Batch mode: report briefly and continue immediately.
Step 3: Final Verification
After all phases are complete:
Project-Wide Validation
- Run full lint/type-check suite
- Run all relevant tests (or full test suite if required by the plan)
- Run build verification if applicable
Stabilize
- Fix regressions introduced during execution.
- Re-run failed checks until green or blocked.
Manual Validation Checkpoint
- If user/manual QA is required, ask explicitly and pause:
Verified to accept
- or provide feedback for follow-up iteration
Update Outcomes
- Complete
Outcomes & Retrospective in SUMMARY.md with final result, verification summary, approved deviations, and follow-ups.
Step 4: Completion Artifacts
Documentation Sync
- If behavior/architecture/codebase expectations changed, update the
docs artifacts.
Create Execution Report
- File:
docs/.plans/YYMMDD-HHmm-<plan-slug>/EXECUTION-REPORT.md
- Include all required sections below.
Prepare Final Gate
- Do not archive before final user confirmation. The user may choose
Need verify, and execution must continue against the same plan path.
Step 5: Final Confirmation Gate
After completion artifacts are done, ask the user for a final confirmation using the input/question tool with exactly these options:
Confirm: End session
Need verify
Handle the selected option as follows:
Confirm: End session
- Archive the plan folder to
docs/.plans/archived/.
- Announce:
Execution complete. Report archived at docs/.plans/archived/YYMMDD-HHmm-<plan-slug>/EXECUTION-REPORT.md.
- End the execution session.
Need verify
- Allow the user to provide verification feedback/details.
- Do not archive.
- Continue the execution loop to address feedback, then re-run verification and completion steps as needed.
Execution Report Standard
EXECUTION-REPORT.md must use the following template: references/execution-report-template.md
Rules
- Respect project standards: follow
docs/ and related project docs.
- Follow the plan strictly: no silent scope changes.
- Stop on blocker: missing dependency, contradictory instructions, or unexplained failures.
- No guessing: ask for clarification when uncertain.
- Verify before complete: never mark phase done without passing checks.
- Keep the plan alive: update progress, discoveries, decisions, and outcomes in
SUMMARY.md as execution proceeds. Do not rely on chat history for important execution state.
- Idempotency: prefer safe/re-runnable operations.
- Simplicity first: Implement the minimum code that satisfies the phase's exit criteria. No features beyond what the plan asks for. No abstractions for single-use code. No configurability that wasn't requested. If you write 200 lines and it could be 50, rewrite it.
- Surgical changes: Touch only what the phase requires. Don't "improve" adjacent code, comments, or formatting. Don't refactor things that aren't broken. Match existing style even if you'd do it differently. Only remove imports/variables/functions that your changes orphaned — don't delete pre-existing dead code unless the plan asks for it. Every changed line should trace to a phase task.
- Write artifacts in language same with the current session.
1---
2name: execute-plan
3description: Execute an approved implementation plan exactly and safely. Use for ExecPlan-style plan execution, resumable phase checklists, multi-hour implementation work, migrations, significant refactors, and plans that require verification checkpoints, status tracking, and final reporting.
4argument-hint: "[plan path, e.g. docs/.plans/YYMMDD-HHmm-<plan-slug>/SUMMARY.md]"
5license: MIT
6metadata:
7 source: https://skillmd.com/skills/gabrielmoreira/execute-plan
8---
9
10# Execute Plan
11
12## Overview
13
14Execute a pre-approved plan with strict adherence to scope, sequence, and verification. Treat the plan as a living document that records progress, findings, decisions, and outcomes as execution proceeds.
15
16The input is typically: `execute-plan docs/.plans/YYMMDD-HHmm-<plan-slug>/SUMMARY.md`
17
18Do not redesign the plan during execution. If ambiguity or blockers appear, stop and ask.
19
20## Workflow
21
22### Step 1: Initialize
23
241. **Locate Plan**
25 - Confirm the plan path exists and is readable.
26 - If a directory is provided, locate `SUMMARY.md` inside it.
27
282. **Load Execution Context**
29 - Load only the project context relevant to the plan:
30 - If `docs/SUMMARY.md` exists, read it first.
31 - Load only task-relevant detail docs.
32 - Prioritize `Code Standard` docs for implementation conventions.
33 - If docs conflict with code or user intent, use the available input/question before broad changes.
34 - Review the plan’s phase files, context/orientation notes, dependencies, acceptance criteria, idempotence/recovery notes, decision log, and open questions.
35 - If an older plan is missing living-plan sections (`Progress`, `Surprises & Discoveries`, `Decision Log`, `Outcomes & Retrospective`), add those sections before execution when the plan is otherwise clear.
36
373. **Select Execution Mode (Explicit Rule)**
38 - Default mode: **Batch**
39 - Use **Interactive** when any of the following is true:
40 - High-risk changes (auth, payments, migrations, security-critical logic)
41 - Irreversible operations (data migrations, destructive scripts)
42 - Unclear acceptance criteria
43 - User explicitly requests checkpoints
44 - If mode is unclear, ask once and proceed with user choice.
45
464. **Find Next Pending Phase**
47 - First `[ ]` phase
48 - If none, first `[-]` phase
49 - If no pending/in-progress phases remain, go to final verification.
50
515. **Critical Plan Sanity Check**
52 - Ensure each phase has:
53 - clear objective
54 - file targets
55 - verification commands
56 - observable acceptance criteria
57 - If observable acceptance criteria are missing but can be inferred from explicit phase verification and exit criteria, add them to the phase before execution.
58 - If essential details are missing or contradictory, stop and request clarification.
59
60### Step 2: Execute Per-Phase Loop
61
62For each phase in order:
63
641. **Skip Completed**
65 - If status is `[x]`, continue to next phase.
66
672. **Mark In Progress**
68 - Update phase status to `[-]` before making changes.
69 - Add a timestamped `Progress` entry in `SUMMARY.md` describing the phase start.
70
713. **Execute Exactly**
72 - Implement only the tasks defined in that phase.
73 - Do not expand scope without approval.
74 - Write the minimum code that satisfies the phase. No speculative features, no abstractions for single-use code, no error handling for impossible scenarios. See **Simplicity first** and **Surgical changes** rules below.
75 - If implementation reveals a material surprise, record it under `Surprises & Discoveries` in `SUMMARY.md`.
76 - If a decision is needed to stay within scope, record the decision and rationale under `Decision Log` before continuing.
77
784. **Verify Phase**
79 - Run the phase-specific verification commands from the plan.
80 - At minimum, run relevant tests/checks tied to touched files.
81 - Record concise verification evidence in `SUMMARY.md` under `Progress` or the phase's requested evidence location.
82
835. **Handle Failures**
84 - If verification fails:
85 - Attempt focused fixes within phase scope.
86 - Re-run verification.
87 - If still failing or root cause is outside scope, stop and report blocker.
88
896. **Mark Complete**
90 - Update phase status to `[x]` only after verification passes.
91 - Add a timestamped `Progress` entry with the verification result and changed files for that phase.
92
937. **Progress Report**
94 - **Interactive mode:** report and wait for confirmation before next phase.
95 - **Batch mode:** report briefly and continue immediately.
96
97### Step 3: Final Verification
98
99After all phases are complete:
100
1011. **Project-Wide Validation**
102 - Run full lint/type-check suite
103 - Run all relevant tests (or full test suite if required by the plan)
104 - Run build verification if applicable
105
1062. **Stabilize**
107 - Fix regressions introduced during execution.
108 - Re-run failed checks until green or blocked.
109
1103. **Manual Validation Checkpoint**
111 - If user/manual QA is required, ask explicitly and pause:
112 - `Verified` to accept
113 - or provide feedback for follow-up iteration
114
1154. **Update Outcomes**
116 - Complete `Outcomes & Retrospective` in `SUMMARY.md` with final result, verification summary, approved deviations, and follow-ups.
117
118### Step 4: Completion Artifacts
119
1201. **Documentation Sync**
121 - If behavior/architecture/codebase expectations changed, update the `docs` artifacts.
1222. **Create Execution Report**
123 - File: `docs/.plans/YYMMDD-HHmm-<plan-slug>/EXECUTION-REPORT.md`
124 - Include all required sections below.
125
1263. **Prepare Final Gate**
127 - Do not archive before final user confirmation. The user may choose `Need verify`, and execution must continue against the same plan path.
128
129### Step 5: Final Confirmation Gate
130
131After completion artifacts are done, ask the user for a final confirmation using the input/question tool with exactly these options:
132
133- `Confirm: End session`
134- `Need verify`
135
136Handle the selected option as follows:
137
1381. **`Confirm: End session`**
139 - Archive the plan folder to `docs/.plans/archived/`.
140 - Announce: `Execution complete. Report archived at docs/.plans/archived/YYMMDD-HHmm-<plan-slug>/EXECUTION-REPORT.md.`
141 - End the execution session.
142
1432. **`Need verify`**
144 - Allow the user to provide verification feedback/details.
145 - Do not archive.
146 - Continue the execution loop to address feedback, then re-run verification and completion steps as needed.
147
148## Execution Report Standard
149
150`EXECUTION-REPORT.md` must use the following template: `references/execution-report-template.md`
151
152## Rules
153
154- **Respect project standards**: follow `docs/` and related project docs.
155- **Follow the plan strictly**: no silent scope changes.
156- **Stop on blocker**: missing dependency, contradictory instructions, or unexplained failures.
157- **No guessing**: ask for clarification when uncertain.
158- **Verify before complete**: never mark phase done without passing checks.
159- **Keep the plan alive**: update progress, discoveries, decisions, and outcomes in `SUMMARY.md` as execution proceeds. Do not rely on chat history for important execution state.
160- **Idempotency**: prefer safe/re-runnable operations.
161- **Simplicity first**: Implement the minimum code that satisfies the phase's exit criteria. No features beyond what the plan asks for. No abstractions for single-use code. No configurability that wasn't requested. If you write 200 lines and it could be 50, rewrite it.
162- **Surgical changes**: Touch only what the phase requires. Don't "improve" adjacent code, comments, or formatting. Don't refactor things that aren't broken. Match existing style even if you'd do it differently. Only remove imports/variables/functions that _your_ changes orphaned — don't delete pre-existing dead code unless the plan asks for it. Every changed line should trace to a phase task.
163- Write artifacts in language same with the current session.