Skip to main content
The /speckit.specify command transforms natural language feature descriptions into structured, implementation-ready specifications.

​
Purpose

Generate complete feature specifications that:
  • Focus on what users need and why (not implementation details)
  • Organize requirements by user journeys with clear priorities
  • Include measurable success criteria
  • Identify gaps and ambiguities for clarification
  • Create numbered feature branches automatically
Specifications are technology-agnostic and written for business stakeholders, not developers. No code, frameworks, or implementation details.

​
Usage

# Create a new feature specification
/speckit.specify Add user authentication with OAuth2 support

# More complex feature
/speckit.specify Build a dashboard showing real-time analytics with filtering by date range and user segments

# From a detailed description
/speckit.specify I want to add a payment processing feature that supports credit cards and PayPal, handles refunds, and sends email receipts to customers

​
How It Works

1

Generate Short Name

Analyzes your description and creates a 2-4 word branch name:
  • “Add user authentication” → user-auth
  • “Build analytics dashboard” → analytics-dashboard
  • “Fix payment timeout bug” → fix-payment-timeout
2

Check Existing Branches

Finds the next available number by checking:
  • Remote branches: git ls-remote --heads origin
  • Local branches: git branch
  • Specs directories: specs/###-*
If user-auth already exists as 002-user-auth, creates 003-user-auth
3

Create Branch and Structure

Runs initialization script to:
  • Create branch ###-feature-name
  • Create directory specs/###-feature-name/
  • Initialize spec.md from template
  • Check out the new branch
4

Generate Specification

Fills the spec template with:
  • User stories organized by priority (P1, P2, P3)
  • Functional requirements (testable, unambiguous)
  • Success criteria (measurable, technology-agnostic)
  • Key entities (if data is involved)
  • Edge cases
  • Assumptions for reasonable defaults
  • [NEEDS CLARIFICATION] markers (max 3) for critical unknowns
5

Validate Quality

Creates checklists/requirements.md and validates:
  • No implementation details leaked
  • All requirements are testable
  • Success criteria are measurable
  • Acceptance scenarios defined
  • No more than 3 clarification markers
6

Handle Clarifications (if needed)

If [NEEDS CLARIFICATION] markers exist:
  • Present each as a multiple-choice question with implications
  • Wait for user responses
  • Update spec with selected answers
  • Re-validate quality

​
Specification Structure

​
Metadata

# Feature Specification: User Authentication

**Feature Branch**: `003-user-auth`  
**Created**: 2024-03-15  
**Status**: Draft

​
User Scenarios & Testing

The core of every spec - user journeys ordered by priority: 
### User Story 1 - Basic Login (Priority: P1)

Users can log in with email and password to access protected features.

**Why this priority**: This is the MVP - without login, no other auth features matter.

**Independent Test**: Can be fully tested by creating an account, logging in, and accessing a protected page. Delivers immediate value by protecting sensitive features.

**Acceptance Scenarios**:

1. **Given** a user with valid credentials, **When** they enter email and password, **Then** they are redirected to the dashboard
2. **Given** a user with invalid credentials, **When** they attempt login, **Then** they see a clear error message and remain on login page
3. **Given** a user has been inactive for 30 minutes, **When** they attempt any action, **Then** they are redirected to login

​
Edge Cases

### Edge Cases

- What happens when email service is down during password reset?
- How does the system handle concurrent login attempts from different locations?
- What happens if OAuth provider revokes access mid-session?
- How are accounts handled when user changes their email at the OAuth provider?

​
Requirements

### Functional Requirements

- **FR-001**: System MUST securely hash passwords using bcrypt or Argon2
- **FR-002**: System MUST enforce password requirements: minimum 12 characters, mix of letters/numbers/symbols
- **FR-003**: System MUST lock accounts after 5 failed login attempts for 15 minutes
- **FR-004**: System MUST expire password reset tokens after 1 hour
- **FR-005**: System MUST generate secure session tokens with 24-hour expiration
- **FR-006**: System MUST support OAuth2 authorization code flow with PKCE
- **FR-007**: System MUST revoke all user sessions when password is changed

