Getting Started with Spec Kitty
Who is this for (1)
- Stakeholder Persona: Project Owner — Written for the Project Owner reader.
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.)

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:
pipx install --pip-args=--pre spec-kitty-clipipx 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
consolidatecommand. The pre-release flag in each install command on this page (--pip-args=--prefor pipx,--prerelease=allowfor uv,--prefor pip) installs the latest 4.x release candidate.
Other supported install methods:
uv tool install --prerelease=allow spec-kitty-cli# Inside an activated virtual environmentpython -m pip install --pre spec-kitty-cliVerify the CLI is available:
spec-kitty --versionExpected output (abridged):
spec-kitty-cli version 4.0.0rc8If 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:
spec-kitty init my-spec-project --ai claudecd my-spec-projectgit init -b maingit add -A && git commit -m "Initial commit"git checkout -b my-first-missionExpected output (abridged):
OK Initialized Spec Kitty projectOK Created .kittify/ scaffoldStep 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 exampletask-list-01M20JM4. The trailing token is the mission’s own identifier, so yours will differ. spec.mdinside 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 initialspec.mdscaffold alone is not ready for planning.
Step 4: Verify Your Work
Confirm the mission directory exists:
ls kitty-specsExample output (your identifier will differ):
task-list-01M20JM4If the command created a new worktree later in the workflow, it will appear here:
ls .worktreesTroubleshooting
spec-kitty: command not found: Reopen your shell, runpipx ensurepathif you installed withpipx, or reinstall viapipxoruv. Then rerunspec-kitty --version.pip installfails withexternally-managed-environment: Usepipx install --pip-args=--pre spec-kitty-cli, or create and activate a virtual environment before usingpython -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 runspecifyagain. SPEC_KITTY_REPO_NOT_INITIALIZEDfromspecify: the project directory is not a git repository. Rungit init -b main, thengit add -A && git commit -m "Initial commit", and retry.spec-kitty initdoes 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"(orgit commit --allow-empty -m "Initial commit"if there is nothing to stage) and retry. - No
/spec-kitty.specifycommand available: Re-runspec-kitty init . --ai <your-agent>from the project root, then verify the setup withspec-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.
Related How-To Guides
- Install and Upgrade - Additional installation options
- Create a Specification - Deep dive into
/spec-kitty.specify - Non-Interactive Init - Scripted project setup
Reference Documentation
- CLI Commands - Full command reference
- Slash Commands - AI agent slash commands
- Supported Agents - Slash-command agents supported by the CLI
Learn More
- Spec-Driven Development - Why specs matter
- Mission System - How missions shape workflows