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.

Claude Code workflow - Mission Kitty splash

Stylized splash — the phase flowchart is decorative. CLI setup, prompt launch, and merge steps are in the sections below.

Tip

For the opinionated slash-command tutorial (/spec-kitty.specify through implement), see Claude Code + Spec Kitty Integration.

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
Analysis Ask Claude to sanity-check cross-artifact consistency before coding /spec-kitty.analyze
Implementation Run Claude on specific prompt files /spec-kitty.implement
Review & Merge Review, accept readiness, then land the branch /spec-kitty.review, /spec-kitty.accept, /spec-kitty.merge

Setup Checklist

Select Claude during project creation:

spec-kitty init my-project --ai claude

This copies Claude-specific commands into .claude/commands/ and registers claude as an active agent in .kittify/config.yaml.

Running Claude Against Prompts

Prompt files live under kitty-specs/<mission-slug>/tasks/WPxx-slug.md (flat directory, no lane subdirectories). Lane state is tracked in the append-only status.events.jsonl event log, not in file frontmatter — see Status Model. Each file contains:

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

Launch Claude against a prompt:

cd .worktrees/001-systematic-recognizer-enhancement-lane-a
spec-kitty agent action implement WP02 --agent claude

That prints the WP02 prompt and moves it to in_progress. Now start Claude Code in that workspace and, in the interactive chat, run the matching slash command:

/spec-kitty.implement

For a non-interactive or scripted run, claude accepts a prompt directly via -p/--print (confirmed in claude --help):

claude -p "$(cat kitty-specs/001-systematic-recognizer-enhancement/tasks/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 action commands (spec-kitty agent action implement/review) surface instantly on the kanban dashboard. The full lane model is: planned, claimed, in_progress (alias: doing), for_review, in_review, approved, done, blocked, and canceled; approved means review passed and merge pending, while done means merged/integrated.
  • Each lane move records agent and shell_pid as event metadata in status.events.jsonl—Claude should still add an ISO 8601 entry to the prompt file's 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 action review WP02
  1. Claude session bootstrapper: Script that reads meta.json for the friendly mission 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/<mission-slug>/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 in_progress lane yet Move prompt to in_progress (or doing alias) via action commands so metadata is injected
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 action commands for lane transitions
Claude session interrupted CLI lost connection Resume by re-running Claude against the same prompt file; the activity log in the WP frontmatter tracks prior progress

Merge and Cleanup

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

  1. Ensure all WPs are approved or done and all review feedback is resolved.
  2. Run the guided merge:
 spec-kitty accept
 spec-kitty merge --remove-worktree

Run it from any checkout where the mission can be resolved; the CLI automatically performs the Git steps from the main checkout so execution workspaces stay in sync. The command documents merge steps, updates activity logs, and optionally removes the execution worktrees to keep the repository tidy. 3. 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> (dry-run by default; add --apply to mutate).

Beyond Claude

Reference

Learn More

Edit this page