Plan it

plan-it

Convert a brief in <repo>/.claude/brief/ into a plan in <repo>/.claude/plan/. The plan must be specific enough that a fresh Sonnet 4.6 (medium effort) session can implement it without making design decisions — exact files, exact signatures, exact verification.

Output file

The plan template's Target: line states where the file is written. Set it to:

.claude/plan/<exact-brief-filename>

Filename matches the brief character-for-character — no renaming, summarizing, or suffixes. Path is repo-relative (the project's .claude/, not ~/.claude/).

When writing, write to the path stated in Target: — do not derive a new path.

Plan mode is the host

This skill runs inside plan mode. Plan mode owns presentation and approval — it shows the plan in a side panel, the user reviews and approves there, and the file write happens on approval.

Chat is reserved for: drilling questions, brief status lines, and a 2-line post-write summary. Never paste the plan content into chat.

Process

1. Read the brief and explore. Read in full, then explore the repo until you know exactly which files change and how.

2. Drill if needed. Drilling is Claude-initiated, never user-prompted. Trigger when the brief has gaps that change the implementation shape, multiple architectures are reasonable, or a wrong assumption now would cost a meaningful rewrite. Otherwise say "Brief is clear, drafting the plan" in chat and skip to step 3.

When drilling: ask one question at a time, propose your recommended answer with brief reasoning, only ask what the codebase can't answer, stop when further questions wouldn't change the plan.

3. Produce the plan using the structure below. Plan mode displays it in the side panel.

4. On approval, write to the path in Target: and post a 2-line summary in chat (path written, step count).

Plan structure

# <title>

> Source: .claude/brief/<filename>

> Target: .claude/plan/<filename>

## Context
2-3 sentences. What's the problem and why does it matter.

## Outcome
One sentence. What "done" looks like in observable terms.

## Files to touch
- `path/to/existing-file.ts` — <what changes>
- `path/to/new-file.ts` — <new, purpose>

## Steps
1. **<action verb + target>**
   - Change: <specific change — function signatures, types, values, exact location>
   - Why: <one line, only if non-obvious>
   - Verify: <command, file to inspect, or observable result>
2. ...

## Watch out for
Real traps only — codebase conventions, edge cases, library quirks the implementer might miss. Omit if none.

## Done when
- [ ] <observable behavior>
- [ ] <command produces expected output>

Source: and Target: use the same filename. If they differ, the plan is wrong.

Rules

• Specify, don't suggest. "Add validateToken(token: string): Result<Claims, AuthError> to src/auth/validate.ts" — not "add a function".
• Never invent paths or APIs. Anything referenced must exist in the repo or be explicitly created in a step.
• Verification is observational. Run code, inspect output, check behavior. Do not instruct the implementer to write tests.
• One file per brief. If the brief covers multiple unrelated changes, ask whether to split before planning.