create-plan

name	create-plan
description	Create a scoped, code-backed implementation plan from a todo, spec, issue, review notes, or raw instructions. Use for multi-step work, cross-area changes, executor handoffs, or a reviewable plan before coding.

Create Plan

Write the minimum sufficient plan for a capable, context-limited executor with repository access but without prior context about the task at hand. Resolve implementation decisions; do not teach inspectable repository basics.

Principles

• Follow repository invariants and project intent, then explicit requirements and accepted decisions, then verified codebase facts.
• Choose the smallest coherent change that satisfies the acceptance criteria.
• For multi-unit work, prefer vertical slices: each unit completes one coherent, observable behavior across the boundaries it needs and can be verified when it lands. Prefer units that separate agents can own with limited overlap and that can be reviewed, landed, or rolled back independently. Keep shared setup to the minimum required by the first slice so later units can proceed in parallel where practical.
• Do not divide work mechanically by repository layer or component type. When an indivisible migration, cross-cutting safety fix, or minimum shared prerequisite must remain horizontal, state briefly why vertical delivery is impractical or unsafe.
• Prefer concise durable paths and symbols over copied source.
• Prefer the highest existing stable test seam that proves acceptance. Add a lower seam only for a distinct invariant or failure mode unobservable there.
• Ask the user before writing when a missing decision materially changes scope or architecture. Do not carry unresolved implementation choices into a plan.

Workflow

1. Ground the work

• Read the source request and repository guidance, including the project intent source when the work affects direction or boundaries.
• Inspect only the relevant code, callers, contracts, tests, and current docs.
• Verify repository commands and external contracts before prescribing them.

Done when: acceptance criteria, relevant invariants, current behavior, and the smallest credible solution are known.

2. Reconcile requirements with reality

• Separate current behavior from requested behavior.
• Resolve stale claims, conflicts, implemented baseline, and real gaps.
• Reject speculative hardening, future-proofing, and unrelated cleanup.
• Ask only questions whose answers change the implementation direction.

Done when: the plan has one coherent direction and no material open choice.

3. Discover executor aids

Inspect available skill descriptions and repository guidance. Read only skills that match a concrete change. Mention a verified skill beside that change only when it adds non-obvious execution guidance; do not add a skills table by default.

Done when: every named aid exists and changes how a step should be executed.

4. Write the plan

Use references/plan-template.md. Name exact files or symbols and the decisions that matter. Keep relevant facts and tests beside the change they justify. Add a section, excerpt, checklist, or command only when it changes an executor decision or proves a distinct criterion, invariant, or verified regression risk.

Done when: a capable executor can implement the outcome from the plan and repository without prior chat.

5. Prune

• Trace every change and test to acceptance, an invariant, or a verified risk.
• Remove repeated criteria, covered commands, duplicated context, and empty optional sections.
• Keep verification to focused behavioral checks and the canonical repository gate.

Done when: removing any remaining material would make execution less safe or leave a decision ambiguous.

Output

Write one plan under dev/plans/ and reconcile dev/plans/README.md according to repository guidance. State findings plainly; plan length follows decision and change-surface complexity, not a target.