---
type: "Guide"
title: "Claude Code Workflow"
description: "End-to-end guide for running Spec Kitty with the Claude Code CLI and lane-based status tracking."
status: "stable"
generated:
  by: "process:dockitty-export"
  at: "2026-10-10T00:00:00Z"
---

# 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 **Claude automation** in lockstep with Spec Kitty's lane-based status.

## 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](https://docs.spec-kitty.ai/guides/assets/images/claude-code-workflow-mission-kitty.png)

_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](/guides/tutorials/claude-code-integration.md).

## 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:**
```bash
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](/architecture/status-model.md). Each file contains:

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

Launch Claude against a prompt:

```bash
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:

```text
/spec-kitty.implement
```

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

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

## Status Integration

- Lane transitions triggered by action commands (`spec-kitty agent action implement/review`) surface immediately in `spec-kitty agent tasks status`. 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 can add a summary note with `spec-kitty agent tasks add-history WP02 --note "..."`, which is also recorded in the event log.
- When Claude finishes a work package, use the workflow command to move it to `for_review` so the status log and reviewers stay in sync:
  ```bash
  spec-kitty agent action review WP02
  ```

## Recommended Automation

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 status 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 |
| Status 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; `status.events.jsonl` 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:
 ```bash
  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

- Mix Claude with Cursor or Gemini by generating commands for multiple agents during `spec-kitty init`.
- Keep the multi-agent playbook handy: [Multi-Agent Parallel Development](/guides/tutorials/multi-agent-workflow.md).
- Check progress at any time with `spec-kitty agent tasks status` (see [Status & History](/guides/how-to/monitoring/index.md)).

## Related How-To Guides

- [Install Spec Kitty](/guides/how-to/installation/install-spec-kitty.md)
- [Non-Interactive Init](/guides/how-to/installation/non-interactive-init.md)

## Reference

- [CLI Commands](/api/cli-commands.md)
- [Slash Commands](/api/slash-commands.md)
- [Agent Subcommands](/api/agent-subcommands.md)

## Learn More

- [Your First Mission](/guides/tutorials/your-first-mission.md) — the full specify-to-merge lifecycle narrative
- [Understanding Spec Kitty Missions](/guides/tutorials/missions-overview.md)
- [Doctrine documentation](/architecture/doctrine-kinds.md)

## Related

- [Claude Code + Spec Kitty Integration Guide](/guides/tutorials/claude-code-integration.md)
- [Getting Started with Spec Kitty](/guides/tutorials/getting-started.md)

## Audience

- [Stakeholder Persona: Project Owner](/context/audience/external/project-owner.md) - Written for the Project Owner reader.
