# 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)
```bash
uv tool install spec-craft
```

### Using pipx
```bash
pipx install spec-craft
```

### From Source (for development)
```bash
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`:

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

### Claude Desktop
Add to `claude_desktop_config.json`:

```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:

```json
{
  "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)=
### 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):

```bash
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`:

```yaml
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:

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

## Spec-Kit Installation

[Spec-Kit](https://github.com/github/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

```bash
# 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:

```bash
# 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](#aider) above to load the generated skill files.
:::