Spec Kitty: spec-driven development for AI coding agents

The problem Spec Kitty addresses: agent sessions that forget

A coding agent starts a session, writes code, and the session ends. The requirements it was working from live in a chat log. The acceptance criteria live in someone's head. The next agent, or the next developer, starts from the code and guesses at the intent behind it. Spec Kitty's README frames this as "AI coding sessions are losing requirements, decisions, or acceptance criteria," and the project's answer is to move all of that into the repository itself.

The intended user is a team, not an individual doing a quick edit. The README says it is "probably overkill for one-off edits, tiny scripts, or teams that do not use Git." That is an unusually direct statement of scope for a project README, and it is worth taking at face value. Spec Kitty assumes Git is the substrate, that work is split across more than one unit, and that someone other than the author will review the result.

The workflow it targets is what the README calls a "governed software factory": repeatable inputs, clear work-package boundaries, isolated execution, visible progress, and review gates. The stated goal is not better prompts. It is a durable operating system for agentic coding where the repository stays the source of truth.

How the spec, plan, task and worktree pipeline fits together

The core loop is printed in the README as a pipeline: spec, plan, tasks, next, review, accept, merge. Each stage is a command, and each stage writes artifacts into the repository rather than into an agent's context window.

Mission artifacts live under kitty-specs/. Work packages move through lifecycle lanes named planned, in_progress, for_review, approved, and done. Those lane names are the vocabulary the dashboard and the review commands operate on, so a work package is a stateful object, not a paragraph of prose.

Parallelism comes from git worktrees under .worktrees/. The README describes giving agents "isolated git worktrees so implementation can happen in parallel without branch chaos." This is the mechanism that makes multi-agent work tractable: two agents editing the same checkout will collide, while two agents in separate worktrees will not, and the merge decision becomes an explicit step rather than an accident.

The runtime is queried with spec-kitty next, which the README describes as asking Spec Kitty what the agent should do next. There is also a governance command, spec-kitty dispatch, which the README says "loads governance context, opens an Op record, and returns the context the agent must use before doing the work." The repository's own docs directory holds a trail model document describing how operator intent maps to runtime behavior, and a host-surface-parity document tracking parity across CLI, slash-command and hosted surfaces. Those are architecture documents, not tutorials, and the README does not summarize their contents.

Installing Spec Kitty and running a first mission

The README recommends pipx because it keeps the CLI in its own virtual environment and avoids the externally-managed-environment errors common on modern Linux distributions. The package name on PyPI is spec-kitty-cli, while the command is spec-kitty.

pipx install spec-kitty-cli

Two other install methods are listed: uv tool install spec-kitty-cli, and python -m pip install spec-kitty-cli inside an activated virtual environment. Python 3.11 or newer is required according to the project metadata in pyproject.toml.

Next, initialize a project and check the wiring. The --ai flag takes an agent key; the README lists claude, codex, cursor, gemini, copilot, opencode, qwen, windsurf, kiro, vibe, pi, and letta as common choices, and points to a supported-agents document for the current list.

spec-kitty init my-project --ai claude
cd my-project
spec-kitty verify-setup

With the project initialized, open your agent in that directory and drive the workflow through slash commands. The README's example starts with a charter, then a specification, then a plan, then tasks:

/spec-kitty.charter
/spec-kitty.specify Build a small task list app.
/spec-kitty.plan
/spec-kitty.tasks

From there the runtime decides the next action until the mission is ready. The mission slug is passed explicitly:

spec-kitty next --agent claude --mission <mission-slug>

Review, accept and merge close the loop with /spec-kitty.review, /spec-kitty.accept and /spec-kitty.merge --push. After the merge, the README says to run /spec-kitty-mission-review, and notes that the mission's retrospective.yaml is authored during the runtime terminus rather than by merge. Cross-mission views come from spec-kitty retrospect summary, and staged proposals are applied with spec-kitty agent retrospect synthesize --mission <mission-slug>, which is a dry run unless --apply is passed. For a local view of progress, spec-kitty dashboard opens the kanban dashboard. For a full walkthrough the README points at a Your First Mission tutorial.

