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.

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

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