Command: `/plan`

Relevant source files

The following files were used as context for generating this wiki page:

• templates/commands/plan.md
• templates/plan-template.md
• spec-driven.md
• README.md
• memory/constitution.md
• scripts/update-agent-context.sh
• templates/agent-file-template.md

The /plan command is the second step in the Spec-Driven Development (SDD) workflow, following /specify and preceding /tasks. Its primary purpose is to translate a high-level feature specification (spec.md) into a detailed, actionable technical implementation plan. It takes user input regarding the desired technology stack and architecture, analyzes the feature requirements, and generates a suite of design artifacts that guide the subsequent implementation phase.

This command embodies the SDD principle of separating the "what" from the "how." While /specify focuses on user needs and business logic, /plan is where technical decisions are made and documented. It ensures that all implementation choices are deliberate, aligned with project principles, and trace back to specific requirements before any code is written.

Sources: spec-driven.md:112-120, README.md:32-36, templates/commands/plan.md:1-5

Execution Flow

The /plan command orchestrates a series of automated steps to generate the implementation plan and its associated artifacts. The process is guided by the plan-template.md file, which acts as an executable blueprint.

This diagram illustrates the sequence of operations when the /plan command is invoked.

The detailed steps are as follows:

1. Initialization: The command runs the scripts/setup-plan.sh script to get key file paths, such as the location of the feature specification (FEATURE_SPEC) and the destination for the new implementation plan (IMPL_PLAN).
2. Analysis: The AI agent reads and analyzes the FEATURE_SPEC file to understand the requirements and user stories. It also reads the project's constitution.md to load the architectural principles that must be followed.
3. Template Execution: The agent uses /templates/plan-template.md as a self-contained, executable guide. It follows the phases defined within the template to generate all required artifacts.
4. Artifact Generation:
   • Phase 0 (Research): The agent identifies any "NEEDS CLARIFICATION" items in the technical context and generates research.md to document decisions and best practices.
   • Phase 1 (Design): Based on the resolved research and the feature spec, the agent generates data-model.md, API contracts in the contracts/ directory, and a quickstart.md guide for validation. It also updates the agent-specific context file (e.g., CLAUDE.md).
5. Task Planning Approach: The command describes the strategy for the /tasks command but does not generate tasks.md itself. This is a crucial distinction, as /plan stops after the design phase.
6. Verification & Reporting: The agent verifies that all steps in the template's Progress Tracking are complete and reports the newly created artifacts to the user.

Sources: templates/commands/plan.md:7-24, templates/plan-template.md:6-18, 93-120

The Plan Template

The /plan command's output and behavior are dictated by /templates/plan-template.md. This file is not just a passive template but an executable set of instructions for the AI agent.

Technical Context

This section captures the high-level technical decisions for the feature. The user's arguments to the /plan command are used to populate these fields. Any unspecified fields are marked as NEEDS CLARIFICATION, which triggers research tasks in Phase 0.

Field	Description	Example
Language/Version	The primary programming language and its version.	Python 3.11
Primary Dependencies	Core frameworks or libraries.	FastAPI
Storage	The data storage solution, if applicable.	PostgreSQL
Testing	The testing framework to be used.	pytest
Target Platform	The environment where the code will run.	Linux server
Project Type	Determines the source code structure (single, web, mobile).	web
Performance Goals	Specific performance targets.	1000 req/s
Constraints	Key limitations or requirements.	<200ms p95
Scale/Scope	The expected scale of the feature.	10k users

Sources: templates/plan-template.md:23-33

Constitution Check

This section acts as a critical quality gate before and after the design phase. It forces the agent to evaluate its plan against the core principles defined in /memory/constitution.md.

The check verifies adherence to principles such as:

• Simplicity: Limiting the number of projects and avoiding premature patterns (e.g., Repository/UoW).
• Architecture: Ensuring every feature is a library and has a corresponding CLI.
• Testing: Enforcing a strict Test-Driven Development (TDD) cycle where tests are written first.
• Observability: Including structured logging.

If a violation is necessary, it must be documented in the Complexity Tracking table with a clear justification.

Sources: templates/plan-template.md:36-65, memory/constitution.md

Project Structure

The template defines three standard project structures based on the Project Type identified in the Technical Context. This ensures a consistent repository layout.

This diagram shows the decision logic for selecting a project structure.

Generated Artifacts

The primary output of the /plan command is a set of markdown and data files within the feature's specs/[###-feature-name]/ directory.

File / Directory	Purpose	Generated In
plan.md	The main implementation plan file, containing all sections described above.	Initial copy
research.md	Documents technical research, decisions, and rationale for technology choices.	Phase 0
data-model.md	Defines data entities, fields, relationships, and validation rules.	Phase 1
contracts/	A directory containing API specifications (e.g., OpenAPI JSON, GraphQL schema).	Phase 1
quickstart.md	Provides steps for validating the feature, derived from user stories.	Phase 1
agent-file.md	An agent-specific file (e.g., CLAUDE.md) is updated with the new technologies.	Phase 1

Note: tasks.md is not created by /plan. The plan only outlines the approach for its creation by the /tasks command.

Sources: templates/plan-template.md:73-79, 93-120, scripts/update-agent-context.sh:1-4, templates/agent-file-template.md

Conclusion

The /plan command is a cornerstone of the Spec-Driven Development methodology. It serves as the critical bridge between a conceptual feature specification and a concrete, technically-sound implementation strategy. By automating the generation of design artifacts and enforcing architectural principles via the constitution, it ensures that development starts with a solid, well-documented, and pre-validated foundation. This structured approach minimizes ambiguity, improves consistency, and accelerates the delivery of high-quality software.

Sources: spec-driven.md:112-120, README.md:32-36