Spec Kit Plan

Generate implementation design artifacts from the approved feature specification.

Invocation Notice

• Inform the user when this skill is being invoked by name: spec-kit-plan.

When to Use

• spec.md exists and you need plan.md plus Phase 0/1 design outputs for task generation.
• plan.md is missing, stale, or invalid after changes to spec.md or memory/constitution.md.
• The next step is spec-kit-tasks, but technical context and design decisions are not yet documented.

When Not to Use

• No usable spec.md exists yet (spec-kit-specify first).
• High-impact ambiguity in spec.md still blocks architecture or validation decisions (spec-kit-clarify first).
• You are decomposing design into executable work items (spec-kit-tasks).
• You only need a read-only consistency audit (spec-kit-analyze).
• You are reconciling cross-artifact drift discovered mid-work (spec-kit-reconcile).

Router Fit

• Primary route from spec-kit after spec-kit-specify / spec-kit-clarify.
• Must complete before spec-kit-tasks.
• Depends on constitution output from spec-kit-constitution.

Preconditions

• Work from the target repository root.
• Active feature branch resolves to a spec directory (NNN-feature-name format when git is available).
• memory/constitution.md exists and is current for planning gates.

Workflow

1. Resolve active feature paths and initialize plan.md:

• Run scripts/setup-plan.sh --json exactly once.
• Parse and retain: FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH.
• If the script exits non-zero (for example branch gate failure), stop and report the blocking error.

1. Enforce artifact gates before writing design outputs:

• If FEATURE_SPEC (spec.md) is missing, stop and route to spec-kit-specify.
• If memory/constitution.md is missing, stop and route to spec-kit-constitution.
• If spec.md has unresolved high-impact ambiguity that can change architecture, data model, testing, UX, operations, or compliance, stop and route to spec-kit-clarify.

1. Load planning inputs with template fallback:

• Required: spec.md, memory/constitution.md.
• Preferred plan template: {REPO_ROOT}/.specify/templates/plan-template.md.
• Fallback template: assets/plan-template.md.
• Preserve template heading order; replace placeholders rather than adding parallel structures.

1. Draft plan.md core sections:

• Complete Summary and Technical Context.
• Mark unknown technical decisions as NEEDS CLARIFICATION.
• Fill Constitution Check from memory/constitution.md with explicit pass/fail status.
• Select one concrete project structure and remove unused template options.
• Use Complexity Tracking only when a constitutional violation remains and is explicitly justified.

1. Run Phase 0 research (research.md):

• Turn each NEEDS CLARIFICATION in Technical Context into a focused research question.
• Record outcomes as:
• Decision
• Rationale
• Alternatives considered
• Resolve all blockers needed for design decisions before continuing.

1. Run Phase 1 design outputs:

• Create/update data-model.md with entities, fields, relationships, validation rules, and state transitions where relevant.
• Create/update contracts/ for externally visible interfaces that the feature introduces or modifies.
• Create/update quickstart.md with concrete validation flow for the designed feature.
• Reflect final decisions back into plan.md so downstream task generation has a single source of truth.

1. Update agent context (explicit user approval required):

• Before running the script, ask for explicit approval to update agent context files (for example AGENTS.md, CLAUDE.md, GEMINI.md, .github/agents/copilot-instructions.md).
• Run scripts/update-agent-context.sh from repository root only after user approval.
• If an agent type is provided by the user, pass it as the first argument.
• If approval is declined or unavailable, skip this step and report it as skipped.
• Report script failures explicitly; do not silently skip context updates.

1. Re-check gates and report completion:

• Re-evaluate Constitution Check after Phase 1 outputs.
• Stop with ERROR if unresolved constitutional violations or unresolved blocking clarifications remain.
• Report BRANCH, absolute artifact paths, and readiness for spec-kit-tasks.

Output

• plan.md:
• Fully populated from the selected plan template.
• Technical Context reflects final decisions from Phase 0.
• Constitution Check is explicit (pass, fail, or justified exception).
• Project Structure shows one concrete layout (no placeholder option blocks).
• research.md:
• One entry per planning unknown using:
• Decision
• Rationale
• Alternatives considered
• Resolves all blocking NEEDS CLARIFICATION items required for design.
• data-model.md:
• Captures entities, fields, relationships, validation constraints, and relevant state transitions.
• Maps model decisions back to spec requirements where practical.
• contracts/* (when applicable):
• Defines each new/changed external interface (endpoint/event/schema).
• Includes input/output shape, validation/error behavior, and compatibility notes.
• quickstart.md:
• Describes a concrete validation flow for the designed feature.
• Covers primary success path plus key error/edge behavior from the spec.
• Updated agent context file(s) from scripts/update-agent-context.sh (only when user-approved):
• Contains newly introduced technologies from the final plan.
• Preserves user-maintained manual sections.
• If the user does not approve context updates:
• Report that agent context sync was intentionally skipped.

Key rules

• Use absolute paths in completion reporting.
• Treat missing prerequisites as hard stops with reroutes to the owning sibling skill.
• Do not generate tasks.md or implementation code in this skill.
• Keep plan artifacts at design granularity: architecture, data model, interfaces/contracts, constraints, and validation approach.
• Do not include execution-level content such as code snippets, patch-style file edits, command runbooks, or checklist task breakdowns.
• Do not leave blocking NEEDS CLARIFICATION unresolved by completion.
• Emit ERROR for unresolved constitution gates without justification.
• Never run scripts/update-agent-context.sh without explicit user approval in the current session.

Common Mistakes

• Planning without an approved spec — the plan will lack stable requirements and churn.
• Using the wrong template source path (spec-template instead of plan-template).
• Keeping placeholder project-structure options in plan.md instead of selecting one concrete layout.
• Including execution details in plan artifacts (code snippets, exact commands, patch-level file changes, or task checklists) — design belongs in spec-kit-plan; execution belongs to spec-kit-tasks and spec-kit-implement.
• Skipping the post-design constitution re-check before handing off to spec-kit-tasks.
• Running context-file updates automatically without asking the user to approve changes to AGENTS.md/CLAUDE.md/related files.

References

• references/spec-kit-workflow.dot for overall context of where planning fits in the Spec Kit sequence.
• scripts/setup-plan.sh
• scripts/update-agent-context.sh
• assets/plan-template.md
• https://github.com/github/spec-kit/blob/9111699cd27879e3e6301651a03e502ecb6dd65d/templates/commands/plan.md