swarm-engine 1.0.0

package/AGENTS.md

@@ -0,0 +1,72 @@
+# AGENTS.md
+# Cross-tool agent instructions — read by Claude Code, Codex, and Gemini CLI
+
+## Swarm Engine
+
+This project uses the Swarm Engine for multi-agent orchestration. The `swarm` CLI coordinates multiple specialized AI agents working together.
+
+## Commands
+
+```bash
+# Main orchestration
+swarm orchestrate "<task>"        # Full multi-phase: research → implement → review
+
+# Single agent
+swarm run <agent> "<task>"        # Run one agent (researcher, implementer, reviewer, etc.)
+
+# Configuration
+swarm setup                       # Interactive wizard — configure backends and models
+swarm status                      # Show registered agents, backends, and patterns
+
+# Memory
+swarm memory search "<query>"     # Search past decisions and knowledge
+swarm memory store <type> "<title>"  # Save knowledge (pipe content via stdin)
+```
+
+## Available Agents
+
+| Agent | Role | Use when |
+|-------|------|----------|
+| researcher | Explores code, finds patterns | You need to understand a codebase area |
+| implementer | Writes code following conventions | You have a clear spec to build |
+| reviewer | Finds bugs, security issues | Code needs quality review |
+| tester | Writes and runs tests | Features need test coverage |
+| debugger | Diagnoses and fixes bugs | Something is broken |
+| planner | Designs architecture | Complex feature needs upfront design |
+| refactorer | Safe incremental refactoring | Code needs restructuring with test gates |
+| integrator | Verifies cross-module contracts | After parallel work on different modules |
+| devils-advocate | Challenges assumptions | High-risk code needs adversarial review |
+| grounding | Verifies implementation matches spec | Risk of scope drift |
+| security-reviewer | Finds security vulnerabilities (OWASP) | Code handles auth, user input, or secrets |
+| performance-reviewer | Finds performance issues | Code has hot paths, large data, or I/O |
+| data-integrity-reviewer | Reviews migrations and data handling | Database changes or multi-table writes |
+| api-contract-reviewer | Checks backward compatibility | Public API or type export changes |
+| testing-reviewer | Reviews test quality and coverage | Tests need gap analysis or flakiness check |
+| accessibility-reviewer | Checks WCAG/ARIA compliance | UI code needs accessibility audit |
+| dependency-reviewer | Reviews dep security and licenses | New packages added or upgraded |
+| error-handling-reviewer | Reviews error handling patterns | Code has I/O, external APIs, or error paths |
+| concurrency-reviewer | Finds race conditions and deadlocks | Shared state or parallel async operations |
+| documentation-reviewer | Checks docs accuracy vs code | Docs may be stale after code changes |
+| judge | Evaluates competing outputs | Spike/discover patterns need a winner |
+| orchestrator | Coordinates multi-agent workflows | Complex multi-phase tasks |
+| sentinel | Monitors git activity | Background knowledge updates |
+| guardian | Runs affected tests | Background regression detection |
+| librarian | Maintains knowledge quality | Vault cleanup and organization |
+| documenter | Writes technical documentation | Code needs docs |
+
+## Orchestration Patterns
+
+| Pattern | Use when |
+|---------|----------|
+| `hybrid` | Most tasks — research → implement → review |
+| `tdd` | New features that need test coverage |
+| `red-team` | Security-sensitive code — build then break |
+| `spike` | Uncertain approach — try two, pick the best |
+| `discover` | Novel problem — hypothesize → experiment → implement |
+
+## Conventions
+
+- Agents follow existing codebase patterns and conventions
+- Every implementation gets reviewed by parallel reviewers (correctness + security + conventions)
+- Knowledge from past sessions is stored in memory — agents check it before starting
+- Tech debt is tagged explicitly: DEBT:NEW, DEBT:EXISTING, DEBT:WORSENED

package/CLAUDE.md

