Generate or update a technical implementation plan (plan.md) from an approved REASONS specification, enforcing verified project context, two-gate Constitution Check, convention enforcement, and the Safe Deferral rule for phased work; when a plan-reviewer agent is requested, generate compatible definitions for both Kiro CLI and Claude Code.
Generate or update a technical implementation plan (plan.md) from an approved REASONS specification, enforcing verified project context, two-gate Constitution Check, convention enforcement, and the Safe Deferral rule for phased work; when a plan-reviewer agent is requested, generate compatible definitions for both Kiro CLI and Claude Code.
license
MIT
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
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.
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.
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.
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.
Abstraction before operations. Complete Technical Context, both Constitution Check gates,
Data Model, and Contracts before drafting plan.md's strategy and decisions section.
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.
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.
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.
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.
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.
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."
Every plan entry is traceable. Each plan.md decision, component, and operation cites the
R-FR##/R-AC##/E-##/R-QR## it satisfies.
Never claim readiness without validation. A plan is READY only after
checklists/plan-quality.md passes and no blocking NEEDS CLARIFICATION remains.
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.
Cross-Platform Agent Compatibility
The complete portability contract lives in the shared, canonical document
spec-kit-shared/agent-portability.md (same document spec-kit-generate-spec uses). Before generating,
validating, or reporting on the plan-reviewer role — or any other agent this skill materializes
— read that file completely and follow it exactly. Do not paraphrase it from memory. If the active
host cannot resolve that file reference, follow its "Fallback for hosts that cannot follow a file
reference" section.
plan-reviewer is the standard role for this skill: validating architectural trade-offs before a
plan is approved. Do not invent a different name for this role or redefine it for another purpose.
Artifact Conventions
The .speckit/ layout (including .speckit/specs/<feature-dir>/), feature.json, state.json, and the Content
Fingerprint Convention used for staleness detection all live in the shared, canonical document
spec-kit-shared/artifact-conventions.md. Read it before Phase 0 below and follow it exactly —
this skill does not redefine its own file layout or hashing scheme.
Input Contract
Resolving the Target Specification
If the user gave an explicit spec.md path or feature directory, use it.
Otherwise, read .speckit/feature.json for the active feature directory.
If neither resolves to a readable spec.md, stop and ask:
Provide the feature directory or spec.md path to plan against. If you haven't generated a
specification yet, run spec-kit-generate-spec first.
Read spec.md completely, along with checklists/requirements.md for its STATUS.
Readiness Gate
If STATUS is READY, proceed.
If STATUS is DRAFT — NEEDS CLARIFICATION, stop and ask the user to either resolve the
blocking clarifications in spec-kit-generate-spec first, or explicitly confirm planning against a
draft. If the user confirms, proceed but record PLANNED_AGAINST_DRAFT: true in plan.md's
header and repeat the warning in the Completion Report — never silently treat a draft as ready.
New vs. Update Mode
New mode: no plan.md exists yet in the feature directory. Proceed through all phases below
in order.
Update mode: plan.md already exists. Read it completely, along with its
checklists/plan-quality.md and state.json. Run the Fase 0 Staleness Check below before doing
anything else — an update is a delta against what changed in spec.md, not a reason to
regenerate unrelated sections. Follow § Updating an Existing Plan.
Fase 0 — Staleness Check (every invocation, new or update)
spec-kit-generate-spec initializes state.json's artifacts.spec/source_documents entries itself
(see its own "Initialize or Refresh state.json" step), so it should already exist. If it
genuinely does not — an older spec.md predating that step, or it was manually removed — skip
straight to Phase 1 and create it (with a fresh artifacts.spec entry too) at the end of
Phase 5, alongside this skill's own artifacts.plan entry.
Otherwise, read spec-kit-sync-artifacts/SKILL.md and follow its Phase 1/2 mechanical
detection procedure against artifacts.plan.based_on_spec_hash vs. spec.md's current content
hash — do not re-derive the hashing/comparison mechanism independently; that definition lives
there so it stays identical across every skill that needs it.
If spec-kit-sync-artifacts reports a match, spec.md has not changed since the last plan — proceed
normally.
If it reports drift, this skill (not spec-kit-sync-artifacts) does the classification spec-kit-sync-artifacts
deliberately leaves to the consuming skill: identify which R-FR##/R-AC##/E-##/R-QR##
IDs actually changed (using spec-kit-sync-artifacts's best-effort localization, or a direct diff if
its localization couldn't resolve one), and classify each as functionally material (scope,
acceptance criteria, entities, safeguards) or non-material (wording, formatting). Only material
changes make the plan stale with impact.
Report the affected IDs and which plan.md sections they touch before proceeding — do not
silently regenerate the whole plan, and do not silently ignore the drift either.
This Fase 0 does not depend on spec-kit-sync-artifacts being invoked as a separate conversational
step — apply its documented procedure directly, inline, as part of this phase.
Workflow
Phase 1 — Inspect Real Context → Technical Context
Reuse verify-before-implement §4 (Pre-Implementation verification sequence): read the actual
manifest/lockfile, existing architecture, and any active architecture skills in this project
(frontend-architecture, backend-api-standards, or equivalent) before writing anything.
Produce the Technical Context block of plan.md (see
spec-kit-shared/templates/plan-template.md): Language/Version, Primary Dependencies, Storage,
Testing, Target Platform, Project Type, Performance Goals, Constraints, Scale/Scope. Every field is
either a verified fact or NEEDS CLARIFICATION — never a plausible guess.
Performance Goals and Constraints come from spec.md's R-QR## (Quality Requirements) and
Safeguards when present; do not invent a numeric target spec.md never stated.
Clarification Policy (Technical Context)
Ask only questions whose answers materially change the technical approach, storage model,
platform, or a measurable constraint.
Ask at most 3 blocking questions per round, same format as spec-kit-generate-spec's Clarification
Policy (context, why it matters, 2–3 options with implications, a custom option).
Do not ask about something derivable from the manifest/lockfile or from spec.md directly.
If the user explicitly requests a draft plan without answering, produce
plan.md marked DRAFT — NEEDS CLARIFICATION and do not report it as ready.
Gate — Constitution Check 1 (before Phase 2)
Read .speckit/memory/constitution.md if it exists.
For each applicable principle, evaluate the proposed technical direction (informed by Technical
Context, not yet by detailed research) as PASS or FAIL.
Report as a table, per plan-template.md's "Constitution Check — Gate 1" section — never as a
prose summary like "reviewed, looks fine."
If constitution.md does not exist, report N/A — sin constitución for this gate rather than
omitting it, and note whether the scope of this plan is broad enough that
spec-kit-establish-constitution should run first.
A FAIL here is not fatal by itself — it must be tracked into Complexity Tracking (Phase 5) or
resolved by changing the proposed direction before Phase 2 starts.
Phase 2 — Research (research.md)
Directed technical research: library/version decisions, verified against what is actually
installed — never against memory of "how this library usually works." Resolve every
NEEDS CLARIFICATION left from Technical Context here, or escalate per the Clarification Policy
above.
For a dependency not currently installed, state that explicitly ("not installed — proposed
addition") rather than treating a proposed library the same as a verified one.
Phase 3 — Data Model (data-model.md)
Only entities already present in spec.md §E — Entities. Do not invent new domain concepts here;
if the design seems to need one spec.md doesn't have, that is a gap to report back — via a
clarification round, or by flagging it for a spec-kit-generate-spec update — not something to add
silently at the planning layer.
Phase 4 — Contracts (contracts/)
If the spec implies an API, follow backend-api-standards when the project is backend. If
frontend with frontend-architecture active, respect its layers. State the verification source
for each endpoint/schema (existing contract file, or "new — proposed").
Phase 4.5 — Project Structure
Document per plan-template.md's Project Structure section:
Documentation (this feature): the fixed .speckit/specs/<feature-dir>/ tree (see
artifact-conventions.md).
Source Code (repository root): in a project that already has structure, this is a
verified snapshot of the real layout (via verify-before-implement), not a free choice
between single-project/web-app/mobile+API templates. Those generic shapes only apply when the
project is genuinely greenfield and has no structure to inspect yet — in that case, the choice
itself is recorded as a decision in Key Decisions and Trade-offs, not left as an unresolved
template option.
Close with Structure Decision: one sentence referencing the real tree — never delivered with
an unresolved Option N label.
Phase 5 — plan.md: Strategy, Decisions, and Gates
Assemble plan.md from spec-kit-shared/templates/plan-template.md, filling every section with
the verified output of Phases 1–4.5, then complete the following in order:
Constitution Check — Gate 2 (re-check)
Re-evaluate the same principles now that data-model.md, contracts/, and Project Structure are
concrete — a specific design choice can introduce a violation the original direction didn't have.
Report as a PASS/FAIL table, same format as Gate 1.
Complexity Tracking
Fill only if a gate (1 or 2) has a FAIL that must be justified to proceed:
Violation
Why Needed
Simpler Alternative Rejected Because
[principle ID]
[concrete, current need]
[why the compliant alternative doesn't work]
A row without a concrete, verifiable need is not a valid justification — it is a signal the
approach must change, not that the table should be filled in anyway. Do not proceed past a FAIL
without either a valid row here or a revised, now-compliant direction.
Convention Enforcement (Structure)
For every new or modified component in S-C0# (from spec.md's Structure section, refined here):
Component (S-C0#)
Pattern Followed
Evidence / Constitution Reference
Deviation
[component]
[existing pattern name, or "new"]
[file example or constitution principle ID]
[none, or → A-D0#]
A component must reference a concrete existing pattern (a file example already inspected, or a
confirmed constitution principle) — never a generic claim like "follows best practices." A
deviation from the dominant pattern or the constitution is recorded as an explicit decision in Key
Decisions and Trade-offs (or, if it's a constitution FAIL, in Complexity Tracking above) — never
as a silent omission.
If .speckit/memory/constitution.md does not exist and the project has relevant prior code,
perform an equivalent targeted inspection (via verify-before-implement) scoped only to the
components this plan touches or extends — and state plainly that this was a targeted inspection,
not a full constitution, suggesting spec-kit-establish-constitution if the detected pattern should apply
project-wide.
Key Decisions and Trade-offs
Standard REASONS-style decision table: alternatives considered, rationale, consequences, evidence
(S#/P# from spec.md, or a freshly verified project fact).
Safe Deferral
Fill only if this plan proposes phases or maps to multiple user stories that will ship
incrementally. For every operation (O-0#) pushed to a later phase or story:
Operation (O-0#)
Deferred To
Condition
Justification
[operation]
[user story / phase]
Dormant / Flagged / Additive
[why this condition genuinely holds]
Dormant: the new code exists but nothing on an active, reachable path invokes it yet.
Flagged: it sits behind a feature flag/toggle that defaults off.
Additive: it adds fields/tables/endpoints without modifying or depending on existing
behavior.
An operation with none of these three conditions is not deferred: it is completed in the
current phase, or the phases are reordered until it genuinely is safe. This is not a preference —
a plan that defers unsafe work is not READY regardless of what its checklist otherwise shows.
When spec-kit-generate-tasks later organizes work by user story (see its SKILL.md), each story's closing
checkpoint verifies this classification held in practice.
Compatibility and Evolution
Backward compatibility, rollout, or migration strategy — cite the Safe Deferral table above when
relevant.
Phase 6 — Quickstart (quickstart.md)
Concrete, manual, step-by-step validation instructions for this feature once implemented — commands
to run, expected observable results. Not a copy of the acceptance criteria; a runnable recipe.
Traceability Consistency Checks
Before validating the checklist:
Every entry in plan.md's Strategy, Data Model, Contracts, and Operations cites at least one
R-FR##/R-AC##/E-##/R-QR## from spec.md.
No component or operation in the plan is absent from spec.md's scope — if the design genuinely
needs something outside it, that's a gap to report, not to add silently.
Terminology (entity names, component names) matches spec.md exactly; if the plan needs to
introduce a new technical term (e.g. a library-specific concept), it's clearly distinguished from
domain vocabulary.
Every Safe Deferral entry references a real O-0# that also appears in Operations/Strategy.
Validate and Iterate
Create checklists/plan-quality.md:
# Plan Quality Checklist: [Feature Name]**Purpose**: Validate technical soundness, constitution compliance, and traceability before task decomposition
**Plan**: [Relative link to plan.md]
**Status**: [READY / DRAFT — NEEDS CLARIFICATION]
## Technical Context- [ ] Every Technical Context field is verified or explicitly `NEEDS CLARIFICATION`- [ ] No field contains a plausible-sounding guess unsupported by a manifest/lockfile/spec citation
## Constitution- [ ] Gate 1 and Gate 2 are both reported as PASS/FAIL tables (or `N/A — sin constitución`)
- [ ] Every Gate FAIL has a corresponding Complexity Tracking row with a concrete justification
- [ ] No gate was skipped or merged into a vague summary
## Design- [ ] Data Model entities all trace to `spec.md` §E — no invented entities
- [ ] Contracts cite a verified source or are explicitly marked "new — proposed"
- [ ] Project Structure documents the real, verified tree (or a justified greenfield choice)
- [ ] Structure Decision references the actual tree, with no unresolved Option labels
## Convention Enforcement- [ ] Every new/modified component cites a concrete existing pattern or constitution principle
- [ ] Every deviation is recorded as an explicit decision, not a silent omission
## Safe Deferral- [ ] Every deferred operation has a valid Dormant/Flagged/Additive justification
- [ ] No operation is deferred without one of the three conditions holding
## Traceability- [ ] Every plan entry cites its source requirement/acceptance criterion/entity
- [ ] No component or operation introduces scope absent from `spec.md`## Governance- [ ] The plan contains no TODOs, placeholders, or unresolved template labels
- [ ] `state.json` was created/updated with this plan's content hash and `based_on_spec_hash`## Agent Portability- [ ] If a `plan-reviewer` (or other agent) was generated, both Kiro and Claude definitions exist and validated per `spec-kit-shared/agent-portability.md`, or `AGENTS: none` is reported
## Notes
[Specific failures, evidence, and remaining decisions]
Validate item by item, fix non-blocking failures, re-run up to three iterations. If a blocking gap
remains (an unresolved FAIL with no valid Complexity Tracking row, or a NEEDS CLARIFICATION
the user hasn't answered), set STATUS to DRAFT — NEEDS CLARIFICATION and do not report the plan
as ready. Set READY only when every checklist item passes.
Updating an Existing Plan
When spec.md changed since the last plan.md (Fase 0 detected material drift):
Identify affected requirement/entity IDs from the diff.
Propagate only through the plan.md sections those IDs touch — Technical Context if a
R-QR## constraint changed, Data Model if an E-## changed, Operations/Strategy if an
R-FR##/R-AC## changed.
Re-run both Constitution Check gates only if the changed sections could plausibly affect them
(a new dependency, a new component) — otherwise note that the gates are unaffected and why.
Preserve stable IDs (A-D0#, S-C0#, O-0#) where semantics are unchanged; add new ones for
new semantics.
Update state.json's artifacts.plan.content_hash and based_on_spec_hash only after the
targeted regeneration validates.
Re-run the full plan-quality.md checklist regardless of how small the change was.
Summarize exactly which plan.md sections changed and why.
If spec.md drifted in a way that invalidates a decision already consumed by an existing
tasks.md (i.e. tasks.md exists and cites the changed O-0#), state this plainly in the
Completion Report — this plan does not update tasks.md itself; that is spec-kit-generate-tasks's job,
triggered separately.
Pre-Execution Extension Hooks
Before planning work, check for .speckit/extensions.yml per
spec-kit-shared/artifact-conventions.md's schema, reading the hooks.before_plan key. Follow
the same enablement/condition/mandatory-vs-optional rules spec-kit-generate-spec uses for its own hooks —
do not reinterpret them differently for this skill.
Mandatory Post-Execution Hooks
After planning work, process hooks.after_plan the same way, using the same emit-then-execute
format spec-kit-generate-spec uses for its own post-hooks.
