Skip to content

Getting Started with Spec Kitty

Who is this for (1)

Divio type: Tutorial

In this tutorial, you’ll install Spec Kitty and create your first mission specification.

Time: ~30 minutes Prerequisites: Python 3.11+, Git, an AI coding agent (Claude Code, Cursor, Gemini CLI, etc.)

Getting started with Spec Kitty - Mission Kitty hero

Stylized splash — the “GET STARTED” lettering is decorative. Install steps and the rest of this tutorial are in the text below; for a dedicated install guide see Install Spec Kitty.

Step 1: Install Spec Kitty

Install the CLI with pipx:

Terminal window
pipx install --pip-args=--pre spec-kitty-cli

pipx is preferred for command-line tools because it creates an isolated virtual environment for Spec Kitty and avoids the externally-managed-environment errors that modern Linux distributions can raise for direct pip install commands.

4.x is in release candidate. Until 4.0.0 is released, a plain install gets the latest stable 3.x release, which has no consolidate command. The pre-release flag in each install command on this page (--pip-args=--pre for pipx, --prerelease=allow for uv, --pre for pip) installs the latest 4.x release candidate.

Other supported install methods:

Terminal window
uv tool install --prerelease=allow spec-kitty-cli
Terminal window
# Inside an activated virtual environment
python -m pip install --pre spec-kitty-cli

Verify the CLI is available:

Terminal window
spec-kitty --version

Expected output (abridged):

spec-kitty-cli version 4.0.0rc8

If this step gives you trouble — a platform not covered above, an externally-managed-environment error, or a Git credential prompt on Linux — the installation guide has the full per-platform instructions and troubleshooting.

Step 2: Initialize a Project

Create a new project directory with the agent you plan to use, then put it under git:

Terminal window
spec-kitty init my-spec-project --ai claude
cd my-spec-project
git init -b main
git add -A && git commit -m "Initial commit"
git checkout -b my-first-mission

Expected output (abridged):

OK Initialized Spec Kitty project
OK Created .kittify/ scaffold

Step 3: Create Your First Specification

Open your AI agent in this repository and run the specify command.

In your agent:

/spec-kitty.specify Build a tiny command-line task list app with add, complete, and delete actions.

You’ll be asked a discovery interview. Answer each question until the command completes.

Expected results:

  • One new mission directory under kitty-specs/, named <slug>-<id> — for example task-list-01M20JM4. The trailing token is the mission’s own identifier, so yours will differ.
  • spec.md inside it (the mission spec)
  • Mission creation commits its generated metadata, event log, and task scaffold. Your agent then writes the substantive specification and commits it with spec-kitty spec-commit; the initial spec.md scaffold alone is not ready for planning.

Step 4: Verify Your Work

Confirm the mission directory exists:

Terminal window
ls kitty-specs

Example output (your identifier will differ):

task-list-01M20JM4

If the command created a new worktree later in the workflow, it will appear here:

Terminal window
ls .worktrees

Troubleshooting

  • spec-kitty: command not found: Reopen your shell, run pipx ensurepath if you installed with pipx, or reinstall via pipx or uv. Then rerun spec-kitty --version.
  • pip install fails with externally-managed-environment: Use pipx install --pip-args=--pre spec-kitty-cli, or create and activate a virtual environment before using python -m pip install --pre spec-kitty-cli.
  • Planning artifacts left uncommitted on a protected branch: mission creation can succeed while reporting its uncommitted files. Run git checkout -b my-first-mission, review and commit those files, and continue the existing mission. Do not run specify again.
  • SPEC_KITTY_REPO_NOT_INITIALIZED from specify: the project directory is not a git repository. Run git init -b main, then git add -A && git commit -m "Initial commit", and retry. spec-kitty init does not create the repository for you.
  • “This checkout has no commits yet”: the repository exists but has no commit, so Spec Kitty cannot commit its mission scaffold. Run git add -A && git commit -m "Initial commit" (or git commit --allow-empty -m "Initial commit" if there is nothing to stage) and retry.
  • No /spec-kitty.specify command available: Re-run spec-kitty init . --ai <your-agent> from the project root, then verify the setup with spec-kitty verify-setup --diagnostics.
  • WAITING_FOR_DISCOVERY_INPUT: The command is paused for your answers; provide the requested details and continue.

What’s Next?

Continue with Your First Mission for the complete workflow from specification to merge. It picks up the mission you just created: its Step 1 is only about confirming you have that mission, so start at Step 2 and do not run /spec-kitty.specify again.

Reference Documentation

Learn More