This release is a pre-release and may not be stable for production use.
Spec Kitty
Spec-driven development for AI coding agents, multi-agent workflows, and governed software factories.
Spec Kitty is an open-source CLI for turning product intent into a repo-native AI coding workflow:
spec -> plan -> tasks -> next -> review -> accept -> merge
Use it to build a governed software factory around Claude Code, Codex, Cursor, Gemini, GitHub Copilot, Windsurf, OpenCode, and other AI coding agents. Spec Kitty keeps specs, plans, work packages, acceptance criteria, review state, and merge decisions in your repository, then gives agents isolated git worktrees so implementation can happen in parallel without branch chaos.
Team Kitty 4.x prerelease
main carries the 4.x release-candidate line. To test RC2, install its exact version:
uv tool install 'spec-kitty-cli==4.0.0rc2'
This prerelease is for qualification; stable launch acceptance remains pending. Normal stable installs continue to select the published stable release.
Bright Software Factory, Not a Black Box
Spec Kitty is for teams building software factories: repeatable inputs, clear work-package boundaries, isolated execution, visible progress, and review gates. It can support dark software factories and autonomous coding experiments, but it 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.
The goal is not more prompt text. The goal is a durable operating system for agentic coding where the repository remains the source of truth.
Is It For You?
Use Spec Kitty when:
- AI coding sessions are losing requirements, decisions, or acceptance criteria.
- You want specs, plans, tasks, reviews, and merge state stored in Git.
- Multiple agents or developers need clear work-package boundaries.
- You are running parallel Claude Code, Codex, Cursor, Copilot, Gemini, or Windsurf work and need git worktree isolation.
- You are moving from vibe coding to a repeatable spec-driven development workflow.
- You want a local workflow first, with optional hosted tracker and sync integrations later.
It is probably overkill for one-off edits, tiny scripts, or teams that do not use Git.
What It Provides
| Need | Spec Kitty provides |
|---|---|
| Start from intent | Guided specify, plan, and tasks workflows |
| Keep agents aligned | Repository-native mission artifacts under kitty-specs/ |
| Split implementation | Work packages with lifecycle lanes such as planned, in_progress, for_review, approved, and done |
| Run agents in parallel | Isolated git worktrees under .worktrees/ |
| Keep quality visible | Review, accept, merge, and retrospective gates |
| See progress | Lane-by-lane mission status with spec-kitty agent tasks status (--json for tools) |
| Integrate agents | Slash commands or skills for Claude Code, Codex, Cursor, Gemini, Copilot, Windsurf, OpenCode, and more |
| Learn from missions | Every completed mission generates a retrospective by default. Tune via .kittify/config.yaml#retrospective or charter; see how-to. |
Common Use Cases
- Replace ad hoc vibe coding with spec-driven development.
- Turn GitHub issues, product requirements, or bug reports into executable work packages.
- Coordinate multiple AI coding agents without losing context between sessions.
- Keep architecture decisions, constraints, and acceptance criteria close to the code.
- Build a governed software factory that can scale toward more autonomy without hiding review, test, or merge decisions.
Governance layer
Spec Kitty keeps runtime governance in the repo instead of treating it as
agent-only prompt text. The trail model in docs/architecture/trail-model.md
describes how spec-kitty dispatch "<request>" maps operator intent to
runtime behavior, while
docs/architecture/host-surface-parity.md tracks parity across
CLI, slash-command, and hosted surfaces.
The primary standalone governance command is:
spec-kitty dispatch "<request>"- loads governance context, opens an Op record, and returns the context the agent must use before doing the work
Quick Start
Install the CLI:
pipx install spec-kitty-cli
pipx is the preferred installer for the CLI because it keeps Spec Kitty in its
own virtual environment and avoids the externally-managed-environment errors
common on modern Linux distributions.
Other supported install methods:
uv tool install spec-kitty-cli
# or, inside an activated virtual environment
python -m pip install spec-kitty-cli
Create or initialize a project:
spec-kitty init my-project --ai claude
cd my-project
spec-kitty verify-setup
Replace claude with your agent key when needed. Common choices include codex, cursor, gemini, copilot, opencode, qwen, windsurf, kiro, vibe, pi, letta, and llxprt. See Supported Agents for the current list.
Open your AI coding agent in the project and run the core workflow:
/spec-kitty.charter
/spec-kitty.specify Build a small task list app.
/spec-kitty.plan
/spec-kitty.tasks
Then let the runtime choose the next action until the mission is ready:
spec-kitty next --agent claude --mission <mission-slug>
Review, accept, merge, and close the loop:
/spec-kitty.review
/spec-kitty.accept
/spec-kitty.merge --push
After merge, run /spec-kitty-mission-review. The mission's
retrospective.yaml is authored during the runtime terminus (HiC prompt or
autonomous facilitator), not by merge. Once it exists, use
spec-kitty retrospect summary for the cross-mission view and
spec-kitty agent retrospect synthesize --mission <mission-slug> to apply any
staged proposals (dry-run by default — pass --apply to mutate).
For the full walkthrough, see Your First Mission.
Everyday Commands
| Command | Purpose |
|---|---|
spec-kitty init . --ai <agent> |
Add Spec Kitty to the current repo |
spec-kitty verify-setup |
Check local installation and project wiring |
spec-kitty agent tasks status |
Show work package status for a mission |
spec-kitty next --agent <agent> --mission <slug> |
Ask Spec Kitty what the agent should do next |
spec-kitty upgrade |
Update an existing project after upgrading the CLI |
spec-kitty --help |
Show available commands |
Documentation
Start here:
- Getting Started
- Your First Mission
- Orchestrator Quickstart
- CLI Command Reference
- Slash Commands
- Supported Agents
- Install and Upgrade
Deeper topics:
- Spec-Driven Development
- Mission System
- Git Worktrees
- Multi-Agent Orchestration
- External Orchestrator Runbook
- Hosted Sync Workspaces
Hosted auth, sync, and tracker flows remain opt-in. For setup details, see Hosted Sync Workspaces, Internal Hosted-Readiness, and Launch-Readiness Behavior.
FAQ
Is Spec Kitty for dark software factories?
Spec Kitty can be used as part of a dark software factory or autonomous coding pipeline, but its default model is governed and human-in-loop. It keeps specs, work packages, agent actions, review decisions, and merge state visible in the repository.
Which AI coding agents does Spec Kitty support?
Spec Kitty supports common AI coding agents and coding harnesses including Claude Code, Codex, Cursor, Gemini, GitHub Copilot, OpenCode, Qwen, Windsurf, Kiro, Vibe, Pi, and Letta. See Supported Agents.
How is Spec Kitty different from prompt templates or Spec Kit?
Spec Kitty is inspired by spec-driven development workflows, but adds repo-native mission state, work-package lanes, git worktree isolation, governance commands, and an explicit next -> review -> accept -> merge runtime loop.
Does Spec Kitty require a SaaS service?
No. Spec Kitty is local-first and stores its core artifacts in your repo. Hosted tracker and sync integrations are optional.
Development
git clone https://github.com/spec-kitty/spec-kitty.git
cd spec-kitty
pip install -e ".[test]"
When testing templates from a source checkout:
export SPEC_KITTY_TEMPLATE_ROOT="$(pwd)"
spec-kitty init my-project --ai claude
See the Contributing guide for contribution guidelines.
Support
- Open a GitHub issue for bugs, feature requests, or questions.
- See the changelog for release notes.
- See CONTRIBUTORS.md and the GitHub contributors graph for contributor credits.
License
Spec Kitty is released under the MIT License.
1 maintainer
Metadata
1 maintainer
Release files for spec-kitty-cli 4.0.0rc6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| spec_kitty_cli-4.0.0rc6.tar.gz | 7.2 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| spec_kitty_cli-4.0.0rc6-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 15.1 MB
Release files / spec_kitty_cli-4.0.0rc6.tar.gz
| Download URL | spec_kitty_cli-4.0.0rc6.tar.gz |
|---|---|
| Size | 7.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c4ae57bf75ad49d97ab5addaeb8992cbe2cab7e756e250b3a28e6d0651299232
|
|
BLAKE2b-256 checksum How to use checksums |
9fdf8220347e62b1e8fe7a904617b0e226f7d2f1723ed77b3170e05822619002
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.
Transparency logRelease files / spec_kitty_cli-4.0.0rc6-py3-none-any.whl
| Download URL | spec_kitty_cli-4.0.0rc6-py3-none-any.whl |
|---|---|
| Size | 7.9 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
24144e2a70f9fcad93cc7ec0dcd03eecc21f0510f2506ed839c443864a4341e7
|
|
BLAKE2b-256 checksum How to use checksums |
e20c2bab8eab4216d58529ca9717be6e3e42f68e3199c8efa976d541ba460fe3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.
Transparency log
