spec-kit-plan（规格套件计划）

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