Installation and Setup

Prerequisites

Before installing Spec-Craft, ensure you have the following:

Python: Version 3.10 or higher.
Node.js: Required for CAD (JSCAD) builds.
Emacs: Version 29.1 or higher (Recommended for isolated AI editing).
uv: Highly recommended for fast package management.

Installation

The easiest way to install Spec-Craft is using uv or pipx to avoid environment conflicts:

Using uv (Recommended)

uv tool install spec-craft

Using pipx

pipx install spec-craft

From Source (for development)

git clone https://github.com/akuroiwa/spec-craft.git
cd spec-craft
uv sync

AI Agent Configuration

Spec-Craft provides an MCP (Model Context Protocol) server. Configuration depends on your AI agent:

Gemini CLI

Add the following to your .gemini/settings.json:

{
  "mcpServers": {
    "spec-craft": {
      "command": "uv",
      "args": ["run", "spec-craft", "serve"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "spec-craft": {
      "command": "uv",
      "args": ["--directory", "/path/to/spec-craft", "run", "spec-craft", "serve"]
    }
  }
}

Antigravity CLI

For project-specific setup, add the following to .antigravitycli/mcp_config.json inside your workspace:

{
  "mcpServers": {
    "spec-craft": {
      "command": "uv",
      "args": ["run", "spec-craft", "serve"]
    }
  }
}

Ensure .antigravitycli/ is added to your .gitignore to avoid checking in local configurations.

For global configuration across all workspaces, the settings can be placed in ~/.gemini/antigravity-cli/mcp_config.json.

Note

Antigravity CLI has a dedicated --integration agy in spec-kit (or --ai agy in older versions). It generates the necessary skill files directly in the .agents/skills/ directory. Alternatively, because Antigravity natively loads .agents/skills/ as agent skills, installing spec-kit with --integration claude or --integration codex will also work.

Aider

Important

spec-kit does not have a native Aider integration (--integration aider does not exist). Aider also does not support agent skills (.agents/skills/) natively. However, the underlying philosophy of Spec-Kit is simply about “mapping the spec-driven development (SDD) workflow to a format that the active agent understands.”

Aider is a terminal-centric, git-aware command line tool that excels at diff editing and low-token local development. You can achieve full SDD compliance by utilizing one of the following three methods:

1. Direct Markdown Loading (Recommended)

You can instruct Aider to read your active skills and rules directly by passing them with the --read option (or running /read inside the Aider terminal):

aider --read AGENTS.md --read .agents/skills/speckit-plan/SKILL.md

This works because Aider can read any markdown file into its context. The .agents/skills/speckit-*/SKILL.md files generated by spec-kit for other integrations (e.g. Claude, Codex) contain the full SDD workflow instructions that Aider can interpret.

2. spec-kit-mcp Integration (MCP Option)

You can configure Aider as an MCP client by adding spec-kit-mcp to your project-local .aider.conf.yml or global ~/.aider.conf.yml:

mcp-servers:
  - name: spec-kit
    command: uvx
    args:
      - --from
      - git+https://github.com/lsendel/spec-kit-mcp
      - spec-kit-mcp

3. Automatic Convention Loading

Add rules and conventions to your .aider.conf.yml so Aider always has access to the SDD instructions:

read:
  - AGENTS.md
  - .specify/constitution.md

Spec-Kit Installation

Spec-Kit provides the tactical layer (Specify → Plan → Implement) for spec-driven development. Install it to scaffold SDD commands for your AI agent.

Quick Start

# Install from a specific stable release (recommended)
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <PROJECT_NAME>

# Or install latest from main
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

Supported Integrations

Spec-Kit supports many AI agents via the --integration flag:

# Antigravity CLI (generates .agents/skills/)
specify init . --integration agy

# Claude Code (generates .claude/commands/ and .agents/skills/)
specify init . --integration claude

# Gemini CLI (generates .gemini/commands/)
specify init . --integration gemini

# GitHub Copilot (generates .github/prompts/)
specify init . --integration copilot

# Codex (generates .agents/skills/)
specify init . --integration codex

# Generic (bring your own agent)
specify init . --integration generic --integration-options="--commands-dir .myagent/commands/"

Note

For Antigravity CLI users: Use --integration agy (recommended), or fall back to --integration claude / --integration codex. All of these generate .agents/skills/ which Antigravity natively loads as agent skills.

For Aider users: Spec-Kit does not have a native --integration aider. Instead, install with any supported integration (e.g. --integration claude or --integration agy) and use one of the three methods described in the Aider section above to load the generated skill files.