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: triage → 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 installs /cc and /cc-cancel into each harness. Inside /cc, three entry modes cover task work, research, and continuation flows.

Why cclaw

• One pipeline, depth scales. Every task runs triage → architect → builder → reviewer → critic → ship. Plan-stage depth scales with ceremonyMode (lite for soft, rich for strict) instead of branching to a different specialist stack.
• Always-auto, hard stops on failure. The flow runs end-to-end without approval pickers at plan / review / critic gates. Hard failures stop and report with a plain-prose status block; resume with /cc, discard with /cc-cancel.
• 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 + a single TDD cycle. Large-risky tasks get a per-slice build with a pre-implementation plan-critic gate.
• Parallel by default. Independent slices in a plan run in parallel — N independent slices finish in the time of the longest, not the sum.
• Research as a separate entry point. /cc research <topic> runs an open-ended discovery dialogue and dispatches five parallel research lenses (engineer / product / architecture / history / skeptic). Output: a synthesised research.md. Optional handoff into a follow-up /cc <task> that consumes it as context.
• Continuation flow. /cc extend <slug> <task> loads a previously-shipped slug's plan.md / build.md / learnings.md (and review.md / critic.md / qa.md when present) as load-bearing 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; outcome signals (good / unknown / manual-fix / follow-up-bug / reverted) down-weight priors that didn't hold up.

When to use which command

Quickstart

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

# Inside your harness:
/cc add caching to the search endpoint
ls .cclaw/flows/20260515-search-caching/
# plan.md  build.md  review.md  critic.md  ship.md

The flow runs end-to-end. cclaw stops only on a hard failure (build broken, reviewer can't converge in 3 fixes, critic block-ship, catastrophic git/dispatch failure). Resume with /cc; discard with /cc-cancel. See Failure handling below.

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.

/cc invocation matrix

Modes

Three top-level entry points share the /cc slash-command surface. The orchestrator picks the mode from the first token after /cc.

/cc <task> — task mode

Runs the full triage → plan → build → review → critic → ship pipeline. The triage sub-agent picks complexity × ceremonyMode × path from heuristics, announces the choice in one line, and dispatches the first specialist. No clarifying questions; no structured ask.

Pin a ceremony level explicitly with mutually-exclusive flags:

/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 + architect's full Frame → Compose pass + per-slice commits + plan-critic gate

When the project has no .git/, the router auto-downgrades strict → soft even with --strict (per-slice commits need a SHA chain to be useful).

Classification work — surface detection, assumption capture, prior-learnings lookup, interpretation forks — lives inside the architect's Bootstrap + Frame phases on strict + soft, nothing on inline.

/cc research <topic> — research mode

A separate entry point for pre-task uncertainty: brainstorming, scope exploration, architecture comparison. Runs as a main-context orchestrator in four phases. Output: .cclaw/flows/<slug>/research.md. No build / review / critic / ship.

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

Phase 1 — open-ended discovery dialogue. The orchestrator opens with "Hi. What are you researching? Tell me what you know and what you don't." and runs an uncapped dialogue (no fixed question budget; no auto-advance). You refine the topic, name constraints, surface prior attempts, name stakeholders, mark scope edges. The orchestrator proceeds only when you signal ready / go ahead / finalize.

Phase 2 — parallel lens dispatch (5 lenses). The orchestrator distils the dialogue into a 5-15 bullet summary and dispatches all five research lenses in parallel:

Engineer + architecture lenses may dispatch the repo-research helper for brownfield context. Engineer / product / architecture / skeptic lenses may use a web-search MCP tool when one is wired (e.g. user-exa), falling back to training knowledge with a Notes: tag otherwise. History lens reads .cclaw/knowledge.jsonl + git log directly. Lenses run independently — no lens cites or chains into another.

Phase 3 — synthesis. The orchestrator pastes each lens's findings verbatim into the matching ## <Lens> lens section of research.md, then runs a cross-lens synthesis covering convergence (where 2+ lenses agree), divergence, the trade-off space, and confidence + coverage gaps. It then writes a recommended next step: exactly one of plan with /cc <task>, more research needed (specific area), or don't proceed (skeptic blocked: <reason>).

Phase 4 — finalize. git mv the artifact into .cclaw/flows/shipped/<slug>/research.md and emit a plain-prose handoff. 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. The handoff is optional — if research finalises and you never run a follow-up /cc, nothing else fires.

Research mode skips the router entirely — no triage gate, no complexity / ceremonyMode heuristic. The five lenses live in src/content/research-lenses/, install to .cclaw/lib/research-lenses/<lens>.md, and are NOT in the core SPECIALISTS array.

/cc extend <slug> <task> — continuation mode

Initialises a new flow that explicitly extends a previously-shipped slug. The orchestrator loads the parent's plan.md, build.md, learnings.md, and (when present) review.md / critic.md / qa.md as flowState.parentContext and surfaces them to architect / reviewer / critic as load-bearing context. Things already settled by the parent are not re-decided.

/cc extend 20260514-auth-flow add SAML login                   # canonical
/cc extend 20260514-auth-flow --strict refactor session store  # ceremony override wins over inheritance
/cc extend 20260514-cli-help fix typo in --help                # inheritance

The orchestrator runs the same pipeline as /cc <task>; the only difference is at init:

• Parent validation. loadParentContext confirms the slug is shipped + has a non-empty plan.md. Four failure modes are explicit: in-flight, cancelled, corrupted, missing. Each surfaces a one-line error and ends the turn.
• State stamp. flow-state.json > parentContext carries the parent's slug + status + shippedAt + structured artifact paths. Plan.md frontmatter carries parent_slug: <parent> and refines: <parent>.
• Triage inheritance. ceremonyMode / surfaces default to the parent's values. Explicit --strict / --soft / --inline flags override. A security-keyword heuristic (security / auth / migration / schema / payment / gdpr / pci) auto-escalates a soft/inline parent → strict for the new flow.
• Specialist consumption. The architect's Bootstrap reads the parent's ## Spec / ## Decisions / ## Selected Direction and authors a mandatory ## Extends section at the top of plan.md. The reviewer runs a parent-contradictions cross-check (silent reversals of a parent decision are required findings). The critic adds a skeptic question on parent decision contradictions.
• Knowledge-store integration. When parentContext is set, findNearKnowledge prepends the parent's knowledge.jsonl entry to the top of the prior-learnings result (load-bearing context overrides Jaccard ranking).

Only the immediate parent is auto-loaded. Specialists may use findRefiningChain on demand when transitive context is needed.

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

    R --> RD[Open-ended discovery dialogue]
    RD --> RL[Dispatch 5 lenses in parallel]
    RL --> RM["research.md (synthesis + recommendation)"]
    RM --> H{Handoff?}
    H -->|"accept research"| END[Finalize]
    H -->|next /cc| T

    E --> LC[loadParentContext<br/>shipped + plan.md required]
    LC -->|ok| EI[Stamp parentContext<br/>+ refines + parent_slug]
    EI --> EHE[Triage inheritance<br/>ceremonyMode/surfaces]
    EHE --> T
    LC -->|in-flight/cancelled<br/>/missing/corrupted| EERR[Surface error<br/>end turn]

    T --> RT[Triage sub-agent<br/>complexity × ceremonyMode × path]
    RT -->|inline| INL[Build inline]
    RT -->|soft| PL[architect Bootstrap+Frame]
    RT -->|strict| DS[architect full ceremony]
    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, chaining automatically. Slim-summary blocks land under ## Triage, ## Plan, ## Build, ## QA, ## Review, ## Critic, ## Ship headers in chat. Artifacts land on disk.

• Triage. The orchestrator dispatches triage with the raw /cc argument. Triage returns a 5-field decision in one slim summary — complexity: small-medium · ceremony mode: soft · path: plan → build → review → critic → ship · runMode: auto · mode: task — plus an ambiguity_score: <0-100> line computed from four signals (vague verbs, missing AC, multiple interpretations, no concrete names). Slug: 20260515-search-caching. Zero clarifying asks at the triage Hop itself. Persisted to flow-state.json > triage; immutable for the slug.
• Plan. The architect opens a Clarify phase (v8.67) when triage.ambiguityScore crosses config.clarify.ambiguity_threshold (default 60) AND ceremonyMode != "inline" — one question per turn, max 5, early-exit on go / ready / proceed. Below threshold or on inline path: skipped silently. Either way, the architect writes plan.md opening with a mandatory ## Assumptions (correct me now) block — Clarify answers are bare bullets, architect-silent inferences carry the (architect inference) tag. After plan.md lands, the orchestrator emits a one-line ack-window prose pointing the user at that section by name (/cc to continue with assumptions as-is, /cc-cancel to discard, or edit the plan in place). The rest of the plan body — Spec, Frame, Plan / Slices (SL-N work units — how we build), Acceptance Criteria (AC-N verification rows back-referencing slices), Edge cases, Topology, Feasibility, Traceability — is unchanged from pre-v8.67. 4 slices, 3 AC, 2 prior lessons surfaced via learnings-research. Confidence: high.
• Build. builder runs one TDD cycle per slice: RED → GREEN → REFACTOR. Each work commit carries an SL-N prefix (red(SL-1): / green(SL-1): / refactor(SL-1):) the reviewer reads via git log --grep="(SL-N):". Slices are dispatched in topological layers with independent slices running in parallel by default; a task with N independent slices finishes in the time of the longest slice, not Σ. Single-slice layers run inline (zero overhead); plan-critic verifies independence claims against surface overlap so parallel sub-builders never race. On strict mode the builder runs a two-stage per-slice review (spec-compliance first, then code-quality) inside its own context after each slice — issues surface where the diff is one slice wide, not where the chain has compounded. Two-attempt cap per stage; on persistent failure the slice's status is BLOCKED. The builder emits a structured Status: (DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED) the orchestrator routes deterministically — DONE_WITH_CONCERNS logs to build.md > ## Concerns; NEEDS_CONTEXT / BLOCKED stop and report. After all slices land, builder writes one verify(AC-N): passing commit per AC (empty diff when slice tests already cover the AC; test-files-only diff when the AC needs broader verification — perf budget, integration, contract). Tests: 14 passing (was 11). Coverage delta: +2.3%. Build failures trigger an auto-fix loop (up to 3 iterations); failure after 3 stops and reports.
• 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). Reviewer critical / required-no-fix triggers an auto-dispatch fix-only loop (up to 3 iterations); failure after 3 stops and reports. On security_flag: true slugs the reviewer walks the threat-model checklist verbatim in the security axis.
• Critic. Adversarial falsificationist pass — predictions, gap analysis, Criterion check across AC + Edge cases + NFR rows, goal-backward verification, realist check. Verdict: pass. block-ship stops immediately (no auto-iteration — re-running on unchanged code returns the same verdict).
• Ship. All 3 AC committed. ship.md carries the release-notes draft and the AC↔commit map. Chains automatically to push.

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.

Failure handling

cclaw stops at hard failures per a fixed matrix. The recovery loop is always the same: read the status block, decide, type /cc (continue) or /cc-cancel (discard). No in-chat picker, no [y/n] ask, no "approve this?" gate.

The status block names the stage, the reason, and the recovery options. Example:

Stopped at review (iteration 3). Reason: reviewer returned 2 critical findings after fix-only loop hit the 3-iteration cap.
To proceed: /cc to continue (continues from the saved state), or /cc-cancel to discard the slug.

What you get

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 legacy extra artifacts
architect:
  ambiguity_threshold: 0.2          # ambiguity soft-warning threshold

Architecture deep dive

The runtime is under 1 KLOC. The prompt content is where the work lives. To understand how /cc actually works, read the source under src/content/:

• src/content/start-command.ts — orchestrator body (detect, dispatch, always-auto chain, critic step, ship, compound, finalize).
• src/content/specialist-prompts/ — 7 specialist contracts.
• src/content/skills/ — 21 auto-trigger skill bodies.
• src/content/runbooks-on-demand.ts — 13 on-demand runbooks loaded 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.
• CHANGELOG.md — release history.

Artifact tree (after install)

.cclaw/
  config.yaml               flow defaults
  state/
    flow-state.json         active flow state (~500 bytes)
    knowledge.jsonl         compound learnings index
    triage-audit.jsonl      routing audit log
  flows/
    <slug>/                 one folder per active task
      plan.md
      build.md
      qa.md                 (UI/web slugs only)
      review.md
      critic.md
      plan-critic.md        (strict + complexity≠trivial + AC≥2)
      ship.md
      research.md           (/cc research <topic> only)
    shipped/<slug>/         finalized tasks (including research-mode flows)
    cancelled/<slug>/       /cc-cancel destination
  lib/
    agents/                 7 specialist contracts + 2 read-only research helpers (learnings-research / repo-research)
    research-lenses/        5 research-only lens contracts
    skills/                 21 auto-trigger skill bodies
    templates/              artifact templates
    runbooks/               13 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.

# 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.