Where Spec Kitty gets in the way

The strongest limitation is stated by the project itself: this is not a lights-out black box. The README says humans define intent, architecture and acceptance criteria, and that the tool "is deliberately not a lights-out black box by default." Anyone hoping to hand a product idea to an agent and walk away is buying the wrong tool. The review, accept and merge gates exist precisely because a human is expected to be at them.

The Git dependency is absolute. Worktrees, repository-native artifacts, review state and merge decisions all assume Git. A team without Git gets nothing from the worktree isolation that is the project's main multi-agent story.

There is a second, quieter cost: the workflow has a fixed vocabulary. Work packages, lanes, missions, charters, retrospectives. Adopting Spec Kitty means adopting that model for how work is described. A team that already has a working issue tracker and a review process will be maintaining two descriptions of the same work unless the two are connected, and the README only mentions "optional hosted tracker and sync integrations later" without describing them.

Finally, the project metadata classifies the release as Development Status 4 - Beta, and pyproject.toml carries a 4.0.0rc3 version string while the most recent published releases are 3.2.7, 3.2.6.2 and 3.2.6.1. The README does not document rollback, and it does not describe what happens to existing kitty-specs/ artifacts if a mission is abandoned midway. Treat the artifact format as something to inspect before you depend on it.

Spec Kit, OpenSpec and plain prompt files compared

The comparison people actually search for is Spec Kitty versus Spec Kit, and the honest difference is scope. Spec Kit style workflows center on a specification and plan that an agent consumes. Spec Kitty adds the surrounding machinery: work packages with lifecycle lanes, isolated git worktrees under .worktrees/, review and accept gates, a kanban dashboard, and a retrospective generated per completed mission. If you only want a structured prompt before coding, the extra machinery is overhead you will pay for on every mission.

Against dropping markdown files into a docs/ directory, the difference is enforcement. Plain files have no lifecycle. A work package in Spec Kitty carries a lane, so the question "what is waiting for review" has a mechanical answer that spec-kitty dashboard and spec-kitty next can act on. The cost is that the files must conform to the tool's expectations, and the README does not describe a migration path for hand-written specifications.

Against a general-purpose agent orchestrator, the difference is where state lives. Spec Kitty's state is in the repository, which means it travels with a clone, appears in code review, and survives a wiped agent session. That is the trade the project is making, and it is the reason the Git requirement is not negotiable.

Maintenance, licensing and upgrade cost

Spec Kitty is MIT licensed, with the licence file referenced from pyproject.toml. MIT is permissive: it allows commercial use and modification, and it comes with no warranty. That is a statement about the licence text, not advice about your situation, and teams with unusual distribution requirements should read the LICENSE file directly rather than rely on a summary.

The repository is not archived and the last push was on 2026-09-10, with releases 3.2.7 on 2026-09-09, 3.2.6.2 on 2026-09-09 and 3.2.6.1 on 2026-09-08. That is a tight release cadence, and it is also the upgrade cost: the README lists spec-kitty upgrade as the command that updates an existing project after upgrading the CLI. Because specs, plans and work packages live in your repository, a CLI upgrade can imply a project upgrade, and you should expect to run that command rather than assume compatibility.

The dependency surface is not trivial. pyproject.toml pins an upper bound on typer with a comment citing an issue number and describing vendored click eras across versions, which is the kind of constraint that appears when a project tracks a moving CLI framework closely. The Makefile exposes dev-setup, lint, format-check, typecheck, test-fast and test-full targets, and notes that test-fast is a baseline rather than a substitute for running the tests of the modules a diff touches. If you plan to contribute rather than just consume, that is the real entry cost.

Editorial conclusion

Adopt Spec Kitty if you already run one or more coding agents against a Git repository and keep losing requirements, acceptance criteria or merge state between sessions. Skip it for one-off edits, tiny scripts, or any team that does not use Git, since the whole model is repository-native. Before committing, run spec-kitty init on a throwaway repository, confirm spec-kitty verify-setup passes for your agent key, and check that .worktrees/ and kitty-specs/ land where your .gitignore and CI expect them.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. spec-kitty/spec-kitty on GitHub