spec-kitty

Spec Kitty is an open-source CLI for turning product intent into a repeatable agent workflow:

spec -> plan -> tasks -> next -> review -> accept -> merge

It keeps the important context in your repository, creates work packages that agents can execute, and uses git worktrees so implementation work can happen without constantly switching branches.

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 the repo.
• Multiple agents or developers need clear work package boundaries.
• 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, and done | | Avoid branch chaos | Isolated git worktrees under .worktrees/ | | See progress | Optional local kanban dashboard with spec-kitty dashboard | | Integrate agents | Slash commands or skills for common AI coding tools | | Learn from missions | Every completed mission generates a retrospective by default. Tune via .kittify/config.yaml#retrospective or charter; see how-to. |

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, and letta.

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 Feature.

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 dashboard | Open the local mission dashboard | | 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 Feature
• CLI Command Reference
• Slash Commands
• Supported Agents
• Dashboard Guide
• 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 today. Internal / pre-launch operators dogfooding the hidden hosted-readiness mode behind SPEC_KITTY_ENABLE_SAAS_SYNC=1 should read Internal Hosted-Readiness (Pre-Launch). The launch-day behavior that will replace today's defaults is staged under Launch-Readiness Behavior (Coming Soon).

Development

git clone https://github.com/Priivacy-ai/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 CONTRIBUTING.md for contribution guidelines.

Identity-Boundary CI Gate

The drift-detector required check runs tests/sync/test_diagnose.py::TestCanonicalRegistryRecognition on every PR against main. It catches drift between the canonical registries in this repo and the consumer-recognition contract that spec-kitty-end-to-end-testing#41 closed over an 8-RC peeling cycle (rc14 → rc22). Workflow file: .github/workflows/drift-detector.yml.

This is one of three coordinated CI gates tracked under #1247:

• drift-detector here (this repo).
• cross-repo-harness-tests in spec-kitty-events — workflow .github/workflows/cross-repo-harness-tests.yml.
• identity-boundary-canary in spec-kitty-saas — workflow .github/workflows/canary-gate.yml.

This repo's drift-detector pins no external SHA — it only runs an in-repo test. The sibling repos' workflows pin a specific commit of Priivacy-ai/spec-kitty-end-to-end-testing; see each sibling's README "Identity-Boundary CI Gate" section for the SHA-bump procedure.

Admin action required (one-time per repo): after this gate merges, a repo admin must register the check as required on main:

1. Open https://github.com/Priivacy-ai/spec-kitty/settings/branches.
2. Edit the rule for main.
3. Under "Require status checks to pass before merging", add the exact name drift-detector.
4. Save.

Until that step is done, the workflow still runs on every PR but its red status does not block merge.

Support

• Open a GitHub issue for bugs, feature requests, or questions.
• See CHANGELOG.md for release notes.
• See CONTRIBUTORS.md and the GitHub contributors graph for contributor credits.

License

Spec Kitty is released under the MIT License.