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). On high-stakes work (security_flag / irreversible D-N) or when invoked with --critic-cross-model, the critic optionally runs a second adversarial pass via a different model (Codex / Gemini via MCP) for an independent second opinion (v8.72).
• 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.
• Pre-build design audit on UI surfaces. On any flow whose triage detects a UI / design / frontend / UX surface in soft or strict ceremony, the v8.75 plan-design specialist walks plan.md against a 7-dimension design-quality rubric (visual hierarchy / type system / color / spacing / interaction affordances / accessibility (WCAG AA) / responsive) before the build runs. Below-6 grades become PD-N findings appended to plan.md; severity ≥ medium blocks ship in strict mode. The same rubric the post-build reviewer applies to the rendered diff is applied here to the plan's design commitments — design bets are challenged once at plan-time and once after the diff lands, with the rubric pinned in a single shared TypeScript const so the two surfaces never drift.
• 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, surfaces an Approaches Gate (Phase 1.5; 2-3 candidate framings of the question, user picks one / many / all default), and dispatches research lenses in parallel (engineer / product / architecture / history / skeptic / design — six lenses on standard+ depth when the topic touches UI/UX, --lens=design force-includes / --lens=-design force-excludes). Depth tiers (--light / --standard / --deep-product) gate the lens set; lenses dispatch first-class web search via MCP (user-exa, user-context7); synthesis runs a four-scan self-review before research.md lands. 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
/cc research --light is fastify still maintained                # 2 lenses, fast clarification
/cc research --deep-product should we replace our calendar     # 5-6 lenses + extra probes (design lens on UI topics)
/cc research --lens=design rework the settings modal           # force-include design lens
/cc research --lens=-design pure backend cache substrate         # force-exclude design lens

Depth tiers (v8.69). The orchestrator picks one of three tiers at the Detect-hop research-mode fork — either explicitly via --light / --standard / --deep-product or auto-classified from topic wording (clarification → light; technical exploration → standard; greenfield / pivot wording → deep-product). Mutually-exclusive flags collapse last-wins.

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 1.5 — Approaches Gate (v8.76). Between the discovery dialogue and lens dispatch, the orchestrator distils 2-3 candidate framings of the research question (NOT 2-3 implementation candidates — each framing changes WHICH dimensions every lens emphasises). You pick a single framing (A), multiple (A B), substring-match a framing title, or accept all / every / silent default (every framing flows to every lens — the canonical broad-coverage case). Selected framings carry forward into every lens envelope as a new Framing: field. Reframings mid-research route through the existing /cc research push-back machinery. Reference patterns: obra-superpowers brainstorming Phase 2-3, addyosmani idea-refine Phase 1.3 Cluster + Stress-test.

Phase 2 — parallel lens dispatch. The orchestrator distils the dialogue into a 5-15 bullet summary, stamps the selected framings, and dispatches the depth-determined lens subset in parallel:

Engineer + architecture lenses may dispatch the repo-research helper for brownfield context. Engineer / product / architecture / skeptic / design lenses dispatch first-class web search via MCP (v8.69 for the first four; v8.76 for design) — user-exa for general web search, user-context7 for library / framework / API docs — and cite hits inline in their ### Sources block. The design lens treats web search as default-on (the design space — shadcn, Radix, Material 3 — is high-churn). When no MCP tool is wired, lenses fall back to training knowledge with a Notes: tag stamping the fallback. History lens is memory-only (web search is out of scope). Lenses run independently — no lens cites or chains into another.

Phase 3 — synthesis + self-review. 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. Before research.md is written to disk, the orchestrator walks the draft through a four-scan self-review (placeholder / contradiction / scope drift / ambiguity) and fixes findings inline; cleanups land in ## Synthesis > ### Self-review notes. 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 3.5 — awaiting user review (v8.71). After Phase 3 lands research.md, the orchestrator stamps flow-state.json > researchState: "awaiting-user-review" and surfaces three follow-ups in plain prose. The user picks one:

• /cc research revise <area> — re-dispatches the lens(es) covering <area> (engineer / product / architecture / history / skeptic / design / synthesis / all), re-runs synthesis + self-review, rewrites research.md. Cycles back to awaiting-user-review so the user can iterate again.
• /cc research push-back <claim> — re-dispatches research-skeptic plus the lens that authored the cited claim. The skeptic surfaces counter-arguments under ### Counter-arguments to <claim>; the authoring lens reaffirms / qualifies / retracts. Synthesis re-runs focused on the divergence paragraph. Same cycle-back.
• /cc research accept — terminal. Appends an accept row to ## Revision history, runs Phase 4 finalize, emits the handoff.

Each revise / push-back / accept appends a row to research.md > ## Revision history (and a matching entry to flow-state.json > revisions[]). The table is the append-only audit trail — five columns: timestamp, kind, area-or-claim, lenses re-dispatched, change. Lifecycle states stamped at every Phase boundary: discovery → lens-dispatch → synthesis → awaiting-user-review ⇄ revising → accepted. Reference patterns: obra-superpowers brainstorming User Review Gate, addyosmani idea-refine divergent-then-converge, everyinc-compound ce-brainstorm Phase 2.5 confirmation gate. Full procedure in runbooks/research-revision.md.

Phase 4 — finalize. Fires only after /cc research accept. 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 (including the ## Revision history block) 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 six 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 --> RA[Approaches Gate: pick framings]
    RA --> RL[Dispatch up to 6 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

cclaw ships a single-source-of-truth ethos preamble at .cclaw/lib/cclaw-ethos.md — five cross-cutting principles (Boil the Lake: gather evidence before deciding; Search Before Building: check existing patterns first; Surgical Edits: smallest diff that delivers; User Sovereignty: user decisions overrule defaults; Three knowledge layers: Layer 1 tried-and-true, Layer 2 popular, Layer 3 first-principles — question Layer 1/2 when stakes warrant). The preamble is auto-prepended to every specialist dispatch envelope as the Required ethos read, one position above the agent contract. Specialist contracts refine HOW each principle applies to their stage; they do not restate the principles themselves. When a specialist's local rule appears to contradict an ethos principle, the ethos wins and the local rule is the bug.

Strict-mode plans classify every D-N decision by reversibility — one of one-way (irreversible-or-effectively-so: data migration, public-API removal, schema rewrite, destructive auth/cryptography, payment commit), two-way (cheaply reversible: feature flag, internal-API behind compat shim, behaviour tweak behind kill switch), or mostly-two-way (the middle ground: schema column add, new dependency, UI surface shipped to users). The classification is borrowed from Bezos's one-way/two-way door framing. plan-critic §A blocks ship on a missing field; the cross-model critic's §3.5 second opinion auto-fires on any one-way decision regardless of triage.securityFlag (keyword detection on Blast-radius prose is preserved as a fallback for plans with no ## Decisions section). Both critic (adversarial mode) and plan-critic open with an explicit force-stance clause that flips the default cognitive posture from balanced review to "find disqualifying evidence first".

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
critic:
  cross_model: false                # opt-in (v8.72): second adversarial pass via a
                                    # different model through MCP on high-stakes
                                    # slugs. Always available on demand via the
                                    # `/cc --critic-cross-model` flag regardless
                                    # of this knob. Graceful fallback when no
                                    # MCP cross-model tool is wired.

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/ — 8 specialist contracts.
• src/content/skills/ — 25 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)
                            (plan-design findings appear inline in plan.md
                             under `## Plan-design findings` when the v8.75
                             design-surface gate fires; no separate file)
    shipped/<slug>/         finalized tasks (including research-mode flows)
    cancelled/<slug>/       /cc-cancel destination
  lib/
    agents/                 8 specialist contracts + 2 read-only research helpers (learnings-research / repo-research)
    research-lenses/        5 research-only lens contracts
    skills/                 25 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.