Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (cclaw-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

cclaw

cclaw is a file-backed flow runtime for coding agents. It turns Claude Code, Cursor, OpenCode, and Codex into one repeatable path from idea to shipped change: visible stages, hard gates, real subagent evidence, and resumable closeout in your repo.

        idea
         |
         v
   +-------------+      +--------+      +--------+      +------+      +------+      +-----+
   | brainstorm  | ---> | scope  | ---> | design | ---> | spec | ---> | plan | ---> | tdd |
   +-------------+      +--------+      +--------+      +------+      +------+      +-----+
                                                                                       |
                                                                                       v
                                                                                  +--------+      +------+
                                                                                  | review | ---> | ship |
                                                                                  +--------+      +------+
                                                                                                      |
                                                                                                      v
                                                                                         retro -> compound -> archive

The promise is simple: at any point you can ask where are we, what is blocked, what evidence exists, and what should run next?

First 5 Minutes

Requirements: Node.js 20+ and a git project root.

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

Then work from your coding harness:

/cc <idea>          start a tracked flow
/cc-next            resume or advance the current flow
/cc-view status     inspect current state without changing it

For scripted setup:

npx cclaw-cli init --harnesses=claude,cursor --no-interactive

If generated files or hooks look stale, run cclaw doctor. If they need to be regenerated, run npx cclaw-cli sync.

Why cclaw

AI coding sessions fail when decisions live only in chat. cclaw puts the operating truth in files:

.cclaw/
  artifacts/              active stage docs: 00-idea.md through 09-retro.md
  state/flow-state.json   current stage, gates, stale markers, closeout.shipSubstate
  state/delegation-log.json
                           subagent dispatches, waivers, evidence refs
  knowledge.jsonl         reusable lessons harvested from stage artifacts
  runs/                   archived run snapshots

That gives you:

One path from idea to ship, with quick, medium, and standard tracks.
Real gates for evidence, tests, review, delegation, stale-stage recovery, and closeout.
Subagents with accountability: controller owns state, workers do bounded tasks, overseers validate, evidence lands in delegation-log.json.
Recovery instead of confusion: /cc-view status tells you the blocker and the next command.
Portable harness behavior across Claude Code, Cursor, OpenCode, and Codex.

The Daily Loop

1. Start or resume
   /cc <idea>    or    /cc-next

2. Work the current stage
   The agent writes/updates .cclaw/artifacts/<stage>.md

3. Prove the gate
   stage-complete records evidence in flow-state.json

4. Inspect when stuck
   /cc-view status

5. Close out after ship
   /cc-next continues retro -> compound -> archive

Tracks keep the flow proportional:

quick     spec -> tdd -> review -> ship
medium    brainstorm -> spec -> plan -> tdd -> review -> ship
standard  brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship

Track selection is model-guided and advisory during /cc. Runtime enforcement begins after state is written: /cc-next follows the selected track, required gates, delegation rules, stale-stage markers, and closeout.shipSubstate.

When Blocked

Start here:

/cc-view status

A useful status should read like an operator note, not a raw dump:

Current: tdd (standard)
Blocked by: NO_SOURCE_CONTEXT
Next: cclaw internal rewind plan "add bootstrap slice", then /cc-next
Evidence needed: fresh RED/GREEN/REFACTOR slice and verification output

Common exits:

Situation	Next action
Missing gates	Run `/cc-next`, finish the stage, then complete with evidence.
Mandatory delegation missing evidence	Dispatch the worker/overseer or waive explicitly with rationale.
`NO_SOURCE_CONTEXT` or `NO_TEST_SURFACE`	Rewind to `plan`/`spec`, define the source or test surface, then resume TDD.
`NO_IMPLEMENTABLE_SLICE` or `RED_NOT_EXPRESSIBLE`	Rework `design`/`spec`/`plan` until one vertical slice is testable.
`NO_VCS_MODE`	Restore git, set `vcs: none` with hash evidence, or configure `tdd.verificationRef`.
Review blocked	`cclaw internal rewind tdd "review_blocked_by_critical <finding-ids>"`.
Stale stage after rewind	Redo the marked stage, then `cclaw internal rewind --ack <stage>`.
Broken hooks or generated files	`cclaw doctor`, then `npx cclaw-cli sync` if needed.

Subagents Without Theater

user goal
   |
   v
controller ---------------> worker: bounded implementation/test/doc task
   |                         |
   |                         v
   +----------------------> overseer: read-only validation
                             |
                             v
                     evidence refs + terminal status
                             |
                             v
                 .cclaw/state/delegation-log.json

The controller owns flow-state.json, sequencing, synthesis, and the final answer. Workers own scoped work. Overseers verify. A waiver means the work was not done by a real worker and must say why proceeding is acceptable.

What Is Enforced

Enforced by generated helpers and state checks:

Stage completion goes through node .cclaw/hooks/stage-complete.mjs <stage>.
Required gates need evidence before advancement.
Mandatory delegations need terminal evidence or explicit waiver.
Stale stages block until redone and acknowledged.
Review criticals route back to TDD.
Ship continues through retro -> compound -> archive with closeout.shipSubstate.

Advisory/model-guided:

Initial track heuristic wording.
Proactive subagents that are not mandatory for the active stage/tier.
Reference patterns that shape prompts but do not add runtime states.

The Deeper Contract

The README is the front door. The full operating contract lives here:

Scheme of Work: stages, gates, recovery, closeout, state files.
Configuration: strictness, tracks, TDD, compound, language packs, hooks.
Harnesses: Claude, Cursor, OpenCode, Codex capabilities and fallbacks.
Generated Agent Block Example: what gets injected into harness guidance.

CLI Reference

npx cclaw-cli                   # interactive setup or installed status hint
npx cclaw-cli init --harnesses=<list> --no-interactive
npx cclaw-cli sync              # regenerate managed runtime files
npx cclaw-cli upgrade           # refresh generated files while preserving config
npx cclaw-cli archive           # explicit archive/reset; normal closeout uses /cc-next
npx cclaw-cli uninstall         # remove .cclaw and generated harness shims
npx cclaw-cli --version

License

MIT