​
Success Criteria

Measurable, technology-agnostic outcomes: 
## Success Criteria

### Measurable Outcomes

- **SC-001**: Users can complete login in under 5 seconds
- **SC-002**: Password reset emails arrive within 1 minute
- **SC-003**: System handles 1,000 concurrent login attempts without degradation
- **SC-004**: 95% of users successfully log in on first attempt (excluding forgotten passwords)
- **SC-005**: Password reset flow completes in under 2 minutes from request to new login
- **SC-006**: OAuth login completes in under 10 seconds
- **SC-007**: Zero plaintext passwords stored anywhere in the system

​
Clarification Workflow

If the AI identifies critical ambiguities, it marks them and asks questions: 
### Functional Requirements

- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password only, OAuth2 only, or both?]

​
Clarification Limits

Maximum 3 [NEEDS CLARIFICATION] markers allowed. The AI makes informed guesses for most details and only asks about decisions that significantly impact scope, security, or UX.

​
Validation Checklist

The command automatically generates checklists/requirements.md: 
# Specification Quality Checklist: User Authentication

**Purpose**: Validate specification completeness before planning
**Created**: 2024-03-15
**Feature**: [Link to spec.md]

## Content Quality

- [ ] No implementation details (languages, frameworks, APIs)
- [ ] Focused on user value and business needs
- [ ] Written for non-technical stakeholders
- [ ] All mandatory sections completed

## Requirement Completeness

- [ ] No [NEEDS CLARIFICATION] markers remain
- [ ] Requirements are testable and unambiguous
- [ ] Success criteria are measurable
- [ ] Success criteria are technology-agnostic
- [ ] All acceptance scenarios defined
- [ ] Edge cases identified
- [ ] Scope is clearly bounded

## Feature Readiness

- [ ] All functional requirements have clear acceptance criteria
- [ ] User scenarios cover primary flows
- [ ] Feature meets measurable outcomes
- [ ] No implementation details leak into specification

​
Real-World Example

/speckit.specify Add a RESTful API for managing tasks with CRUD operations, filtering by status and priority, and user assignment

​
Best Practices

​
Write User-Focused Descriptions

/speckit.specify Users can export their data to CSV format for backup and analysis

​
Trust the AI for Defaults

The AI makes reasonable assumptions:
  • Data retention: Industry-standard practices
  • Performance: Standard web app expectations
  • Error handling: User-friendly messages
  • Auth patterns: OAuth2 for web services, session-based for traditional apps
Only specify these if your requirements differ significantly from standards.

​
Prioritize User Stories Thoughtfully

  • P1: Minimum viable product - delivers core value independently
  • P2: Enhances UX but system works without it
  • P3: Nice-to-have features for polish
Each priority should be independently testable and deployable.

​
Common Patterns

​
Web Services

/speckit.specify Create a RESTful API for user management with CRUD operations, pagination, and search
Generates:
  • User stories for each operation (Create, Read, Update, Delete)
  • Pagination requirements
  • Search/filter capabilities
  • Success criteria for response times
  • API versioning assumptions

​
CLI Tools

/speckit.specify Build a command-line tool for deploying applications with configuration validation and rollback support
Generates:
  • User stories for deploy, validate, rollback
  • CLI argument requirements
  • Output formatting expectations
  • Success criteria for execution time

​
UI Features

/speckit.specify Add a dashboard showing real-time metrics with customizable widgets and export capabilities
Generates:
  • User stories for viewing, customizing, exporting
  • Widget type requirements
  • Real-time update expectations
  • Success criteria for load times

​
Handoffs

After specification is complete:

Clarify Requirements

Resolve ambiguities with targeted questions (if [NEEDS CLARIFICATION] markers exist)

Build Technical Plan

Generate architecture and design decisions (skip clarify if spec is clear)

​
File Structure

specs/003-task-api/
├── spec.md                    # Feature specification (this command)
└── checklists/
    └── requirements.md        # Quality validation checklist

​
Next Steps

Clarify

Learn how to resolve specification ambiguities

Build docs developers (and LLMs) love

Get started for freeTalk to us