Spec Kitty: A Repo-Native Workflow Layer for AI Coding Agents
Spec-Driven Development for serious software developers. Spec Coding with with Claude, Cursor, Gemini, Codex. Kanban dashboard, git worktrees, auto-merge and more.
At a glance
- What is it?
- Spec Kitty is an MIT-licensed Python CLI that turns product intent into a spec, plan, task and merge pipeline stored in Git, with isolated git worktrees for parallel agents. It is a governance layer for teams already using coding agents, not a tool for one-off edits.
- Who is it for?
- Adopt Spec Kitty if your repository already holds the requirements and you want them to stay there while several agents work in parallel. Skip it for one-off edits, tiny scripts, or teams that do not use Git, since the README says it is probably overkill for those cases.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem Spec Kitty addresses: intent that evaporates between agent sessions
The README frames the problem in terms of loss. AI coding sessions lose requirements, decisions, or acceptance criteria, and the fix it proposes is to keep specs, plans, work packages, acceptance criteria, review state, and merge decisions inside the repository rather than in prompt history. That is a narrower claim than "make agents write better code". It is about where the durable record lives.
The target user is stated fairly directly: teams running parallel Claude Code, Codex, Cursor, Copilot, Gemini, or Windsurf sessions who need work-package boundaries, and teams moving from what the README calls vibe coding toward a repeatable spec-driven workflow. The project also positions itself against a fully autonomous model. It says it can support dark software factories and autonomous coding experiments, but is deliberately not a lights-out black box by default. Humans define intent, architecture, and acceptance criteria; agents implement inside traceable worktrees; reviewers accept, reject, or merge with an audit trail.
That positioning has a cost. If your work is a one-off edit or a tiny script, the README itself says the tool is probably overkill. The same applies to teams that do not use Git, because the entire artifact model depends on repository storage.
How the workflow is structured: spec, plan, tasks, review, accept, merge
The pipeline is spelled out as a linear sequence: spec, plan, tasks, next, review, accept, merge. The first three stages are guided workflows invoked from inside your coding agent, which is why the README shows them as slash commands rather than shell commands. The agent-facing surface includes /spec-kitty.charter, /spec-kitty.specify, /spec-kitty.plan, /spec-kitty.tasks, /spec-kitty.review, /spec-kitty.accept, and /spec-kitty.merge.
The runtime side is a CLI call, spec-kitty next --agent <agent> --mission <slug>, which the README describes as asking Spec Kitty what the agent should do next. So the loop alternates: the agent proposes or executes, the runtime decides the next action, and the mission advances until it is ready.
Work packages carry lifecycle lanes named planned, in_progress, for_review, approved, and done. Those lanes are the state machine that makes progress visible without reading a chat log. Parallel execution is handled by isolated git worktrees under .worktrees/, and the mission artifacts live under kitty-specs/. That combination is the core architectural bet: the repository is the source of truth, and the agent's working directory is disposable.
The governance layer and the dispatch command
Spec Kitty separates runtime governance from prompt text. The README states that runtime governance lives in the repo instead of being treated as agent-only prompt text, and it points to docs/architecture/trail-model.md for how spec-kitty dispatch "<request>" maps operator intent to runtime behavior. A second document, docs/architecture/host-surface-parity.md, tracks parity across CLI, slash-command, and hosted surfaces.
The standalone governance command is spec-kitty dispatch "<request>". According to the README, it loads governance context, opens an Op record, and returns the context the agent must use before doing the work. The phrase "must use" is the interesting part: the command is not a suggestion mechanism, it is a checkpoint that produces a record before implementation starts.
What the supplied material does not describe is the schema of an Op record, where it is stored, or how it is validated. Anyone evaluating this for a regulated environment should read the trail-model document directly rather than infer the guarantees from the command name.
Installation and the commands you actually type
The preferred installer is pipx, and the README gives a reason: it keeps Spec Kitty in its own virtual environment and avoids the externally-managed-environment errors common on modern Linux distributions. That is a concrete packaging decision, not marketing.
pipx install spec-kitty-cli
Two alternatives are listed. uv tool install spec-kitty-cli, or, inside an activated virtual environment, python -m pip install spec-kitty-cli. Python 3.11+ is required according to the badge in the README.
Project setup is two commands. spec-kitty init my-project --ai claude creates a new project, and spec-kitty init . --ai <agent> adds Spec Kitty to the current repository. The agent key is replaceable; the README lists codex, cursor, gemini, copilot, opencode, qwen, windsurf, kiro, vibe, pi, and letta as common choices, and points to docs/api/supported-agents.md for the current list. After initialization you run spec-kitty verify-setup to check local installation and project wiring.
The remaining everyday commands are spec-kitty dashboard for the local mission dashboard, spec-kitty next --agent <agent> --mission <slug> for the next-action query, spec-kitty upgrade to update an existing project after upgrading the CLI, and spec-kitty --help. Note the split: init and upgrade are project-level operations, which means the CLI version and the project scaffolding are two things you track separately.
Retrospectives, config keys, and the cost of keeping the loop closed
Every completed mission generates a retrospective by default. The README says this can be tuned via .kittify/config.yaml under the retrospective key, or through the charter, and links docs/guides/how-to/governance/use-retrospective-learning.md. After merge you run /spec-kitty-mission-review, and the mission's retrospective.yaml is authored during what the README calls the runtime terminus, either a HiC prompt or an autonomous facilitator. The README is explicit that merge does not author it.
Two commands read that material: spec-kitty retrospect summary for the cross-mission view, and spec-kitty agent retrospect synthesize --mission <mission-slug> to apply staged proposals. The synthesize command is dry-run by default and requires --apply to mutate anything. That default is the right one for a tool that can change project state, but it also means a team that never passes --apply accumulates proposals that nobody reads.
The maintenance cost here is real and worth naming. You have a CLI version, a project scaffold that spec-kitty upgrade must bring forward, a config file at .kittify/config.yaml, and a growing set of mission artifacts under kitty-specs/. None of that is heavy in isolation. Together it is a second structure inside your repository that reviewers have to learn.
Where the model strains: parallel worktrees, review gates, and small tasks
The worktree approach solves branch chaos by giving each agent an isolated directory under .worktrees/. It does not solve the merge itself. The README lists merge as a gate with an audit trail, which means a human or a defined process still decides. Teams expecting the tool to reconcile conflicting agent output automatically should read the description of auto-merge in the repository summary carefully against the gate language in the README; the supplied material does not detail how conflicts are resolved.
A second strain point is the lifecycle. Work packages move through planned, in_progress, for_review, approved, and done. That is five states to maintain. For a change that one person would finish in twenty minutes, the bookkeeping exceeds the work, which is consistent with the README's own warning that the tool is probably overkill for one-off edits.
A third is the review gate itself. Because humans define acceptance criteria and reviewers accept, reject, or merge, throughput is bounded by review capacity, not by agent speed. Adding more agents in parallel worktrees does not raise that ceiling. If your bottleneck is review, Spec Kitty will make the queue more visible without making it shorter.
How this differs from plain agent sessions or a hosted tracker
The most direct alternative is what the README calls vibe coding: opening an agent in a repository, describing the change, and reviewing the diff. That approach has no persistent artifact for acceptance criteria, no work-package boundaries, and no lifecycle lanes. Spec Kitty's difference is not the agent integration, since it drives the same agents. The difference is that the spec, plan, tasks, review state, and merge decisions are files in Git, and the agent runs in a worktree rather than your working directory.
A hosted issue tracker is the other comparison. Spec Kitty's README describes it as a local workflow first, with optional hosted tracker and sync integrations later. So the default is repository-native, and hosted sync is an add-on rather than the system of record. If your organization already treats a hosted tracker as authoritative, you are choosing which of the two holds the acceptance criteria, and the README does not describe how conflicts between them resolve.
Against a plain spec template committed to the repository, the difference is the runtime. A template has no spec-kitty next, no lifecycle lanes, and no dispatch record. Whether that runtime earns its keep depends on how many concurrent work packages you actually run.
Licence, release cadence, and what to check before adopting
Spec Kitty is MIT licensed, which permits commercial use and modification, and the CLI is published on PyPI as spec-kitty-cli. Nothing in the supplied material suggests a separate licence for the hosted integrations, so if you plan to use the optional hosted tracker or sync, confirm the terms for that component yourself. This is not legal advice.
The release history shows v3.2.7 on 2026-09-09, v3.2.6.2 the same day, and v3.2.6.1 on 2026-09-08. Three releases in two days, with two of them patch-level. That pattern usually means active bug fixing, and it also means you should pin a version rather than track the latest, because spec-kitty upgrade exists specifically to reconcile an existing project with a newer CLI. Upgrading the CLI without running the project upgrade leaves the scaffold behind.
Before adopting, verify three things in a throwaway repository: what spec-kitty init writes under kitty-specs/, whether .worktrees/ is covered by your .gitignore policy, and whether spec-kitty verify-setup passes with your chosen agent key. The README's own boundary is the clearest signal about fit: humans at the review gate, agents inside traceable worktrees, and a repository that stays the source of truth.
Editorial conclusion
Adopt Spec Kitty if your repository already holds the requirements and you want them to stay there while several agents work in parallel. Skip it for one-off edits, tiny scripts, or teams that do not use Git, since the README says it is probably overkill for those cases. Before committing, run spec-kitty init on a throwaway repo, then spec-kitty verify-setup, and inspect what lands under kitty-specs/ and .worktrees/ to confirm the layout matches how your team reviews and merges code.
Community notes