--- 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/.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/.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 gitignored** — don't assume it. Ensure `.claude/plans/` is in the repo's `.gitignore` (add it if missing) before writing the plan. `repo-setup` seeds this alongside `.worktrees/`, but `plan-file` guarantees it too so the property holds even when invoked standalone. **Deleting the plan is `cleanup-artifacts`' job** (#35) at the draft→ready boundary, not this primitive's. Until `cleanup-artifacts` ships, the gitignore guarantee above is what keeps a plan from leaking into a PR. ## Plan structure ```markdown # : ## Story reference ## 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 gitignored (add it if missing), then write the plan to `.claude/plans/.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/.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/.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`. - **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.