/speckit.specify Command

Relevant source files

• README.md
• templates/commands/specify.md

Purpose and Scope

The /speckit.specify command transforms natural language feature descriptions into structured, implementation-agnostic specifications. This command is the first step in the Spec-Driven Development workflow after establishing project principles with /speckit.constitution (see page 5.2). It creates a new feature branch, initializes the specification directory structure, and generates a requirements document focused on what users need and why, deliberately excluding how to implement.

The command orchestrates three primary operations:

1. Branch creation: Invokes scripts/bash/create-new-feature.sh or scripts/powershell/create-new-feature.ps1 to create a Git branch with pattern NNN-short-name
2. Spec generation: Populates .specify/specs/NNN-short-name/spec.md from templates/spec-template.md
3. Quality validation: Creates .specify/specs/NNN-short-name/checklists/requirements.md and validates specification completeness

For clarifying underspecified areas in an existing specification, see page 5.4. For creating technical implementation plans from specifications, see page 5.5.

Sources: templates/commands/specify.md1-14 README.md96-109 templates/commands/specify.md26-198

---

Command Overview

The command accepts a natural language feature description as its argument and executes a multi-stage process:

Stage	Code Entity	Operation
1. Keyword Extraction	AI agent	Generates 2-4 word short-name from feature description
2. Collision Detection	git ls-remote, git branch, filesystem	Queries remote branches, local branches, and specs/ directory to find highest NNN
3. Script Invocation	scripts/bash/create-new-feature.sh or scripts/powershell/create-new-feature.ps1	Executes with --number NNN+1 --short-name "short-name", returns JSON with BRANCH_NAME, SPEC_FILE, FEATURE_DIR keys
4. Specification Generation	AI agent, templates/spec-template.md	Copies template structure to SPEC_FILE and populates sections
5. Quality Validation	AI agent	Creates checklists/requirements.md and validates against 14 checklist items
6. Clarification Workflow	AI agent	Presents max 3 [NEEDS CLARIFICATION] questions with Option A/B/C/Custom table format
7. Completion Report	AI agent	Outputs BRANCH_NAME, SPEC_FILE, checklist pass/fail counts, next command recommendation

Sources: templates/commands/specify.md26-198 README.md96-109

<old_str>

Clarification Marker System

The command enforces a strict maximum of 3 [NEEDS CLARIFICATION] markers per specification templates/commands/specify.md87

Prioritization hierarchy templates/commands/specify.md88-89 templates/commands/specify.md224:

Priority	Category	Example Clarifications
1 (Highest)	Feature scope and boundaries	"Should search include archived items?"
2	Security/privacy requirements	"What user data needs encryption at rest?"
3	User experience impacts	"Should bulk operations be cancelable?"
4 (Lowest)	Technical details	"Preferred authentication flow?"

Marker insertion criteria templates/commands/specify.md82-86:

Reasonable defaults that do NOT require clarification templates/commands/specify.md231-237:

Aspect	Default Assumption
Data retention	Industry-standard practices for the domain
Performance targets	Standard web/mobile app expectations unless specified
Error handling	User-friendly messages with appropriate fallbacks
Authentication method	Standard session-based or OAuth2 for web apps
Integration patterns	RESTful APIs unless specified otherwise

Marker format in spec.md:

Sources: templates/commands/specify.md82-89 templates/commands/specify.md220-237 </old_str> <new_str>

Script Integration

The command invokes platform-specific scripts through YAML frontmatter placeholder substitution defined in templates/commands/specify.md templates/commands/specify.md11-13

Script Invocation Patterns

Bash invocation:

PowerShell invocation:

Script Execution Flow

Script Output Contract

The script writes JSON to stdout with three keys:

JSON Key	Type	Example	Purpose
BRANCH_NAME	string	"004-user-auth"	Git branch created and checked out
SPEC_FILE	string	".specify/specs/004-user-auth/spec.md"	Absolute or relative path to spec file for AI to populate
FEATURE_DIR	string	".specify/specs/004-user-auth"	Feature directory for checklists and artifacts

Critical constraint: The script must only be executed once per feature templates/commands/specify.md68-69 Re-execution would create duplicate branches.

Argument escaping: For single quotes in feature descriptions like "I'm building a feature", use bash escape syntax 'I'\''m building' or PowerShell double-quotes "I'm building" templates/commands/specify.md72

Sources: templates/commands/specify.md11-13 templates/commands/specify.md59-72

---

Command Execution Flow

End-to-End Workflow Diagram

Sources: templates/commands/specify.md76-100 templates/commands/specify.md103-195

---

Feature Branch Creation System

Branch Naming and Collision Detection

The command implements intelligent branch naming with collision detection across three data sources to ensure unique feature numbers.

Short Name Generation Rules templates/commands/specify.md30-40:

