Skip to main content
The /speckit.plan command executes the implementation planning workflow, transforming your feature specification into concrete technical architecture, design decisions, and development artifacts.

​
Purpose

Generate production-ready design documents:
  • Research and resolve all technical unknowns
  • Define data models and entity relationships
  • Create API contracts and interface specifications
  • Document technology stack and architecture decisions
  • Update AI agent context with project specifics
  • Validate against constitution principles
Planning focuses on how to build the feature (architecture, tech stack, design patterns) while specifications focus on what to build (requirements, user value).

​
Usage

# Create implementation plan with tech stack hints
/speckit.plan I am building with Python and FastAPI

# Plan with specific constraints
/speckit.plan Using TypeScript, React, and PostgreSQL. Must support 10k concurrent users

# Plan without hints (AI infers from project context)
/speckit.plan

​
How It Works

1

Setup

Runs setup script and parses JSON for:
  • FEATURE_SPEC: Path to spec.md
  • IMPL_PLAN: Path to plan.md (newly created from template)
  • SPECS_DIR: Feature directory
  • BRANCH: Current feature branch name
2

Load Context

Reads:
  • Feature specification (spec.md)
  • Project constitution (.specify/memory/constitution.md)
  • Plan template (already copied to feature directory)
3

Fill Technical Context

Populates plan.md Technical Context section:
  • Language/Version (from user input or project files)
  • Primary Dependencies (framework, libraries)
  • Storage (database, file system, cache)
  • Testing approach (framework, strategy)
  • Target Platform (server, mobile, desktop, browser)
  • Project Type (library, CLI, web service, mobile app)
  • Performance Goals (latency, throughput)
  • Constraints (memory, offline, compliance)
  • Scale/Scope (users, data volume, complexity)
Marks unknowns as “NEEDS CLARIFICATION”
4

Constitution Check

Validates against constitutional principles:
  • Complexity limits (e.g., max 3 services)
  • Architectural patterns (required/forbidden)
  • Technology constraints
  • Quality gates (testing, security, observability)
Errors on violations unless justified in Complexity Tracking table
5

Phase 0: Research

For each “NEEDS CLARIFICATION” in Technical Context:
  • Research best practices for the domain
  • Evaluate technology options
  • Document decisions with rationale
  • Consider alternatives
Generates research.md with all unknowns resolved
6

Phase 1: Design

Creates design artifacts:data-model.md: Entity definitions
  • Extract entities from spec.md
  • Define fields, types, relationships
  • Add validation rules from requirements
  • Document state transitions
contracts/: Interface specifications
  • API endpoints (for web services)
  • CLI command schemas (for CLI tools)
  • Public interfaces (for libraries)
  • Event schemas (for event-driven systems)
quickstart.md: Integration guide
  • Development environment setup
  • Running tests
  • Common workflows
  • Example usage scenarios
7

Phase 1: Agent Context Update

Runs agent-specific script to update AI assistant context:
  • Detects which AI agent is in use
  • Updates agent context file (e.g., .claude/commands/specify-context.md)
  • Adds new technologies from current plan
  • Preserves manual additions between markers
8

Re-evaluate Constitution

Post-design constitution check:
  • Verify design doesn’t violate principles
  • Ensure complexity tracking justifies any violations
  • Confirm quality gates can be met
9

Report Completion

Outputs:
  • Branch name
  • Path to plan.md
  • List of generated artifacts
  • Suggested next command: /speckit.tasks

​
Plan Structure

​
Metadata

# Implementation Plan: User Authentication

**Branch**: `003-user-auth` | **Date**: 2024-03-15 | **Spec**: [link]

​
Summary

High-level overview extracted from spec: 
## Summary

Implement user authentication system supporting email/password login, password reset via email, and OAuth2 social login (Google, GitHub). System must securely hash passwords, enforce password policies, lock accounts after failed attempts, and maintain session security.

​
Technical Context

Concrete technology decisions: 
## Technical Context

**Language/Version**: Python 3.11  
**Primary Dependencies**: FastAPI 0.104, SQLAlchemy 2.0, Pydantic 2.5  
**Storage**: PostgreSQL 15 (user accounts, sessions), Redis 7 (session cache)  
**Testing**: pytest 7.4, pytest-asyncio, httpx (for API testing)  
**Target Platform**: Linux server (Docker containers)  
**Project Type**: RESTful web service  
**Performance Goals**: 
  - Login endpoint: < 200ms p95
  - Password reset email: < 1 minute delivery
  - Support 1,000 concurrent login attempts  
**Constraints**: 
  - GDPR compliance required (data export/deletion)
  - Must integrate with existing user profile service
  - Offline capability not required  
**Scale/Scope**: 
  - Expected: 10,000 active users
  - Session data: ~1MB per 1000 active sessions
  - OAuth providers: Google, GitHub (extensible for more)

​
Best Practices

​
Provide Tech Stack Hints

/speckit.plan I am building with Go 1.21, Gin framework, and MongoDB

​
Justify Constitution Violations

If your design requires complexity:
  • Add entry to Complexity Tracking table
  • Explain why it’s needed
  • Document simpler alternative and why it’s insufficient
  • Get buy-in before proceeding

​
Document Research Thoroughly

Future developers (including you) will ask:
  • Why did we choose X over Y?
  • What were the tradeoffs?
  • Can we switch to Z now?
Answer these questions in research.md.

​
Keep Contracts Implementation-Agnostic

Define the interface, not the implementation:
  • API endpoints: request/response schemas, status codes
  • CLI commands: argument formats, output structure
  • Library interfaces: function signatures, return types
  • Events: schema and semantics
Avoid: “Uses FastAPI routing” or “Calls UserRepository.find()“

​
Handoffs

After planning:

Create Tasks

Break the plan into actionable, dependency-ordered tasks

Create Checklist

Generate quality checklists for the plan (optional)

​
File Structure

specs/003-user-auth/
├── spec.md                    # Feature specification
├── plan.md                    # Implementation plan (this command)
├── research.md                # Technical decisions (Phase 0)
├── data-model.md              # Entity definitions (Phase 1)
├── quickstart.md              # Development guide (Phase 1)
└── contracts/                 # API specifications (Phase 1)
    ├── auth.md
    └── oauth.md

​
Next Steps

Tasks

Break down the plan into executable tasks

Build docs developers (and LLMs) love

Get started for freeTalk to us