plan

name	plan
description	Create implementation plan before coding. Plan file must exist with required sections before completion.

/plan

Create a detailed, actionable implementation plan. No vague language. No optional sections.

No arguments? Describe this skill and stop. Do not execute.

First: Activate Workflow

mkdir -p .claude && echo '{"skill":"plan","started":"'$(date -Iseconds)'"}' > .claude/active-workflow.json

Craft Standards (MANDATORY)

Plan for code a master craftsperson would be proud of.

The plan should produce code that looks like it was written by a skilled human engineer, not generated by AI.

Plan AGAINST These AI Antipatterns

• Over-abstraction (don't plan factories/builders unless truly needed)
• Speculative features (plan only what's requested)
• Enterprise patterns in simple code (no AbstractFactoryBeans)
• Unnecessary layers (don't plan wrappers that add no value)
• Config options nobody asked for

Plan FOR Human Craft

• Minimal, focused interfaces
• Single-responsibility functions
• Names that reveal intent
• Direct solutions to actual problems
• Simplicity over "flexibility"

If your plan includes something a senior engineer would delete, remove it from the plan.

Plan FOR Product Quality and Production Readiness (MANDATORY)

Load the rubric files (see Step 0d below) and apply them:

• Product quality criteria → walk through each as a user would before finalizing the plan
• Base criteria → ensure every applicable item is addressed in the plan
• Domain criteria → include domain-specific concerns that match the target

Every plan must explicitly address the loaded rubric concerns. For each item, the plan must either include a WORK_ITEM that implements it or state why it's not applicable (with justification). "Not applicable" is only valid for items that genuinely don't apply to the target (e.g., CSRF doesn't apply to a CLI tool).

If the plan omits any applicable item without justification, it fails validation.

Document decisions in the plan under ## PRODUCTION_CHECKLIST: using the Planning Checklist templates from each loaded rubric file. Combine all loaded templates into one section.

Library Audit (MANDATORY)

Before designing any component, check: does a well-known library already solve this?

• CLI argument parsing → use commander, yargs, or cac — never hand-roll a parser
• File locking → use proper-lockfile or lockfile — never hand-roll with mkdir/spin
• Password prompts → use prompts or inquirer — never hand-roll with readline
• Validation → use zod, joi, or framework validators — never hand-roll schema validation for complex inputs
• Date handling → use date-fns or dayjs if needed — never hand-roll date math

The rule: If a mature, maintained library exists for the subproblem, plan to use it. Hand-rolling is only justified when the library would be heavier than the entire project, or when you need <20 lines of logic that doesn't warrant a dependency.

Document library choices in the plan under a DEPENDENCIES: section:

## DEPENDENCIES:
- commander: CLI argument parsing (replaces hand-rolled parser)
- prompts: interactive password input

---

⚠️ STRICT REQUIREMENTS - NO JUDGMENT CALLS

You MUST produce a plan with ALL sections below. No "TBD". No "as needed". No "if applicable".

Every item must be SPECIFIC and ACTIONABLE.

Process

Step 0: Load Expert Guidance

Before starting, read these canon skills and apply their principles throughout:

Always load (base brain — all 10):

1. canon/clarity/SUMMARY.md
2. canon/pragmatism/SUMMARY.md
3. canon/simplicity/SUMMARY.md
4. canon/composition/SUMMARY.md
5. canon/distributed/SUMMARY.md
6. canon/data-first/SUMMARY.md
7. canon/correctness/SUMMARY.md
8. canon/algorithms/SUMMARY.md
9. canon/abstraction/SUMMARY.md
10. canon/optimization/SUMMARY.md

Auto-detect domain canon (check files, load matches):

Check	If found, also read
*.ts or *.js files in target	canon/javascript/typescript/SUMMARY.md, canon/javascript/js-safety/SUMMARY.md, canon/javascript/js-perf/SUMMARY.md, canon/javascript/js-internals/SUMMARY.md, canon/javascript/functional/SUMMARY.md
angular.json in project root	canon/angular/angular-arch/SUMMARY.md, canon/angular/angular-core/SUMMARY.md, canon/angular/angular-perf/SUMMARY.md, canon/angular/rxjs/SUMMARY.md
package.json contains "react"	canon/javascript/react-state/SUMMARY.md, canon/javascript/react-test/SUMMARY.md, canon/javascript/reactivity/SUMMARY.md
pom.xml or build.gradle in project	canon/java/SUMMARY.md
*.py files in target	canon/python/python-advanced/SUMMARY.md, canon/python/python-idioms/SUMMARY.md, canon/python/python-patterns/SUMMARY.md, canon/python/python-protocols/SUMMARY.md
*.cs files or *.csproj in project	canon/csharp/csharp-depth/SUMMARY.md, canon/csharp/type-systems/SUMMARY.md, canon/csharp/async/SUMMARY.md
.tsx, .jsx, or HTML template files	canon/ui-ux/components/SUMMARY.md, canon/ui-ux/usability/SUMMARY.md, canon/ui-ux/tokens/SUMMARY.md
d3 in package.json or imports	canon/visualization/d3/SUMMARY.md, canon/visualization/charts/SUMMARY.md, canon/visualization/dashboards/SUMMARY.md
SQL files or ORM imports	canon/database/sql/SUMMARY.md, canon/database/sql-perf/SUMMARY.md
Auth, tokens, secrets, encryption	canon/security/security-mindset/SUMMARY.md, canon/security/owasp/SUMMARY.md, canon/security/web-security/SUMMARY.md

If a skill file doesn't exist (not installed in this project), skip it and continue. List loaded experts in EXPERTS_LOADED. In EXPERT_DECISIONS, show each specific planning decision an expert drove.

Step 0b: Learn From Past Mistakes

Read both lessons files if they exist:

1. .claude/universal-lessons.md — universal patterns (ships with skills, applies to all projects)
2. .claude/lessons.md — project-specific patterns (accumulated from this project's runs)

These contain patterns that later quality phases (gemini-review, qodana-review, security-review) have repeatedly caught. Your plan should proactively address these known patterns so they don't recur:

• LOGIC entries → plan to avoid these bug patterns (e.g., TOCTOU, path traversal, shell injection)
• DESIGN entries → plan architecture that avoids these structural mistakes
• CODE_QUALITY entries → plan naming/structure that won't trigger these findings
• DUPLICATION entries → check for these duplicate patterns in your plan
• AI_SMELL entries → plan at the right abstraction level: no single-use wrappers, no speculative config/types, no over-decomposition

If a file doesn't exist, skip it and continue.

Step 0c: Surface Eval Proposals

Read .claude/eval-proposals.md if it exists. This file contains proposals from phase 8 (evaluation) — findings that suggest changes to skills, pipeline, profiles, or config. Each proposal has a status (PENDING, APPLIED, REJECTED).

For each PENDING proposal:

1. Check if it's relevant to the current target (mentions files, patterns, or categories that overlap)
2. If relevant, incorporate it into your plan:
   • SKILL_CHANGE → note the suggested skill improvement in your plan rationale
   • PIPELINE_CHANGE → flag for the user (pipeline changes are outside plan scope)
   • CONFIG_CHANGE → include the config change as a WORK_ITEM if it affects the target
   • DEPENDENCY_CHANGE → include in DEPENDENCIES section if applicable
   • RUBRIC_CHANGE → note for the user (rubric changes are outside plan scope)

List surfaced proposals in the plan under:

## EVAL_PROPOSALS_SURFACED:
- [proposal title]: [how it was incorporated or "flagged for user — outside plan scope"]

If no proposals file exists or no PENDING proposals are relevant, write:

## EVAL_PROPOSALS_SURFACED: none

Step 0d: Load Rubric

Read .claude/rubric/AUTO-DETECT.md for the detection table. Then:

1. Always load: .claude/rubric/base.md and .claude/rubric/product-quality.md
2. Auto-detect domains: Check target files against the detection table in AUTO-DETECT.md. Load matching domain rubrics (.claude/rubric/web-api.md, .claude/rubric/data-persistence.md, .claude/rubric/cli.md, .claude/rubric/microservice.md).
3. Extract Planning Checklists: From each loaded rubric, collect the ## Planning Checklist table and template. Combine into a single PRODUCTION_CHECKLIST for the plan output.

If a rubric file doesn't exist, skip it and continue. List loaded rubrics in:

## RUBRICS_LOADED: [base, product-quality, cli, data-persistence, ...]

Step 0e: Load Quality Contracts

Read .claude/rubric/contracts.md. Use the 7 abstract types when writing WORK_ITEM constraints and CONSTRUCTION_CHECKS. If Phase 2 (structure) produced a QUALITY_CONTRACTS table, incorporate its Construction Check entries into CONSTRUCTION_CHECKS.

Step 1: Explore

1. Explore - Use Glob, Grep, Read to understand existing code
2. Design - Create plan with ALL required sections
3. Save - Write to .claude/plans/[slug].md
4. Stop - Exit and wait for approval

⚠️ NO INTERVIEW QUESTIONS

• Do NOT ask clarifying questions before planning
• Make reasonable assumptions
• State assumptions in the plan and proceed

MANDATORY Plan File Format

# Plan: [Feature/Task Name]

## FILES:
- path/to/file.ts: purpose of this file
- path/to/another.ts: purpose of this file

## FUNCTIONS:
- functionName(params): ReturnType (max N lines) - purpose
- anotherFunction(params): ReturnType (max N lines) - purpose

## TYPES:
- TypeName: { field: Type, field2: Type }
- AnotherType: { field: Type }

## DEPENDENCIES:
- library-name: what subproblem it solves (why not hand-roll)

## INVARIANTS:
- Specific condition that must always be true
- Another specific invariant

## SECURITY:
- Specific security measure to implement
- Another specific security consideration

## QUALITY_CONTRACTS:
{from Phase 2, or identify boundaries here if Phase 2 was skipped}
| Boundary | Abstract Type | Contract | Construction Check |
|----------|--------------|----------|--------------------|

## UX:
- Default config path: [exact path, e.g., ~/.toolname/config.json]
- Required inputs: [input] → [flag] / [ENV_VAR] / [interactive prompt]
- Error messages: [scenario] → [user-facing message]

## TESTS:
- Specific test case: [what it verifies]
- Another test case: [what it verifies]

## PRODUCTION_CHECKLIST:
{Combine Planning Checklist templates from all loaded rubric files — base.md + product-quality.md + any domain matches}

## CONSTRUCTION_CHECKS:
- FILE: path/to/new-file.ts
- EXPORT_FUNCTION: functionName IN path/to/file.ts
- EXPORT_TYPE: TypeName IN path/to/file.ts

## WORK_ITEMS:
- [ ] WI-1: [verb] [specific thing] in [file(s)] [S/M/L]
  Constraint: [one canon principle + BAD/GOOD]
- [ ] WI-2: [verb] [specific thing] in [file(s)] [S/M/L]
  Constraint: [one canon principle + BAD/GOOD]
- [ ] WI-3: [verb] [specific thing] in [file(s)] [S/M/L]
  Constraint: [one canon principle + BAD/GOOD]

## EXPERTS_LOADED: [list of skill names actually read]
## EXPERT_DECISIONS:
- [expert-skill]: [specific planning decision it drove]

PLAN_COMPLETE

WORK_ITEMS Rules

Each work item includes a Constraint: — the ONE canon principle most likely to be violated in this unit. Name the source (Bloch, OWASP, GoF, Fowler, etc.) when applicable. Include a BAD/GOOD one-liner showing wrong vs right for this specific unit.

Example:

- [ ] WI-3: Create profile write function in src/profiles/create.ts [M]
  Constraint: [ValidatedInput + CausedError] Validate inputs at boundary (Bloch Item 49). File I/O in try-catch with cause.
  BAD:  function create(name: string) { writeFileSync(path.join(dir, name), ...) }
  GOOD: function create(validated: ValidatedName) { try { ... } catch(e) { throw new Error(..., {cause: e}) } }

The [AbstractType + ...] tag tells Phase 3 which contract idiom to implement. Tag every constraint with the matching abstract types from .claude/rubric/contracts.md.

WORK_ITEMS is the implementation checklist. Phases 3 and 4 iterate through it. Every item must be:

1. Discrete — one item = one independently verifiable change
2. Specific — names exact files and what changes
3. Verifiable — you can check if it's done by reading the file
4. Sized — S (< 20 lines changed), M (20-100), L (100+)

Group related changes into one item. "Add destroy() to all 24 modules" is one L item, not 24 S items.

Every planned change must appear as a WORK_ITEM. If it's in FILES/FUNCTIONS but not in WORK_ITEMS, it won't get implemented.

DO NOT:

• Be vague ("consider adding tests")
• Leave sections empty
• Say "as needed" or "if applicable"
• Use "TBD" or "to be determined"
• Make suggestions instead of decisions
• Proceed without all sections complete
• Put work in FILES/FUNCTIONS that isn't tracked in WORK_ITEMS

Validation (Phase will FAIL if violated)

• Missing any of: FILES, FUNCTIONS, TYPES, DEPENDENCIES, INVARIANTS, SECURITY, QUALITY_CONTRACTS, UX, TESTS, CONSTRUCTION_CHECKS, WORK_ITEMS, PRODUCTION_CHECKLIST
• QUALITY_CONTRACTS is empty and the feature has external boundaries (user input, file I/O, network, env vars)
• WORK_ITEMS is empty or has zero items
• WORK_ITEMS contains items without size tags (S/M/L)
• Contains "as needed", "if applicable", "TBD", "to be determined"
• Contains "consider" without specific action

🛑 MANDATORY STOP

After outputting the plan:

• DO NOT proceed to /structure
• DO NOT start writing any code
• DO NOT continue with "let me also..."

Your turn ends here. Output the plan and STOP.