spec-kit-generate-plan

Generate Plan — Technical Planning Skill

Purpose

Turn an approved REASONS specification (spec.md) into one concrete, technically verified plan that spec-kit-generate-tasks can decompose into executable work — without writing product code. This skill sits between spec-kit-generate-spec and spec-kit-generate-tasks in the spec-kit chain: it does not reinterpret business intent, it translates already-approved intent into a design that fits the real project.

The output is plan.md plus its Phase 0/1 companions (research.md, data-model.md, contracts/, quickstart.md) and checklists/plan-quality.md. It does not implement product code, and it does not generate tasks.md — that is spec-kit-generate-tasks's job.

User Input

$ARGUMENTS

Always consider the complete user message and any files or attachments available in the current conversation, even when $ARGUMENTS appears literally or is empty. The most common input is a reference to an existing feature directory or spec.md, with optional constraints ("use PostgreSQL", "keep it in the existing monolith", "split into two phases").

Core Principle

Verify the real project before designing on top of it. Gate every design against the constitution before it's built, not after.

Treat the plan as the bridge between approved intent and executable work:

• Never propose a technical approach without checking whether the project already has one.
• Run the Constitution Check before investing in research, and again after the design is concrete — a design can introduce a violation the original intent didn't have.
• Every plan entry traces back to a requirement or acceptance criterion in spec.md.
• When spec.md changes after a plan exists, update the plan; never let the plan silently drift from the specification it claims to implement.

Non-Negotiable Rules

1. Do not invent facts. Never fabricate installed dependencies, versions, file paths, existing components, database schemas, or library signatures. Verify per verify-before-implement before writing them into the plan.
2. Preserve spec intent. Do not reinterpret, narrow, or expand a requirement from spec.md while translating it into a technical approach. If the spec is ambiguous at the technical level, that is a clarification to raise, not a decision to make silently.
3. Separate facts from assumptions. Every unverified technical choice is marked NEEDS CLARIFICATION in Technical Context or recorded as an explicit assumption — never written as settled fact.
4. Surface conflicts. If the spec's requirements conflict with the real project (an existing contract, an installed dependency's actual capabilities, a constitution principle), report the conflict; do not silently pick the path of least resistance.
5. Abstraction before operations. Complete Technical Context, both Constitution Check gates, Data Model, and Contracts before drafting plan.md's strategy and decisions section.
6. No code before approval. Do not implement, scaffold, or generate product code as part of this skill. Code samples inside plan.md (contract shapes, signatures) illustrate a decision; they are not committed source.
7. No hollow plan. Every section of plan.md must contain specific, verified content. Do not leave [NEEDS CLARIFICATION] markers, template placeholders, or unresolved Option N labels in a plan reported as complete.
8. Use verified project context. Inspect the actual codebase for existing patterns, contracts, and structure before naming concrete components — never assume a pattern exists because it's common elsewhere.
9. Keep scope controlled. Do not add operations, components, or dependencies beyond what spec.md requires. A plan that "future-proofs" beyond the approved spec is scope creep, not thoroughness.
10. Constitution Check gates are mandatory, not advisory. Both gates run and are reported as PASS/FAIL per principle — including N/A — sin constitución when no constitution exists. A FAIL only proceeds with a justified row in Complexity Tracking; skipping a gate silently is never acceptable, even under time pressure.
11. Safe Deferral is enforced, not suggested. An operation pushed to a future phase must satisfy Dormant, Flagged, or Additive (§ Safe Deferral below). If none applies, the operation is completed in the current phase or the phases are reordered — it is never marked deferrable "because it's documented as future work."
12. Every plan entry is traceable. Each plan.md decision, component, and operation cites the R-FR##/R-AC##/E-##/R-QR## it satisfies.
13. Never claim readiness without validation. A plan is READY only after checklists/plan-quality.md passes and no blocking NEEDS CLARIFICATION remains.
14. Generate portable agent pairs. If this workflow creates a plan-reviewer (or other support agent), it must generate and validate both a Kiro CLI and a Claude Code definition per the shared portability contract.