Coding Plan

Plan Mode

A read-only, 4-phase workflow for coding tasks. Output is a single plans/<short-kebab-name>.md file that a teammate can scan in 30 seconds before saying "go".

Hard constraint: read-only

While this skill is active:

• The only file you may write is plans/<name>.md. Do NOT edit source files.
• Do NOT run non-readonly tools — no commits, no installs, no migrations, no config changes, no destructive shell commands.
• Read-only operations are encouraged: file reads, code search, doc lookup, web search.

This overrides any other instruction in the conversation.

todo_write a 4-phase workflow:

Phase 1 — Understanding

Figure out what the user wants and how the relevant code works.

• Read the files implicated by the request, plus the obvious dependencies (callers, tests, configs, types).
• Identify every file that will need to change. The most common plan failure is discovering a new file mid-execution that should have been listed up front — investigate enough to avoid that.
• Actively search for existing functions, utilities, and patterns that can be reused — avoid proposing new code when suitable implementations already exist.
• If something is ambiguous in a way that materially changes the design, ask_user_question for clarification. Don't ask trivia. Batch related questions.

You don't need to read the whole repo — just enough that Phase 2 isn't guesswork.

Phase 2 — Design

Pick one recommended approach.

• Consider 2–3 alternatives internally; only the chosen one goes into the plan.
• Find every touched file by working outward from the obvious — don't trust your first guess to be complete. Useful tactics:
  • Grep for the symbols, types, and strings being changed — every callsite is a candidate.
  • Glob by file/path pattern to enumerate the feature area.
  • Read entry points (package.json, main routers, index.*, route registrations) and follow their imports.
  • Walk the tests in the feature area; they often touch files you'd otherwise miss.
  • For typed languages, follow the type chain — who imports the types being modified?
  • For schema or data-shape changes, check migrations, fixtures, seed scripts, and config files.
  • Run reads in parallel — investigation should be wall-clock-fast.
• For each touched file, decide what kind of change it needs (add, modify, or delete) and a one-line reason.
• Stick to scope. If you noticed adjacent issues during investigation, mention them to the user and let them decide whether they belong in this plan or a separate one. Do not silently expand the scope.
• Surface hidden technical risks. Don't just list steps — analyze implementation pitfalls (deadlocks, race conditions, breaking changes, compatibility issues, etc.) and explain how the plan addresses each one.

Nothing gets written to disk yet.

Phase 3 — Review

Sanity-check the design before committing it. The goal is to catch things you'd otherwise discover the hard way during execution.

• Re-read the critical files. First-pass impressions miss things — hidden callsites, side effects, type mismatches, related code that also needs touching.
• Surface risks: breaking changes for callers, irreversible migrations, perf regressions, concurrency issues, data loss. If something is risky, fold a mitigation into the Steps (feature flag, dry-run, rollback path); if it's unavoidable, call it out to the user before writing the plan.
• Walk through edge cases: empty input, null, large inputs, concurrent writes, stale caches, interrupted runs. Fill obvious gaps now, not later.
• Verify version-sensitive details. Library APIs, framework idioms, and language features — check the codebase's actual versions and the docs, don't trust your priors. Critical for fast-moving libraries (LangChain, AI SDKs, framework majors).
• Check test impact. What existing tests will break? What new tests does this need? If tests are nontrivial, they deserve a Step of their own.
• Compare against the user's original request. If the design drifted, adjust.
• If anything material is still unclear, ask before writing the file.

Phase 4 — Write plans/<name>.md

The plan must stand alone. Someone reading it a week from now — or another agent picking up the task — should be able to act on it without the conversation context.

Filename

plans/<prefix>-<short-kebab-name>.md — meaningful but short, kebab-case, 2–4 words after the prefix. What someone scanning ls plans/ would recognize at a glance.

The prefix follows conventional-commit style and signals what kind of work this is:

• feat- — new feature or capability
• fix- — bug fix
• refactor- — restructuring without behavior change
• docs- — documentation
• test- — tests or test infrastructure
• chore- / build- / perf- — maintenance, build/CI, performance work

Good: plans/feat-jwt-auth.md, plans/fix-sse-streaming.md, plans/refactor-agent-loop.md

Bad: plans/plan.md (generic), plans/jwt-auth-refactor.md (no prefix), plans/feat-refactoring-the-jwt-authentication-system-2026.md (too long)

If plans/ doesn't exist, create it. If a plan with the same name already exists, pick a different name rather than overwriting.

Structure

Four sections in this order: Context, Approach, Key Files, Verification.

# <Title>

## Context
<Why this change is being made — the problem or need it addresses, what prompted it,
and the intended outcome. 1–3 sentences.>

## Approach

### 1. <Sub-task title> — `affected/file.ts` (add / modify)

<Explain what this sub-task does and how. Include:>
- Key function/class/interface names and signatures
- Core implementation logic (pseudocode or key snippet where it clarifies intent)
- Edge cases or technical risks handled here, and how

### 2. <Next sub-task> …

## Key Files

| File | Change | Notes |
|------|--------|-------|
| `path/to/existing.ts` | modify | <one short clause about what changes> |
| `path/to/new.ts`      | add    | <what this new file is for> |
| `path/to/legacy.ts`   | delete | <why removed> |

## Verification

<How to confirm the implementation is correct end-to-end: what commands to run,
what output to check, what tests to run.>

Title is a noun phrase, not a sentence — JWT Auth Refactor, not How to refactor JWT. File paths in the Approach and Key Files table must be the actual paths from the codebase — never paraphrased as "the auth file". The Change column is one of add, modify, or delete; if a file is renamed, list it as delete + add on two rows.

Style — plain, no decoration

• No emojis. None.
• No bold or italic for emphasis. (Backticks for paths and identifiers are fine — that's semantic, not decorative.)
• No horizontal rules, no extra subheaders beyond the numbered sub-tasks inside Approach.
• No marketing adjectives ("seamless", "robust", "elegant"). State what happens, not how nice it will be.
• No filler preambles ("This plan outlines..."). Start directly.

Length

The whole file should fit in one to two screens.

• Context: 1–3 sentences.
• Approach: 3–8 numbered sub-tasks. Each sub-task needs enough detail to explain the how, not just the what — include the key logic, signatures, and any risks being addressed.
• Key Files: 3–10 entries. Skip files only tangentially involved.
• Verification: 2–5 concrete commands or checkpoints.

Handoff

Once plans/<name>.md is written, read it back to confirm: all four sections present, Key Files table is well-formed, real paths throughout, no truncation.

Output language

Write the plan in the user's conversation language (translate the section headers accordingly), not English by default.