Claude Code + Spec Kitty Integration Guide
Who is this for (1)
- Stakeholder Persona: Project Owner — Written for the Project Owner reader.
Complete workflow for using Spec Kitty with Claude Code CLI

Stylized splash — the detective’s case board is decorative. The opinionated workflow phases are in the sections below.
Why Claude Code + Spec Kitty?
The Problem with Ad-Hoc AI Coding:
- Claude loses context across long sessions
- Requirements get missed or misunderstood
- No systematic way to track what’s been built
- Difficult to coordinate multiple features
The Solution: Spec Kitty provides structured slash commands that keep Claude Code focused on requirements, with live kanban tracking of all work.
Quick Start (5 Minutes)
# 1. Install both toolspipx install spec-kitty-cli
# 2. Initialize your projectspec-kitty init myproject --ai claudecd myproject
# 3. Launch Claude Codeclaude
# 4. Inside Claude, use slash commands/spec-kitty.specify Add user authentication with email/password# Claude will ask discovery questions, then create spec
/spec-kitty.plan# Claude creates technical plan with database schema, API design
/spec-kitty.tasks# Generates 5-10 work packages ready for implementation
/spec-kitty.implement# Claude implements first task, moves it through kanban lanes
# 5. Check progress# Run `spec-kitty agent tasks status` to see where each work package standsThe Opinionated Workflow (Explained)
Spec Kitty enforces a specific sequence that prevents common AI coding failures:
Phase 1: Specify BEFORE Coding
Why: Forces you and Claude to agree on requirements before any code is written.
# Inside Claude Code/spec-kitty.specify Build a REST API for managing todo items with CRUD operationsWhat Claude Does:
- Asks discovery questions (What auth? What database? What validation?)
- Creates
kitty-specs/001-todo-api/spec.mdwith:- User stories
- Functional requirements
- Acceptance criteria
- You review and clarify until accurate
Why This Matters: Spec becomes the source of truth. Claude can’t invent requirements mid-implementation.
Phase 2: Plan BEFORE Implementing
Why: Forces architectural thinking before coding. Prevents “code first, design never.”
/spec-kitty.plan We'll use FastAPI, PostgreSQL with SQLAlchemy, JWT auth, and pytestWhat Claude Does:
- Asks planning questions (error handling? migrations? testing?)
- Creates:
plan.md- System architecturedata-model.md- Database schemacontracts/- API specifications
- You review and approve architecture
Why This Matters: Major decisions are documented. You catch architectural issues before code exists.
Phase 3: Break Down BEFORE Building
Why: Large features overwhelm AI agents. Spec Kitty forces decomposition into work packages.
/spec-kitty.tasksWhat Claude Does:
- Reads your spec + plan
- Creates 5-10 work packages (WP01, WP02, etc.)
- Each WP is a focused prompt file with:
- Clear objective
- Implementation steps
- Testing requirements
- Work packages organized in kanban lanes (planned → doing → for_review → in_review → approved → done)
Why This Matters:
- Claude focuses on ONE thing at a time
- Progress is visible (
spec-kitty agent tasks statusshows review-passed and merged task counts separately) - You can pause/resume without losing context
Phase 4: Implement Systematically
Why: Structured workflow prevents Claude from jumping around or missing pieces.
/spec-kitty.implement# Claude auto-picks WP01, moves it to "doing", starts implementation# When done, moves to "for_review"
/spec-kitty.review# Claude reviews WP01, provides feedback or approves (moves to "approved")
/spec-kitty.implement# Auto-picks WP02, repeats processWhat You See:
spec-kitty agent tasks statusreflects each lane move- Activity log shows: “WP01 moved planned → doing (by Claude Code)”
- Clear visibility into progress (3 approved, 2 in review, 5 planned)
Why This Matters:
- Systematic completion (no orphaned code)
- Built-in review process
- You can hand off to different agents (Cursor takes over WP05)
Phase 5: Accept BEFORE Merging
Why: Final readiness checks catch mission-level gaps before merge.
/spec-kitty.accept# Validates: All WPs approved or done? Spec requirements met? Tests passing?
/spec-kitty.merge --push# Merges to main, copies specs to kitty-specs/, cleans up worktreeAfter merge, run /spec-kitty-mission-review, then review the retrospective
captured at the runtime terminus: spec-kitty retrospect summary
(cross-mission view) and
spec-kitty agent retrospect synthesize --mission <slug> to apply staged
proposals (dry-run by default; add --apply to mutate).
Why This Matters: Git main branch stays clean. Every feature that lands has: spec + plan + approved WPs + acceptance validation + post-merge learning.
The Opinionated Part (And Why It Works)
Opinion 1: Spec MUST Exist Before Code
Rationale: AI agents are eager to code. Without forcing specification first, they’ll implement their interpretation of your vague request.
How Enforced: /spec-kitty.plan and /spec-kitty.tasks REQUIRE spec.md to exist first.
Real Example:
❌ Without Spec Kitty:You: "Add authentication"Claude: [writes OAuth implementation with assumptions]You: "I meant simple email/password..."Claude: [rewrites everything]
✅ With Spec Kitty:You: "/spec-kitty.specify Add authentication"Claude: "What auth method? What about password reset? Session timeout?"[You answer, spec gets created]Claude: [implements exactly what's in spec]Opinion 2: Git Worktrees For Execution Lanes
Rationale: Feature branches in place = context confusion. Worktrees = physical isolation.
How It Works:
# Spec Kitty automatically creates:.worktrees/001-auth-system-lane-a/ # Shared execution workspace for lane A├── src/ # Your code (on the lane branch)├── kitty-specs/001-auth-system/ # Specs for THIS feature└── .claude/commands/ # Slash commands work hereWhy This Matters for Claude:
- Clear context: “You’re in 001-auth-system worktree = work on auth”
- No branch switching = no lost context
- Parallel work: You can have 3 features active, each in separate worktree
Opinion 3: Kanban Lanes Are Required
Rationale: “Are we done?” is impossible to answer without systematic tracking.
The Kanban Lanes (8 internal, 5 displayed):
- planned - Ready to implement (backlog)
- claimed - Assigned to an agent, not yet started
- in_progress (displayed as “Doing”) - Currently being worked on
- for_review - Code complete, needs review
- approved - Review passed, awaiting merge
- done - Merged and accepted
- blocked - Blocked by dependency or issue
- canceled - Permanently abandoned
spec-kitty agent tasks status groups work packages by lane.
How Enforced: Every WP has lane: in frontmatter. Commands auto-update lanes.
Why This Matters:
- Status shows 3 in “doing” = too many parallel tasks, focus!
- Agent A does implementation, Agent B does review (clean handoff)
- Historical record: “WP03 took 3 transitions (sent back to planned twice)”
Real-World Claude Code Workflow
Scenario: “Build a Markdown Preview Feature”
Step 1: Initialize (1 minute)
spec-kitty init markdown-preview --ai claudecd markdown-previewclaudeStep 2: Create Specification (5 minutes)
# Inside Claude Code:/spec-kitty.specify Build a markdown preview feature with live reload and syntax highlighting
# Claude asks:# - What framework? (React? Vue? Plain JS?)# - What markdown features? (tables? code blocks? math?)# - What syntax theme? (light? dark? both?)
# You answer, spec gets createdStep 3: Navigate to Worktree (CRITICAL!)
# Claude Code shows you the path:✓ Feature created at: .worktrees/001-markdown-preview/
# You MUST do this:cd .worktrees/001-markdown-preview# All future commands run from here!Step 4: Create Plan (5 minutes)
/spec-kitty.plan Use React with marked.js for parsing, highlight.js for syntax,and WebSocket for live reload. Dark mode toggle.
# Claude creates:# - plan.md (component structure)# - data-model.md (state management)# - contracts/ (WebSocket protocol)Step 5: Generate Tasks (2 minutes)
/spec-kitty.tasks
# Claude generates:# WP01 - Setup React project with Vite# WP02 - Integrate marked.js markdown parser# WP03 - Add highlight.js syntax highlighting# WP04 - Implement WebSocket live reload# WP05 - Create dark mode toggle# WP06 - Add error handling and edge cases# WP07 - Write integration testsStep 6: Implement (variable time)
/spec-kitty.implement# Claude picks WP01, moves to "doing", implements
# When done:/spec-kitty.review# Claude reviews WP01, moves to "approved"
# Repeat for WP02-WP07Step 7: Accept and Merge (2 minutes)
/spec-kitty.accept# Validates all tasks complete
/spec-kitty.merge --push# Merges to main, feature complete!Total Time: ~30-60 minutes for a well-specified, tested, reviewed feature.
Status Tracking
Checking Status
The bundled local web dashboard has been removed. Check progress from the CLI instead:
spec-kitty agent tasks status # human-readable lane boardspec-kitty agent tasks status --json # machine-readableA read-only Mission Status Read API (#5528) is planned as the contract for a replacement UI, which will live in its own repository.
What You See
Kanban Board:
┌─ Planned ──┬─ Doing ────┬─ For Review ┬─ Done ─────┐│ WP04 │ WP01 │ WP03 │ WP05 ││ WP06 │ WP02 │ │ WP07 ││ WP08 │ │ │ │└────────────┴────────────┴─────────────┴────────────┘Activity Log:
15:23 - WP01 moved planned → doing (Claude Code, shell 12345)15:31 - WP01 moved doing → for_review (Claude Code)15:35 - WP01 moved in_review → approved (Claude Code)Agent Tracking:
- See which shell PID each agent is using
- Identify who’s working on what
- Historical record of all transitions
Advanced: Multi-Agent Handoff
Scenario: Claude Implements, Cursor Reviews
Terminal 1: Claude Code
cd .worktrees/001-auth-systemclaude# Inside: /spec-kitty.implement (WP01-WP04)# Claude implements, moves each to "for_review"Terminal 2: Cursor
cd .worktrees/001-auth-system # Same worktree!cursor# Inside: /spec-kitty.review (WP01-WP04)# Cursor reviews each, moves to "approved" or back to "planned"Why This Works:
- Both agents see same
tasks/*.mdfiles - Frontmatter
lane:field coordinates them spec-kitty agent tasks statusshows both agents’ activity- No race conditions (file-based locking via git)
Common Patterns
Pattern 1: Resume After Break
# Next day, forgot what you were doing?cd .worktrees/001-auth-systemclaude/spec-kitty.implement
# Claude auto-detects: "WP03 is in 'doing' lane, resuming..."Pattern 2: Skip Review for Simple Tasks
/spec-kitty.implement# After implementation:spec-kitty agent action review WP01# Review workflow moves to approved when there is no feedback; merge later records donePattern 3: Parallel Features
# Terminal 1: Feature Acd .worktrees/001-auth-systemclaude/spec-kitty.implement
# Terminal 2: Feature B (different feature!)cd .worktrees/002-payment-flowcursor/spec-kitty.implement
# `spec-kitty agent tasks status --mission <slug>` shows each Mission progressingTroubleshooting
“Slash commands not found”
Cause: Not in the project root or worktree Fix:
cd myproject # or cd .worktrees/001-featureclaude# Commands should now appear“Scripts not found” error
Symptom: bash: .kittify/scripts/bash/check-prerequisites.sh: No such file or directory
Cause: Installed v0.10.0-0.10.8 which had bundling bug Fix:
pipx upgrade spec-kitty-cli # Get v0.10.9+cd myprojectspec-kitty upgrade # Auto-repairs templatesClaude ignores slash commands
Cause: Commands might not be visible to Claude Fix:
ls .claude/commands/# Should show: spec-kitty.specify.md, spec-kitty.plan.md, etc.
# If missing:spec-kitty upgrade # Regenerates commandsKey Commands Reference
| Slash Command | When to Use | What It Does |
|---|---|---|
/spec-kitty.specify | Start new feature | Discovery interview → create spec.md |
/spec-kitty.plan | After spec done | Architecture planning → create plan.md |
/spec-kitty.tasks | After plan done | Break down → create work packages |
/spec-kitty.implement | Ready to code | Auto-pick task → implement → move lanes |
/spec-kitty.review | Code review time | Review completed work → approve or reject |
/spec-kitty.accept | WPs approved | Validate mission readiness → ready to merge |
/spec-kitty.merge | Accepted mission | Merge to mission target branch → cleanup worktree |
CLI Commands (Outside Claude)
| Command | When to Use | What It Does |
|---|---|---|
spec-kitty init | New project | Initialize Spec Kitty in project |
spec-kitty upgrade | After pip upgrade | Apply migrations, fix templates |
spec-kitty agent tasks status | Anytime | Show the lane-based status board |
spec-kitty verify-setup | Troubleshooting | Check tools and project health |
Advanced Workflows
Research-Heavy Features
For features requiring upfront research (e.g., “Add ML-based recommendations”):
/spec-kitty.specify Add ML-based product recommendations# Spec created
/spec-kitty.research Compare collaborative filtering vs content-based approaches# Creates research.md with evidence logs
/spec-kitty.plan Use hybrid approach with scikit-learn# Plan incorporates research findings
/spec-kitty.tasks# Implementation tasks based on researched approachCharter-Driven Development
Encode your team’s quality standards once:
/spec-kitty.charter# Claude helps create charter.md with principles like:# - All APIs must have rate limiting# - All database queries must use parameterized statements# - All user input must be validated
# Now ALL slash commands automatically reference charter# Claude: "Per charter principle 2, I'm adding parameterized queries..."Tips for Maximum Effectiveness
✅ DO
-
Answer discovery questions thoroughly
- Claude needs good requirements to succeed
- Vague answers = implementation guesswork
-
Always
cd .worktrees/001-feature- Slash commands need feature context
- Status commands need to know which Mission you’re in
-
Check status often
- Catches: “Wait, why are 3 tasks in ‘doing’?”
- Insight: “WP05 failed review twice, might need redesign”
-
Review before merging
/spec-kitty.acceptis your quality gate- Run
/spec-kitty-mission-reviewand the retrospective after merge
❌ DON’T
-
Skip specification
- “Just build it” = context loss + rework
- Spec takes 5 minutes, saves hours
-
Work directly on main
- Use execution workspaces
- Keeps main clean and deployable
-
Manually edit lane metadata
- Use workflow commands to advance lanes
- Preserves history and status accuracy
-
Ignore stale-work warnings
- “Task stuck in ‘doing’ for 2 days” = blocked work
spec-kitty agent tasks statusflags stale WPs you might miss
Integration with Other Tools
With Git
Spec Kitty uses standard git operations:
# Commits work in feature branchcd .worktrees/001-featuregit commit -m "Implement WP03"
# Merges use standard git merge/spec-kitty.merge # Uses git merge under the hoodWith CI/CD
# Run validation in CIspec-kitty verify-setup --jsonspec-kitty agent tasks validate-workflowWith IDEs
Claude Code, Cursor, Windsurf all support slash commands natively. The commands appear in autocomplete once you type /spec-kitty.
Performance at Scale
Tested Scenarios
- ✅ Single agent: 1-10 work packages per feature
- ✅ Multiple agents: 2-3 agents working on different features simultaneously
- ✅ Large features: Up to 30 work packages decomposed and tracked
- ✅ Parallel missions: 5 active worktrees tracked via per-Mission status
Next Steps
- Try the Quick Start - 5 minute hands-on experience
- Read Full Workflow - Getting Started Tutorial
- Explore Advanced Features - Multi-Agent Orchestration
Getting Help
Issues: https://github.com/spec-kitty/spec-kitty/issues
Common Issues:
- Template bundling bug → Upgrade to v0.10.9+
- Slash commands not found → Check you’re in project/worktree
Documentation:
Why This Workflow Works
The Pattern Recognition Problem:
AI coding agents are pattern-matching machines. Without specs:
- They match patterns from training data (may not fit your needs)
- They make assumptions (may conflict with your requirements)
- They lose context (session length limits)
The Spec Kitty Solution:
- Specification = Pattern to match
- Plan = Architecture constraints
- Tasks = Focused context windows
- Status = Progress visibility
Result: Claude Code (or any agent) stays focused, builds systematically, and you maintain oversight without micromanaging.
The opinionated workflow isn’t arbitrary - it’s specifically designed around how AI agents work (and fail) in practice.