{"id":47608928,"url":"https://github.com/cowwoc/cat","last_synced_at":"2026-05-13T02:01:56.549Z","repository":{"id":332159396,"uuid":"1129943970","full_name":"cowwoc/cat","owner":"cowwoc","description":"AI Agents that land on their feet","archived":false,"fork":false,"pushed_at":"2026-04-30T20:38:02.000Z","size":19088,"stargazers_count":95,"open_issues_count":1,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-04-30T22:20:29.535Z","etag":null,"topics":["ai-agents","automation","claude","claude-code","context-engineering","developer-tools","meta-programming","project-management","software-development","spec-driven-development","workflow"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cowwoc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-07T20:04:53.000Z","updated_at":"2026-04-17T21:24:00.000Z","dependencies_parsed_at":"2026-04-17T18:01:45.401Z","dependency_job_id":null,"html_url":"https://github.com/cowwoc/cat","commit_stats":null,"previous_names":["cowwoc/claude-code-cat","cowwoc/cat"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/cowwoc/cat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cowwoc%2Fcat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cowwoc%2Fcat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cowwoc%2Fcat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cowwoc%2Fcat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cowwoc","download_url":"https://codeload.github.com/cowwoc/cat/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cowwoc%2Fcat/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32964444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-12T23:30:32.555Z","status":"online","status_checked_at":"2026-05-13T02:00:07.132Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","automation","claude","claude-code","context-engineering","developer-tools","meta-programming","project-management","software-development","spec-driven-development","workflow"],"created_at":"2026-04-01T19:50:15.376Z","updated_at":"2026-05-13T02:01:56.542Z","avatar_url":"https://github.com/cowwoc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# \u003cimg src=\"docs/cat-logo.svg\" height=\"36\" alt=\"CAT logo\"\u003e CAT: AI Coding That Ships on Schedule\n\n\u003e *\"Build on solid ground, not a house of cards.\"*\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#cat-ai-agents-that-land-on-their-feet\"\u003e\u003cimg src=\"docs/intro-box.svg\" alt=\"CAT Overview\" width=\"500\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n**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.\n\n| Benefit | Impact |\n|---------|--------|\n| **Predictable Progress** | Track completion across versions, tasks, and milestones |\n| **Consistent Quality** | Every developer follows the same structured workflow |\n| **Reduced Rework** | Built-in verification catches issues before code review |\n| **Team Alignment** | Shared preferences and quality gates across projects |\n\n---\n\n## The Problem: AI Coding Without Structure\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/problem.png\" alt=\"The problem with AI projects\" width=\"600\"/\u003e\n\u003c/p\u003e\n\n**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.\n\n**For Teams:** AI assistants forget context, ignore conventions, and make inconsistent decisions. Every session starts from scratch. Code quality varies wildly.\n\n**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.\n\n---\n\n## See It In Action\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.youtube.com/watch?v=IvRLJq989og\u0026t=167s\"\u003e\n    \u003cimg src=\"docs/video-thumbnail.png\" alt=\"Watch CAT in action - click to play video\" width=\"600\"/\u003e\n  \u003c/a\u003e\n  \u003cbr/\u003e\n  \u003cem\u003eSee how CAT transforms chaotic AI coding into structured, reliable progress.\u003c/em\u003e\n\u003c/p\u003e\n\n---\n\n## Getting Started\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#getting-started\"\u003e\u003cimg src=\"docs/choose-path.svg\" alt=\"Choose Your Path\" width=\"500\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-start\"\u003e\u003cb\u003e[A] Quick Start\u003c/b\u003e\u003c/a\u003e ·\n  \u003ca href=\"#how-cat-works\"\u003e\u003cb\u003e[B] How It Works\u003c/b\u003e\u003c/a\u003e ·\n  \u003ca href=\"#commands\"\u003e\u003cb\u003e[C] Commands\u003c/b\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Quick Start\n\n### Step 1: Install CAT\n\n```bash\n# Add the plugin marketplace\n/plugin marketplace add cowwoc/cat\n\n# Install CAT\n/plugin install cat@cowwoc-claude-code-cat\n\n# Verify you're ready\n/cat:help\n```\n\n### Step 2: Initialize Your Project\n\n```bash\n/cat:init\n```\n\nCAT will ask about your project and your preferences:\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-start\"\u003e\u003cimg src=\"docs/choose-partner.svg\" alt=\"Choose Your Partner\" width=\"500\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nYour answers shape how CAT makes decisions throughout your project.\n\n### Step 3: Chart Your Course\n\n```bash\n# Add structure (versions and tasks)\n/cat:add\n\n# See your project status\n/cat:status\n```\n\n### Step 4: Start Working\n\n```bash\n/cat:work\n```\n\nCAT spawns a subagent in an isolated worktree, executes the task, and presents\nyou with results at a checkpoint:\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-start\"\u003e\u003cimg src=\"docs/checkpoint.svg\" alt=\"Checkpoint\" width=\"500\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## How CAT Works\n\n### Hierarchical Planning\n\nCAT organizes work into three levels:\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#hierarchical-planning\"\u003e\n    \u003cimg src=\"docs/hierarchy.svg\" alt=\"Hierarchy\" width=\"500\"/\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n- **Major versions** are your milestones (v1: \"Core Features\", v2: \"Polish \u0026 Performance\")\n- **Minor versions** group related work (v1.0: \"Authentication\", v1.1: \"User Profiles\")\n- **Tasks** are individual units of work sized to fit in a single session\n\n### Team Preferences\n\nDuring `/cat:init`, you configure preferences that apply consistently across your team:\n\n| Preference | What It Controls |\n|------------|------------------|\n| **Trust** | How much autonomy CAT has to make decisions |\n| **Verify** | What verification runs before presenting changes |\n| **Curiosity** | Whether CAT notes optimization opportunities beyond the task |\n| **Patience** | When CAT acts on discovered opportunities |\n\n**For Teams:** These preferences become your team's coding standards. Every developer, every project, every session follows the same rules.\n\n### The Workflow: Task Lifecycle\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#the-workflow-task-lifecycle\"\u003e\n    \u003cimg src=\"docs/task-lifecycle.svg\" alt=\"Task Lifecycle\" width=\"500\"/\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nEach task follows this path:\n\n1. **Planning** → PLAN.md defines the task objectives\n2. **Approach Selection** → At forks in the road, you choose the path\n3. **Execution** → Subagent works in isolation (no risk to your main branch)\n4. **Verification** → Build, test, lint—all must pass\n5. **Review** → Optional stakeholder council weighs in\n6. **Checkpoint** → You approve or request changes\n7. **Completion** → Merged to main, progress saved\n\n### Built-In Reliability\n\nCAT includes safeguards that protect your codebase and ensure consistent delivery:\n\n| Feature | Business Value |\n|---------|----------------|\n| **Token-Aware Tasks** | Tasks sized to complete successfully, reducing failed sessions |\n| **Isolated Worktrees** | Each task runs separately — no risk to your main branch |\n| **Automatic State Tracking** | Resume instantly after interruptions — no lost progress |\n| **Learn from Mistakes** | CAT analyzes failures and prevents the same issues recurring |\n| **Quality Gates** | Multi-perspective reviews catch bugs before they reach production |\n\n---\n\n## Commands\n\n### Your Main Actions\n\n| Command | What It Does |\n|---------|--------------|\n| `/cat:init` | Initialize project structure |\n| `/cat:status` | View project status and progress |\n| `/cat:work [scope]` | Execute tasks (see below) |\n| `/cat:help` | Quick reference for all commands |\n\n**`/cat:work` scope options:**\n\n| Scope | Example | What Happens |\n|-------|---------|--------------|\n| (none) | `/cat:work` | Work through ALL incomplete tasks |\n| major | `/cat:work 0` | Complete all tasks in v0.x |\n| minor | `/cat:work 0.5` | Complete all tasks in v0.5 |\n| task | `/cat:work 0.5-auth` | Complete single task only |\n\nWhen trust \u003e= medium, CAT auto-continues to the next task within scope.\n\n### Building Your Map\n\n| Command | What It Does |\n|---------|--------------|\n| `/cat:add [description]` | Add a task or version. With description, creates task directly |\n| `/cat:research` | Research before committing to an approach |\n\n### Housekeeping\n\n| Command | What It Does |\n|---------|--------------|\n| `/cat:cleanup` | Clear abandoned worktrees and orphaned branches |\n| `/cat:config` | Change your preferences |\n| `/cat:learn` | Analyze and learn from mistakes |\n| `/cat:remove` | Remove a task or version |\n\n---\n\n## Configuration\n\nYour CAT settings live in `.claude/cat/cat-config.json`:\n\n```json\n{\n  \"trust\": \"medium\",\n  \"verify\": \"changed\",\n  \"curiosity\": \"low\",\n  \"patience\": \"high\",\n  \"terminalWidth\": 120\n}\n```\n\n### Options Reference\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `trust` | string | `medium` | Autonomy level (controls review and approval behavior) |\n| `verify` | string | `changed` | What verification runs before checkpoints |\n| `curiosity` | string | `low` | Whether CAT notices opportunities beyond the task |\n| `patience` | string | `high` | When CAT acts on discovered opportunities |\n| `terminalWidth` | number | `120` | Display width in characters for output formatting |\n| `autoRemoveWorktrees` | boolean | `true` | Auto-cleanup worktrees on task completion |\n\n**trust** — How much trust you place in CAT to make decisions:\n- `low` — CAT presents options frequently; you guide most decisions\n- `medium` — CAT presents options for meaningful trade-offs; handles routine choices\n- `high` — CAT decides autonomously; only presents HIGH risk or architectural choices\n\n**verify** — What verification CAT runs before presenting changes:\n- `none` — No verification; fastest iteration\n- `changed` — Verify modified file/module only; balanced confidence\n- `all` — Verify entire project; highest confidence before checkpoint\n\n**curiosity** — Whether CAT notices optimization opportunities while working:\n- `low` — Stays focused; only completes the assigned task\n- `medium` — Notes obvious issues in touched files; documents but doesn't act\n- `high` — Actively explores for improvements; documents opportunities found\n\n**patience** — When CAT acts on opportunities discovered during work:\n- `low` — Acts immediately on high-priority discoveries (benefit/cost \u003e 3)\n- `medium` — Defers most discoveries; acts on critical issues only\n- `high` — Defers all discoveries to backlog; maximum focus on current task\n\n**terminalWidth** — Display width in characters for output formatting:\n- `120` — Desktop/Laptop (Recommended). Optimized for wide monitors\n- `50` — Mobile. Optimized for phones and narrow screens\n- `40-200` — Custom. Any value in this range is valid\n\n### Stakeholder Reviews\n\nWhen `verify` is `changed` or `all`, CAT runs multi-perspective stakeholder reviews before merge:\n\n| Stakeholder | Focus |\n|-------------|-------|\n| **requirements** | Verifies task satisfies its claimed requirements from PLAN.md |\n| **architect** | System design, module boundaries, API design, dependencies |\n| **security** | Vulnerabilities, injection, auth, input validation |\n| **quality** | Code duplication, complexity, maintainability, obvious bugs |\n| **tester** | Test coverage, missing tests, edge cases |\n| **performance** | Algorithm complexity, memory usage, blocking operations |\n| **ux** | Usability, accessibility, interaction design |\n| **sales** | Customer value, competitive positioning, demo-readiness |\n| **marketing** | Positioning, messaging, go-to-market readiness |\n\n---\n\n## Skills Reference\n\nSkills are specialized abilities CAT can invoke. Most run automatically, but some\nyou can call directly:\n\n### Git Operations\n`git-commit` · `git-squash` · `git-rebase` · `git-amend` · `git-merge-linear`\n\n### Multi-Agent Coordination\n`spawn-subagent` · `monitor-subagents` · `collect-results` · `merge-subagent` · `parallel-execute`\n\n### Quality \u0026 Learning\n`stakeholder-review` · `learn-from-mistakes` · `run-retrospective` · `decompose-task`\n\n---\n\n## Project Structure\n\nAfter `/cat:init`, your project gains a planning structure:\n\n```\nyour-project/\n└── .claude/cat/\n    ├── PROJECT.md          # Project overview\n    ├── ROADMAP.md          # The big picture\n    ├── cat-config.json     # Your preferences\n    └── v1/                 # Major version 1\n        ├── STATE.md        # Chapter progress\n        ├── PLAN.md         # Chapter objectives\n        └── v1.0/           # Minor version\n            ├── STATE.md    # Section progress\n            └── setup-auth/ # Individual task\n                ├── STATE.md\n                └── PLAN.md\n```\n\n---\n\n## Tips for Success\n\n**Start small** — Begin with one major version and a few tasks. Expand as you\nfind your rhythm.\n\n**Check status** — Run `/cat:status` often. It shows where you are and\nsuggests next steps.\n\n**Scout unfamiliar territory** — Use `/cat:research` before tackling complex\nfeatures in unknown domains.\n\n**Clear the fog** — Run `/clear` between tasks to start fresh with full context.\n\n**Trust the process** — CAT tracks state automatically. If a session ends\nmid-task, just run `/cat:work` to continue where you left off.\n\n---\n\n## Contributing\n\nCAT is opinionated by design. It does a few things well rather than everything\npoorly.\n\nContributions are welcome when they:\n- Solve real problems encountered during structured project execution\n- Align with the existing structured workflow\n- Maintain the focused nature of the tool\n\nOpen an issue to discuss before investing significant effort.\n\n---\n\n## License\n\nCAT Source-Available Commercial License — see [LICENSE.md](LICENSE.md)\n\n**Free for solo developers.** See [pricing](docs/PRICING.md) for team and enterprise options.\n\n---\n\n\u003cp align=\"center\"\u003e\u003cem\u003eNow go build something amazing.\u003c/em\u003e\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcowwoc%2Fcat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcowwoc%2Fcat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcowwoc%2Fcat/lists"}