spec-kitty

Spec Kitty is an open-source CLI workflow for spec-driven development with AI coding agents. It helps teams turn product intent into implementation with a repeatable path: spec -> plan -> tasks -> spec-kitty next (agent loop) -> review -> merge.

Why teams use it

AI coding workflows often break down on larger features:

• Requirements and design decisions drift over long agent sessions
• Parallel work is hard to coordinate across branches
• Review and acceptance criteria become inconsistent from one feature to the next

Spec Kitty addresses this with repository-native artifacts, work package workflows, and lane-aware git worktree isolation.

Who it's for

• Project Owners who need explicit approval boundaries and outcome accountability
• External Tech Lead Evaluators assessing delivery predictability and adoption fit
• External Architect Evaluators evaluating governance durability and boundary clarity
• External Product Manager Evaluators validating intent-to-delivery traceability
• Lead Developers coordinating implementation quality and handoffs
• Maintainers preserving operational consistency across features and agents

Stakeholder Value Proposition

| Stakeholder Persona | Value Proposition | |---|---| | Project Owner | Faster onboarding with explicit governance checkpoints and acceptance accountability | | External Tech Lead Evaluator | Deterministic, auditable multi-agent workflow with clear lifecycle guardrails | | External Architect Evaluator | C4 + ADR traceability with explicit host authority and integration boundaries | | External Product Manager Evaluator | Clear intent-to-artifact mapping and lower handoff ambiguity between product and engineering | | Lead Developer | Structured work package flow, quality gates, and review-ready evidence trails | | Maintainer | Stable operational model with bounded external integrations and trackable state transitions |

Try it now: pip install spec-kitty-cli && spec-kitty init my-project --ai claude

🚀 What You Get in 3.1.x

| Capability | What Spec Kitty provides | |------------|--------------------------| | Spec-driven artifacts | Generates and maintains spec.md, plan.md, wps.yaml, and tasks.md in kitty-specs/<mission>/ | | Work package execution | Uses canonical lifecycle lanes (planned, claimed, in_progress, for_review, in_review, approved, done, blocked, canceled) with doing as UI alias for in_progress | | Parallel implementation model | Creates isolated git worktrees under .worktrees/; every mission executes through lane-based worktrees, with exactly one worktree per computed execution lane | | Live project visibility | Local dashboard for kanban and mission progress (spec-kitty dashboard) | | Review resilience | Persisted versioned review artifacts, focused fix prompts, dirty-state classification, and arbiter checklists | | Execution resilience | Interrupted merge recovery (merge --resume), crash recovery (implement --recover), stale-claim diagnostics (doctor) | | Multi-agent support | Template and command generation for 12 AI agent integrations |

From Idea to Production in 6 Automated Steps

graph LR
    A[📝 Specify<br/>WHAT to build] --> B[🎯 Plan<br/>HOW to build]
    B --> C[📋 Tasks<br/>Work packages]
    C --> D[⚡ spec-kitty next<br/>Agent loop]
    D --> E[🔍 Review<br/>Quality gates]
    E --> F[🚀 Merge<br/>Ship it]

    style A fill:#e1f5ff
    style B fill:#e1f5ff
    style C fill:#fff3e0
    style D fill:#f3e5f5
    style E fill:#e8f5e9
    style F fill:#fce4ec

📊 Project Snapshot

Current stable release line: v3.1.x (development version 3.1.2a2; main, GitHub Releases, and PyPI)

3.1.0 highlights:

• Planning integrity — read-only status commands no longer dirty the git tree; spec-kitty next without --result is a safe query-only operation
• Structured WP manifest — new wps.yaml format is the primary dependency source for finalize-tasks, eliminating prose-parser corruption of lane assignments
• Review resilience — focused fix prompts (~40 lines vs 400+), persisted versioned review-cycle-N.md artifacts, dirty-state classification, baseline test context, and arbiter checklists
• Execution resilience — merge --resume recovers interrupted merges; implement --recover handles crash recovery; doctor diagnoses stale claims and zombie worktrees
• Tasks stabilization — dependency preservation, lane-graph completeness, parallelism protection, and consistent --mission flag naming across all commands
• Merge strategy — MERGE / SQUASH / REBASE via --strategy flag or config.yaml; linear-history protection hint on push failures
• Charter — spec-kitty charter replaces spec-kitty constitution across all surfaces; auto-migrated by spec-kitty upgrade
• Mission identity — --mission is now the canonical flag; --feature is retained only as a hidden deprecated alias during migration

Jump to: Getting Started • Examples • 12 AI Tools • CLI Reference • Worktrees • Troubleshooting

📌 Release Track

Spec Kitty now uses main as the stable 3.x release line. The former 1.x line is deprecated and moves to 1.x-maintenance for maintenance-only fixes.

| Branch | Version | Status | Install | |--------|---------|--------|---------| | main | 3.1.x | Current stable line | pip install spec-kitty-cli | | 1.x-maintenance | 1.x | Deprecated, maintenance-only | Install from a pinned maintenance tag or source checkout |

For users: install the stable line from PyPI with pip install spec-kitty-cli. For existing 3.0.x users: run spec-kitty upgrade in each project — the charter rename and mission identity migration are automatic. For existing 1.x or 2.x users: migrate to 3.1.x; 1.x-maintenance is maintenance-only and will no longer publish new PyPI releases.

🤝 Multi-Agent Coordination for AI Coding

Run multi-agent delivery with an external orchestrator while keeping workflow state and guardrails in spec-kitty. Core CLI orchestration is exposed as spec-kitty orchestrator-api; there is no in-core spec-kitty orchestrate shim.

Terminology note:

• Mission Type = reusable blueprint
• Mission = concrete tracked item
• Mission Run = runtime/session instance
• --mission is the canonical flag in 3.1.x; --feature is retained only as a hidden deprecated alias

# Verify host contract
spec-kitty orchestrator-api contract-version --json

# Use the reference external orchestrator
spec-kitty-orchestrator orchestrate --mission 034-my-mission --dry-run
spec-kitty-orchestrator orchestrate --mission 034-my-mission

Docs:

• External provider runbook: docs/how-to/run-external-orchestrator.md
• Custom provider guide: docs/how-to/build-custom-orchestrator.md

sequenceDiagram
    participant Lead as 👨‍💼 Lead Architect
    participant Claude as 🤖 Claude (Spec)
    participant Cursor as 🤖 Cursor (Impl)
    participant Gemini as 🤖 Gemini (Review)
    participant Dashboard as 📊 Live Kanban

    Lead->>Claude: /spec-kitty.specify
    Claude->>Dashboard: WP01-WP05 (planned)

    par Parallel Work
        Lead->>Cursor: implement WP01
        Lead->>Cursor: implement WP02
    end

    Cursor->>Dashboard: WP01 → in_progress (Doing)
    Cursor->>Dashbo