spec-kitty

Claude Code Workflow

Anthropic’s Claude Code pairs naturally with Spec Kitty’s guardrails. This guide explains how to integrate the Claude CLI, wire the prompts, and keep the Claude dashboard automation in lockstep with the Spec Kitty kanban view.

Prerequisites

• Claude Code CLI installed (claude --version).
• Spec Kitty project initialized with the claude agent selected.
• .claude/commands/ directory generated by spec-kitty init.

Workflow Overview

Phase	Claude Code Usage	Spec Kitty Command
Discovery	Prompt Claude to interview stakeholders	/spec-kitty.specify
Research	Summarize evidence and data model findings	/spec-kitty.research
Planning	Generate architecture briefs via Claude	/spec-kitty.plan
Tasks	Produce work packages and prompts that Claude can execute	/spec-kitty.tasks
Implementation	Run Claude on specific prompt files	/spec-kitty.implement
Review & Merge	Summarize results and follow-up tasks, then land the branch	/spec-kitty.review, /spec-kitty.merge

Setup Checklist

1. Select Claude during project creation

   spec-kitty init my-project --ai claude
   

   This copies Claude-specific commands into .claude/commands/ and activates the automation scripts under .kittify/scripts/.

2. Refresh Claude’s long-term context after planning

   cd <feature worktree>
   .kittify/scripts/bash/update-agent-context.sh claude
   

   The script injects new architecture decisions, tech stacks, and vocabulary into Claude’s context files. Re-run it whenever plan.md or tasks.md changes.

Running Claude Against Prompts

Prompt files live under kitty-specs/<feature>/tasks/<lane>/WPxx-slug.md. Each contains:

• Mission-aligned context.
• Checklist of subtasks.
• Activity log for audit.

Launch Claude against a prompt:

cd .worktrees/001-systematic-recognizer-enhancement
claude prompt kitty-specs/001-systematic-recognizer-enhancement/tasks/doing/WP02-synthetic-benchmark.md

Claude will use the template metadata to understand scope, file boundaries, and Definition of Done.

Dashboard Integration

• Lane transitions triggered by workflow commands (spec-kitty agent workflow implement/review) surface instantly on the kanban dashboard.
• Each lane move records agent, assignee, and shell_pid in prompt frontmatter—Claude should add an ISO 8601 entry to the Activity Log summarizing what changed.
• When Claude finishes a work package, use the workflow command to move it to for_review so the dashboard and reviewers stay in sync:

  spec-kitty agent workflow review WP02
  

Recommended Automation

1. Claude session bootstrapper: Script that reads meta.json for the friendly feature name and injects it into Claude’s context.
2. Claude completion validator: Automatically checks that Claude’s output modifies only the allowed files referenced in the prompt.
3. Claude dashboard notifier: Sends Claude’s status updates to a team Slack channel whenever a work package changes lanes.
4. Checklist watcher: Parse kitty-specs/<feature>/checklists/ and block Claude from moving prompts to done when acceptance criteria are unchecked.

Troubleshooting Claude Sessions

Problem	Cause	Fix
Claude asks for missing context	Prompt not in doing lane yet	Move prompt to doing so scripts inject metadata
Claude edits unexpected files	Prompt instructions unclear	Refine tasks.md and regenerate prompt
Dashboard shows stale lane	Prompt moved manually	Always use spec-kitty agent workflow commands for lane transitions
Claude session interrupted	CLI lost connection	Resume using the prompt transcript stored under .claude/history/

Merge and Cleanup

Once Claude (and any partner agents) finish the feature:

1. Ensure tasks/for_review/ is empty and all checklists are complete.
2. Run the guided merge:

     spec-kitty merge --remove-worktree
   

   Run it from the feature worktree; the CLI automatically performs the Git steps from the main checkout so worktrees stay in sync. The command documents merge steps, updates activity logs, and optionally removes the feature worktree to keep the repository tidy.

Beyond Claude

• Mix Claude with Cursor or Gemini by generating commands for multiple agents during spec-kitty init.
• Keep the multi-agent orchestration playbook handy: Multi-Agent Orchestration.
• Review the dashboard monitoring workflow in Use the Dashboard.

Related How-To Guides

• Install Spec Kitty
• Non-Interactive Init
• Use the Dashboard

Reference

• CLI Commands
• Slash Commands
• Agent Subcommands

Learn More

• Spec-Driven Development
• Mission System
• Kanban Workflow

This site is open source. Improve this page.