GitHub Showcase Quickstart

GitHub Showcase: Quickstart

Requirements

• Node.js 18 or newer.
• An external agent command for live reviews, such as Claude Code, Codex, or an HTTP agent endpoint.

The tamper-evidence demo does not need an agent, API key, or cloned repo.

Install

npx cool-workflow … needs no install. To put cw on your PATH, pick one:

npm

npm install -g cool-workflow

Homebrew — one tap of this repo; there is no separate homebrew-* tap repo:

brew tap coo1white/cool-workflow https://github.com/coo1white/cool-workflow
brew install coo1white/cool-workflow/cool-workflow
cw version   # prints the installed release

Upgrade later with brew update && brew upgrade cool-workflow. The formula pins its source to the matching git tag, so brew install works without a new release and needs no checksum step.

If you also have an npm-global cw, the one earlier in your PATH wins when you type cw. To run the Homebrew build for sure, use its full path: "$(brew --prefix)/bin/cw" version.

1. Prove The Integrity Demo

npx cool-workflow demo tamper

Expected result: stdout ends with a VERDICT: tamper-evidence holds line. The demo builds a signed report and forges it three ways — flipping a ledger verdict, reusing a signature over inflated tokens, and editing a signed finding — and shows all three being detected offline, with only the public key.

For a scriptable proof payload:

npx cool-workflow demo tamper --json

The JSON includes proven: true, the number of ledger records, and one result per tamper layer.

2. Run A Real Repo Review

npx cool-workflow quickstart architecture-review \
  --repo /path/to/your/project \
  --question "What are the main risks in this codebase?" \
  --agent-command builtin:claude

Or point it at a folder from anywhere, or a remote repo by URL — no cd needed:

cw -q "What are the main risks here?" -dir /path/to/your/project
cw -q "What are the main risks here?" --link https://github.com/owner/repo
cw -q "What are the main risks here?" --link https://github.com/owner/repo/archive/refs/heads/main.tar.gz

--link clones any git host (or downloads a .tar.gz/.zip) into a content-addressed, fail-closed cache and reviews the checkout. The report records Source: <url>@<commit> plus a tamper-evident audit event; manage the cache with cw clones list / cw clones gc. Validate a URL without fetching: cw -q "…" --link <url> --check.

While it runs you get a calm, Claude-Code-style live view — a compact rolling window that updates in place instead of an endless wall:

● Read(execution-backend.ts)
  ⎿ 910 lines
● Grep(spawnSync)
  ⎿ 17 matches
✶ Searching worker-isolation.ts… (3s)

Each tool folds to a ● ToolName(arg) line with a dim ⎿ result summary; older steps fold away (the window stays a few rows) and the worker collapses to one line when done. It's compact by default (reasoning hidden); --verbose shows the full agent narration, --full also prints the report inline, and --no-color drops ANSI (NO_COLOR / FORCE_COLOR are honored). The complete narration + tool I/O is always saved to a per-worker transcript.md, and at the end CW prints a compact findings table (id / severity / classification) with the report path and the run dir. It's vendor-neutral — CW renders this itself for any agent backend (Claude / Codex / Gemini / OpenCode), with the ⎿ result lines on Claude today — and with --json stdout stays pure data (all the chrome goes to stderr, on a TTY only).

The command prints JSON that includes a runId, status, worker counts, and a reportPath.

Read the report:

cat /path/to/your/project/.cw/runs/<run-id>/report.md

If the agent is not configured, CW returns status: blocked. That is expected fail-closed behavior: the run is saved for triage, but CW does not fabricate a completed report.

Check the agent backend before a live run:

cw backend probe agent --json

When no command or endpoint is configured, the probe reports ready: false and a reason naming the missing CW_AGENT_COMMAND or CW_AGENT_ENDPOINT.

3. Try A Resumable Run

Advance one step and stop:

cw quickstart architecture-review \
  --repo /path/to/your/project \
  --question "What should I audit first?" \
  --agent-command builtin:claude \
  --resume

Continue the same run:

cw quickstart architecture-review --run <run-id> --resume

You can also resume through the registry:

cw run resume <run-id> --drive

The default run resume view is read-only. Adding --drive hands pending work to the existing agent delegation loop.

Re-running after a change? Add --incremental and CW reuses the cached result of every step whose inputs are unchanged, so only the first changed task and what depends on it run again:

cw run <app> --drive --incremental

4. Hand The Report To Someone (Verify Offline)

Seal a finished run into one portable file. The recipient needs nothing but the file and the public key:

cw -q "…" --bundle                              # seal the run into report.cwrun.json
cw report verify-bundle report.cwrun.json       # they check it offline
cw report verify-bundle report.cwrun.json \
  --require-signatures                          # …and insist the findings are signed

verify-bundle re-proves the archive bytes, the telemetry and trust-audit chains, and the ed25519 signatures, and confirms every signed finding is in the report unaltered — all offline, with only the public key. See Trust And Audit for exactly what this proves.

From A Source Checkout

cd plugins/cool-workflow
npm install
npm run build
node scripts/cw.js app list
node scripts/cw.js demo tamper

Run the deterministic integration proof:

npm run golden-path

It exercises app validation, planning, dispatch, worker output, candidate selection, verifier-gated commit, report generation, status, and graph views.

Troubleshooting

Symptom	What to do
status: blocked	Configure an agent with --agent-command, CW_AGENT_COMMAND, or CW_AGENT_ENDPOINT.
claude: command not found	Install Claude Code or use another agent command.
You want to see the next action only	Add --preview; it is read-only.
You want one step at a time	Add --resume, then continue with the printed --run <run-id> command.
You need a shorter review	Try architecture-review-fast; see Workflow Apps.

Next Pages

• Workflow Apps
• Trust And Audit
• Recovery And Restore