• 2-4 words maximum
• Action-noun format preferred (e.g., add-user-auth, fix-payment-bug)
• Preserves technical terms and acronyms (OAuth2, API, JWT)
• Examples:
  • "I want to add user authentication" → user-auth
  • "Implement OAuth2 integration for the API" → oauth2-api-integration
  • "Create a dashboard for analytics" → analytics-dashboard

Collision Detection Algorithm

This diagram maps the collision detection flow from natural language to Git/filesystem operations:

Key code entities referenced:

• Git commands: git fetch, git ls-remote, git branch, git checkout -b
• Scripts: .specify/scripts/bash/create-new-feature.sh, .specify/scripts/powershell/create-new-feature.ps1
• Template: templates/spec-template.md
• Output keys: BRANCH_NAME, SPEC_FILE, FEATURE_DIR

Sources: templates/commands/specify.md42-72

Script Integration

The command invokes platform-specific scripts through placeholder substitution:

Bash invocation templates/commands/specify.md12:

scripts/bash/create-new-feature.sh --json "{ARGS}"

PowerShell invocation templates/commands/specify.md13:

scripts/powershell/create-new-feature.ps1 -Json "{ARGS}"

Script responsibilities:

1. Create feature branch with pattern NNN-short-name
2. Check out the new branch
3. Create directory specs/NNN-short-name/
4. Initialize spec.md from templates/spec-template.md
5. Output JSON with BRANCH_NAME and SPEC_FILE keys

Important: The script must only be executed once per feature templates/commands/specify.md68

Sources: templates/commands/specify.md12-13 templates/commands/specify.md59-71

---

Specification Generation Process

Template Loading and Section Population

The command loads templates/spec-template.md to understand required sections templates/commands/specify.md73 then populates it following strict content guidelines.

Content Generation Guidelines

Mandatory focus templates/commands/specify.md203-206:

• WHAT users need (requirements, scenarios, outcomes)
• WHY features matter (business value, user problems solved)
• Avoid HOW to implement (no tech stack, APIs, code structure)
• Written for business stakeholders, not developers

Section Population Flow

Sources: templates/commands/specify.md76-100

Clarification Marker System

The command enforces a maximum of 3 [NEEDS CLARIFICATION] markers per specification templates/commands/specify.md88

Marker Insertion Rules

Usage criteria templates/commands/specify.md82-89:

• Choice significantly impacts scope or user experience
• Multiple reasonable interpretations exist with different implications
• No reasonable default exists

Prioritization hierarchy (when more than 3 clarifications are needed) templates/commands/specify.md89 templates/commands/specify.md224:

Priority	Category	Example
1	Feature scope and boundaries	"Should search include archived items?"
2	Security/privacy requirements	"What user data needs encryption at rest?"
3	User experience impacts	"Should bulk operations be cancelable?"
4	Technical details	"Preferred authentication flow?"

Reasonable Defaults

The following aspects have reasonable defaults and should NOT trigger [NEEDS CLARIFICATION] markers templates/commands/specify.md232-238:

Aspect	Default Assumption
Data retention	Industry-standard practices for the domain
Performance targets	Standard web/mobile app expectations
Error handling	User-friendly messages with appropriate fallbacks
Authentication method	Session-based or OAuth2 for web apps
Integration patterns	RESTful APIs

Marker Format

In spec.md:

In clarification questions templates/commands/specify.md163-181:

Sources: templates/commands/specify.md82-89 templates/commands/specify.md163-181 templates/commands/specify.md220-238

---

Quality Validation System

Specification Quality Checklist

After generating the initial specification, the command creates FEATURE_DIR/checklists/requirements.md templates/commands/specify.md106-143

Checklist file structure:

Checklist Validation Items

Section	Item Count	Pass Criteria
Content Quality	4	No tech stack mentions, business-focused language, non-technical audience, all mandatory sections present
Requirement Completeness	8	Zero [NEEDS CLARIFICATION] markers, testable requirements, measurable success criteria, complete scenarios
Feature Readiness	4	Acceptance criteria defined, primary flows covered, success criteria met, no implementation leaks
Total	16	All items must pass for spec to be marked ready for /speckit.plan

Sources: templates/commands/specify.md105-143

Validation Execution Flow

Validation outcomes:

Condition	Action	Next Step
All items pass	Mark checklist complete	Recommend /speckit.plan
[NEEDS CLARIFICATION] markers remain	Present questions (max 3)	User resolves → re-validate
Non-clarification failures	Update spec (max 3 iterations)	Re-validate or document issues
Failures after 3 iterations	Document in checklist Notes	Warn user, mark complete with failures

Sources: templates/commands/specify.md143-194

Clarification Question Presentation

Question Format

When [NEEDS CLARIFICATION] markers remain after initial spec generation, the command presents questions sequentially (max 3 total) templates/commands/specify.md162-191

