Quick Start

Source Files

This page is generated from the following source files:

• README.md
• docs/installation.md
• docs/quickstart.md
• pyproject.toml
• src/specify_cli/init.py
• src/specify_cli/agents.py
• src/specify_cli/presets.py
• src/specify_cli/extensions.py
• scripts/bash/setup-plan.sh
• scripts/powershell/setup-plan.ps1

Prerequisites

Before installing Spec Kit, ensure the development environment meets the following requirements:

Supported Operating Systems:

• Linux (docs/installation.md:5)
• macOS (docs/installation.md:5)
• Windows (PowerShell scripts supported without WSL) (docs/installation.md:5)

Supported AI Agents:

The toolkit supports a wide range of AI coding agents, including but not limited to:

For a complete list of 25+ supported agents, refer to the Supported AI Agents section in the README.

Installation Methods

Spec Kit offers three installation approaches to accommodate different workflow preferences and enterprise requirements.

Option 1: Persistent Installation (Recommended)

This method installs Specify CLI permanently on the system, making it available globally in PATH.

Install a specific stable release:

bash
1# Replace vX.Y.Z with the latest release tag from https://github.com/github/spec-kit/releases
2uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

(README.md:56)

Install latest from main branch:

bash
1uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

(README.md:59)

Benefits of persistent installation:

• Tool remains installed and available in PATH (README.md:99)
• No need to create shell aliases (README.md:100)
• Better tool management with uv tool list, uv tool upgrade, uv tool uninstall (README.md:101)
• Cleaner shell configuration (README.md:102)

Option 2: One-time Usage

For users who prefer not to install the tool permanently, uvx allows running Specify CLI directly.

Create a new project:

bash
1# Replace vX.Y.Z with the latest release tag
2uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <PROJECT_NAME>

(README.md:89)

Initialize in existing project:

bash
1uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init . --ai claude

(README.md:92)

Alternative syntax for existing projects:

bash
1uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here --ai claude

(README.md:94)

Option 3: Enterprise / Air-Gapped Installation

For environments that block access to PyPI or GitHub, Spec Kit provides an enterprise installation guide. This method uses pip download to create portable, OS-specific wheel bundles on a connected machine for transfer to air-gapped systems (README.md:106).

Refer to the Enterprise / Air-Gapped Installation guide for detailed step-by-step instructions.

Installation Comparison

Quick Start Guide

This section provides the fastest path to get Spec Kit running with a new or existing project.

Step 1: Initialize Project

After installation, initialize Spec Kit in the target project directory.

Create a new project:

bash
1specify init <PROJECT_NAME>

(README.md:66)

Initialize in existing project with Claude:

bash
1specify init . --ai claude

(README.md:69)

Alternative syntax:

bash
1specify init --here --ai claude

(README.md:71)

Step 2: Verify Installation

Run the check command to verify all required tools are installed:

bash
1specify check

(README.md:74)

This command validates:

• Git installation
• All CLI-based agents configured in AGENT_CONFIG (e.g., claude, gemini, code/code-insiders, cursor-agent, windsurf, junie, qwen, opencode, codex, kiro-cli, shai, qodercli, vibe, kimi, iflow, pi) (README.md:215)

Step 3: Launch AI Assistant

Start the AI assistant in the project directory. Most agents expose Spec Kit as /speckit.* slash commands (README.md:110).

Note: Codex CLI in skills mode uses $speckit-* syntax instead of slash commands (README.md:110).

Core Workflow Commands

Spec Kit follows a spec-driven development workflow with six primary commands.

1. Establish Project Principles

Use the /speckit.constitution command to create governing principles and development guidelines:

bash
1/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements

(README.md:115)

This command establishes the project's constitution that guides all subsequent development decisions.

2. Create Specification

Use the /speckit.specify command to describe the desired functionality. Focus on what and why, not the technical implementation:

bash
1/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.

(README.md:123)

3. Create Technical Plan

Use the /speckit.plan command to define the tech stack and architecture:

bash
1/speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.

(README.md:131)

4. Generate Tasks

Use /speckit.tasks to create an actionable task list from the implementation plan:

bash
1/speckit.tasks

(README.md:139)

5. Execute Implementation

Use /speckit.implement to execute all tasks and build the feature:

bash
1/speckit.implement

(README.md:147)

Verification and Testing

Verify Tool Installation

After installation, confirm Specify CLI is properly installed:

bash
1specify check

Expected behavior: The command checks for git and all configured CLI-based agents (README.md:215).

Verify Project Initialization

After running specify init, the project directory should contain the Spec Kit configuration files and agent-specific command files. The exact structure depends on the AI agent selected during initialization.

Upgrade Verification

To upgrade to a newer version:

bash
1uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z

(README.md:80)

For detailed upgrade instructions, refer to the Upgrade Guide (README.md:77).

Troubleshooting

Issue 1: Command Not Found After Installation

Symptoms: Running specify command returns "command not found" error.

Possible Causes:

• The uv tool directory is not in PATH
• Installation did not complete successfully

Solutions:

1. Verify uv is properly installed: uv --version
2. Check if specify-cli is in the tool list: uv tool list
3. Reinstall with force flag: uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z

Issue 2: Agent-Specific Command Not Working

Symptoms: Slash commands like /speckit.constitution are not recognized by the AI agent.

Possible Causes:

• Incorrect AI agent selection during initialization
• Codex CLI requires different syntax

Solutions:

1. Verify the correct --ai flag was used during initialization (README.md:69)
2. For Codex CLI, use --ai-skills flag and $speckit-* syntax instead of slash commands (README.md:184)
3. Re-initialize with correct agent: specify init . --ai <agent-name>

Issue 3: Network/Access Issues in Enterprise Environment

Symptoms: Installation fails due to blocked access to PyPI or GitHub.

Solution: Use the Enterprise / Air-Gapped Installation method which creates portable wheel bundles on a connected machine for transfer (README.md:106).

Issue 4: Version Compatibility Issues

Symptoms: Unexpected behavior after upgrading or using latest main branch.

Possible Causes:

• Using unreleased changes from main branch
• Breaking changes between versions

Solutions:

1. Pin to a specific stable release tag instead of using main branch (README.md:56)
2. Check Releases for the latest stable version
3. Review changelog before upgrading

Issue 5: Python Version Incompatibility

Symptoms: Installation fails with Python version errors.

Solution: Ensure Python 3.11 or higher is installed (docs/installation.md:8). Verify with:

bash
1python --version

Next Steps

After completing the quick start, explore these resources for deeper understanding:

1. Comprehensive Guide: Follow the detailed step-by-step instructions in spec-driven.md (README.md:150)

2. Video Overview: Watch the video overview to see Spec Kit in action (README.md:154)

3. Community Walkthroughs: Explore real-world examples:

   • Greenfield .NET CLI tool (README.md:162)
   • Greenfield Spring Boot + React platform (README.md:164)
   • Brownfield ASP.NET CMS extension (README.md:166)
   • Brownfield Java runtime extension (README.md:168)
   • Brownfield Go / React dashboard demo (README.md:170)

4. Customization: Learn about Extensions & Presets to customize Spec Kit for specific workflows (README.md:28)

5. CLI Reference: Review the complete Specify CLI command reference for advanced options (README.md:206)