cclaw

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

cclaw drops a /cc slash command into Claude Code, Cursor, OpenCode, or Codex. It routes the task, picks the right amount of ceremony, and runs the work through a fixed pipeline: route → plan → build → qa → review → critic → ship. Each stage emits a slim summary back to the harness and writes a tracked artifact under .cclaw/flows/<slug>/. Sub-agents are isolated; the orchestrator keeps the slug's history.

cclaw v8.58 ships two entry points: /cc <task> (the historical default — runs the full route → plan → build → ship pipeline) and /cc research <topic> (a standalone brainstorming entry that runs the design specialist in research mode and stops at the synthesis artifact). See Modes below.

Why cclaw

• Pipeline, not autopilot. Every stage pauses at a structured gate so the human can read the artifact, edit it, or /cc-cancel. There is no "let it run for an hour and hope".
• Two-model review. A read-only reviewer walks ten axes; an adversarial critic falsifies what the reviewer cleared. They share no context and write to separate artifacts (review.md, critic.md).
• Right-sized ceremony. Trivial edits run inline (one commit, no plan). Small/medium tasks get a soft-mode plan and a single TDD cycle. Large-risky tasks get a full per-criterion build with a pre-implementation plan-critic gate.
• Lightweight router. v8.58 — the routing hop is zero-question by default (no structured ask, no clarifying prompt). Explicit override flags (/cc --inline <task> / /cc --soft <task> / /cc --strict <task>) short-circuit the heuristic when you want to pin a ceremony level. Classification work (surface detection, assumption capture, prior-learnings, interpretation forks) moved into the specialist that already has the codebase context — design Phase 0-2 on strict, ac-author Phase 0-1 on soft.
• Research mode. v8.58 — /cc research <topic> is a separate entry point for pre-task uncertainty: brainstorming, scope exploration, architecture comparison. Runs the design specialist standalone (Phase 0 Bootstrap → Phase 6 Compose), emits a research.md synthesis artifact, and stops. Optional handoff into a follow-up /cc <clarified task> flow that consumes the research as priorResearch context.
• Same runtime, four harnesses. Claude Code, Cursor, OpenCode, and Codex all read the same .cclaw/ install. Each harness gets the same /cc body plus harness-namespaced ambient rules.
• Compound learnings. Non-trivial slugs emit a learnings.md. Future runs read prior shipped lessons through knowledge.jsonl before authoring a plan; v8.50 outcome signals (good / unknown / manual-fix / follow-up-bug / reverted) down-weight priors that didn't hold up.

Quickstart

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

# Inside your harness:
/cc add caching to the search endpoint

# After cclaw pauses at a gate, type /cc again to resume.
# Artifacts land in .cclaw/flows/<slug>/.
ls .cclaw/flows/20260515-search-caching/
# plan.md  build.md  review.md  critic.md  ship.md

For CI / scripted installs, use the non-interactive escape hatch:

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

There is no cclaw plan, cclaw build, or cclaw status. Flow control lives inside /cc.

Modes

v8.58 ships two top-level entry points. Both invocations use the same /cc slash-command surface; the orchestrator picks which mode to run based on the first token after /cc.

/cc <task> — task mode (the historical default)

Runs the full route → plan → build → ship pipeline with all the gates. The router (formerly "triage") is zero-question by default — it picks complexity × ceremonyMode × path from heuristics and announces the choice in one line, then dispatches the first specialist. No clarifying questions; no structured ask. If you want to pin a ceremony level explicitly, pass one of:

/cc --inline <task>    # forces inline edit (one commit, no plan)
/cc --soft <task>      # forces soft-mode plan → build → review → ship
/cc --strict <task>    # forces strict + design Phase 0-7 + per-criterion commits + plan-critic gate

The flags are mutually exclusive and orthogonal to the --mode=auto / --mode=step runMode toggle (/cc --strict --mode=auto <task> is valid). When the project has no .git/, the router auto-downgrades strict → soft even with --strict (per-criterion commits need a SHA chain to be useful).

What used to live at the router — surface detection, assumption capture, prior-learnings lookup, interpretation forks — now lives inside the specialist that has the codebase context to do it well: design Phase 0-2 (strict), ac-author Phase 0-1 (soft), nothing (inline). Pre-v8.58 state files continue to validate verbatim; readers default to mode: "task" when the field is absent.

/cc research <topic> — research mode (v8.58 new entry point)

Runs the design specialist in standalone activation mode — same Phase 0-6 as the in-flow brainstormer (Bootstrap → Clarify → Frame → Approaches → Decisions → Pre-mortem → Compose), but stops at Compose. Output: .cclaw/flows/<slug>/research.md. No build / review / critic / ship. The Phase 7 picker is a two-option accept research / revise (instead of the intra-flow three-option approve / request-changes / reject).

/cc research storage strategy for shared agent memory
/cc --research auth library trade-offs                 # equivalent

After accepting the research, the orchestrator surfaces a plain-prose handoff:

Ready to plan? Run /cc <clarified task description> and I'll carry the research forward as context.

The next /cc <task> invocation on the same project reads flow-state.json > priorResearch and consumes the most-recent shipped research as input to its plan stage (design Phase 0 / ac-author Phase 0 include the research artifact in their reads). The handoff is optional — if you accept the research and never run a follow-up /cc, nothing else fires.

Research mode skips the router entirely. There is no triage gate; no complexity / ceremonyMode heuristic runs. The orchestrator stamps a sentinel triage block (mode: "research", ceremonyMode: "strict", path: ["plan"]) so downstream readers that assume triage is present continue to work.

flowchart LR
    A[/cc input/] -->|"research <topic>" or --research| R[Research mode]
    A -->|"<task>"| T[Task mode]

    R --> D1[design standalone<br/>Phase 0-6]
    D1 --> RM["research.md"]
    RM --> H{Handoff?}
    H -->|"accept research"| END[Finalize]
    H -->|next /cc| T

    T --> RT[Router<br/>complexity × ceremonyMode × path]
    RT -->|inline| INL[Build inline]
    RT -->|soft| PL[ac-author Phase 0-1<br/>surfaces, assumptions, priorLearnings]
    RT -->|strict| DS[design Phase 0-7<br/>+ Phase 0-2 absorb classification]
    PL --> BD[plan → build → review → critic → ship]
    DS --> BD

Worked example

You type:

/cc add caching to the search endpoint

The orchestrator runs through these stages in order, pausing at each gate. The slim-summary blocks the orchestrator emits sit under ## Triage, ## Plan, ## Build, ## QA, ## Review, ## Critic, ## Ship section headers in chat. Artifacts land on disk.

• Triage (lightweight router). complexity: small-medium · ceremony mode: soft · path: plan → build → review → critic → ship · slug: 20260515-search-caching · mode: task. The router runs zero-question by default — no clarifying ask. The decision is persisted to flow-state.json > triage and is immutable for the slug. (v8.58 — surface detection / assumption capture / prior-learnings lookup moved into ac-author Phase 0-1 on the soft path; they used to live here.)
• Plan. ac-author writes plan.md — Spec section (Objective / Success / Out of scope / Boundaries), Frame, Acceptance Criteria, Edge cases, Topology, Feasibility stamp, Traceability block. 3 AC, 2 prior lessons surfaced from knowledge.jsonl. Confidence: high.
• Build. slice-builder runs one TDD cycle per criterion: RED → GREEN → REFACTOR. Each commit carries an AC-N prefix the reviewer reads via git log --grep. Tests: 14 passing (was 11). Coverage delta: +2.3%.
• Review. Ten-axis reviewer opens 2 findings on the first iteration: cache-key collision on case-sensitive queries (correctness, required) and missing TTL refresh on stale entries (architecture, consider). Fix-only re-review closes both findings.
• Critic. Adversarial falsificationist pass — predictions, gap analysis, Criterion check across AC + Edge cases + NFR rows, goal-backward verification, realist check. Verdict: pass.
• Ship. All 3 AC committed. ship.md carries the release-notes draft and the AC↔commit map. The picker asks before pushing.

After ship, the orchestrator moves the artifacts to .cclaw/flows/shipped/<slug>/ and (when the slug earned capture) appends one row to .cclaw/state/knowledge.jsonl.

What you get

Utility commands

Beyond the main /cc flow, cclaw installs two direct-callable utility commands into each enabled harness. They are escape valves for ad-hoc moments — when the full plan → build → review → critic → ship ceremony is too heavy for the task at hand. Both commands reuse the same specialist contracts the /cc flow dispatches, but skip flow state, triage, the artifact tree, and slug tracking.

• /cclaw-review [<git-ref-or-paths>] — run the reviewer's 10-axis pass directly on a diff or set of files. Default: staged changes (git diff --cached); falls back to git diff HEAD when nothing is staged. Accepts a git ref or ref range (e.g. HEAD~3..HEAD) or one or more file paths. Pass --out <path> to write findings as markdown.
• /cclaw-critic <path> — run the critic's adversarial 8-section protocol (predictions, gap analysis, 4 falsification techniques, lens sweep, criterion check, goal-backward, realist check, verdict) against any document: a plan written outside cclaw, a design doc, an RFC, a PR description, an ADR, a README. Pass --out <path> to write findings as markdown.

Both commands emit findings directly to chat. Neither touches .cclaw/state/flow-state.json, .cclaw/flows/<slug>/, or any flow artifact. For the full slug ceremony (AC, plan traceability, per-criterion commits, post-implementation critic), use /cc <task> instead.

Harnesses supported

Run npx cclaw-cli@latest and the TUI auto-detects whatever you have. For CI / scripted installs, pass --non-interactive install --harness=<id>[,<id>] (comma-separated; supported ids: claude, cursor, opencode, codex).

Configuration

.cclaw/config.yaml is optional. Defaults are good. Common knobs:

harnesses: [claude, cursor]
reviewerTwoPass: false              # opt-in: spec-review + code-quality-review split
compoundRefreshEvery: 5             # how often to dedup knowledge.jsonl
compoundRefreshFloor: 10            # minimum entries before refresh kicks in
captureLearningsBypass: false       # true = silent skip on non-trivial slugs
legacy-artifacts: false             # true brings back v8.11-era extra artifacts
design:
  ambiguity_threshold: 0.2          # v8.53 — design Phase 7 soft warning threshold

Architecture deep dive

The runtime is under 1 KLOC. The prompt content is where the work lives. If you want to understand how /cc actually works, read the source — the on-disk reference lives under src/content/:

• src/content/start-command.ts — orchestrator body (detect, triage, dispatch, pause/resume, critic step, ship, compound, finalize).
• src/content/specialist-prompts/ — 8 specialist contracts.
• src/content/skills/ — 21 auto-trigger skill bodies.
• src/content/runbooks-on-demand.ts — 11 on-demand runbooks the orchestrator opens by trigger.
• src/content/artifact-templates.ts — plan / build / qa / review / critic / plan-critic / ship / learnings templates.
• src/content/anti-rationalizations.ts — cross-cutting rebuttal catalog (v8.49+).
• CHANGELOG.md — release history.

Artifact tree (after install)

.cclaw/
  config.yaml               flow defaults
  ideas.md                  /cc-idea drops land here
  state/
    flow-state.json         active flow state (~500 bytes)
    knowledge.jsonl         compound learnings index
    triage-audit.jsonl      v8.44 audit log
  flows/
    <slug>/                 one folder per active task
      plan.md
      build.md
      qa.md                 (v8.52+, UI/web slugs only)
      review.md
      critic.md             (v8.42+)
      plan-critic.md        (v8.51+, strict + complexity≠trivial + AC≥2)
      ship.md
      research.md           (v8.58+, /cc research <topic> only — design standalone synthesis)
    shipped/<slug>/         finalized tasks (including research-mode flows)
    cancelled/<slug>/       /cc-cancel destination
  lib/
    agents/                 8 specialist contracts
    skills/                 21 auto-trigger skill bodies
    templates/              artifact templates
    runbooks/               11 on-demand runbooks
    patterns/               reference patterns
    anti-rationalizations.md
    antipatterns.md

CLI surface

Two invocations cover every use case. There is no cclaw plan / cclaw status / cclaw build / cclaw ship — flow control lives inside /cc. The bare subcommand surface (init, sync, upgrade) was retired in v8.29 + v8.37.

# Interactive (humans): opens a TUI menu — Install / Uninstall / Quit
npx cclaw-cli@latest

# Non-interactive (CI / scripts): explicit command, no TUI
npx cclaw-cli@latest --non-interactive install [--harness=<id>[,<id>]]
npx cclaw-cli@latest --non-interactive uninstall
npx cclaw-cli@latest --non-interactive knowledge [--tag=<tag>] [--surface=<sub>] [--type=<kind>] [--all] [--json]
npx cclaw-cli@latest --version
npx cclaw-cli@latest --help

install is idempotent and runs orphan cleanup, so it handles first-time setup, re-sync after a package upgrade, and stale-file cleanup in one command. The TUI menu and the --non-interactive install path share the same installer code — they are byte-for-byte identical in write behaviour.

Contributing

cclaw is dogfooded — every release is shipped via /cc against itself. To contribute:

1. Fork and clone.
2. npm install && npm run build && npm test (the test suite is the spec; PRs without test updates are rare).
3. Run /cc <your change> inside a cclaw-installed harness, or write tests + code directly.
4. Open a PR. CI runs lint, typecheck, unit tests, integration tests, and a smoke runtime test.

The runtime stays under 1 KLOC; new behaviour usually means new prompt content under src/content/, not new code under src/.

License

MIT. See LICENSE.