Presentation workflow:

1. Extract all [NEEDS CLARIFICATION: ...] markers from spec.md
2. If more than 3 markers exist, keep only the 3 most critical by priority (scope > security/UX > technical)
3. Format each as ## Question N with table of options
4. Present all questions together before waiting for responses
5. Wait for user to respond with choices (e.g., "Q1: A, Q2: Custom - [details], Q3: B")
6. Replace [NEEDS CLARIFICATION] markers in spec with selected answers
7. Re-run quality validation

Table Formatting Requirements

Critical formatting rules templates/commands/specify.md183-187:

Rule	Correct	Incorrect
Cell spacing	| Content |	|Content|
Header separator	|--------| (min 3 dashes)	|--|
Pipe alignment	Consistent spacing	Inconsistent spacing
Markdown preview	Must render correctly	Broken table rendering

Response Handling

User response format: "Q1: A, Q2: Custom - User must have edit permission, Q3: B"

Processing steps:

1. Parse user response to extract choice for each question
2. For Option A/B/C: Use pre-defined answer from table
3. For Custom: Use user-provided text
4. Replace corresponding [NEEDS CLARIFICATION] marker in spec.md
5. Update checklists/requirements.md to reflect resolved status
6. Re-run validation cycle

Sources: templates/commands/specify.md162-194

---

Success Criteria Requirements

Success criteria in spec.md must follow strict validation rules to remain implementation-agnostic templates/commands/specify.md240-247

Validation Rules

Rule	Description	Checklist Item
Measurable	Include specific metrics (time, percentage, count, rate)	"Success criteria are measurable"
Technology-agnostic	No mention of frameworks, languages, databases, or tools	"Success criteria are technology-agnostic (no implementation details)"
User-focused	Describe outcomes from user/business perspective	Validated in "Content Quality" section
Verifiable	Can be tested without knowing implementation details	"Requirements are testable and unambiguous"

Valid vs Invalid Examples

Valid success criteria templates/commands/specify.md249-254:

• "Users can complete checkout in under 3 minutes"
• "System supports 10,000 concurrent users"
• "95% of searches return results in under 1 second"
• "Task completion rate improves by 40%"

Invalid success criteria (implementation details leaked) templates/commands/specify.md256-261:

Invalid Criterion	Why Invalid	Correct Version
"API response time is under 200ms"	Mentions API (implementation)	"Users see results instantly"
"Database can handle 1000 TPS"	Mentions database (technology)	"System processes 1000 transactions per second"
"React components render efficiently"	Mentions React (framework)	"UI updates appear instant to users"
"Redis cache hit rate above 80%"	Mentions Redis (technology)	"Data retrieval completes in under 100ms"

Validation enforcement: The checklists/requirements.md item "Success criteria are technology-agnostic (no implementation details)" templates/commands/specify.md125 enforces these rules during validation.

Sources: templates/commands/specify.md240-261

---

Command Handoffs

The command defines handoffs to subsequent workflow commands through YAML frontmatter in templates/commands/specify.md templates/commands/specify.md3-10

YAML Frontmatter Definition

Handoff Flow

Handoff Configuration

Handoff	Command	Label	Prompt Template	send Flag	Next File Operations
1	/speckit.clarify	"Clarify Spec Requirements"	"Clarify specification requirements"	true	Updates spec.md, replaces [NEEDS CLARIFICATION]
2	/speckit.plan	"Build Technical Plan"	"Create a plan for the spec. I am building with..."	false	Creates plan.md, data-model.md, contracts/

Handoff 1 (send: true): Agent automatically includes spec.md content when invoking /speckit.clarify templates/commands/specify.md10 User does not need to manually provide context.

Handoff 2 (user-initiated): User must provide tech stack details. Agent reads spec.md and memory/constitution.md to generate technical artifacts templates/commands/specify.md4-6

Sources: templates/commands/specify.md3-10

---

Script Output and JSON Parsing

The command relies on JSON output from .specify/scripts/bash/create-new-feature.sh or .specify/scripts/powershell/create-new-feature.ps1 to obtain branch and file paths templates/commands/specify.md69-71

Expected JSON Structure

The scripts output JSON to stdout with these keys:

JSON Output Contract

Key	Type	Example Value	Purpose
BRANCH_NAME	string	"001-user-auth"	Git branch created/checked out
SPEC_FILE	string	".specify/specs/001-user-auth/spec.md"	Path to specification file for AI to write
FEATURE_DIR	string	".specify/specs/001-user-auth"	Feature directory for checklists, artifacts

Parsing and Usage

Bash script invocation and parsing:

PowerShell script invocation and parsing:

Critical parsing requirements templates/commands/specify.md69-71:

