Plan File

---
name: plan-file
description: Use BEFORE writing implementation code in /implement, after repo-setup and once a ticket exists. Produces an approval-blocked plan at .claude/plans/<branch>.md (story ref, change summary, affected files, approach, test cases, open questions) and blocks coding until it exists and the user has approved it. Skip only for trivial changes, with an auditable one-line reason.
---

# Plan File

The plan gate in `/implement`'s repo path: runs after `repo-setup`, before any implementation code. Produces a written, **approval-blocked** plan for the branch — coding doesn't start until the plan file exists and the user has approved it. Ported from the work `implementation-plan` skill, genericized.

## When to invoke

Before writing any implementation code, once both are true:
1. A branch + worktree are set up (via `repo-setup`).
2. A story/ticket is the agreed scope for the session.

If implementation is requested and no plan file exists for the current branch, run this first.

## When to skip

Skip only for:
- Single-line fixes, typos, renames, trivial string edits.
- Emergency hotfixes where speed outweighs discipline.
- Spikes or throwaway experiments explicitly flagged as such.

If skipping, **state the reason in one sentence** before proceeding, so the skip is auditable in the session log (and note it in the eventual commit message).

## Plan file location

`.claude/plans/<branch>.md` in the worktree root. **Flatten `/` in the branch name to `-`** so the plan is a single file, not a nested path: `feat/new-thing` → `.claude/plans/feat-new-thing.md`. This `/`→`-` rule is canonical here; `repo-setup`'s plan-file prune and `cleanup-artifacts`' deletion must use the same flattening.

The plan is working scaffolding, not shipped documentation, so `.claude/plans/` **must be ignored by git** — don't assume it. Before writing the plan, from the worktree root, check `git check-ignore -q .claude/plans/<flattened-branch>.md` (exit 0 = ignored, 1 = not ignored; anything else is an error — stop and surface it). If it isn't ignored, add `.claude/plans/` to the repo-local exclude file rather than editing the tracked `.gitignore`, using `repo-setup` step 0's two-command snippet (canonical) with `.claude/plans/` as the only pattern, then re-run the check — if it still isn't ignored, a tracked `.gitignore` rule (e.g. `!.claude/plans/`) is overriding the exclude; stop and surface it. The exclude file is shared by every worktree and never shows up in a diff. A worktree-isolated session refuses writes into the main checkout's `.git`, so if the append is refused, stop and give the user the exact command to run themselves (e.g. via `! <command>`) — don't fall back to editing `.gitignore`.

`repo-setup` seeds the same entry before entering the worktree, so in `/implement` the check normally passes; `plan-file` guarantees it too so the property holds even when invoked standalone. A `.gitignore` entry the project already tracks satisfies the check just as well. A project that tracks plan files overrides this (see Project overrides) — otherwise new plans are silently ignored.

**Deleting the plan is `cleanup-artifacts`' job** (#35) at the draft→ready boundary, not this primitive's; the ignore guarantee above is what keeps a plan from leaking into a PR before then.

## Plan structure

```markdown
# <story-id>: <short-title>

## Story reference
<link to the ticket, plus 2–3 sentences of context — enough that the plan stands alone without opening the ticket>

## Change summary
1–2 sentences: what is changing and why.

## Affected files
- `path/to/file.ext` — new | modified | deleted — one-line note on the change
- `path/to/test.ext` — new | modified — test-side change

## Approach
Bullet list keyed to the files above. Describe the shape of each change, not full pseudocode. Example:

- `src/foo/usage.ts` — add a `usage` accessor that reads from the cache with a short TTL; expose it so the caller can use it directly instead of hitting the cache.
- `src/foo/caller.ts` — replace the direct cache call with the new accessor.

## Test cases
- Happy path: ...
- Edge: ...
- Regression to guard: ...
- Known gotchas from past incidents in this area: ...

## Open questions
Anything the story did not fully answer. Resolve with the user before coding, or mark as explicit assumptions to validate during review.
```

## Process

1. Read the story/ticket to ground the plan in the stated scope.
2. If a plan file already exists for this branch, read it and offer to revise rather than overwrite.
3. Scan the affected files briefly to ground the approach in real code (do not start modifying them).
4. Draft the plan using the structure above.
5. Ensure `.claude/plans/` is ignored (`git check-ignore`; add it to `info/exclude` if not), then write the plan to `.claude/plans/<branch>.md` (flattened name).
6. Hand the plan off for approval per **Approval handoff** below, and wait for explicit approval.
7. Iterate on feedback — update the plan file in place, then re-surface only what changed and what is still open (see **Approval handoff**).
8. Only after approval does the recipe proceed to implementation — referencing the plan file on subsequent turns as the source of truth.

Approval signals: "looks good", "proceed", "yes", "go ahead", or a direct instruction like "start implementing X."

## Approval handoff

The plan file is the durable artifact, but it lives in a worktree the user is usually not standing in. **Naming the file is not showing the plan.** Surface the following in the conversation itself — the summary never replaces writing the file:

1. **The absolute path**, resolved from the worktree root — never repo-relative, never `~`-relative. The user is typically in the main checkout or another directory entirely, so a relative path gives them nothing to open.
2. **A summary that stands alone.** Approving without opening the file is the normal path, not a shortcut. Include the change summary, the affected-files list with its one-line notes, the approach as a few bullets, and one line on test coverage.
3. **Every open question, in full** — numbered, each carrying your recommended default, so "go with your defaults" is a complete reply. Never compress them into a count or a pointer to the file. If there are none, **say so explicitly**; silence reads as "unread," not "none."

Ask for approval in **plain conversational text**. Don't route it through a structured-choice prompt (e.g. `AskUserQuestion`) — approval usually arrives mixed with open-question answers and plan edits, and a fixed option list can't carry that.

On revision, re-surface what changed and what remains open — not the whole plan again.

## Enforcement

Write no implementation code — no file creation, no edits to source or test files beyond the plan file itself — until:
1. The plan file exists at `.claude/plans/<branch>.md`, and
2. The user has approved it.

If the user explicitly says "skip the plan" / "just do it", comply, but record the skip reason in the resulting commit message so the decision is traceable.

## Context recovery

If the conversation context is cleared mid-implementation, the **first action** in the new session is to read the plan file to re-ground. When dispatching a subagent to execute part of the plan, **always pass the plan file path in the subagent's initial prompt** so it reads the plan before acting.

## Living-document caveat

On a greenfield story, the affected-files list and approach often can't be fully specified until implementation begins — that's expected. The plan is a living document for the branch: when the file list or approach changes during implementation, update the plan file before continuing. Its value comes from being current, not from being complete on first draft.

## Output / contract

- **In:** a story/ticket reference + the branch (from `repo-setup`).
- **Out:** an approved plan at `.claude/plans/<flattened-branch>.md`; the path is passed forward to execution and to any dispatched subagent.
- **Surfaced to the user:** the plan file's **absolute** path, a stand-alone summary, and every open question in full — see **Approval handoff**.
- **Side effects:** writes the plan file; **gates** implementation until the plan exists and is approved.

## Project overrides

- **Plan-artifact location** — a repo that tracks plans elsewhere (e.g. `docs/plans/`) overrides the location; keep the flatten rule consistent with `repo-setup` and `cleanup-artifacts`.
- **Tracked plans under `.claude/plans/`** — skip the exclude fallback here and `repo-setup` step 0's `.claude/plans/` entry, so new plans aren't silently ignored.
- **Size-skip threshold** — a repo may tune what counts as "trivial."

## Future scope

- Size-skip auto-detection (heuristic on diff size / file count) rather than agent judgment.