# Spec Kit: Spec-Driven Development Toolkit Spec Kit is a command-line toolkit that enables specification-driven development (SDD), a methodology where natural language specifications become the primary development artifact. Rather than treating documentation as scaffolding for code, Spec Kit inverts the relationship: specifications drive implementation through structured workflows that transform user requirements into concrete features. The toolkit provides slash commands that guide AI coding agents through creating specifications, generating implementation plans, breaking work into tasks, and executing implementations—all while maintaining alignment with project principles and architectural constraints. The system operates on a principle of executable specifications: requirements documents are precise enough to directly generate working code through AI agents. This eliminates the traditional gap between intent and implementation by making specifications the source of truth. Code becomes an expression of the specification rather than the authoritative artifact. The workflow supports both greenfield development (0-to-1) and iterative enhancement (brownfield modernization), enabling teams to explore parallel implementations, experiment with technology stacks, and maintain engineering velocity through requirement changes. ## Specify CLI: Project Initialization Command-line interface for bootstrapping new Spec Kit projects with AI agent configurations and templates. ```bash # Install the CLI tool globally uv tool install specify-cli --from git+https://github.com/github/spec-kit.git # Check current version specify version # Initialize a new project with interactive AI selection specify init my-project # Initialize with a specific AI agent specify init my-project --ai claude specify init my-project --ai gemini specify init my-project --ai copilot specify init my-project --ai cursor-agent specify init my-project --ai qwen specify init my-project --ai opencode specify init my-project --ai codex specify init my-project --ai windsurf specify init my-project --ai kilocode specify init my-project --ai auggie specify init my-project --ai roo specify init my-project --ai codebuddy specify init my-project --ai amp specify init my-project --ai shai specify init my-project --ai bob specify init my-project --ai qoder specify init my-project --ai q # Initialize with PowerShell scripts for Windows specify init my-project --ai copilot --script ps # Initialize in the current directory specify init . --ai claude # or specify init --here --ai claude # Force merge into non-empty directory without confirmation specify init --here --force --ai gemini # Skip git initialization specify init my-project --ai cursor-agent --no-git # Check installed tools and supported agents specify check # Use GitHub token for API requests (corporate environments) specify init my-project --ai claude --github-token ghp_your_token_here # Enable debug output specify init my-project --ai claude --debug ``` ## Supported AI Agents Spec Kit supports a wide range of AI coding assistants across different platforms: | Agent | Type | CLI Tool | Support | |-------|------|----------|---------| | Claude Code | CLI | `claude` | ✅ Full | | Gemini CLI | CLI | `gemini` | ✅ Full | | GitHub Copilot | IDE | N/A (VS Code) | ✅ Full | | Cursor | CLI | `cursor-agent` | ✅ Full | | Qwen Code | CLI | `qwen` | ✅ Full | | opencode | CLI | `opencode` | ✅ Full | | Codex CLI | CLI | `codex` | ✅ Full | | Windsurf | IDE | N/A (Windsurf IDE) | ✅ Full | | Kilo Code | IDE | N/A (Kilo IDE) | ✅ Full | | Auggie CLI | CLI | `auggie` | ✅ Full | | Roo Code | IDE | N/A (Roo IDE) | ✅ Full | | CodeBuddy CLI | CLI | `codebuddy` | ✅ Full | | Amp | CLI | `amp` | ✅ Full | | SHAI (OVHcloud) | CLI | `shai` | ✅ Full | | IBM Bob | IDE | N/A (Bob IDE) | ✅ Full | | Qoder CLI | CLI | `qoder` | ✅ Full | | Amazon Q Developer | CLI | `q` | ⚠️ Partial (no custom args) | | Jules (Google) | IDE | N/A | ✅ Full | ## /speckit.constitution: Establish Project Principles Slash command that creates or updates governing principles and development guidelines for the project with version management and handoff support. ```bash # In your AI coding agent (Claude Code, GitHub Copilot, etc.) /speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements # The command creates/updates memory/constitution.md with versioning # Handoff support: Automatically offers to transition to /speckit.specify # Example output structure: # --- # # Project Constitution # Version: 1.0.0 # Ratification Date: 2025-10-09 # Last Amended: 2025-10-09 # # ## Code Quality Principles # - MUST maintain test coverage above 80% # - MUST use meaningful variable names # - MUST document complex algorithms # # ## Architecture Guidelines # - Prefer composition over inheritance # - Keep functions under 50 lines # - Separate business logic from UI # # ## Testing Standards # - Write unit tests before implementation (TDD) # - Integration tests for all API endpoints # - End-to-end tests for critical user flows # # ## Governance # - Amendment Procedure: Requires team consensus # - Versioning: MAJOR.MINOR.PATCH semantic versioning # - Compliance Reviews: Before each sprint # --- # Version updates follow semantic versioning: # - MAJOR: Backward incompatible governance/principle removals # - MINOR: New principles or expanded guidance # - PATCH: Clarifications, wording fixes # The constitution is referenced during planning to ensure alignment ``` ## /speckit.specify: Create Feature Specifications Transforms natural language feature descriptions into structured specifications with automatic repository management and intelligent branch naming. ```bash # Basic usage - describe what you want to build /speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Within each album, photos are previewed in a tile-like interface. # The command executes scripts/bash/create-new-feature.sh which: # 1. Scans specs/ directory to determine next feature number (001, 002, etc.) # 2. Creates semantic branch name using intelligent filtering: # - Filters out common stop words (I, want, to, the, for, etc.) # - Removes words shorter than 3 characters (except uppercase acronyms) # - Takes 3-4 most meaningful words from description # - Enforces GitHub's 244-byte branch name limit # 3. Creates directory structure: specs/001-photo-albums/ # 4. Copies spec template and fills with requirements # 5. Sets SPECIFY_FEATURE=001-photo-albums environment variable # Example branch naming: # "I want to create user authentication" → 001-create-user-authentication # "Implement OAuth2 integration for API" → 001-implement-oauth2-integration-api # "Fix payment processing bug" → 001-fix-payment-processing # Example script output (JSON format): # { # "BRANCH_NAME": "001-photo-albums", # "SPEC_FILE": "/path/to/repo/specs/001-photo-albums/spec.md", # "FEATURE_NUM": "001" # } # Generated spec.md structure: # --- # # Feature Specification: Photo Album Manager # # **Feature Branch**: `001-photo-albums` # **Created**: 2025-10-09 # **Status**: Draft # # ## User Scenarios & Testing # # ### User Story 1 - Create and Organize Albums (Priority: P1) # Users can create photo albums grouped by date and reorganize them by dragging # # **Why this priority**: Core functionality for basic photo management # **Independent Test**: Create album, add photos, drag to reorder # # **Acceptance Scenarios**: # 1. **Given** no albums exist, **When** user creates new album, **Then** album appears in list # 2. **Given** albums exist, **When** user drags album, **Then** album position updates # # ## Requirements # # ### Functional Requirements # - **FR-001**: System MUST allow users to create photo albums # - **FR-002**: System MUST support drag-and-drop album reordering # - **FR-003**: System MUST display photo previews in tile layout # # ### Key Entities # - **Album**: Collection of photos with metadata (name, date, order) # - **Photo**: Image file with preview thumbnail and metadata # # ## Success Criteria # - **SC-001**: Users can create and organize 100+ albums without performance degradation # - **SC-002**: Photo previews load in under 1 second # --- # For non-Git repositories, set SPECIFY_FEATURE manually: export SPECIFY_FEATURE="001-photo-albums" ``` ## /speckit.clarify: Structured Clarification Workflow Optional command that systematically identifies and resolves underspecified areas before planning. ```bash # Run after /speckit.specify to identify gaps /speckit.clarify # The command analyzes spec.md for: # - [NEEDS CLARIFICATION: ...] markers (max 3 allowed) # - Ambiguous requirements # - Missing edge cases # - Undefined constraints # Example clarification output: # --- # ## Question 1: Photo Storage Location # # **Context**: "System MUST store photos" (spec.md line 45) # **What we need to know**: Where should photos be stored? # # **Suggested Answers**: # | Option | Answer | Implications | # |--------|--------|--------------| # | A | Local filesystem only | Simpler, no cloud costs, limited to device storage | # | B | Cloud storage (S3, etc.) | Scalable, accessible anywhere, requires API integration | # | C | Hybrid (local + cloud) | Best UX, complex sync logic, higher development cost | # | Custom | Your own approach | [Describe your preference] | # # **Your choice**: _[Wait for user response]_ # --- # User responds: "Q1: A, Q2: B, Q3: Custom - Use SQLite for metadata" # Command updates spec.md, replacing [NEEDS CLARIFICATION] markers with answers ``` ## /speckit.plan: Generate Implementation Plan Creates technical implementation plan from feature specification, including architecture, data models, and API contracts. Updates agent-specific context files. ```bash # Specify your tech stack and architecture choices /speckit.plan The application uses Vite with minimal libraries. Use vanilla HTML, CSS, and JavaScript. Images stored locally, metadata in SQLite database. # The command executes scripts/bash/setup-plan.sh which: # 1. Validates feature branch is active (or SPECIFY_FEATURE is set) # 2. Reads specs/001-photo-albums/spec.md # 3. Reads memory/constitution.md for compliance # 4. Copies plan template to specs/001-photo-albums/plan.md # Example script output: # { # "FEATURE_SPEC": "/path/to/specs/001-photo-albums/spec.md", # "IMPL_PLAN": "/path/to/specs/001-photo-albums/plan.md", # "SPECS_DIR": "/path/to/specs/001-photo-albums", # "BRANCH": "001-photo-albums", # "HAS_GIT": "true" # } # Phase 0: Research (research.md) # - Investigates Vite setup, SQLite browser integration # - Documents decisions with rationale # --- # ## Decision: Use sql.js for Browser SQLite # **Rationale**: Compiled to WebAssembly, runs in browser, no server needed # **Alternatives considered**: IndexedDB (less SQL familiarity), LocalStorage (size limits) # --- # Phase 1: Design (data-model.md, contracts/, quickstart.md) # Generated data-model.md: # --- # # Data Model: Photo Album Manager # # ## Entities # # ### Album # - id (INTEGER PRIMARY KEY) # - name (TEXT NOT NULL) # - created_date (TEXT) # - sort_order (INTEGER) # # ### Photo # - id (INTEGER PRIMARY KEY) # - album_id (INTEGER FOREIGN KEY) # - filename (TEXT) # - file_path (TEXT) # - thumbnail_path (TEXT) # --- # Updates agent context files: # - AGENTS.md (all agents) # - CLAUDE.md (Claude Code) # - .github/copilot-instructions.md (Copilot) # - .windsurf/rules/specify-rules.md (Windsurf) # - And other agent-specific files # Uses scripts/bash/update-agent-context.sh to synchronize context ``` ## /speckit.tasks: Generate Task Breakdown Analyzes implementation plan and generates dependency-ordered task list organized by user story. ```bash # After /speckit.plan completes /speckit.tasks # The command executes scripts/bash/check-prerequisites.sh which: # 1. Validates plan.md, spec.md exist # 2. Checks for optional docs (data-model.md, contracts/, research.md) # 3. Extracts user stories with priorities from spec.md # Generated tasks.md structure: # --- # # Task Breakdown: Photo Album Manager # # ## Phase 1: Setup (4 tasks) # - **T001**: Initialize Vite project with TypeScript # - **T002**: Configure sql.js WebAssembly integration # - **T003**: Set up directory structure (src/models, src/services, src/ui) # - **T004**: Create SQLite schema initialization script # # ## Phase 2: Foundational (2 tasks) # - **T005**: Implement database connection manager # - **T006**: Create base error handling utilities # # ## Phase 3: User Story 1 - Create and Organize Albums (Priority: P1) # # **Story Goal**: Users can create albums and reorder them via drag-and-drop # **Independent Test**: Create 3 albums, drag to reorder, verify persistence # # ### Implementation Tasks # - **T007 [Story: US1]**: Create Album model class (src/models/Album.ts) # - **T008 [Story: US1]**: Implement AlbumService CRUD operations (src/services/AlbumService.ts) # - **T009 [Story: US1] [P]**: Create album list UI component (src/ui/AlbumList.ts) # - **T010 [Story: US1] [P]**: Implement drag-and-drop library integration (src/ui/DragDrop.ts) # - **T011 [Story: US1]**: Wire album UI to service layer (src/ui/AlbumList.ts) # - **T012 [Story: US1]**: Persist album order changes to database # # **Checkpoint**: User Story 1 complete - albums can be created and reordered # # ## Dependency Graph # ``` # Setup (T001-T004) → Foundational (T005-T006) # ↓ # User Story 1 (T007-T012) → User Story 2 (T013-T019) # ``` # # ## Parallel Execution Opportunities # - Within US1: T009 (Album UI) and T010 (Drag-drop) can run in parallel [P] # # ## Summary # - Total tasks: 22 # - User Story 1: 6 tasks # - Parallel opportunities: 4 tasks # - Suggested MVP: Phase 1 + Phase 2 + Phase 3 (User Story 1 only) # --- # Task markers: # [P] - Can be executed in parallel with adjacent [P] tasks # [Story: US1] - Belongs to User Story 1 (links back to spec.md) ``` ## /speckit.implement: Execute Implementation Executes the full implementation plan by processing tasks from tasks.md in dependency order with TDD approach. ```bash # After /speckit.tasks completes /speckit.implement # The command executes scripts/bash/check-prerequisites.sh with flags: # --json --require-tasks --include-tasks # Validation checks: # 1. Scans FEATURE_DIR/checklists/ for completion status # 2. Counts checklist items: total vs completed # 3. Creates status table # Example checklist validation output: # | Checklist | Total | Completed | Incomplete | Status | # |----------------|-------|-----------|------------|---------| # | requirements.md| 12 | 12 | 0 | ✓ PASS | # | ux.md | 8 | 7 | 1 | ✗ FAIL | # | security.md | 6 | 6 | 0 | ✓ PASS | # # Status: FAIL - Some checklists incomplete # Prompt: "Some checklists are incomplete. Proceed anyway? (yes/no)" # If all pass or user confirms, execution begins: # Phase 1: Setup (T001-T004) # [T001] Initialize Vite project... # → npm create vite@latest photo-albums -- --template vanilla-ts # → ✓ Project created at /path/to/photo-albums # # [T002] Configure sql.js... # → npm install sql.js # → Created src/db/init.ts with WASM loader # → ✓ SQLite integration ready # Progress tracking: # - Each completed task marked [X] in tasks.md # - Errors halt sequential tasks, report failed parallel tasks # - Checkpoints verify phase completion before proceeding # Final validation: # ✓ All 22 tasks completed # ✓ Tests passing (if TDD approach used) # ✓ Features match spec.md requirements # ✓ Implementation follows plan.md architecture ``` ## /speckit.analyze: Cross-Artifact Consistency Analysis Optional command that validates alignment between specification, plan, and tasks before implementation. ```bash # Run after /speckit.tasks, before /speckit.implement /speckit.analyze # The command reads: # - spec.md (user stories, requirements, success criteria) # - plan.md (technical decisions, architecture) # - tasks.md (implementation tasks) # - data-model.md (entities and relationships) # - contracts/ (API specifications) # - memory/constitution.md (project principles - non-negotiable) # Analysis report structure: # --- # # Consistency Analysis: Photo Album Manager # Generated: 2025-10-09 # # ## Requirement Coverage # # ✓ **FR-001** (Create albums): Covered by T007-T012 # ✓ **FR-002** (Drag-and-drop): Covered by T010, T012 # ✓ **FR-003** (Tile layout): Covered by T013-T019 # # ## User Story Mapping # # ✓ **US1** (Albums): Complete task chain T007-T012 # ✓ **US2** (Photos): Complete task chain T013-T019 # # ## Success Criteria Validation # # ✓ **SC-001** (100+ albums): Addressed in T022 (performance optimization) # ⚠ **SC-002** (1s load time): Not explicitly tested - recommend adding benchmark # # ## Constitution Compliance # # ✓ All principles from constitution v1.0.0 respected # 🔴 **CRITICAL**: Plan violates testing standard (TDD requirement) # Action: Add test tasks before implementation tasks # # ## Issues Found # # 1. **Missing test coverage**: No explicit performance tests for SC-002 # - Recommendation: Add task for performance testing # # Overall Status: ⚠️ WARNING (address constitution violations before implementing) # --- # Constitution conflicts are CRITICAL - must be resolved before implementation ``` ## /speckit.taskstoissues: Convert Tasks to GitHub Issues Optional command that converts existing tasks from tasks.md into actionable, dependency-ordered GitHub issues in the repository. ```bash # After /speckit.tasks completes and you want to track work in GitHub Issues /speckit.taskstoissues # The command executes scripts/bash/check-prerequisites.sh with flags: # --json --require-tasks --include-tasks # Prerequisites: # 1. Repository must have a GitHub remote (git config --get remote.origin.url) # 2. tasks.md must exist in the feature directory # 3. GitHub MCP server must be available for issue creation # The command will: # 1. Validate the repository has a GitHub remote URL # 2. Parse all tasks from tasks.md # 3. Create a GitHub issue for each task with: # - Task description as the issue title # - Task details and dependencies as the issue body # - Appropriate labels based on task type (setup, story, polish) # - Milestone linking to the feature specification # Example output: # --- # Creating GitHub issues for feature: 001-photo-albums # # [T001] Initialize Vite project → Issue #45 created # [T002] Configure sql.js → Issue #46 created # [T003] Set up directory structure → Issue #47 created # ... # [T022] Performance optimization → Issue #66 created # # ✓ 22 issues created successfully # View all issues: https://github.com/your-org/your-repo/issues?q=milestone%3A001-photo-albums # --- # Benefits: # - Track individual tasks as separate GitHub issues # - Enable team collaboration on specific tasks # - Maintain dependency relationships through issue descriptions # - Link all tasks back to the feature specification via milestone # - Support project management workflows (Kanban boards, sprint planning) # IMPORTANT: This command requires the GitHub MCP server integration # Issues will ONLY be created in the repository matching the git remote URL ``` ## /speckit.checklist: Generate Quality Checklists Optional command that creates custom validation checklists for requirements, UX, testing, security, or other concerns. ```bash # Generate checklists after /speckit.plan /speckit.checklist Create checklists for: requirements completeness, UX consistency, test coverage, and security best practices # The command creates FEATURE_DIR/checklists/ with structured validation lists: # Generated checklists/requirements.md: # --- # # Requirements Quality Checklist # # ## Specification Completeness # - [ ] All user stories have acceptance criteria # - [ ] Edge cases documented for each feature # - [ ] Error scenarios identified # - [ ] Success criteria are measurable # - [ ] No [NEEDS CLARIFICATION] markers remain # # ## Requirement Clarity # - [ ] Requirements use "MUST", "SHOULD", "MAY" consistently # - [ ] Each requirement is testable # - [ ] No implementation details in spec # - [ ] Business value clear for each story # --- # Generated checklists/security.md: # --- # # Security Best Practices Checklist # # ## Input Validation # - [ ] Album name length limits enforced # - [ ] File upload type validation (images only) # - [ ] File size limits implemented # - [ ] SQL injection prevention (parameterized queries) # # ## Data Protection # - [ ] Local storage encryption (if sensitive metadata) # - [ ] Secure file path handling (prevent directory traversal) # - [ ] No sensitive data in logs # --- # Check completion before /speckit.implement # Update checklists as implementation progresses # Use as gate criteria for quality assurance ``` ## Workflow Integration: Complete Feature Development End-to-end example demonstrating the full Spec Kit workflow from idea to implementation. ```bash # Step 0: Initialize project specify init task-manager --ai claude cd task-manager # Step 1: Establish project principles # (In Claude Code) /speckit.constitution Create principles focused on simplicity, testability, and user-first design. Prefer native solutions over libraries. Maintain <50ms response time for all user interactions. # Output: memory/constitution.md created with principles # --- # # Project Constitution # Version: 1.0.0 # Ratification Date: 2025-10-09 # Last Amended: 2025-10-09 # # ## Simplicity Principles # - MUST minimize dependencies - use browser native APIs when possible # - MUST avoid over-engineering - implement only what's specified # - MUST keep functions under 30 lines # # ## Testing Standards # - MUST follow TDD approach - tests before implementation # - MUST maintain 90% code coverage minimum # - MUST include integration tests for all user flows # # ## Performance Requirements # - MUST respond to all user interactions within 50ms # - MUST load initially under 2 seconds # - MUST support 1000+ tasks without degradation # --- # Step 2: Create feature specification /speckit.specify Build a task management app where users can create tasks, assign priorities (high/medium/low), set due dates, and mark tasks complete. Tasks should be filterable by priority and due date. Include a dashboard showing task statistics. # Output: Branch 001-task-management created # Output: specs/001-task-management/spec.md generated with: # - User Story 1 (P1): Create and manage tasks # - User Story 2 (P2): Filter and search tasks # - User Story 3 (P3): View statistics dashboard # - Requirements FR-001 through FR-008 # - Success criteria SC-001 through SC-004 # Step 3: Optional clarification (if spec has [NEEDS CLARIFICATION] markers) /speckit.clarify # Output: Interactive questions presented: # Q1: Should tasks support subtasks or remain flat? # Q2: What date format for due dates (calendar picker vs text)? # Q3: Should task statistics update in real-time or on refresh? # User responds: "Q1: A (flat structure), Q2: A (calendar picker), Q3: B (on refresh)" # Output: spec.md updated with clarifications # Step 4: Create implementation plan /speckit.plan Use vanilla JavaScript with Web Components for UI. Store data in IndexedDB. Use Chart.js for statistics visualization. No backend - fully client-side. # Output: specs/001-task-management/ now contains: # - plan.md (tech stack, architecture, component structure) # - research.md (Web Components best practices, IndexedDB patterns) # - data-model.md (Task entity definition) # - contracts/task-api.json (internal API between components and storage) # - quickstart.md (example user flows for testing) # Output: AGENTS.md and agent-specific files updated with tech stack # Step 5: Optional consistency analysis /speckit.analyze # Output: Analysis report shows: # ✓ All requirements covered # ⚠ Missing explicit test for 50ms response time (constitution requirement) # Recommendation: Add performance benchmark tasks # Step 6: Generate task breakdown /speckit.tasks # Output: specs/001-task-management/tasks.md generated with 28 tasks: # - Phase 1: Setup (T001-T004) - Project init, dependencies # - Phase 2: Foundational (T005-T007) - IndexedDB setup, base components # - Phase 3: User Story 1 (T008-T015) - Task CRUD functionality # - Phase 4: User Story 2 (T016-T021) - Filtering and search # - Phase 5: User Story 3 (T022-T025) - Statistics dashboard # - Phase 6: Polish (T026-T028) - Performance, responsive design # Step 7: Optional quality checklists /speckit.checklist Create checklists for requirements, UX, performance, and accessibility # Output: specs/001-task-management/checklists/ created with: # - requirements.md (19 items) # - ux.md (14 items) # - performance.md (8 items) # - accessibility.md (12 items) # Step 8: Optional convert to GitHub issues /speckit.taskstoissues # Output: 28 GitHub issues created in the repository # View: https://github.com/your-org/task-manager/issues?q=milestone%3A001-task-management # Step 9: Execute implementation /speckit.implement # Output: Checklist validation runs first: # | Checklist | Total | Completed | Incomplete | Status | # |-------------------|-------|-----------|------------|---------| # | requirements.md | 19 | 19 | 0 | ✓ PASS | # | ux.md | 14 | 14 | 0 | ✓ PASS | # | performance.md | 8 | 8 | 0 | ✓ PASS | # | accessibility.md | 12 | 12 | 0 | ✓ PASS | # # All checklists pass - proceeding with implementation # Output: Task execution begins: # [T001] Initialize project structure... # → Created index.html, src/main.js, src/styles.css # → ✓ Complete # # [T002] Install dependencies... # → npm install chart.js idb # → ✓ Complete # # ... (26 more tasks execute in dependency order) # # [T028] Final responsive design polish... # → Added mobile breakpoints, touch-friendly targets # → Updated tasks.md: marked [X] # → ✓ Complete # # All 28 tasks completed ✓ # Implementation complete - ready for testing # Step 10: Test the application npm run dev # Open http://localhost:5173 # Verify all user stories work as specified # Step 11: Commit and create PR git add . git commit -m "Implement task management feature (001) - User Story 1: Task CRUD (P1) ✓ - User Story 2: Filtering (P2) ✓ - User Story 3: Statistics (P3) ✓ All requirements (FR-001 to FR-008) implemented All success criteria (SC-001 to SC-004) met Constitution compliance verified" git push origin 001-task-management # Create PR using GitHub CLI gh pr create --title "Feature: Task Management System" --body "$(cat < # Constitution governance fields: # - CONSTITUTION_VERSION: Semantic version # - RATIFICATION_DATE: Original adoption date (ISO format YYYY-MM-DD) # - LAST_AMENDED_DATE: Most recent change date (ISO format YYYY-MM-DD) ``` ### Intelligent Branch Naming The create-new-feature script uses intelligent filtering for branch names: ```bash # Branch naming algorithm: # 1. Filter out common stop words (I, want, to, the, for, a, an, etc.) # 2. Remove words shorter than 3 characters (except uppercase acronyms) # 3. Take 3-4 most meaningful words from description # 4. Enforce GitHub's 244-byte branch name limit with truncation # Examples: # Input: "I want to create user authentication" # Output: 001-create-user-authentication # Input: "Implement OAuth2 integration for API" # Output: 001-implement-oauth2-integration-api # Input: "Fix payment processing bug in checkout flow" # Output: 001-fix-payment-processing # Very long descriptions are automatically truncated at word boundaries # to stay within GitHub's 244-byte limit with warning message # Custom short name support: # scripts/bash/create-new-feature.sh --short-name "user-auth" # Creates: 001-user-auth ``` ## Environment Variables ```bash # SPECIFY_FEATURE: Override feature detection for non-Git repositories # Set to the feature directory name (e.g., 001-photo-albums) # Must be set in the agent context before using /speckit.plan export SPECIFY_FEATURE="001-photo-albums" # GH_TOKEN or GITHUB_TOKEN: GitHub API authentication # Used by specify CLI for template fetching in corporate environments export GITHUB_TOKEN="ghp_your_token_here" specify init my-project --ai claude ``` ## Summary and Integration Patterns Spec Kit transforms software development by making natural language specifications executable through AI-powered workflows. The toolkit provides a structured approach to translating user intent into working code: establish project principles with `/speckit.constitution` (with version management and handoffs), create detailed specifications with `/speckit.specify` (with intelligent branch naming), optionally clarify ambiguities with `/speckit.clarify`, generate technical plans with `/speckit.plan` (with automatic agent context updates), break work into tasks with `/speckit.tasks`, validate consistency with `/speckit.analyze` (including constitution compliance), ensure quality with `/speckit.checklist`, optionally convert tasks to GitHub issues with `/speckit.taskstoissues`, and execute implementation with `/speckit.implement`. Each phase builds on the previous, maintaining traceability from requirements through implementation. The system supports multiple development patterns: greenfield projects start from scratch with full specification-to-code generation; brownfield projects add features to existing codebases through branch-based workflows; exploratory development uses parallel implementations to evaluate technology choices; and iterative enhancement maintains velocity through specification changes that regenerate affected code. Integration with 17+ AI coding agents (Claude Code, GitHub Copilot, Gemini CLI, Cursor, Windsurf, Amp, SHAI, IBM Bob, Qoder, and others) across CLI and IDE platforms enables teams to focus on creative problem-solving while automation handles mechanical translation from intent to implementation. The result is faster development cycles, better alignment between specifications and code, constitution-enforced compliance with project principles, and the ability to maintain engineering velocity through requirement changes and pivots.