Command: `/specify`
Relevant source files
The following files were used as context for generating this wiki page:The /specify command is the entry point into the Spec-Driven Development (SDD) workflow. Its primary purpose is to transform a high-level, natural-language feature description into a structured, formal specification document within a new, dedicated feature branch. This command automates the initial setup for a new feature, ensuring consistency and creating the foundational artifact for subsequent commands like /plan and /tasks.
By running /specify, a developer initiates a process that creates the necessary repository structure, including a new Git branch and a specification file based on a standard template. This allows the development team to focus on defining the "what" and "why" of a feature before moving on to the "how."
Sources: spec-driven.md:144-152, README.md:27-31, templates/commands/specify.md:1-5
Execution Flow
When an AI agent executes the /specify command with a feature description, it triggers a sequence of automated actions orchestrated by a shell script. The command's definition outlines a clear, step-by-step process.
Sources: templates/commands/specify.md:7-14
The following diagram illustrates the interaction between the user, the AI agent, and the underlying system components when /specify is invoked.
The process is as follows:
- The AI agent is instructed to run the
create-new-feature.shscript, passing the user's feature description as an argument. - The script handles all repository-level operations: creating a new feature branch and initializing the
spec.mdfile from a template. - The script returns the new branch name and the absolute path to the created
spec.mdfile in JSON format. - The
/specifycommand logic then parses this output. - It proceeds to populate the newly created
spec.mdfile, using thespec-template.mdas a structural guide and inserting the user's description. - Finally, it reports back that the process is complete, indicating the new branch and spec file are ready for the next phase.
Sources: templates/commands/specify.md:7-14, scripts/create-new-feature.sh:10-16
Core Component: create-new-feature.sh
This shell script is the engine behind the /specify command's repository management tasks. It is responsible for creating a consistent environment for every new feature.
Sources: scripts/create-new-feature.sh
Script Logic
The script follows a deterministic process to set up the feature branch and directory structure.
Sources: scripts/create-new-feature.sh:18-77
Branch and Directory Naming
The script automatically generates a feature number and branch name.
- Feature Number: It scans all subdirectories in
specs/to find the highest existing number (e.g.,001,002) and increments it. The number is zero-padded to three digits (e.g.,003). - Branch Name: The user's description is converted to lowercase, special characters are replaced with hyphens, and the first 2-3 words are taken to form a concise name. The final branch name combines the feature number and the kebab-cased words (e.g.,
001-create-taskify). - Directory: A directory matching the branch name is created under
specs/.
Sources: scripts/create-new-feature.sh:30-60
Script Output
The script communicates its results back to the calling process. It supports two output formats, controlled by the --json flag.
| Key | Description | Example |
|---|---|---|
BRANCH_NAME | The name of the newly created Git branch. | 001-build-photo-app |
SPEC_FILE | The absolute path to the generated specification file. | /path/to/repo/specs/001-build-photo-app/spec.md |
FEATURE_NUM | The generated three-digit feature number. | 001 |
Sources: scripts/create-new-feature.sh:71-77
Generated Artifact: spec.md
The primary output of the /specify command is the spec.md file. This document is generated from templates/spec-template.md and serves as the single source of truth for the feature's requirements.
The core philosophy of this specification is to focus on WHAT the user needs and WHY, while strictly avoiding any details on HOW to implement it. This separation of concerns is critical to the SDD methodology.
Sources: templates/spec-template.md:16-18, spec-driven.md:4-8
Structure of spec.md
The template enforces a consistent structure for all feature specifications.
| Section | Purpose |
|---|---|
| User Scenarios & Testing | (Mandatory) Describes the main user journey, acceptance criteria in a "Given/When/Then" format, and potential edge cases. |
| Requirements | (Mandatory) Lists specific, testable functional requirements (e.g., FR-001: System MUST...). |
| Key Entities | (Optional) Included if the feature involves data. Describes conceptual entities and their relationships without implementation details. |
| Review & Acceptance Checklist | A gate-keeping checklist to ensure the spec is high-quality, complete, and free of implementation details before proceeding to the planning phase. |
Sources: templates/spec-template.md:38-90
Handling Ambiguity
A key feature of the specification template is its mechanism for handling unclear requirements from the initial user prompt. Any assumption or ambiguity must be explicitly marked using the [NEEDS CLARIFICATION: specific question] tag. This forces a dialogue to resolve uncertainties before implementation planning begins.
Example from the template:
- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
This practice prevents the AI or developer from making incorrect assumptions and ensures the final specification is unambiguous and testable.
Sources: templates/spec-template.md:22-25, templates/spec-template.md:65-66
Summary
The /specify command is the foundational first step in the Spec-Driven Development process. It automates the tedious setup of creating a new feature branch and structured specification file. By transforming a simple, natural-language idea into a formal, version-controlled artifact, it establishes a clear, unambiguous source of truth that guides the entire development lifecycle for that feature.