Skip to content

Instantly share code, notes, and snippets.

@shawn-sandy

shawn-sandy/plan-mode.md

Created May 14, 2026 19:35
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save shawn-sandy/9a365988b885973431ee5c1931a7cb61 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save shawn-sandy/9a365988b885973431ee5c1931a7cb61 to your computer and use it in GitHub Desktop.
Download ZIP
Claude Code plan mode rule
Raw
plan-mode.md
description Plan mode rules — workflow, required structure, writing style, and scope discipline

Plan Mode Instructions

When to plan

  • When a skill/slash-command requires write operations (git, filesystem, migrations), do not enter plan mode. Execute directly.
  • Only produce a plan if the change spans multiple files or has unclear requirements; for simple fixes (missing dep, typo, small edit), apply the change directly.

Workflow

  1. Create — Place plans in docs/plans/ (or the configured plansDirectory) using a verb-target kebab-case filename. Examples: add-dark-mode-toggle, fix-login-redirect, refactor-auth-module.
  2. Frontmatter — Always add YAML frontmatter at the top of every new plan file: status: todo, type: <feature|fix|refactor|docs|chore>, created: YYYY-MM-DD.
  3. Rename — Always update the filename when the plan's purpose shifts; re-evaluate before committing. A stale filename is a plan defect — do not commit until the name matches the content.
  4. Commit — Always commit plan files to version control alongside the related changes.
  5. Status — Always update status (and modified: YYYY-MM-DD) in the frontmatter as the plan progresses: todo → in-progress → completed. Use /plan-status to automate this.

Required Structure

Every plan must include the following sections:

  • context — Background and motivation; why this work is needed.
  • objective — One or two sentences summarising the goal.
  • steps — A numbered list where each item has three parts: the action, a brief why, and a verify line stating how to confirm that step succeeded before moving on.
    • Per-step verification is local (did this step do what it should?); the top-level verification section covers end-to-end correctness.
  • verification — How to confirm the entire plan was executed correctly end-to-end.
  • next-steps (optional) — Out-of-scope follow-ups and unsolicited ideas, one line each; never place these in steps.
  • unresolved-questions (optional) — Open questions needing user input; omit entirely if none.

Writing Style

Direct, imperative, developer-friendly — real names (file paths, function names, CLI flags), lists over prose, one idea per item, explicitly scoped. Plan only what was requested; unsolicited ideas go in next-steps.

Skeleton

Copy docs/plans/SKELETON.md as a starter for every new plan.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment