claude-code-cat

<img src="docs/cat-logo.svg" height="36" alt="CAT logo"> CAT: AI Coding That Ships on Schedule

"Build on solid ground, not a house of cards."

<p align="center"> <a href="#cat-ai-agents-that-land-on-their-feet"><img src="docs/intro-box.svg" alt="CAT Overview" width="500"/></a> </p>

CAT transforms chaotic AI coding sessions into predictable, reliable delivery. Your team gets consistent results, trackable progress, and code that passes review the first time.

Benefit	Impact
Predictable Progress	Track completion across versions, tasks, and milestones
Consistent Quality	Every developer follows the same structured workflow
Reduced Rework	Built-in verification catches issues before code review
Team Alignment	Shared preferences and quality gates across projects

---

The Problem: AI Coding Without Structure

<p align="center"> <img src="docs/problem.png" alt="The problem with AI projects" width="600"/> </p>

For Engineering Leaders: AI tools promise 10x productivity, but deliver unpredictable results. One developer gets magic, another gets chaos. Progress is invisible until something breaks.

For Teams: AI assistants forget context, ignore conventions, and make inconsistent decisions. Every session starts from scratch. Code quality varies wildly.

CAT solves this. You define your standards once. CAT enforces them consistently across every developer, every task, every session. Work progresses when you approve it. Nothing changes while you're away.

---

See It In Action

<p align="center"> <a href="https://www.youtube.com/watch?v=IvRLJq989og&t=167s"> <img src="docs/video-thumbnail.png" alt="Watch CAT in action - click to play video" width="600"/> </a> <br/> <em>See how CAT transforms chaotic AI coding into structured, reliable progress.</em> </p>

---

Getting Started

<p align="center"> <a href="#getting-started"><img src="docs/choose-path.svg" alt="Choose Your Path" width="500"/></a> </p> <p align="center"> <a href="#quick-start"><b>[A] Quick Start</b></a> · <a href="#how-cat-works"><b>[B] How It Works</b></a> · <a href="#commands"><b>[C] Commands</b></a> </p>

---

Quick Start

Step 1: Install CAT

# Add the plugin marketplace
/plugin marketplace add cowwoc/cat

# Install CAT
/plugin install cat@cowwoc-claude-code-cat

# Verify you're ready
/cat:help

Step 2: Initialize Your Project

/cat:init

CAT will ask about your project and your preferences:

<p align="center"> <a href="#quick-start"><img src="docs/choose-partner.svg" alt="Choose Your Partner" width="500"/></a> </p>

Your answers shape how CAT makes decisions throughout your project.

Step 3: Chart Your Course

# Add structure (versions and tasks)
/cat:add

# See your project status
/cat:status

Step 4: Start Working

/cat:work

CAT spawns a subagent in an isolated worktree, executes the task, and presents you with results at a checkpoint:

<p align="center"> <a href="#quick-start"><img src="docs/checkpoint.svg" alt="Checkpoint" width="500"/></a> </p>

---

How CAT Works

Hierarchical Planning

CAT organizes work into three levels:

<p align="center"> <a href="#hierarchical-planning"> <img src="docs/hierarchy.svg" alt="Hierarchy" width="500"/> </a> </p>

• Major versions are your milestones (v1: "Core Features", v2: "Polish & Performance")
• Minor versions group related work (v1.0: "Authentication", v1.1: "User Profiles")
• Tasks are individual units of work sized to fit in a single session

Team Preferences

During /cat:init, you configure preferences that apply consistently across your team:

Preference	What It Controls
Trust	How much autonomy CAT has to make decisions
Verify	What verification runs before presenting changes
Curiosity	Whether CAT notes optimization opportunities beyond the task
Patience	When CAT acts on discovered opportunities

For Teams: These preferences become your team's coding standards. Every developer, every project, every session follows the same rules.

The Workflow: Task Lifecycle

<p align="center"> <a href="#the-workflow-task-lifecycle"> <img src="docs/task-lifecycle.svg" alt="Task Lifecycle" width="500"/> </a> </p>

Each task follows this path:

1. Planning → PLAN.md defines the task objectives
2. Approach Selection → At forks in the road, you choose the path
3. Execution → Subagent works in isolation (no risk to your main branch)
4. Verification → Build, test, lint—all must pass
5. Review → Optional stakeholder council weighs in
6. Checkpoint → You approve or request changes
7. Completion → Merged to main, progress saved

Built-In Reliability

CAT includes safeguards that protect your codebase and ensure consistent delivery: