plan-file

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

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