Skip to main content
skill CX Codex

exec-plan — Claude Code skill: what it does, how to install

exec-plan manages self-contained Markdown execution plans across agent sessions for tasks touching more than three files or taking over an hour.

MIT 239 installs ★ 227 updated 2026-08-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pproenca/dot-skills --skill exec-plan -a claude-code
Open on GitHub

What exec-plan does

This skill guides agents through structured implementation plans stored in docs/exec-plans/. Instead of a bare todo list, it enforces a self-contained narrative based on docs/PLANS.md. Each plan documents visible behavior changes, full file paths from repo root, explicit verification commands, and a log of decisions.

The workflow uses three distinct modes. During creation, the agent drafts a new plan in docs/exec-plans/active/. When resuming, it finds unchecked milestones and logs timestamped progress as changes land. Without updating the plan file after each step, the next agent session will redo the work. Once every milestone passes validation, the skill moves the document to completed/ using git mv.

What it helps with

  • maintain context across multiple agent sessions
  • break multi-file refactors into verifiable milestones
  • record explicit verification commands with expected outputs
  • track architectural choices and surprises during implementation

Example prompts for the agent

  • Create an execution plan for migrating the database schema
  • Continue working on the active plan
  • Finish the plan and write the retrospective

How to install exec-plan

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill exec-plan -a claude-code

2Manually: put the files in place

~/.claude/skills/exec-plan/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/exec-plan/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about exec-plan

How to install exec-plan in Claude Code?

Run npx skills add pproenca/dot-skills --skill exec-plan -a claude-code. Alternatively, place the definition file at ~/.claude/skills/exec-plan/SKILL.md.

When should exec-plan be used?

Use it whenever work spans across sessions, touches more than three files, or takes more than an hour to finish.

What happens when an execution plan is finished?

The agent fills in the retrospective section and runs git mv docs/exec-plans/active/{name}.md docs/exec-plans/completed/{name}.md to archive it.

Source text

SKILL.md · MIT
---
name: exec-plan
description: |
  Manage the lifecycle of ExecPlans — self-contained, living specifications for multi-step work.
  Creates plans in the correct format, enforces living section updates, and handles the
  active → completed transition. Use for any work expected to take more than one session or
  touching more than 3 files.
  Triggers: "create a plan", "write a plan", "start plan", "continue plan", "resume plan",
  "finish plan", "complete plan", multi-step features, refactors, or tasks spanning sessions.
allowed-tools: Read, Glob, Grep, Write, Edit, Bash
---

# 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:

1. Read the plan file in `docs/exec-plans/active/`.
2. Find the first unchecked item in Progress.
3. Before starting work, check: are there any Surprises from previous sessions that affect this task?
4. Execute the milestone following the Plan of Work.
5. **After each completed milestone, IMMEDIATELY update the plan:**
   - Check the Progress item with a timestamp: `- [x] (YYYY-MM-DD HH:MMZ) Description`
   - Add any Surprises & Discoveries encountered
   - Add any Decision Log entries for choices made
6. Commit the plan update alongside the code changes.
7. Run the Validation commands to confirm success.

**CRITICAL: Never claim a milestone is done without updating the plan file.** The plan IS the persistence mechanism. If you don't update it, the next session will redo the work.

### Mode 3: COMPLETE a plan

When all milestones are done:

1. Fill the **Outcomes & Retrospective** section:
   - What was achieved vs what was planned
   - Any remaining gaps
   - Lessons learned
   - Unexpected benefits or costs
2. Move the file: `git mv docs/exec-plans/active/{name}.md docs/exec-plans/completed/{name}.md`
3. Commit with message: `docs: complete exec-plan {name}`

## Quality Checks

Before committing any plan (new or updated), verify:

- [ ] Purpose describes user-visible behavior, not just code changes
- [ ] Progress has timestamps on completed items
- [ ] Context names files by full path from repo root
- [ ] All terms are defined inline (no "see external doc" for critical terms)
- [ ] Validation has exact commands AND expected outputs
- [ ] Recovery section explains rollback for each risky step
- [ ] Surprises section is up to date (even if empty)
- [ ] Decision Log captures any choices made during implementation

## Anti-patterns

- **Checklist without narrative**: "- [ ] Edit file X" tells the next session nothing. WHY edit it? WHAT changes? HOW to verify?
- **External references for critical context**: "See ARCHITECTURE.md for details" — the plan must be self-contained. Copy the relevant context in.
- **Forgetting to update Progress**: The most common failure. If you finish a milestone and don't check the box with a timestamp, the next session will redo it.
- **Leaving completed plans in active/**: After all milestones are done, MOVE to completed/. Active plans should only be unfinished work.
- **Skipping Validation**: "Tests pass" is not acceptance. "The `isValid` computed property no longer exists in the file, verified by `grep -n isValid file.swift` returning no results" IS acceptance.

## Integration with other skills

- Before implementing plan milestones that involve TCA code: invoke `/pfw-composable-architecture`
- Before implementing plan milestones that involve debugging: invoke the `debug` skill
- Before implementing plan milestones that involve refactoring: invoke the `refactor` skill
- Before implementing plan milestones that involve API design: invoke the `rest-api-design` skill
- After completing all plan milestones: invoke `refactor` skill for a final cleanup pass

© pproenca · MIT · pproenca/dot-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set139

The whole set →
domain-architect domain-architect identifies business domains in a Swift codebase by tracing user capabilities, not folder names. Maps each domain's vertical slice from types to UI. CX Codex +1 249installs app-planner app-planner creates a structured Markdown design plan using Apple Design DNA patterns before coding starts. Organizes screens into buildable milestones for ios-taste. CX Codex +1 244installs threat-model threat-model maps attack surfaces and trust boundaries across a codebase by tracing untrusted inputs directly to execution sinks. CX Codex +1 243installs opencode-ts The opencode-ts skill guides TypeScript implementation, tests, and refactoring in Effect-based projects. It gives the agent a workflow tied to the project’s architecture and conventions. CX Codex +1 240installs graph-schema graph-schema is a Claude Code skill for designing, reviewing, and refactoring graph database schemas. It activates for node and relationship modeling or when mapping a domain into a graph. CX Codex +1 239installs clean-code-ts-react clean-code-ts-react adapts Robert C. Martin's Clean Code principles for TypeScript 5.x and React 19. Guides code reviews, component architecture, and refactoring sessions. CX Codex +1 238installs cli-for-agents cli-for-agents is a Claude Code skill for designing and reviewing CLIs used by AI agents and automation. It applies to work on subcommands, flags, help text, and error messages. CX Codex +1 237installs eval-mcp eval-mcp measures MCP tool schema quality and Claude's tool selection accuracy. Detects confusing descriptions and runs intent benchmarks. CX Codex +1 234installs

Project sponsors

Companies that keep this analytics open