cclaw

A multi-stage planning + review harness for coding agents.

Drops /cc into Claude Code, Cursor, OpenCode, and Codex. Every task flows through triage → plan → build → review → critic → ship. Two reviewers run in series — a read-only walk over 14 axes, then an adversarial critic that falsifies what the reviewer cleared. Independent slices run in parallel worktrees. Sub-agents stay isolated; the orchestrator keeps the slug's history. Always-auto: no "approve this?" pickers between stages. Resume with /cc, discard with /cc-cancel.

Install

cd /path/to/your/repo
npx cclaw-cli@latest

The TUI auto-detects your harness. For CI / scripted installs:

npx cclaw-cli@latest --non-interactive install --harness=cursor

Supported harnesses: claude (CLAUDE.md or .claude/), cursor (.cursor/), opencode (opencode.json[c] or .opencode/), codex (.codex/ or .agents/skills/). Same .cclaw/ runtime, harness-namespaced ambient rules — install once per harness if you use more than one.

Use

Four entry shapes share the /cc surface:

# 1. Ship a code change end-to-end.
# Triage → plan → build → review → critic → ship, chained automatically.
/cc add caching to the search endpoint

# 2. Open-ended research, no build.
# Dispatches up to 6 research lenses in parallel; synthesises research.md.
/cc research storage strategy for shared agent memory

# 3. Post-ship micro-edit on a shipped slug.
# Skips triage / plan-critic / critic; single commit, parent context reused.
/cc patch 20260514-auth-flow rename loginUser to authenticateUser

# 4. Full follow-up arc on a shipped slug.
# Parent's plan / build / learnings load as context for the new flow.
/cc extend 20260514-auth-flow add SAML login

# Cancel the active flow.
/cc-cancel

Slim summaries land in chat under ## Triage, ## Plan, ## Build, ## Review, ## Critic, ## Ship; artifacts land on disk under .cclaw/flows/<slug>/. cclaw stops only on hard failures (build broken, reviewer can't converge in 3 fixes, critic block-ship, irreversible decision pending user confirmation). The status block names the stage and the reason — type /cc to continue or /cc-cancel to discard.

How it works

triage picks the ceremony tier from the task shape and dispatches the first specialist. Each specialist runs in isolation, writes one artifact, returns one slim summary; the orchestrator forwards the slug's history but nothing else. After build, two reviewers run in series — a read-only reviewer walks 14 quality axes, then an adversarial critic falsifies what the reviewer cleared (separate contexts, separate artifacts). On UI / SDK surfaces, plan-critic gates the plan against a design or DevEx rubric before build burns context. Bug reports route through an investigator ahead of architect. Shipped slugs emit learnings.md; future plans read prior lessons through knowledge.jsonl before authoring.

flowchart LR
 U[user] -->|"/cc <task>"| T[triage]
 U -->|"/cc research <topic>"| RES[research orchestrator]
 U -->|"/cc patch <slug>"| PT[load parent context]
 U -->|"/cc extend <slug>"| EX[load parent context]
 EX --> T
 PT --> B
 T --> AR[architect]
 AR --> PC[plan-critic gate]
 PC --> B[builder]
 B --> RV[reviewer]
 RV --> C[critic]
 C --> S[ship]
 RES --> RM[research.md]

Ceremony modes

| Mode | When triage picks it | Pipeline | |------|---------------------|----------| | inline | trivial edits — typo, comment, one-line fix; also auto-set on /cc patch | one commit, no plan | | soft (default) | small / medium tasks | architect → single TDD cycle → reviewer → critic → ship | | strict | risky / multi-slice / security / migration | architect → plan-critic gate → per-slice TDD → reviewer (dual-chain) → critic → ship |

Triage announces its auto-pick in one line before the first specialist runs, so you can see what was chosen and reframe the task on the next invocation if the tier is wrong. The triage heuristic is the source of truth for the tier; v8.112 retired the per-flow ceremony override flags in favour of trusting the router. Pin via the task wording itself ("just a typo", "small refactor", "auth migration") — the heuristic reads those signals deterministically.

Configuration

.cclaw/config.yaml is optional. Defaults are good — every knob below is opt-in.

| Knob | Default | Purpose | | --- | --- | --- | | harnesses | (set at install time; merged on re-install) | List of harnesses to wire (claude / cursor / opencode / codex). v8.109 — re-running install --harness=<id> MERGES with the existing list instead of replacing it. | | legacyArtifacts | false | Keep the pre-v8.11 9-artefact layout (separate manifest.md / pre-mortem.md / decisions.md) instead of the consolidated plan.md shape. | | compoundRefreshEvery | 5 | Run the compound-refresh sub-step every Nth capture (T2-4 everyinc). Set to 0 to disable. | | compoundRefreshFloor | 10 | Minimum knowledge.jsonl entries the floor gate requires before compound-refresh fires. Belt-and-braces with compoundRefreshEvery. | | captureLearningsBypass | false | Skip the learnings hard-stop structured-ask in CI / autonomous pipelines that can't surface an interruption. | | modelPreferences.<specialist> | per-specialist (see src/config.ts DEFAULT_MODEL_PREFERENCES) | Tier hint (fast / balanced / powerful) passed through to the harness's model router on dispatch. | | clarify.ambiguity_threshold | 60 | triage.ambiguityScore >= this AND ceremonyMode != "inline" opens the architect's Clarify phase before Bootstrap. Integer in [0, 100]. | | critic.cross_model | false | Opt-in second adversarial critic pass via a different model through an available MCP cross-model tool (Codex / Gemini / etc.) on high-stakes slugs. | | critic.cross_model_min_context | 16000 | Minimum char budget the second-opinion model needs before the critic dispatches; below this the critic refuse-and-skip path fires (v8.108 §3.5 priority-drop). |

Example:

harnesses: [claude, cursor]
critic:
  cross_model: false # opt-in second adversarial pass via a different model (MCP)
  cross_model_min_context: 16000 # v8.108 — refuse-and-skip below this budget
clarify:
  ambiguity_threshold: 60 # default; lower = more Clarify, higher = less
modelPreferences:
  builder: balanced # default fast
  reviewer: powerful # default balanced
  critic: balanced # default powerful
compoundRefreshEvery: 5
compoundRefreshFloor: 10
captureLearningsBypass: false

Deeper docs

The runtime is < 1 KLOC; behaviour lives in prompt content under src/content/. To understand how /cc actually works, read the source:

• src/content/start-command.ts — orchestrator body (detect, dispatch, ship, compound)
• src/content/specialist-prompts/ — 8 specialist contracts (triage, investigator, architect, builder, plan-critic, qa-runner, reviewer, critic)
• src/content/skills/ — 34 auto-trigger skills loaded per stage
• src/content/research-lenses/ — 6 research lenses dispatched on /cc research
• src/content/runbooks-on-demand.ts — 28 on-demand runbooks loaded by trigger
• src/content/artifact-templates.ts — plan / build / qa / review / critic / ship templates
• src/content/anti-rationalizations.ts — cross-cutting rebuttal catalog
• CHANGELOG.md — release history with every flag, gate, rubric, and version
• CONTRIBUTING.md — dogfooded; new behaviour usually means new prompt content under src/content/, not new TypeScript

License

MIT. See LICENSE.