Table of Contents

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

Reference

Learn More

Edit this page