@@ -0,0 +1,89 @@
+# Swarm Engine — Developer Guide
+
+## Architecture
+
+```
+src/
+├── core/
+│   ├── types.ts             # 18+ types: Agent, Phase, Orchestration, Event, Pattern
+│   ├── event-bus.ts         # Typed events + JSONL logging + 10MB rotation
+│   ├── lifecycle.ts         # Agent FSM (registered → spawning → running → idle → shutdown)
+│   ├── registry.ts          # Agent registration from code or .md files (js-yaml)
+│   ├── patterns.ts          # 7 composable patterns with compose() + extend()
+│   ├── checkpoint.ts        # Save/resume orchestration state (UUID-validated)
+│   ├── permissions.ts       # Fine-grained permission model + doom loop detector
+│   └── snapshots.ts         # Filesystem snapshot/rollback for agent changes
+├── runtime/
+│   ├── engine.ts            # DAG executor: work-queue, retries, timeouts, approvals
+│   ├── executor.ts          # Routes to pluggable backends with permission/snapshot hooks
+│   ├── compaction.ts        # Context window management and summarization
+│   ├── distiller.ts         # Context distillation between phases
+│   ├── verifier.ts          # Project verification + ContinuousVerifier
+│   ├── cost-model.ts        # Cost estimation and budget tracking
+│   ├── stats.ts             # Execution statistics collector
+│   ├── model-router.ts      # UCB1-based model selection across task types
+│   ├── autonomy.ts          # Autonomy level tracking per task type
+│   ├── adaptive.ts          # Adaptive replanning based on phase results
+│   ├── reflexion.ts         # Post-phase reflection engine
+│   ├── rewriter.ts          # Plan rewriting rules
+│   ├── traces.ts            # Execution trace storage and similarity search
+│   ├── templates.ts         # Reusable orchestration templates
+│   ├── sharing.ts           # Generate HTML/Markdown/JSON reports
+│   ├── plugins.ts           # TypeScript plugin loader with lifecycle hooks
+│   ├── worktree.ts          # Git worktree isolation for parallel agents
+│   ├── panes.ts             # Tmux split pane manager for visible agent execution
+│   ├── mcp.ts               # MCP client (stdio + HTTP transports)
+│   ├── lsp.ts               # LSP client for type info and diagnostics
+│   ├── acp.ts               # ACP server for IDE integration
+│   ├── heuristics.ts        # Task-level learning from execution traces
+│   ├── compounder.ts        # Knowledge compounding across orchestrations
+│   ├── plan-search.ts       # Plan search and optimization
+│   ├── cache-optimizer.ts   # Prompt cache optimization
+│   ├── cascade.ts           # Task complexity classification + model cascading
+│   ├── living-spec.ts       # Living specification that evolves during execution
+│   ├── chunker.ts           # Content chunking for large inputs
+│   ├── review-schema.ts     # Review output schema validation
+│   └── backends/
+│       ├── types.ts         # ExecutionBackend interface
+│       ├── claude.ts        # Claude Code via Agent SDK
+│       ├── codex.ts         # OpenAI Codex CLI
+│       ├── gemini.ts        # Google Gemini CLI
+│       ├── vercel-ai.ts     # Vercel AI SDK (20+ providers)
+│       ├── mock.ts          # Testing backend
+│       └── index.ts         # BackendRegistry
+├── memory/                  # SQLite + FTS5 + Obsidian vault sync
+├── hooks/                   # TypeScript hook handlers (universal ANSI)
+├── plugin/                  # Claude Code plugin generator
+├── cli/                     # 21 CLI commands (15 visible + 6 hidden)
+└── utils/                   # Logger, config, terminal, paths, redact, tokens, errors, env
+```
+
+## Development
+
+```bash
+npm install          # Install dependencies
+npm run dev          # Run CLI in dev mode (tsx)
+npm test             # Run tests in watch mode
+npm run test:run     # Run tests once (871 passing)
+npm run build        # Compile TypeScript to dist/
+npm run lint         # Type-check without emit
+```
+
+## Key Design Decisions
+
+- **Backend selection**: mock flag → config.backend → defaultBackend → 'claude'
+- **Permission mode**: defaults to 'default' (not bypassPermissions)
+- **Phase DAG**: work-queue approach, not linear loop
+- **IDs**: crypto.randomUUID() everywhere
+- **Checkpoint security**: UUID format validation prevents path traversal
+- **Terminal**: standard ANSI only, no iTerm2-specific codes
+- **Memory**: write-through to ~/swarm-vault/ for Obsidian Sync
+- **Event bus**: try/catch on listeners, 10MB JSONL rotation
+
+## Agents
+
+26 agents in agents/*.md with YAML frontmatter, "Before You Act" + "Self-Check" blocks, debt tagging (DEBT:NEW/EXISTING/WORSENED). Includes 10 specialized reviewers: security, performance, data-integrity, api-contract, testing, accessibility, dependency, error-handling, concurrency, documentation.
+
+## Testing
+
+871 tests across 54 files covering core (types, events, lifecycle, registry, patterns, checkpoints, permissions, snapshots), runtime (engine, executor, backends, compaction, distiller, sharing, plugins, MCP, ACP, panes, heuristics, cascade, cost-model, plan-search, adaptive, reflexion, review-schema, compounder, traces, stats, verifier, templates), memory, hooks, TUI (renderer, dashboard), utils (terminal, config, logger, project-config, errors, env, redact, compact-format), CLI commands (doctor, agents, init, learn), and integration tests.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simon Coombes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,235 @@
+# Swarm Engine
+
+**Your agents. Orchestrated.**
+
+Coordinate multiple AI agents working on your code - researching, implementing, reviewing, testing - with an intelligent planner that learns from every run.
+
+Works with Claude Code, OpenAI Codex, and Google Gemini CLI. Mix models across agents in the same orchestration.
+
+## What It Looks Like
+
+```
+  Swarm Engine - hybrid pattern
+
+  Phase 1: research ━━━━━━━━━━━━━━━━━━━━ 100%  42s
+    ✓ researcher-code       sonnet   3.2K tokens
+    ✓ researcher-context    sonnet   1.8K tokens
+
+  Phase 2: implement ━━━━━━━━━━━━━━━━━━━  55%  1m 12s
+    ● implementer           opus     src/auth/rate-limit.ts...
+
+  Phase 3: review                         pending
+    ○ reviewer-correctness  ○ reviewer-security  ○ reviewer-convention
+
+  $0.24 spent | 12.8K tokens | ~2m remaining
+```
+
+```
+  ┌─────────────────────────────────────────────────┐
+  │  ✓ Orchestration complete                       │
+  │  Pattern: hybrid (3 phases, 6 agents)           │
+  │  Duration: 3m 42s | Tokens: 47K | Cost: $0.38   │
+  │                                                 │
+  │  Save as template? deploy-lambda                │
+  └─────────────────────────────────────────────────┘
+```
+
+## Install
+
+```bash
+git clone https://github.com/simoncoombes/swarm-engine.git ~/dev/swarm-engine
+cd ~/dev/swarm-engine && npm install && bash install.sh
+swarm doctor  # verify everything works
+```
+
+Requires Node.js 20+, jq, and at least one of Claude Code, Codex, or Gemini CLI.
+
+## Quick Start
+
+```bash
+# From Claude Code (agents run in split panes)
+/swarm "add rate limiting to the API"
+
+# From any terminal
+swarm orchestrate "add rate limiting to the API"
+
+# Preview what will happen before running
+swarm plan "add rate limiting" --dry-run
+```
+
+## VS Code and Cursor
+
+Swarm Engine ships with a VS Code extension that works in both VS Code and Cursor.
+
+**Install the extension:**
+```bash
+cd ~/dev/swarm-engine/vscode-extension
+npm install && npm run build
+npx @vscode/vsce package --allow-missing-repository
+```
+Then: `Cmd+Shift+P` > "Extensions: Install from VSIX" > select the `.vsix` file.
+
+**What you get:**
+- `@swarm` in Copilot Chat - type `@swarm add auth middleware` and it orchestrates the task
+- Sidebar panel with quick actions, pattern browser, and agent list
+- Command palette (`Cmd+Shift+P` > "Swarm") for all commands
+- Status bar shortcut
+
+**Copilot Chat examples:**
+```
+@swarm add rate limiting to the API
+@swarm plan add auth middleware
+@swarm template bug-fix
+@swarm status
+```
+
+## Why Swarm Engine
+
+AI coding agents work alone. You get one agent, one model, one approach. For complex tasks, that's not enough.
+
+Swarm Engine orchestrates multiple agents in parallel. Each has a specialized role, the right model for the job, and shared knowledge from past runs.
+
+- **7 composable patterns** - hybrid, TDD, red-team, spike, discover, review-cycle, research. Compose them: `--pattern "research | tdd | red-team"`
+- **Intelligent planner** - cost-based optimization, adaptive execution, learns from every run
+- **Mix any backend** - Claude for implementation, Codex for review, Gemini for research. Different model per agent.
+- **Reusable templates** - save successful workflows, run them again with different parameters
+- **26 specialized agents** - 16 core roles plus 10 focused reviewers (security, performance, data integrity, API contracts, testing, accessibility, dependencies, error handling, concurrency, documentation)
+- **871 tests** - 4 rounds of security review, clean on all adversarial attack vectors
+
+## Templates
+
+Save successful orchestrations as reusable templates:
+
+```bash
+swarm template list
+
+  add-endpoint     - REST API endpoint with tests
+  bug-fix          - Reproduce, diagnose, fix, verify
+  security-audit   - OWASP security review
+  refactor         - Safe refactoring with verification gates
+  migration        - Schema migration with rollback
+
+swarm template run add-endpoint -i
+```
+
+## Explain Plan
+
+See exactly what will happen before it runs:
+
+```bash
+swarm plan "add auth middleware" --pattern hybrid
+
+  Phase 1: research [parallel]
+    researcher-code    sonnet   ~5K tokens
+    researcher-context sonnet   ~3K tokens
+  Phase 2: implement [sequential]
+    implementer        opus     ~15K tokens
+  Phase 3: review [parallel]
+    reviewer-correct   opus     ~8K tokens
+    reviewer-security  opus     ~8K tokens
+
+  Est. cost: $0.51 | Est. duration: 95s
+  Optimizations: model downgrade for research phase (sonnet vs opus)
+```
+
+## Commands
+
+**Daily use**
+
+| Command | What it does |
+|---------|-------------|
+| `/swarm <task>` | Full orchestration - research, implement, review |
+| `/review-cycle <task>` | Implement with iterative quality gate |
+| `/diff-review [base]` | Review branch diff before PR |
+| `/research <question>` | Parallel research across multiple angles |
+| `/tdd <feature>` | Test-driven: write tests first, then implement |
+
+**Advanced**
+
+| Command | What it does |
+|---------|-------------|
+| `/spike <problem>` | Two approaches compete, judge picks winner |
+| `/red-team <task>` | Adversarial build and break |
+| `/discover <problem>` | Hypothesize, experiment, implement winner |
+| `/fix-pr <PR#>` | Fix PR review comments |
+| `/resume` | Resume from checkpoint |
+
+## Patterns
+
+7 composable patterns. Use them individually or combine them.
+
+| Pattern | Flow | Phases |
+|---------|------|--------|
+| hybrid | Research, Implement, Review | 3 |
+| research | Parallel fan-out research | 1 |
+| review-cycle | Implement, Challenge, Review (iterative) | 4 |
+| tdd | Test-first, Implement, Verify, Review | 5 |
+| spike | Two approaches compete, judge decides | 4 |
+| red-team | Build, Break, Harden | 4 |
+| discover | Hypothesize, Experiment, Implement winner | 5 |
+
+Compose patterns: `swarm orchestrate "task" --pattern "tdd | red-team"`
+
+## Agents
+
+16 core agents plus 10 specialized reviewers.
+
+| Agent | Role |
+|-------|------|
+| researcher | Explores code, finds patterns, traces dependencies |
+| implementer | Writes clean, tested code following conventions |
+| reviewer | Finds bugs, security issues, convention violations |
+| tester | Writes and runs tests, reports coverage |
+| debugger | Reproduces and fixes bugs systematically |
+| planner | Designs architecture before code is written |
+| refactorer | Safe incremental refactoring with test gates |
+| integrator | Verifies cross-module contracts after parallel work |
+| devils-advocate | Challenges every assumption before review |
+| grounding | Verifies the implementation solves the actual problem |
+| orchestrator | Coordinates everything |
+| judge | Evaluates competing implementations and picks the winner |
+| sentinel | Background: watches git activity |
+| guardian | Background: runs affected tests |
+| librarian | Background: maintains knowledge quality |
+| documenter | Writes technical documentation |
+
+**Specialized reviewers:** security, performance, data integrity, API contracts, testing, accessibility, dependencies, error handling, concurrency, documentation.
+
+## Cross-Tool Support
+
+Convert your agents to work natively in other tools:
+
+```bash
+swarm convert --to copilot    # GitHub Copilot .agent.md format
+swarm convert --to cursor     # Cursor .mdc rules
+swarm convert --to codex      # OpenAI Codex prompts
+swarm convert --to gemini     # Gemini CLI skills
+swarm convert --to opencode   # OpenCode agents
+swarm convert --to windsurf   # Windsurf skills
+```
+
+## Memory
+
+SQLite-backed knowledge base with full-text search. Syncs to Obsidian vault for cross-machine access. The engine learns from every run and compounds knowledge over time.
+
+```bash
+swarm memory search "authentication"
+swarm compound stats
+```
+
+## Requirements
+
+- Node.js 20+
+- jq (`brew install jq`)
+- At least one AI backend:
+  - [Claude Code](https://claude.ai/code) (recommended)
+  - [Codex CLI](https://github.com/openai/codex) (`npm i -g @openai/codex`)
+  - [Gemini CLI](https://github.com/google-gemini/gemini-cli) (`npm i -g @google/gemini-cli`)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Share agents, templates, patterns, and plugins.
+
+## License
+
+MIT

package/agents/accessibility-reviewer.md

@@ -0,0 +1,118 @@
+---
+name: accessibility-reviewer
+description: |
+  Reviews UI code for accessibility compliance — WCAG, ARIA, keyboard navigation, screen reader support.
+
+  <example>
+  <context>New form component has been built</context>
+  <user-request>Review this form for accessibility — labels, keyboard nav, screen readers</user-request>
+  <assistant-response>Launches accessibility-reviewer to check WCAG compliance and ARIA usage</assistant-response>
+  <commentary>Accessibility audit on a new UI component</commentary>
+  </example>
+
+  <example>
+  <context>Dashboard with interactive elements</context>
+  <user-request>Check the dashboard for keyboard navigation and focus management</user-request>
+  <assistant-response>Launches accessibility-reviewer to verify keyboard and screen reader support</assistant-response>
+  <commentary>Interactive UI accessibility review</commentary>
+  </example>
+model: sonnet
+tools: Read, Glob, Grep
+disallowedTools: Write, Edit, Bash
+permissionProfile: safe
+maxTurns: 30
+tags: [review, accessibility, frontend]
+---
+
+You are an Accessibility Review Agent. You analyze UI code for WCAG compliance, ARIA correctness, keyboard accessibility, and screen reader compatibility.
+
+## Process
+
+1. **Identify interactive elements** — Buttons, links, forms, modals, dropdowns, tabs, custom widgets
+2. **Check semantic HTML**:
+   - Using `<div>` or `<span>` where `<button>`, `<a>`, `<nav>`, `<main>`, `<section>` is appropriate
+   - Missing heading hierarchy (`<h1>` → `<h2>` → `<h3>`, not skipping levels)
+   - Lists not using `<ul>`/`<ol>`/`<li>`
+   - Tables not using `<th>`, `<caption>`, `scope` attributes
+3. **Check ARIA usage**:
+   - Missing `aria-label` or `aria-labelledby` on icon-only buttons and non-text elements
+   - Incorrect ARIA roles (e.g., `role="button"` on a `<div>` instead of using `<button>`)
+   - Missing `aria-expanded`, `aria-haspopup` on disclosure widgets
+   - Missing `aria-live` regions for dynamic content updates
+4. **Check keyboard navigation**:
+   - All interactive elements reachable via Tab
+   - Focus visible on all interactive elements (`:focus-visible` styles)
+   - Focus trapped properly in modals (no Tab escape)
+   - Escape key closes modals/popups
+   - Arrow keys work for grouped controls (tabs, radio buttons, menus)
+5. **Check visual accessibility**:
+   - Color contrast ratios (4.5:1 for normal text, 3:1 for large text — WCAG AA)
+   - Information not conveyed by color alone
+   - Text resizable to 200% without loss
+   - Touch targets at least 44x44px
+6. **Check form accessibility**:
+   - All inputs have associated `<label>` elements (via `for`/`id` or wrapping)
+   - Error messages associated with inputs via `aria-describedby`
+   - Required fields indicated with `aria-required` and visual indicator
+   - Form validation errors announced to screen readers
+7. **Check image/media accessibility**:
+   - All `<img>` have meaningful `alt` text (or `alt=""` for decorative)
+   - Video has captions, audio has transcripts
+
+## Before You Act
+
+Before executing your process, reason through these questions internally (do not output this thinking):
+
+1. **What's the REAL problem?** Restate the accessibility review scope. What UI am I auditing?
+2. **What could go wrong?** Missing a barrier that makes the UI unusable for someone. Over-flagging patterns that are actually accessible.
+3. **What's the blast radius?** Accessibility failures exclude users entirely — not a degraded experience, but no experience.
+4. **Am I the right agent for this?** If the code has no UI, defer. If the issue is purely visual design, note it but focus on functional accessibility.
+
+## Output Format
+
+```
+## Accessibility Review Summary
+[ACCESSIBLE / CONCERNS FOUND / BARRIERS FOUND — 1-2 sentence assessment]
+[WCAG Level targeted: A / AA / AAA]
+
+## Findings
+
+| # | WCAG | Category | Severity | File:Line | Finding | Confidence |
+|---|------|----------|----------|-----------|---------|------------|
+| 1 | 1.1.1 | Images | High | `file:line` | Missing alt text on logo | 95% |
+| 2 | 2.1.1 | Keyboard | Critical | `file:line` | Custom dropdown not keyboard accessible | 90% |
+
+## Keyboard Navigation Audit
+- [List of interactive elements and their keyboard accessibility status]
+
+## Screen Reader Audit
+- [How the page would be experienced with a screen reader]
+
+## Recommendations
+- [Prioritized fixes — critical barriers first]
+```
+
+## Rules
+
+1. **Confidence threshold** — Only report findings with confidence >= 80%
+2. **WCAG references required** — Every finding must cite the relevant WCAG success criterion
+3. **Barriers over preferences** — Focus on things that prevent access, not style preferences
+4. **Check the rendered output** — ARIA in the code must produce correct screen reader experience
+5. **Stay read-only** — Report issues, don't fix them
+6. **Be specific** — Include file paths, line numbers, and the exact element with the issue
+7. **Abstention** — If there's no UI code in scope, say so clearly
+8. **Scratchpad** — If a scratchpad path is provided, read it first and append findings under `## Agent: accessibility-reviewer`
+
+## Self-Check (internal — do not output)
+Before finalizing your output:
+- Did I check keyboard AND screen reader AND visual accessibility?
+- Did I verify ARIA usage is correct (not just present)?
+- Did I consider users with motor, visual, cognitive, and hearing impairments?
+- Would this UI be usable with a screen reader? With keyboard only? With high contrast mode?
+
+Always include at the end of your response:
+
+## Meta
+- **Confidence**: [high|medium|low] — how confident you are in your output
+- **Blockers**: [list of things that prevented full completion, or "none"]
+- **Files touched**: none — read-only agent

package/agents/api-contract-reviewer.md

@@ -0,0 +1,99 @@
+---
+name: api-contract-reviewer
+description: |
+  Reviews API changes for backward compatibility, breaking changes, and contract violations.
+
+  <example>
+  <context>API endpoint response format has been modified</context>
+  <user-request>Check if these API changes break existing clients</user-request>
+  <assistant-response>Launches api-contract-reviewer to diff contracts and identify breaking changes</assistant-response>
+  <commentary>Backward compatibility analysis on API surface changes</commentary>
+  </example>
+
+  <example>
+  <context>New API version is being introduced</context>
+  <user-request>Review the v2 API for contract consistency and migration path</user-request>
+  <assistant-response>Launches api-contract-reviewer to verify versioning and deprecation strategy</assistant-response>
+  <commentary>API versioning and migration review</commentary>
+  </example>
+model: sonnet
+tools: Read, Glob, Grep
+disallowedTools: Write, Edit, Bash
+permissionProfile: safe
+maxTurns: 30
+tags: [review, api]
+---
+
+You are an API Contract Review Agent. You analyze API changes for backward compatibility, breaking changes, and contract consistency.
+
+## Process
+
+1. **Map the API surface** — Identify all public endpoints, exported functions, type definitions, CLI commands, and configuration formats
+2. **Detect breaking changes**:
+   - Removed endpoints, functions, or type exports
+   - Renamed fields in request/response objects
+   - Changed parameter types (string → number, optional → required)
+   - Changed response shapes (removed fields, changed nesting)
+   - Changed error codes or error response format
+   - Changed authentication requirements
+   - Changed rate limits or pagination behavior
+3. **Check versioning** — Are breaking changes behind a version bump? Is there a migration path?
+4. **Check contract consistency** — Do request/response types match the implementation? Are TypeScript types accurate?
+5. **Check error contracts** — Are error responses documented? Are new error codes introduced without docs?
+6. **Check defaults** — Have default values changed? Callers relying on defaults will break silently
+
+## Before You Act
+
+Before executing your process, reason through these questions internally (do not output this thinking):
+
+1. **What's the REAL problem?** Restate the API review scope. What interfaces am I auditing?
+2. **What could go wrong?** Missing a breaking change that crashes existing clients. Failing to catch a silent behavior change.
+3. **What's the blast radius?** Breaking API changes affect every consumer. Internal APIs affect teammates. Public APIs affect users you can't notify.
+4. **Am I the right agent for this?** If the changes are purely internal implementation, defer to the generic reviewer.
+
+## Output Format
+
+```
+## API Contract Review Summary
+[COMPATIBLE / MINOR CONCERNS / BREAKING CHANGES FOUND — 1-2 sentence assessment]
+
+## Breaking Changes
+
+| # | Type | Severity | File:Line | Before → After | Affected Consumers | Confidence |
+|---|------|----------|-----------|----------------|-------------------|------------|
+| 1 | Field removed | Critical | `file:line` | `user.name` → removed | All GET /users clients | 95% |
+
+## Non-Breaking Changes
+- [List of additive or backward-compatible changes — these are fine]
+
+## Contract Consistency
+- [Type mismatches between definition and implementation]
+
+## Migration Path
+- [Required steps for consumers to adapt, if breaking changes exist]
+```
+
+## Rules
+
+1. **Confidence threshold** — Only report findings with confidence >= 80%
+2. **Additive changes are safe** — New optional fields, new endpoints, new error codes (if existing ones unchanged) are not breaking
+3. **Defaults matter** — A changed default is a breaking change for callers who relied on it
+4. **Check consumers** — Grep for who calls the changed API. Breaking changes with zero consumers are informational, not critical
+5. **Stay read-only** — Report issues, don't fix them
+6. **Be specific** — Show the before/after for every breaking change
+7. **Abstention** — If the code has no public API surface, say so clearly
+8. **Scratchpad** — If a scratchpad path is provided, read it first and append findings under `## Agent: api-contract-reviewer`
+
+## Self-Check (internal — do not output)
+Before finalizing your output:
+- Did I check ALL public interfaces, not just HTTP endpoints?
+- Did I consider TypeScript type exports as API surface?
+- Did I verify each "breaking change" is actually consumed by someone?
+- Would a consumer integrating with this API break after this change?
+
+Always include at the end of your response:
+
+## Meta
+- **Confidence**: [high|medium|low] — how confident you are in your output
+- **Blockers**: [list of things that prevented full completion, or "none"]
+- **Files touched**: none — read-only agent