exec-plan

ExecPlan — Lifecycle Management

Announce at start: "Using the exec-plan skill."

What is an ExecPlan

A self-contained, living document that a fresh agent session can follow to deliver observable, working behavior. Lives in docs/exec-plans/. The format follows the specification in docs/PLANS.md.

An ExecPlan is NOT a todo list. It is a narrative that tells the story of a change: why it matters, what the codebase looks like now, what it should look like after, and how to prove it worked.

When to use this skill

• Required for multi-step or multi-file work, new features, refactors, or tasks expected to take more than about an hour.
• Optional for trivial fixes, but if you skip it for a substantial task, state the reason.
• Always when resuming work from a previous session.

The Three Modes

Mode 1: CREATE a new plan

When starting new multi-step work:

1. Read docs/PLANS.md for the template and requirements.
2. Create the plan at docs/exec-plans/active/{descriptive-kebab-name}.md.
3. Fill ALL sections from the template. Non-negotiable sections:
   • Purpose / Big Picture — what the user can see/do after the change
   • Progress — empty checkboxes for each milestone
   • Surprises & Discoveries — start with (none yet)
   • Decision Log — start with (none yet)
   • Outcomes & Retrospective — start with (fill when complete)
   • Context and Orientation — full file paths, term definitions, current state
   • Plan of Work — narrative milestones with goal → work → result → proof
   • Concrete Steps — exact commands with expected outputs
   • Validation and Acceptance — observable proof of success
   • Idempotence and Recovery — how to retry or roll back
4. Every file path must be absolute from repo root.
5. Every term must be defined inline — assume the reader knows nothing.
6. Commit the plan before starting implementation.

Mode 2: CONTINUE an existing plan

When resuming work or executing the next milestone: