# Coding Plan > Enter "plan mode" for a coding task — read the relevant code, optionally ask clarifying questions, design one recommended approach, then write a plain, scannable plans/-.md file. No source files are edited in this mode. Use this skill whenever the user says "plan mode", "/coding-plan", "make a plan", "draft a plan first", "give me a plan before you code", "let's plan this out", "write a plan.md", "think before you code on this one", or otherwise asks for a written implementation plan to be produced before any changes happen. Also trigger when the user wants the agent to investigate a codebase and propose an approach without touching files. Even casual phrasing like "don't rush, think it through first" should trigger this skill. - Skill: `magiccube/coding-plan` (Agent Skill) - Install (CLI): `npx skillmds@latest add magiccube/coding-plan` - Raw SKILL.md: https://api.skillmd.com/api/skills/magiccube/coding-plan/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: magiccube (https://skillmd.com/u/magiccube) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/magiccube/coding-plan --- # Plan Mode A read-only, 4-phase workflow for coding tasks. Output is a single `plans/.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/.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/.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/-.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**. ``` # ## 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.