ai-engineering-cookbook

Installation and Setup Guide

This guide walks you through setting up the AI-Native SDLC environment on your machine. We will set up Spec-Kit for planning and Superpowers for execution.

🛠 Prerequisites

Before installing the tools, make sure you have the following installed on your system:

📦 Step-by-step Installation

1. Install uv (Fast Python Package Manager)

Spec-Kit is distributed as a Python package. We recommend using uv to manage Python CLI tools because it is significantly faster and more isolated than standard pip.

# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Verify that uv is installed:

uv --version
# Expected: uv x.y.z

[!NOTE] Windows users: After installing uv, close and reopen your terminal before running uv --version. To reload the PATH without restarting, run:

$env:PATH = [System.Environment]::GetEnvironmentVariable("PATH","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("PATH","User")

2. Install Spec-Kit

Use uv to install the Spec-Kit CLI tool globally. This ensures that the CLI and its dependencies are placed in an isolated, dedicated environment.

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

Verify that Spec-Kit is installed:

specify --version
# Expected: specify-cli x.y.z

3. Install Superpowers

Superpowers is installed directly inside your AI coding agent (e.g. Claude Code, Cursor, Gemini CLI).

graph TD
    A[Choose AI Agent] --> B(Claude Code)
    A --> C(Cursor)
    A --> D(Gemini CLI)
    A --> E(Codex CLI)

    B --> F["/plugin install superpowers@claude-plugins-official"]
    C --> G["/add-plugin superpowers"]
    D --> H["gemini extensions install https://github.com/obra/superpowers"]
    E --> I["Use /plugins -> Search 'superpowers' -> Click Install"]

[!IMPORTANT] Command accuracy: Plugin install commands change as agents evolve. If the command above fails for your agent, check the official Superpowers repository for the latest install instructions for your specific agent version.

Verifying Superpowers Installation

After installing, type the following in your agent’s chat interface to confirm it’s active:

/sp-status

If Superpowers is installed correctly, you will see a list of available skills including using-git-worktrees, test-driven-development, and requesting-code-review.

🚀 Initializing Your Project

Once the tools are installed globally, you must initialize Spec-Kit in your project root directory.

Scenario A: Greenfield Project (From Scratch)

If you are starting a completely new project in a blank directory, run:

mkdir my-new-project
cd my-new-project
specify init . --integration claude

[!NOTE] Change --integration claude to matches your target agent (e.g. gemini, copilot, cursor).

Scenario B: Brownfield Project (Existing Codebase)

If you are adding AI-assisted workflows to an existing project, navigate to the project directory and run:

cd my-existing-project
specify init . --force --integration claude

[!IMPORTANT] The --force flag is safe to use. It only creates the .specify/ directory structure and does not modify or delete any of your existing source files.

🔍 Verifying the Directory Structure

After initialization, you should see a new .specify/ folder in your project root containing:

your-project/
└── .specify/
    ├── memory/
    │   └── constitution.md        # [Editable] Project principles & stack rules
    ├── specs/                     # Contains individual feature specs
    ├── templates/                 # Custom formatting templates
    └── scripts/                   # Integration bash/PowerShell scripts

If these files are present, you are successfully set up and ready to create your first specification!

📖 Next Steps

This site is open source. Improve this page.