1. JSON is provided in terminal output - AI agent must parse stdout, not assume values
2. Always use parsed values - Do not construct paths manually
3. Single execution guarantee - Parse JSON from single script run, never re-run script

Sources: templates/commands/specify.md69-72

---

Section Requirements and Template Structure

Mandatory vs Optional Sections

Section handling rules templates/commands/specify.md208-212:

• Mandatory sections: Must be completed for every feature
• Optional sections: Include only when relevant to the feature
• When a section doesn't apply, remove it entirely (don't leave as "N/A")

Common Sections from spec-template.md

Based on the execution flow, the template includes these sections templates/commands/specify.md73 templates/commands/specify.md89-98:

Section	Content	Required
User Scenarios & Testing	User flows and acceptance scenarios	Yes
Functional Requirements	Testable, unambiguous requirements	Yes
Success Criteria	Measurable, technology-agnostic outcomes	Yes
Key Entities	Data objects and relationships	If data involved
Assumptions	Documented defaults and context	When guesses made
Dependencies	External systems and constraints	If applicable
Scope Boundaries	What's included/excluded	Yes

Sources: templates/commands/specify.md89-98 templates/commands/specify.md208-212

---

Completion Report

After execution, the command outputs a structured completion report templates/commands/specify.md196

Report Structure

Component	Example Value	Data Source
Branch name	004-user-auth	JSON key BRANCH_NAME from script stdout
Spec file path	.specify/specs/004-user-auth/spec.md	JSON key SPEC_FILE from script stdout
Checklist path	.specify/specs/004-user-auth/checklists/requirements.md	Generated by validation step
Checklist pass/fail	"✓ 14/16 items passed"	Validation iteration output
Next command recommendation	"Ready for /speckit.clarify" or "Ready for /speckit.plan"	Based on [NEEDS CLARIFICATION] presence

Example Output

✓ Feature specification created successfully

Branch: 004-user-auth
Spec file: .specify/specs/004-user-auth/spec.md
Checklist: .specify/specs/004-user-auth/checklists/requirements.md

Quality Validation:
  ✓ Content Quality: 4/4 items passed
  ✓ Requirement Completeness: 6/8 items passed (2 [NEEDS CLARIFICATION] remain)
  ✓ Feature Readiness: 4/4 items passed
  
Status: Ready for /speckit.clarify (2 clarification markers remain)

Next steps:
  1. Run /speckit.clarify to resolve specification questions
  2. Or run /speckit.plan with tech stack details to proceed directly

Readiness Logic

Next command selection:

• [NEEDS CLARIFICATION] markers present → Recommend /speckit.clarify
• No markers, all checklist items pass → Recommend /speckit.plan
• No markers, checklist failures after 3 iterations → Warn user, recommend manual review

Sources: templates/commands/specify.md196 templates/commands/specify.md148-157

---

Integration with Project Structure

Directory Structure Created

The /speckit.specify command creates this directory structure within .specify/:

.specify/
├── specs/
│   └── NNN-short-name/                    # Created by create-new-feature.{sh,ps1}
│       ├── spec.md                        # Populated from templates/spec-template.md
│       └── checklists/                    # Created during quality validation
│           └── requirements.md            # Generated by validation step
├── templates/
│   └── spec-template.md                   # Loaded as structure reference
└── scripts/
    ├── bash/
    │   └── create-new-feature.sh          # Invoked for bash environments
    └── powershell/
        └── create-new-feature.ps1         # Invoked for PowerShell environments

Git Branch Structure

File Creation Timeline

Step	File/Branch Created	Created By	Purpose
1	NNN-short-name branch	create-new-feature.{sh,ps1}	Isolate feature work
2	.specify/specs/NNN-short-name/	create-new-feature.{sh,ps1}	Feature artifact directory
3	.specify/specs/NNN-short-name/spec.md	AI agent via template	Specification document
4	.specify/specs/NNN-short-name/checklists/	AI agent	Validation checklist directory
5	.specify/specs/NNN-short-name/checklists/requirements.md	AI agent	Quality validation checklist

Sources: templates/commands/specify.md11-13 templates/commands/specify.md59-71 templates/commands/specify.md105-107 README.md440-459

---

Error Handling

The command implements validation gates at key decision points:

Error conditions templates/commands/specify.md78-79 templates/commands/specify.md90-91:

Error	Trigger Condition	Resolution
"No feature description provided"	Empty user input after command	User must provide feature description
"Cannot determine user scenarios"	No clear user flow extractable from description	User must provide more context about user interactions

Validation failures templates/commands/specify.md150-157:

• Non-clarification issues: Update spec (max 3 iterations)
• After 3 iterations: Document remaining issues in checklist notes and warn user
• Clarification markers: Present questions, wait for answers, update spec

Sources: templates/commands/specify.md78-91 templates/commands/specify.md150-157