spec-kit

# Spec Kit — Spec-Driven Development Build high-quality software faster using **Spec-Driven Development** (SDD). Specifications become executable artifacts that generate working implementations, not just documentation. **Homepage:** https://github.github.com/spec-kit/ **GitHub:** https://github.com/github/spec-kit --- ## What is Spec-Driven Development? SDD flips traditional software development: | Traditional | Spec-Driven | |-------------|-------------| | Specs are scaffolding → discarded | Specs are **executable** → generate code | | Code is king | **Intent** is king | | One-shot prompts | Multi-step refinement | | Focus on "how" | Focus on "what" and "why" | **Core Philosophy:** - Intent-driven development - Rich specifications with guardrails - Heavy reliance on AI model capabilities - Technology-independent process --- ## Prerequisites - **OS:** Linux, macOS, Windows (PowerShell supported) - **AI Agent:** Claude Code, GitHub Copilot, Gemini CLI, or Codebuddy CLI - **Package Manager:** [uv](https://docs.astral.sh/uv/) - **Python:** 3.11+ - **Git:** Any recent version --- ## Installation & Setup ### Initialize a New Project ```bash # Create new project directory uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME> # Initialize in current directory uvx --from git+https://github.com/github/spec-kit.git specify init . uvx --from git+https://github.com/github/spec-kit.git specify init --here ``` ### Specify AI Agent ```bash # Proactively set AI agent during init uvx --from git+https://github.com/github/spec-kit.git specify init <project> --ai claude uvx --from git+https://github.com/github/spec-kit.git specify init <project> --ai gemini uvx --from git+https://github.com/github/spec-kit.git specify init <project> --ai copilot uvx --from git+https://github.com/github/spec-kit.git specify init <project> --ai codebuddy ``` ### Script Type (Shell vs PowerShell) Auto-selected by OS, or force explicitly: ```bash # Force PowerShell (Windows) uvx --from git+https://github.com/github/spec-kit.git specify init <project> --script ps # Force POSIX shell (Linux/macOS) uvx --from git+https://github.com/github/spec-kit.git specify init <project> --script sh ``` ### Skip Tool Checks ```bash uvx --from git+https://github.com/github/spec-kit.git specify init <project> --ai claude --ignore-agent-tools ``` --- ## The 6-Step Spec-Driven Process ### Step 1: Initialize Run `specify init` to create project structure with templates. ```bash uvx --from git+https://github.com/github/spec-kit.git specify init my-app --ai claude ``` **Creates:** - `.speckit/` directory with configuration - Agent-specific templates - Git repository structure --- ### Step 2: Define Constitution Establish core rules and principles for your project. **Slash Command:** ``` /speckit.constitution This project follows a "Library-First" approach. All features must be implemented as standalone libraries first. We use TDD strictly. We prefer functional programming patterns. ``` **Purpose:** Sets guardrails and organizational principles that all specs must follow. --- ### Step 3: Create Specification Describe **what** you want to build, not **how**. **Slash Command:** ``` /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. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface. ``` **Best Practices:** - Focus on user scenarios and behaviors - Avoid tech stack details (AI picks appropriate tech) - Describe UI/UX in plain language - Include constraints and business rules --- ### Step 4: Refine (Clarify) Identify and resolve ambiguities in your specification. **Slash Command:** ``` /speckit.clarify Focus on security implications and edge cases ``` **What it does:** - Detects vague or ambiguous requirements - Asks clarifying questions - Suggests concrete implementations - Updates spec with resolved details --- ### Step 5: Plan Generate detailed implementation plan from specification. **Slash Command:** ``` /speckit.plan ``` **Output:** - Architecture decisions - File structure - Implementation steps - Testing strategy - Dependencies to install --- ### Step 6: Build Execute the implementation plan. **Slash Command:** ``` /speckit.build ``` **Features:** - Generates code based on spec + plan - Creates files incrementally - Runs tests as specified - Commits progress to Git --- ## Context Awareness: Git Branch-Based Spec Kit automatically detects the active feature based on your current Git branch. **Naming Convention:** ``` 001-feature-name 002-user-authentication 003-photo-album-grid ``` **To switch between specifications:** ```bash git checkout 001-feature-name # Work on feature 1 git checkout 002-user-auth # Work on feature 2 ``` **Context is automatically loaded** when you run Spec Kit commands. --- ## Development Phases ### Phase 1: 0-to-1 (Greenfield) **Focus:** Generate from scratch - Start with high-level requirements - Generate specifications - Plan implementation steps - Build production-ready applications ### Phase 2: Creative Exploration **Focus:** Parallel implementations - Explore diverse solutions - Support multiple technology stacks - Experiment with UX patterns - Compare approaches ### Phase 3: Iterative Enhancement (Brownfield) **Focus:** Modernization - Add features iteratively - Modernize legacy systems - Adapt existing processes - Refactor with specs --- ## All Slash Commands Reference | Command | Purpose | When to Use | |---------|---------|-------------| | `/speckit.constitution` | Define project principles | At project start | | `/speckit.specify` | Create specification | For each new feature | | `/speckit.clarify` | Resolve ambiguities | When spec is vague | | `/speckit.plan` | Generate implementation plan | Before coding | | `/speckit.build` | Execute implementation | After planning | --- ## Enterprise Features ### Organizational Constraints - **Cloud Providers:** Target specific platforms (AWS, Azure, GCP) - **Tech Stacks:** Enforce approved technologies - **Design Systems:** Integrate enterprise UI libraries - **Compliance:** Meet security/regulatory requirements ### Technology Independence Spec Kit works with: - Any programming language - Any framework - Any architecture pattern - Any deployment target --- ## Local Development (Contributing) ### Clone and Setup ```bash git clone https://github.com/github/spec-kit.git cd spec-kit ``` ### Run CLI Directly ```bash # Fastest feedback - no install needed python -m src.specify_cli --help python -m src.specify_cli init demo-project --ai claude --script sh ``` ### Editable Install ```bash uv venv source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1 uv pip install -e . specify --help ``` ### Test From Branch ```bash # Push branch first git push origin your-feature-branch # Test via uvx uvx --from git+https://github.com/github/spec-kit.git@your-feature-branch \ specify init demo-branch-test --script ps ``` --- ## Best Practices ### Specification Writing ✅ **DO:** - Describe user scenarios - Include business rules - Mention constraints - Use plain language - Focus on behavior, not implementation ❌ **DON'T:** - Specify tech stack (let AI choose) - Write implementation details - Use jargon without context - Make assumptions unstated ### Example Good Spec ``` /speckit.specify Build a task management app where: - Users can create projects with color-coded labels - Tasks have priorities (High/Medium/Low) with visual indicators - Drag-and-drop to reorder tasks within a project - Tasks can be assigned to multiple users - Due dates trigger notifications 24h before - Completed tasks archive automatically after 7 days - Mobile-responsive with touch-friendly interactions ``` ### Example Bad Spec ``` /speckit.specify Build a React app with Redux for state management. Use Material-UI for components. Store data in PostgreSQL. ``` --- ## Troubleshooting ### Command Not Found **Problem:** AI agent doesn't recognize `/speckit.*` commands **Solution:** Re-run `specify init` in the project directory ### Wrong Context Loaded **Problem:** Working on wrong specification **Solution:** Check current branch with `git branch` and switch: `git checkout <branch>` ### Script Type Issues **Problem:** PowerShell scripts on macOS or vice versa **Solution:** Force script type: `--script sh` or `--script ps` ### Agent Tool Missing **Problem:** Spec Kit complains about missing AI agent tools **Solution:** Use `--ignore-agent-tools` flag during init --- ## Workflow Examples ### New Feature Workflow ```bash # 1. Create feature branch git checkout -b 004-dark-mode # 2. In AI agent chat: /speckit.specify Add dark mode toggle to the application. System should detect OS preference but allow manual override. Store preference in localStorage. # 3. Clarify ambiguities: /speckit.clarify Focus on accessibility (WCAG contrast) # 4. Generate plan: /speckit.plan # 5. Build: /speckit.build # 6. Commit and PR git add . git commit -m "feat: add dark mode toggle" ``` ### Brownfield Enhancement ```bash # 1. Switch to existing feature git checkout 002-user-auth # 2. Enhance spec: /speckit.specify Add OAuth2 login with Google and GitHub providers # 3. Plan the enhancement: /speckit.plan # 4. Build iteratively: /speckit.build ``` --- ## Resources - **Documentation:** https://github.github.com/spec-kit/ - **GitHub Repo:** https://github.com/github/spec-kit - **Contributing:** https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md - **Support:** https://github.com/github/spec-kit/blob/main/SUPPORT.md --- ## Key Principles Summary 1. **Intent over Implementation** — Describe what, not how 2. **Specifications are Assets** — Treat them as primary deliverables 3. **Multi-step Refinement** — Iterate: Constitute → Specify → Clarify → Plan → Build 4. **Context-Aware** — Git branches maintain feature context 5. **Technology Agnostic** — Process works with any stack --- _Last updated: 2026-02-28_