Execution Plans: From Epic to Verified Change
Applies to: any change bigger than one sentence, and every epic you deliver with an agent · Time to learn: 40 min reading + 20 min exercise · Lever: context + feedback
Large changes fail in agent sessions for a simple reason: the work does not fit in one focused context. The fix is the same one engineers have always used. Write the plan down, cut it into pieces that can each be finished and verified, and let the agent execute one piece at a time.
- Follow explore, plan, implement, verify, commit. Use plan mode for the first two steps.
- Keep the plan in a file in the repo, not in chat. It survives
/clear, handoffs, and a teammate picking the work up. - For an epic, write several small plans, not one giant one:
docs/plans/<epic>/with a README index and01-...md,02-...md. Each plan is one session or one PR. - Every step in a plan has a verification the agent can run. No verification, no step.
- Run independent plans in parallel with worktrees or subagents. Run dependent plans in order.
Why it matters in the AI age
An agent is only as good as the context it gets, the feedback loop it can run, and the guardrails around it. An execution plan serves two of those: it is focused context for one session, and it holds the verification commands that close the loop.
- Anthropic's core constraint: the context window fills up fast, and performance degrades as it fills (best practices). A plan sized to one session keeps the window small.
- Anthropic's long-running agent work found that a fresh session orients itself well from a progress file, git history, and a structured task list (harnesses for long-running agents).
- As an FDE you will often inherit half-finished work in a client repo. A plan file lets you, a teammate, or a new agent session resume without replaying a chat.
Core concepts
The Anthropic workflow
Anthropic recommends four phases: explore, plan, implement, commit, with plan mode separating exploration from execution (best practices). Add an explicit verify step, because Anthropic's top tip is to give Claude a way to check its own work: tests, a build, a linter, or a screenshot.
| Phase | What happens | Tool in Claude Code |
|---|---|---|
| Explore | Read code, find conventions, no edits | Plan mode, Explore subagent |
| Plan | Write the steps, files, and checks | Plan mode, then save to docs/plans/ |
| Implement | Do one step at a time | Normal mode, one plan per session |
| Verify | Run the checks from the plan | Tests, linters, hooks |
| Commit | One logical change, clear message | Git, PR |
Skip the plan for changes you could describe in one sentence (best practices).
Plan mode in Claude Code
Plan mode tells Claude to research and propose changes without making them: it reads files, runs shell commands to explore, and writes a plan, but does not edit your source (permission modes).
| Action | How |
|---|---|
| Enter during a session | Shift+Tab to cycle default, acceptEdits, plan; the status bar shows plan mode on |
| Enter for one prompt | Prefix the prompt with /plan |
| Start in plan mode | claude --permission-mode plan |
| Make it the project default | Set defaultMode to plan in .claude/settings.json |
| Edit the plan | Ctrl+G opens it in your editor |
| Leave | Approve the plan (choose how edits are approved) or choose to keep planning |
Source for all rows: permission modes and common workflows. Approving a plan exits plan mode. Other harnesses have similar read-only modes; the file-based plan below works in all of them.
Why a written plan beats a chat plan
| A plan in chat | A plan in docs/plans/ |
|---|---|
Lost on /clear or when the window compacts | Reloaded from disk by any session |
| Only you can see it | Reviewed in a PR by the client team and by teammates |
| Hard to resume after a break | Progress log says what is done and what is next |
| Drifts silently as the agent works | Agent updates it; the diff shows drift |
| Cannot be handed to another agent | Any agent, or a subagent, can execute it |
This is the plan-side version of structured note-taking: keep persistent notes outside the window and reload them (effective context engineering). Plans live with the rest of your project knowledge; see Scratchpads, Memory, and Markdown Knowledge Bases.
Plan formats in use
You do not need a framework to start. These are the shapes you will meet:
| Format | Shape | Where it fits |
|---|---|---|
OpenAI ExecPlans (PLANS.md) | One living design document per feature. AGENTS.md tells the agent when to write one; PLANS.md defines the format. Mandatory sections: Progress, Surprises and Discoveries, Decision Log, Outcomes and Retrospective (cookbook) | Multi-hour single-feature work |
| GitHub Spec Kit | Constitution once, then per feature spec.md, plan.md, tasks.md under specs/<branch>/ (repo, spec-driven.md) | Teams that want a spec-first process and a CLI scaffold |
| Kiro specs | Three files per spec: requirements.md (or bugfix.md), design.md, tasks.md (Kiro docs) | Work inside the Kiro IDE |
| Anthropic long-running harness | An init.sh, a progress file (claude-progress.txt), and a JSON feature list where each entry has passes: false until tested; one feature per session; git commits as checkpoints (Anthropic) | Long autonomous runs with many small features |
The template below borrows the best parts: ExecPlan's living progress and decision logs, Spec Kit's separation of what from how, and the harness's rule that nothing is done until it is verified. Spec Kit's own guidance is that a plan should "remain high-level and readable" (spec-driven.md). The command prefix differs between Spec Kit docs (/speckit.* and /speckit-*), so check the version you install.
One epic, several plans
One plan for a whole epic becomes a long file that no single session can hold. Split it.
- An epic is the business outcome (for example, "move auth to the client's SSO").
- A plan is one slice of it that one agent session can finish and one PR can contain.
- A session executes one plan, starting from a clean context.
- A PR is the reviewable result of one plan.
In the diagram, plan 01 comes first, plans 02 and 03 depend only on 01 and can run side by side, and plan 04 waits for both.
How to do it
1. Explore and draft in plan mode
Start Claude Code in plan mode (claude --permission-mode plan) and ask for the breakdown (prompt below). Review the proposed slices. Edit them yourself; you know the client context.
2. Lay out the epic directory
docs/plans/sso-migration/
README.md # epic overview + plan index (status, dependencies)
01-user-model.md # one session / one PR
02-auth-endpoints.md
03-admin-ui.md
04-cutover.md
The README is the only file every session reads first. Keep it short.
# Epic: SSO migration
**Goal:** All users sign in through the client's identity provider; local passwords are removed.
**Non-goals:** Changing roles or permissions; mobile app.
**Links:** `docs/adr/0007-sso.md`, ticket [PROJ-123], IdP docs.
## Plan index
| # | Plan | Depends on | Status | PR |
|---|---|---|---|---|
| 01 | User model and IdP link table | none | done | #41 |
| 02 | Auth endpoints (OIDC callback) | 01 | in progress | #44 |
| 03 | Admin UI for linking | 01 | not started | none |
| 04 | Cutover and password removal | 02, 03 | not started | none |
## Epic-level acceptance
- E2E login through the staging IdP passes.
- No code path reads `password_hash`.
## Epic decisions
- 2026-10-20: Use OIDC, not SAML (client IdP supports both; OIDC has a maintained library here).
3. Write each plan from the template
# Plan 02: Auth endpoints (OIDC callback)
**Epic:** [SSO migration](./README.md) · **Depends on:** 01 · **Status:** in progress
## Goal
One sentence: what is true when this plan is done.
## Context and links
- Relevant code: `src/auth/`, `src/api/routes.py`
- Decisions: `docs/adr/0007-sso.md`
- Plan 01 added the table `idp_links`.
## Non-goals
- No UI changes (plan 03). No removal of password login (plan 04).
## Steps
1. Add `/auth/oidc/login` and `/auth/oidc/callback` handlers.
- Verify: `make test tests/auth/test_oidc.py` passes.
2. Link the IdP subject to the user through `idp_links`.
- Verify: new unit test for first login and repeat login passes.
3. Return the same session cookie as password login.
- Verify: `make e2e-auth` passes against the stub IdP.
## Acceptance criteria
- [ ] All steps verified, with commands and results recorded in the progress log.
- [ ] `make lint` and `make test` pass.
- [ ] No change outside `src/auth/` and `tests/auth/` except the route registration.
## Risks
- The IdP clock skew may break token validation. Mitigation: allow 60 s leeway, add a test.
## Progress log
- 2026-10-21: Plan drafted.
## Decisions log
- 2026-10-21: Store the IdP subject, not the email, as the link key (emails change).
Why each part is there:
| Section | Purpose |
|---|---|
| Goal and non-goals | Stops scope creep; tells a fresh session when to stop |
| Context and links | Just-in-time pointers instead of pasted code |
| Steps with verification | Closes the feedback loop per step; Anthropic's key lever |
| Acceptance criteria | The definition of done a reviewer can check |
| Risks | Names what to watch so it is not discovered in review |
| Progress log | Lets the next session resume; the agent updates it as it works |
| Decisions log | Records why, so nobody reverses it by accident |
4. Size each plan
A plan is the right size when one session can execute it and a reviewer can read the PR in one sitting.
| Signal | Action |
|---|---|
| More than about 6 steps or more than one subsystem | Split into two plans |
| Steps need different areas of expertise or different test suites | Split along that line |
The context fills up or you need /compact mid-plan | The plan was too big; split it and start a fresh session |
| A single step is "implement everything" | Break it down until each step has one check |
5. Execute one plan per session
Start with a clean context for each plan (/clear or a new session). One plan per session keeps the window focused; see Context Engineering. Anthropic's long-running harness uses the same discipline: one feature per session, verify end to end, then update the progress file and commit (Anthropic).
6. Run independent plans in parallel
| Approach | Command or setting | Use when |
|---|---|---|
| Worktree sessions | claude --worktree plan-02 (or -w) creates .claude/worktrees/plan-02/ on a new branch worktree-plan-02 | Plans touch different files; you want separate PRs (worktrees docs) |
| Subagent in a worktree | isolation: worktree in the subagent's frontmatter | The main session coordinates and delegates plans |
| Subagent for research | "Use subagents to investigate X" | Reading and exploration, not edits (sub-agents docs) |
Practical notes from the worktrees docs: a worktree needs at least one commit in the repository, add .claude/worktrees/ to .gitignore, and list files such as .env in .worktreeinclude to copy them into new worktrees. By default new worktrees branch from the default branch (worktree.baseRef set to fresh); set it to head to branch from your current commit, which you will want when plan 02 builds on an unmerged plan 01 (worktrees docs).
Which plans must be sequential:
- A plan that uses code, schema, or an API introduced by another plan.
- Plans that edit the same files, or the same migration sequence.
- Cutover, cleanup, and removal plans; they come last.
- Anything that changes shared tooling (lockfiles, build config) before the plans that rely on it.
Which can run in parallel: plans that depend only on already-merged work and touch different directories, such as an API plan and a UI plan against an agreed contract. Record the contract in the epic README so both plans use it.
7. Prompts to copy
Draft the epic breakdown (run in plan mode):
We are planning the epic described in docs/plans/sso-migration/README.md
(goal and links are there). Explore the codebase first; do not edit source.
Propose a breakdown into execution plans:
- Each plan must be completable in one focused session and fit in one PR.
- For each plan give: title, goal, files and areas touched, dependencies on
other plans, and the verification commands.
- Mark which plans can run in parallel and which must be sequential, and why.
- List open questions for me before you write anything.
When I approve, write docs/plans/sso-migration/README.md (with the plan index
table) and one numbered file per plan using the template in
docs/plans/_template.md.
Execute plan 02 and keep the log current:
Read docs/plans/sso-migration/README.md and docs/plans/sso-migration/02-auth-endpoints.md.
Execute plan 02 only. Do not start work from other plans.
For each step:
1. Implement it.
2. Run the step's verification command and show the result.
3. Append a dated line to the plan's Progress log with what you did and the result.
Record any non-obvious choice in the Decisions log.
If a step cannot be verified, or the plan is wrong, stop and update the plan
with what you found before continuing. At the end, tick the acceptance criteria,
set the plan's status in README.md, and summarize the diff. Do not commit until
lint and tests pass.
Keep a docs/plans/_template.md in the repo with the template above, so the prompt can refer to it.
8. Point AGENTS.md at the plans
Add two lines to the AGENTS.md, the way the ExecPlans approach does: when to write a plan, and where plans live.
## Plans
- For changes touching more than three files, write a plan in `docs/plans/` first (template: `docs/plans/_template.md`).
- Epics live in `docs/plans/<epic>/`; read its README.md before starting any plan, and update the progress log as you work.
Best practices
- Review the plan before the code. A mistake in a plan costs minutes; the same mistake in implemented code costs a PR.
- One verification per step. If you cannot name the command that proves a step, the step is not specific enough.
- Make the agent update the file. The progress log is the handoff. Ask for it in the prompt every time.
- Keep plans short and link out. Point to ADRs and code paths rather than pasting them.
- Commit the plan with the work. Plans are docs-as-code, reviewed in the same PR as the change they describe; see memory and knowledge.
- Use a fresh-context reviewer. Before calling a plan done, ask a subagent with no prior context to review the diff against the plan's acceptance criteria (best practices).
- Record decisions as they happen. The epic README holds epic-wide decisions, each plan holds local ones.
- Match the harness. The file format is plain markdown, so the same plans work in Claude Code, OpenCode, and Codex. Add a rule in
AGENTS.mdfor when to write one.
Pitfalls to design around
- Split by deliverable, not by layer of effort. A plan called "refactor everything" will not fit a session. Name plans after something a reviewer can see in one PR.
- Plan once, then execute with a clean context. Do not carry a long planning conversation into implementation; the saved file is the handoff.
- Keep dependencies explicit. If plan 03 needs plan 01's schema, the index says so, and the worktree branches from a commit that contains it.
- Re-plan when reality changes. After two failed corrections on the same issue, clear the context and restart with a better prompt (best practices); update the plan with what you learned first.
- Verify with tools, not with the agent's opinion. Agents tend to grade their own work positively; a separate skeptical evaluator or a real test is more reliable (harness design).
- Skip the ceremony for small changes. One sentence of intent is a plan. Reserve files for work that needs them.
- Avoid parallel plans on overlapping files. Merge conflicts cost more than the time you saved; sequence them.
Try it
Lab (20 min)
- Choose a real ticket in a repo you work in that touches several files, or invent a two-day task.
- Start
claude --permission-mode planand use the breakdown prompt above. Aim for 2 to 4 plans. - Save the output as
docs/plans/<epic>/README.mdand01-...md,02-...mdusing the template. - Execute plan 01 in a fresh session with the "execute plan" prompt. Check that the progress log and index status are updated.
- If plan 02 is independent of 01, start it in a second terminal with
claude --worktree plan-02and compare timing. - Review the PRs: can a teammate tell what each one is for from the plan alone?
Checklist
- I used plan mode (or a read-only phase) to explore before editing.
- The plan is saved in the repo, not only in chat.
- Each plan has a goal, non-goals, steps with verification, acceptance criteria, risks, and both logs.
- The epic has a README with a plan index showing status and dependencies.
- Each plan fits one session and one PR.
- Each session starts clean and executes one plan.
- Parallel plans touch different files and use separate worktrees.
- Sequential plans are marked as such in the index.
- The agent updated the progress log and decisions log.
-
AGENTS.mdsays when to write a plan and where plans live.
Sources
- Claude Code best practices (explore, plan, implement, commit; verification; subagents;
/clear): https://code.claude.com/docs/en/best-practices - Claude Code permission modes (plan mode): https://code.claude.com/docs/en/permission-modes
- Claude Code common workflows (plan mode, worktrees): https://code.claude.com/docs/en/common-workflows
- Claude Code worktrees: https://code.claude.com/docs/en/worktrees
- Claude Code subagents: https://code.claude.com/docs/en/sub-agents
- Anthropic, Effective harnesses for long-running agents (2025-11-26): https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
- Anthropic, Effective context engineering for AI agents (2025-09-29): https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
- Anthropic, Harness design for long-running apps (2026-03-24): https://www.anthropic.com/engineering/harness-design-long-running-apps
- OpenAI, Using PLANS.md for multi-hour problem solving (ExecPlans): https://developers.openai.com/cookbook/articles/codex_exec_plans
- GitHub Spec Kit: https://github.com/github/spec-kit and https://github.com/github/spec-kit/blob/main/spec-driven.md
- Kiro specs: https://kiro.dev/docs/specs/