Execute an plan end-to-end. Use when a plan exists and is ready to implement, when resuming a partially completed plan, or when asked to "execute the plan", "run the plan", or "implement the plan".
Plan Progress checkboxes — checked items with timestamps are authoritative
Git log — commits referencing this plan
If prior work found: Summarize done / in-progress / remaining. Confirm with user. Skip to Phase 2 at the correct milestone.
If fresh: Proceed to Phase 1.
Phase 1: Understand, Setup, Decompose
1. Find and Read the Plan
Resolution order:
$ARGUMENTS path (if provided)
Newest file in docs/plans/active/ matching *-plan.md
Ask the user
Read the plan completely. Understand Purpose, milestones, validation steps, and tech stack.
2. Critical Review
Before executing, verify the plan is executable:
Every milestone has a validation step (commands, expected output)
File paths referenced in the plan exist (spot-check via basic shell existence checks)
Commands are runnable (check binary existence, correct flags)
No ambiguous steps that would require guessing
If gaps found: Report them clearly. Recommend re-planning with dev-plan or ask the user to clarify. Do not proceed with a broken plan.
3. Workspace Isolation
First, identify the current branch (git branch --show-current) so choices are concrete.
Ask the user:
A) Create worktree (Recommended) — isolated workspace, easy cleanup
B) Create branch — lighter isolation
C) Continue on current branch — requires explicit consent if main/master
If worktree: use git-worktrees skill. Record baseline SHA with git rev-parse HEAD.
4. Task Creation
Map the plan into the plan file itself:
Ensure the plan's Progress section contains one checkbox per actionable step, grouped by milestone.
If your environment supports a task list, you may mirror milestones/steps there, but do not treat that task list as a source of truth.
Show the proposed task breakdown. Get user approval before creating/mirroring tasks.
5. Execution Preference
Present interactive choice:
A) Execute all, report when done (Default) — autonomous, minimal interruption
B) Pause per milestone — review between milestones
C) Pause per step — maximum control
6. Skill Discovery
Scan the plan for work that maps to known skills. Inject relevant skills into subagent prompts:
Feature implementation → test-driven-development
Git worktree setup → git-worktrees
Framework-specific work → relevant framework skills
Phase 2: Execute (per milestone)
Repeat for each milestone in order.
Step 1: Re-Anchor (mandatory)
Re-read the plan's Purpose / Big Picture and the current milestone's scope. This prevents drift during long implementations. Do this every milestone, no exceptions.
Step 2: Analyze Dependencies
Group the milestone's steps into execution batches:
Steps with no shared files and no sequential dependencies → same batch (parallel)
Steps that modify the same file or depend on prior output → sequential batches
When in doubt: sequential. Wrong parallelization causes merge conflicts and subtle bugs.
Step 3: Execute Steps
Spawn one subagent per step. Each subagent receives:
Applicable skills (e.g., test-driven-development for feature work)
The expectation that the orchestrator will independently verify and commit
Subagent protocol:
For feature work: TDD — write test first, verify it fails, implement, verify it passes
Read referenced files and patterns before writing code
Do not commit by default. Leave a clean working tree for the orchestrator to validate and commit.
Report back: what was done, how to validate, any surprises
Step 4: Independent Verification
Never trust subagent reports alone. The orchestrator runs the step's validation command itself:
Execute the exact validation command from the plan
Compare output against expected result
Evidence is stale after 5 minutes or any code change — re-run if needed
Step 5: Failure Loop
If verification fails, escalate through 3 iterations:
Same agent retry — give it the failure output, let it fix
Fresh subagent — new agent with full failure context (avoids prior agent's blind spots)
Ask user — present what failed and what was tried. Options: A) Skip this step, B) Stop execution, C) Modify the plan
Step 6: Milestone Verification Gate
All of these must pass before proceeding to the next milestone:
Milestone's validation commands pass
The plan's regression checks pass (tests, and lint/format if the plan defines those commands)
Do not proceed with a failing gate. Fix or ask the user.
Step 7: Update Living Document
Update the Plan file:
Check off Progress items with timestamps: - [x] 1.1 (YYYY-MM-DD HH:MMZ) Step description
If new steps were added during this milestone (scope expansion, plan modification, or discovery), add them as unchecked items in the Progress section under the correct milestone before checking off completed work
Log any surprises in Surprises & Discoveries
Record decisions in Decision Log
Step 8: Milestone Transition
If execution preference is B (pause per milestone):
Present summary: what was completed, any surprises, what's next
Ask to continue or adjust
Phase 3: Finish
Steps are strictly sequential. Do not parallelize.
1. Verify Completeness
Every Progress checkbox in the plan is checked
Run the plan's final acceptance test
Run the plan's regression checks — all passing, no regressions
2. Simplification Pass
Get changed files: git diff --name-only $(git merge-base HEAD <base>)..HEAD
Review for behavior-preserving simplifications only:
Dead code removal
Unnecessary complexity
Naming improvements
Separate refactor: commits. Do not change behavior.
3. Final Review Offer
Present interactive choice:
A) Full review with /dev-review (Recommended) — runs all applicable reviewers as parallel subagents, synthesizes findings
B) Quick review — correctness + simplicity only
C) Skip to finish
If A or B selected, invoke /dev-review with the current base branch. It handles severity gating, fix loops, and re-review internally.
If fixes applied during review, recommend another review round to verify.
4. Plan Retrospective
Update the plan's Outcomes & Retrospective section:
What was accomplished vs. original purpose
Surprises encountered
Decisions made and their rationale
Lessons learned
5. Handoff
Present interactive choice:
A) Ship it — use dev-commit skill
B) Another review round
C) Capture learnings & archive plan — use dev-wrapup to extract lessons, update docs, and move plan to completed
D) Keep branch, I'll handle PR myself
E) Done — work stays on branch
Plan Drift Handling
Drift Level
Action
Minor (different file path, small API change)
Update plan, note in Surprises, continue
Significant (wrong approach, new dependency)
STOP. Report with evidence. Ask user: update plan / continue as-is / stop
Blocked (external dep unavailable)
Mark blocked, skip to next unblocked step, report
Scope expansion (new work discovered)
Add steps to plan and to Progress section, create tasks, get user approval before executing
Commit Strategy
One commit per completed step (after orchestrator verification): <type>(<scope>): <description>
Commit body includes: Plan: <plan-name>, Milestone: <N>.0, Step: <N>.<M>
Step is the plan's step ID (e.g., 1.2), not the internal Phase/Step headings in this skill
No commit if the plan's validation/regression checks fail
Simplification and review fixes get separate commits
Partial progress → update plan Progress with note, not a commit
Resume and Recovery
State lives in two places: plan Progress checkboxes (authoritative) and git history (supplementary).
Phase 0 reconciles both on resume
On context window limits: update plan Progress, commit any valid work, tell user: "Resume with /dev-work <plan-path>"
Steps are idempotent per Plan contract — safe to re-execute
Guardrails
NEVER:
Claim completion without running verification yourself
Silently deviate from the plan
Commit with failing tests
Skip milestone verification gate
Start on main/master without explicit consent
Use mock tests
Force push without explicit request
Run code changes parallel with code review
ALWAYS:
Re-read Purpose and milestone scope before starting each milestone
Run verification commands independently (not trusting subagent output)
Update plan Progress section after each step
Keep Progress section in sync: any step added to the plan must also appear in Progress
Record surprises and decisions as they happen
Use subagents for implementation (keep orchestrator context clean)