The /speckit.plan command transforms a technology-agnostic feature specification into a concrete technical implementation plan. It serves as the bridge between business requirements (captured in spec.md) and executable tasks, translating user stories into technical architecture while enforcing constitutional principles through validation gates.
This command is the third phase in the Spec-Driven Development workflow, following /speckit.constitution and /speckit.specify. For resolving specification ambiguities before planning, see /speckit.clarify. For generating executable tasks from the plan, see /speckit.tasks.
The command accepts natural language arguments describing:
Example invocations:
Sources: README.md112-117 README.md492-498
Before executing /speckit.plan, the following must exist:
| Artifact | Location | Purpose |
|---|---|---|
constitution.md | .specify/memory/ | Immutable architectural principles for validation |
spec.md | .specify/specs/NNN-feature-name/ | Feature specification with user stories and acceptance criteria |
| Feature branch | Git repository | Isolated development context (e.g., 001-create-taskify) |
The command will fail if spec.md contains unresolved [NEEDS CLARIFICATION] markers. Run /speckit.clarify first to address ambiguities.
Sources: spec-driven.md86-94 README.md462-466
Sources: spec-driven.md86-94 README.md490-530
The command reads specs/NNN-feature-name/spec.md and extracts:
User-provided arguments are analyzed to determine:
The command loads all nine articles from memory/constitution.md:
| Article | Principle | Enforcement Point |
|---|---|---|
| I | Library-First | Feature must be standalone library |
| II | CLI Interface Mandate | Must expose text-based interface |
| III | Test-First Imperative | Tests before implementation code |
| VII | Simplicity Gate | Maximum 3 projects initially |
| VIII | Anti-Abstraction Gate | Use framework features directly |
| IX | Integration-First Testing | Real dependencies, not mocks |
Sources: spec-driven.md275-346 README.md404-405
The validation system enforces architectural discipline through binary checks:
Each gate implements a template-driven checkpoint in plan-template.md:
Gate Failure Handling:
When a gate fails (checkbox unchecked), the plan must include a Complexity Tracking section:
Sources: spec-driven.md209-225 spec-driven.md347-371
| File | Purpose | Key Sections |
|---|---|---|
plan.md | Main implementation blueprint | Overview, Tech Stack, Phase -1 Gates, Core Implementation, Testing Strategy, Deployment, Complexity Tracking |
data-model.md | Database schema and relationships | Entity definitions, Foreign keys, Indexes, Validation rules |
contracts/ | API and integration contracts | REST endpoints, WebSocket events, gRPC services, GraphQL schema |
research.md | Technology evaluation | Library comparisons, Version compatibility, Performance benchmarks, Security considerations |
quickstart.md | Manual validation guide | Key user flows, Expected outcomes, Edge cases to test |
The primary artifact follows templates/plan-template.md:
Sources: README.md500-528 spec-driven.md86-94
After generating plan artifacts, the command triggers infrastructure scripts:
| Script | Location | Purpose |
|---|---|---|
setup-plan.sh | .specify/scripts/ | Validates plan.md structure |
update-agent-context.sh | .specify/scripts/ | Extracts tech stack to agent context files |
update-claude-md.sh | .specify/scripts/ | Updates CLAUDE.md with project dependencies |
The update-agent-context.sh script parses plan.md to update agent-specific files:
.claude/CONTEXT.md for Claude Code.gemini/context.toml for Gemini CLI.github/agents/context.md for GitHub Copilot.cursor/context.md for Cursor.windsurf/context.yml for WindsurfThis ensures AI agents have current project context for /speckit.implement.
Sources: README.md447-458 spec-driven.md86-94
The /speckit.plan command is defined in templates/commands/plan.md with YAML frontmatter:
The command template is processed during specify init to create agent-specific files:
Different AI agents require different command formats:
| Agent Type | Format | Placeholder | Example Location |
|---|---|---|---|
| Claude Code | Markdown | $ARGUMENTS | .claude/commands/plan.md |
| Gemini CLI | TOML | {{args}} | .gemini/commands/plan.toml |
| GitHub Copilot | Markdown | Standard | .github/agents/plan.md |
| Cursor | Markdown | Chat mode | .cursor/commands/plan.md |
| Windsurf | Markdown | Workflow | .windsurf/workflows/plan.md |
Sources: README.md245-269
User prompt:
Plan output (Complexity Tracking section):
User prompt:
Plan output (Complexity Tracking section):
User prompt:
Plan output (Complexity Tracking section):
Sources: spec-driven.md322-333 spec-driven.md209-225
Good examples:
Poor examples:
When the tech stack involves rapidly changing libraries, prompt for research:
This triggers the AI agent to:
research.md with specific investigation tasksSources: README.md532-553
Before proceeding to /speckit.tasks, verify:
Sources: README.md557-575
Error symptom: Command fails with "spec.md not found"
Resolution:
001-feature-name)specs/NNN-feature-name/spec.md exists/speckit.specify if spec doesn't existError symptom: Plan contains [NEEDS CLARIFICATION] markers
Resolution:
[NEEDS CLARIFICATION] markers/speckit.clarify to resolve ambiguities/speckit.planSymptom: Plan proposes complex architecture not justified by requirements
Resolution:
Symptom: contracts/ directory empty or incomplete
Resolution:
Sources: README.md554-575
| Command | Relationship | Purpose |
|---|---|---|
| /speckit.constitution | Prerequisite | Establishes architectural principles enforced during planning |
| /speckit.specify | Prerequisite | Creates feature specification that planning transforms into technical design |
| /speckit.clarify | Optional predecessor | Resolves ambiguities in spec before planning to reduce rework |
| /speckit.tasks | Successor | Converts plan into ordered, executable task list |
| /speckit.analyze | Validation | Cross-checks plan consistency with spec and constitution |
| /speckit.implement | Final step | Executes tasks generated from plan |
| Path Pattern | Description |
|---|---|
.specify/memory/constitution.md | Source of validation rules and architectural principles |
.specify/specs/NNN-feature-name/spec.md | Input specification with user stories and requirements |
.specify/specs/NNN-feature-name/plan.md | Primary output - technical implementation blueprint |
.specify/specs/NNN-feature-name/data-model.md | Generated entity schemas and relationships |
.specify/specs/NNN-feature-name/contracts/ | API specifications, event schemas, service contracts |
.specify/specs/NNN-feature-name/research.md | Technology evaluation and version decisions |
.specify/specs/NNN-feature-name/quickstart.md | Manual validation scenarios for testing |
.specify/templates/plan-template.md | Template structure that defines plan.md format |
.specify/scripts/setup-plan.sh | Post-generation validation script |
.specify/scripts/update-agent-context.sh | Extracts tech stack to agent context files |
Sources: README.md500-528 spec-driven.md86-94
Refresh this wiki