cool-workflow 0.1.78

package/scripts/version-sync-check.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+"use strict";
+
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const pluginRoot = path.resolve(__dirname, "..");
+const repoRoot = path.resolve(pluginRoot, "..", "..");
+
+// Deterministic source-of-record: validate the COMMIT being released (the blob
+// at HEAD), NOT the mutable working tree. A working tree is a moving target —
+// any concurrent editor, formatter, or stray process can write-then-revert a
+// surface file, and a read that lands in that window makes a release gate
+// false-RED on a clean tree (and, symmetrically, a gate that trusts an
+// uncommitted edit could false-GREEN). Reading `git show HEAD:<path>` removes
+// that entire failure class: the bytes are immutable for the life of the commit.
+// CI checks out HEAD, so HEAD === the tree it is releasing.
+//
+// Fallback to the filesystem only when we cannot read from HEAD: not a git work
+// tree, or the path is not tracked at HEAD (e.g. the gitignored package-lock).
+// node + git only — no ripgrep (CI portability rule).
+const insideGitWorkTree = (() => {
+  const r = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: repoRoot, encoding: "utf8" });
+  return r.status === 0 && (r.stdout || "").trim() === "true";
+})();
+
+function readReleaseSource(relativePath) {
+  // relativePath is repoRoot-relative (the form every check below already uses).
+  if (insideGitWorkTree) {
+    const r = spawnSync("git", ["show", `HEAD:${relativePath}`], {
+      cwd: repoRoot,
+      encoding: "utf8",
+      maxBuffer: 1024 * 1024 * 32
+    });
+    if (r.status === 0) return { text: r.stdout, exists: true, fromHead: true };
+    // Not tracked at HEAD — fall through to the working tree (e.g. package-lock).
+  }
+  const abs = path.join(repoRoot, relativePath);
+  if (!fs.existsSync(abs)) return { text: null, exists: false, fromHead: false };
+  return { text: fs.readFileSync(abs, "utf8"), exists: true, fromHead: false };
+}
+
+// Single source of truth: package.json. `scripts/bump-version.js` rewrites this
+// (and every other surface); version:sync then asserts all surfaces equal it.
+// Read it from the released commit so the asserted-against version is itself
+// taken from HEAD, not a half-written working copy.
+const VERSION = JSON.parse(readReleaseSource("plugins/cool-workflow/package.json").text).version;
+const canonicalApps = [
+  "architecture-review",
+  "end-to-end-golden-path",
+  "pr-review-fix-ci",
+  "release-cut",
+  "research-synthesis"
+];
+
+function main() {
+  const checks = [];
+  checkJson("plugins/cool-workflow/package.json", "version", VERSION, checks);
+  // package-lock.json is a gitignored install artifact (the documented install
+  // uses `npm install --no-package-lock`), so only validate it when present.
+  checkJsonIfPresent("plugins/cool-workflow/package-lock.json", "version", VERSION, checks);
+  checkJson("plugins/cool-workflow/.codex-plugin/plugin.json", "version", VERSION, checks);
+  checkNestedJson("plugins/cool-workflow/manifest/plugin.manifest.json", ["identity", "version"], VERSION, checks);
+  checkJson("plugins/cool-workflow/.claude-plugin/plugin.json", "version", VERSION, checks);
+  checkJson("plugins/cool-workflow/.gemini-plugin/plugin.json", "version", VERSION, checks);
+  checkJson("plugins/cool-workflow/.opencode-plugin/plugin.json", "version", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/src/version.ts", `CURRENT_COOL_WORKFLOW_VERSION = "${VERSION}"`, checks);
+  checkIncludes("plugins/cool-workflow/src/version.ts", "CURRENT_RUN_STATE_SCHEMA_VERSION = 1", checks);
+  checkIncludes("plugins/cool-workflow/src/mcp-server.ts", "CURRENT_COOL_WORKFLOW_VERSION", checks);
+  checkIncludes("plugins/cool-workflow/src/workflow-app-framework.ts", "CURRENT_COOL_WORKFLOW_VERSION", checks);
+
+  for (const appId of canonicalApps) {
+    checkJson(`plugins/cool-workflow/apps/${appId}/app.json`, "version", VERSION, checks);
+  }
+
+  checkIncludes("plugins/cool-workflow/scripts/golden-path.js", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/scripts/canonical-apps.js", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/scripts/dogfood-release.js", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/test/dogfood-release-smoke.js", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/test/coordinator-blackboard-smoke.js", "coordinator-blackboard-smoke", checks);
+  checkIncludes("plugins/cool-workflow/test/multi-agent-topologies-smoke.js", "multi-agent-topologies-smoke", checks);
+  checkIncludes("plugins/cool-workflow/test/multi-agent-cli-mcp-surface-smoke.js", "multi-agent-cli-mcp-surface-smoke", checks);
+  checkIncludes("plugins/cool-workflow/test/multi-agent-eval-replay-harness-smoke.js", "multi-agent-eval-replay-smoke", checks);
+  checkIncludes("plugins/cool-workflow/test/state-explosion-management-smoke.js", "state-explosion-management-smoke", checks);
+  checkIncludes("plugins/cool-workflow/test/evidence-adoption-reasoning-smoke.js", "evidence-adoption-reasoning-smoke", checks);
+  checkIncludes("plugins/cool-workflow/test/mcp-app-surface-smoke.js", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/test/canonical-workflow-apps-smoke.js", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/test/workflow-app-framework-smoke.js", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/dist/version.js", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/dist/mcp-server.js", "CURRENT_COOL_WORKFLOW_VERSION", checks);
+  checkIncludes("plugins/cool-workflow/dist/workflow-app-framework.js", "CURRENT_COOL_WORKFLOW_VERSION", checks);
+
+  checkIncludes("plugins/cool-workflow/README.md", `v${VERSION}`, checks);
+  checkIncludes("plugins/cool-workflow/docs/index.md", "release and migration", checks);
+  checkIncludes("plugins/cool-workflow/docs/multi-agent-topologies.7.md", "Multi-Agent Topologies", checks);
+  checkIncludes("plugins/cool-workflow/docs/multi-agent-cli-mcp-surface.7.md", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/docs/multi-agent-operator-ux.7.md", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/docs/multi-agent-eval-replay-harness.7.md", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/docs/state-explosion-management.7.md", "State Explosion Management", checks);
+  checkIncludes("plugins/cool-workflow/docs/state-explosion-management.7.md", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/docs/evidence-adoption-reasoning-chain.7.md", "Evidence Adoption Reasoning Chain", checks);
+  checkIncludes("plugins/cool-workflow/docs/evidence-adoption-reasoning-chain.7.md", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/docs/coordinator-blackboard.7.md", "Coordinator / Blackboard", checks);
+  checkIncludes("plugins/cool-workflow/docs/cli-mcp-parity.7.md", "CLI", checks);
+  checkIncludes("plugins/cool-workflow/docs/cli-mcp-parity.7.md", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/docs/index.md", "cli-mcp-parity.7.md", checks);
+  checkIncludes("plugins/cool-workflow/docs/run-registry-control-plane.7.md", "Run Registry / Control Plane", checks);
+  checkIncludes("plugins/cool-workflow/docs/run-registry-control-plane.7.md", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/docs/index.md", "run-registry-control-plane.7.md", checks);
+  checkIncludes("plugins/cool-workflow/test/run-registry-control-plane-smoke.js", "run-registry-control-plane-smoke", checks);
+  checkIncludes("plugins/cool-workflow/docs/execution-backends.7.md", "Execution Backends", checks);
+  checkIncludes("plugins/cool-workflow/docs/execution-backends.7.md", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/docs/index.md", "execution-backends.7.md", checks);
+  checkIncludes("plugins/cool-workflow/test/execution-backends-smoke.js", "execution-backends-smoke", checks);
+  checkIncludes("plugins/cool-workflow/docs/web-desktop-workbench.7.md", "Web / Desktop Workbench", checks);
+  checkIncludes("plugins/cool-workflow/docs/web-desktop-workbench.7.md", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/docs/index.md", "web-desktop-workbench.7.md", checks);
+  checkIncludes("plugins/cool-workflow/test/web-desktop-workbench-smoke.js", "web-desktop-workbench-smoke", checks);
+  checkIncludes("plugins/cool-workflow/docs/observability-cost-accounting.7.md", "Observability + Cost Accounting", checks);
+  checkIncludes("plugins/cool-workflow/docs/observability-cost-accounting.7.md", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/docs/index.md", "observability-cost-accounting.7.md", checks);
+  checkIncludes("plugins/cool-workflow/test/observability-cost-accounting-smoke.js", "observability-cost-accounting-smoke", checks);
+  checkIncludes("plugins/cool-workflow/docs/team-collaboration.7.md", "Team Collaboration", checks);
+  checkIncludes("plugins/cool-workflow/docs/team-collaboration.7.md", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/docs/index.md", "team-collaboration.7.md", checks);
+  checkIncludes("plugins/cool-workflow/test/team-collaboration-smoke.js", "team-collaboration-smoke", checks);
+  checkIncludes("plugins/cool-workflow/docs/release-tooling.7.md", "Release Tooling", checks);
+  checkIncludes("plugins/cool-workflow/docs/release-tooling.7.md", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/docs/index.md", "release-tooling.7.md", checks);
+  checkIncludes("plugins/cool-workflow/test/release-tooling-smoke.js", "release-tooling-smoke", checks);
+  checkIncludes("plugins/cool-workflow/docs/real-execution-backends.7.md", "Real Execution Backend Integrations", checks);
+  checkIncludes("plugins/cool-workflow/docs/real-execution-backends.7.md", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/docs/index.md", "real-execution-backends.7.md", checks);
+  checkIncludes("plugins/cool-workflow/test/real-execution-backends-smoke.js", "real-execution-backends-smoke", checks);
+  checkIncludes("plugins/cool-workflow/docs/node-snapshot-diff-replay.7.md", "Node Snapshot / Diff / Replay", checks);
+  checkIncludes("plugins/cool-workflow/docs/node-snapshot-diff-replay.7.md", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/docs/index.md", "node-snapshot-diff-replay.7.md", checks);
+  checkIncludes("plugins/cool-workflow/test/node-snapshot-diff-replay-smoke.js", "node-snapshot-diff-replay-smoke", checks);
+  checkIncludes("plugins/cool-workflow/docs/contract-migration-tooling.7.md", "Contract Migration Tooling", checks);
+  checkIncludes("plugins/cool-workflow/docs/contract-migration-tooling.7.md", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/docs/index.md", "contract-migration-tooling.7.md", checks);
+  checkIncludes("plugins/cool-workflow/test/contract-migration-tooling-smoke.js", "contract-migration-tooling-smoke", checks);
+  checkIncludes("plugins/cool-workflow/docs/control-plane-scheduling.7.md", "Control-Plane Scheduling", checks);
+  checkIncludes("plugins/cool-workflow/docs/control-plane-scheduling.7.md", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/docs/index.md", "control-plane-scheduling.7.md", checks);
+  checkIncludes("plugins/cool-workflow/test/control-plane-scheduling-smoke.js", "control-plane-scheduling-smoke", checks);
+  checkIncludes("plugins/cool-workflow/docs/agent-delegation-drive.7.md", "Agent Delegation Drive", checks);
+  checkIncludes("plugins/cool-workflow/docs/agent-delegation-drive.7.md", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/docs/index.md", "agent-delegation-drive.7.md", checks);
+  checkIncludes("plugins/cool-workflow/test/agent-delegation-drive-smoke.js", "agent-delegation-drive-smoke", checks);
+  checkIncludes("plugins/cool-workflow/docs/run-retention-reclamation.7.md", "Run Retention & Provable Reclamation", checks);
+  checkIncludes("plugins/cool-workflow/docs/run-retention-reclamation.7.md", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/docs/index.md", "run-retention-reclamation.7.md", checks);
+  checkIncludes("plugins/cool-workflow/test/run-retention-reclamation-smoke.js", "run-retention-reclamation-smoke", checks);
+  checkIncludes("plugins/cool-workflow/src/capability-registry.ts", "gc.plan", checks);
+  checkIncludes("plugins/cool-workflow/docs/durable-state-and-locking.7.md", "Durable State & Locking", checks);
+  checkIncludes("plugins/cool-workflow/docs/durable-state-and-locking.7.md", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/docs/index.md", "durable-state-and-locking.7.md", checks);
+  checkIncludes("plugins/cool-workflow/test/durable-atomic-write-smoke.js", "durable-atomic-write-smoke", checks);
+  checkIncludes("plugins/cool-workflow/src/state.ts", "withFileLock", checks);
+  checkIncludes("plugins/cool-workflow/src/drive.ts", "driveStep", checks);
+  checkIncludes("plugins/cool-workflow/dist/drive.js", "driveStep", checks);
+  checkIncludes("plugins/cool-workflow/src/capability-registry.ts", "run.drive", checks);
+  checkIncludes("plugins/cool-workflow/src/collaboration.ts", "deriveReviewState", checks);
+  checkIncludes("plugins/cool-workflow/dist/collaboration.js", "deriveReviewState", checks);
+  checkIncludes("plugins/cool-workflow/src/capability-registry.ts", "review.status", checks);
+  checkIncludes("plugins/cool-workflow/src/observability.ts", "deriveMetricsReport", checks);
+  checkIncludes("plugins/cool-workflow/dist/observability.js", "deriveMetricsReport", checks);
+  checkIncludes("plugins/cool-workflow/src/capability-registry.ts", "metrics.show", checks);
+  checkIncludes("plugins/cool-workflow/manifest/pricing.policy.json", "schemaVersion", checks);
+  checkIncludes("plugins/cool-workflow/src/workbench.ts", "buildWorkbenchRunView", checks);
+  checkIncludes("plugins/cool-workflow/dist/workbench.js", "buildWorkbenchRunView", checks);
+  checkIncludes("plugins/cool-workflow/src/capability-registry.ts", "workbench.view", checks);
+  checkIncludes("plugins/cool-workflow/src/execution-backend.ts", "ExecutionBackend", checks);
+  checkIncludes("plugins/cool-workflow/dist/execution-backend.js", "ExecutionBackend", checks);
+  checkIncludes("plugins/cool-workflow/src/capability-registry.ts", "backend.list", checks);
+  checkIncludes("plugins/cool-workflow/src/run-registry.ts", "RunRegistry", checks);
+  checkIncludes("plugins/cool-workflow/dist/run-registry.js", "RunRegistry", checks);
+  checkIncludes("plugins/cool-workflow/src/capability-registry.ts", "registry.refresh", checks);
+  checkIncludes("plugins/cool-workflow/package.json", "parity:check", checks);
+  checkIncludes("plugins/cool-workflow/scripts/parity-check.js", "buildParityReport", checks);
+  checkIncludes("plugins/cool-workflow/test/cli-mcp-parity-smoke.js", "cli-mcp-parity-smoke", checks);
+  checkIncludes("plugins/cool-workflow/src/capability-registry.ts", "CAPABILITY_REGISTRY", checks);
+  checkIncludes("plugins/cool-workflow/src/capability-core.ts", "planSummary", checks);
+  checkIncludes("plugins/cool-workflow/dist/capability-registry.js", "CAPABILITY_REGISTRY", checks);
+  checkIncludes("plugins/cool-workflow/docs/multi-agent-runtime-core.7.md", "Multi-Agent Runtime Core", checks);
+  checkIncludes("plugins/cool-workflow/docs/dogfood-one-real-repo.7.md", "Dogfood One Real Repo", checks);
+  checkIncludes("plugins/cool-workflow/docs/getting-started.md", "npm run release:check", checks);
+  checkIncludes("plugins/cool-workflow/package.json", "eval:replay", checks);
+  checkIncludes("plugins/cool-workflow/docs/release-and-migration.7.md", VERSION, checks);
+  checkIncludes("CHANGELOG.md", `## ${VERSION}`, checks);
+  checkIncludes("RELEASE.md", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/skills/cool-workflow/SKILL.md", "release:check", checks);
+
+  process.stdout.write(
+    `${JSON.stringify({ ok: true, version: VERSION, source: insideGitWorkTree ? "git:HEAD" : "working-tree", checks }, null, 2)}\n`
+  );
+}
+
+function checkJson(relativePath, key, expected, checks) {
+  const src = readReleaseSource(relativePath);
+  assert.ok(src.exists, `${relativePath} must exist`);
+  const value = JSON.parse(src.text)[key];
+  assert.equal(value, expected, `${relativePath}.${key} must be ${expected}`);
+  checks.push({ path: relativePath, key, value });
+}
+
+function checkNestedJson(relativePath, keyPath, expected, checks) {
+  const src = readReleaseSource(relativePath);
+  assert.ok(src.exists, `${relativePath} must exist`);
+  let value = JSON.parse(src.text);
+  for (const key of keyPath) value = value?.[key];
+  assert.equal(value, expected, `${relativePath}.${keyPath.join(".")} must be ${expected}`);
+  checks.push({ path: relativePath, key: keyPath.join("."), value });
+}
+
+function checkJsonIfPresent(relativePath, key, expected, checks) {
+  const src = readReleaseSource(relativePath);
+  if (!src.exists) {
+    checks.push({ path: relativePath, key, skipped: "absent" });
+    return;
+  }
+  const value = JSON.parse(src.text)[key];
+  assert.equal(value, expected, `${relativePath}.${key} must be ${expected}`);
+  checks.push({ path: relativePath, key, value });
+}
+
+function checkIncludes(relativePath, needle, checks) {
+  const src = readReleaseSource(relativePath);
+  assert.ok(src.exists, `${relativePath} must exist`);
+  assert.ok(src.text.includes(needle), `${relativePath} must include ${needle}`);
+  checks.push({ path: relativePath, includes: needle });
+}
+
+main();

package/skills/cool-workflow/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: cool-workflow
+description: Use when the user asks for Cool Workflow, CW, agent workflow control-plane, TypeScript workflow orchestration, phased multi-agent work, background workflow tasks, or reusable workflow apps.
+---
+
+# Cool Workflow
+
+Cool Workflow (CW) is an agent workflow control-plane. Use it to turn broad tasks into a
+TypeScript/Node workflow run with phases, agent task manifests, durable run
+state, verifier-gated commits, and a final report.
+
+CW is a control plane: it makes an agent host's work durable, inspectable,
+verifiable, and replayable. **It delegates execution; it never runs models
+itself.** The host still executes agents and enforces OS/process/network/
+environment controls — CW records, validates, and gates.
+
+## When To Use
+
+Use this skill when the user asks for:
+
+- `Cool Workflow` or `CW`
+- agent workflow control-plane
+- TypeScript workflow runner/orchestration
+- multi-agent phased work
+- background task style planning
+- reusable workflow apps/scripts
+- architecture review workflows
+- canonical workflow apps such as `architecture-review`, `pr-review-fix-ci`,
+  `release-cut`, and `research-synthesis`
+
+## Core Model
+
+CW has three layers:
+
+- **Package**: installable shared runtime.
+- **Skill**: trigger and operating instructions for the agent host (this file).
+- **TypeScript Node/Bun runtime**: workflow definitions, state files, task
+  queue, deterministic harness, verifier, commits, and reports.
+
+Treat CW like a platform framework. The runtime owns the contract; developers write
+workflow apps against it using `defineWorkflowApp`, `workflow`, `phase`,
+`agent`, `artifact`, and `input`. First-class apps live under
+`apps/<app-id>/app.json` with a plain JavaScript entrypoint; legacy
+`workflows/*.workflow.js` factories remain valid as wrapped compatibility apps.
+
+The runner does **not** spawn workers. It writes pending agent tasks to
+`.cw/runs/<run-id>/tasks/*.md`. The agent host reads those tasks, spawns workers
+only when the user explicitly asks for agent/parallel/background work, then
+records results back with the runner.
+
+CW records the model loop explicitly as:
+
+```text
+interpret -> act -> observe -> adjust -> checkpoint
+```
+
+Use this loop to explain workflow progress when reporting status.
+
+## Operating Loop
+
+1. Pick or create a workflow.
+2. `node scripts/cw.js plan <workflow-id> ...` from the plugin root (or the
+   absolute plugin script path).
+3. `node scripts/cw.js dispatch <run-id> --limit N` to create a dispatch
+   manifest for the current phase. Add `--sandbox <profile-id>` when an explicit
+   worker policy profile is needed.
+4. If — and only if — the user explicitly asked for agents, spawn one subagent
+   per dispatched task with disjoint scopes.
+5. Save each subagent summary to `.cw/runs/<run-id>/results/<task-id>.md`.
+6. `node scripts/cw.js result <run-id> <task-id> <result-file>`.
+7. When all required work is complete, `node scripts/cw.js report <run-id>`.
+8. Synthesize the final user-facing answer from the report and verified
+   evidence.
+
+Run data is written to `.cw/runs/<run-id>/` under `--cwd`, or under `--repo`
+when `--cwd` is not given. Durable state lives at
+`.cw/runs/<run-id>/state.json`; `state check <run-id>` dry-runs migration and
+normalization, failing closed on newer unsupported schemas while preserving
+unknown user data. The runtime source is TypeScript under `src/`, compiled to
+`dist/`.
+
+## Capabilities
+
+CW layers these on top of the plan → dispatch → record → verify → commit →
+report chain. See `references/commands.md` for the exact invocations.
+
+- **Workflow apps** — discover, validate, plan, package, and scaffold apps;
+  canonical apps are `architecture-review`, `pr-review-fix-ci`, `release-cut`,
+  `research-synthesis`.
+- **Topologies** — `map-reduce`, `debate`, and `judge-panel` as deterministic
+  userland recipes, not hidden autonomous coordination.
+- **Multi-agent host surface** — high-level `run -> status -> step ->
+  blackboard -> score -> select` plus operator views (dependencies, failures,
+  adopted evidence), wrapping the low-level runtime state and the coordination
+  filesystem.
+- **Coordinator / blackboard** — durable shared substrate (topics, messages,
+  context frames, artifact refs, snapshots, coordinator decisions).
+- **Trust / policy / audit** — inspect role authority, message provenance,
+  blackboard write decisions, and judge/panel rationale; missing
+  policy/evidence/provenance/rationale fail closed.
+- **State explosion management** — derived, provenance-backed digests for runs
+  too large to read; summaries never delete raw records and fail closed when
+  stale.
+- **Eval & replay** — deterministic snapshot/replay/compare/score/gate/report
+  for release-gate evidence under `.cw/evals/<suite-id>/`.
+- **Sandbox profiles** — named CW policy contracts (read/write paths, command,
+  network, environment, host enforcement); CW validates, the host enforces.
+- **Scheduling & routines** — loop/cron/reminder schedules and API/GitHub
+  trigger routines.
+
+## Essential Commands
+
+```bash
+node scripts/cw.js list
+node scripts/cw.js plan architecture-review --repo /path/to/repo --question "Is this architecture sound?"
+node scripts/cw.js dispatch <run-id> --limit 6
+node scripts/cw.js result <run-id> <task-id> /path/to/result.md
+node scripts/cw.js report <run-id> --show
+```
+
+When working in this repository, the plugin root is `plugins/cool-workflow`.
+When installed from a GitHub package source, the host resolves the package root
+from the source snapshot.
+
+**For the full command catalog and the matching MCP tool surface, read
+`references/commands.md`.** It covers apps, topologies, the multi-agent host and
+low-level state, eval/replay, blackboard/coordinator, sandbox profiles, commit/
+state/summaries, scheduling/routines, and release scripts.
+
+## CLI / MCP Parity
+
+When an MCP host is available, the same runtime surface is exposed with
+JSON-first `cw_*` tools (see `references/commands.md`). Operator output is
+human-readable by default; pass `--json` / `--format json` for structured
+output. **Preserve CLI/MCP parity when extending CW** — every CLI capability
+must have a matching MCP tool and vice versa. Status recommendations are
+deterministic hints, not hidden automation.
+
+## Multi-Agent Rule
+
+Only spawn workers when the user explicitly asks for agents, delegation,
+parallel work, or background work. Otherwise run the phases locally in the main
+thread and still use CW state/report files when helpful.
+
+## Result Quality
+
+Subagent results should be concise, evidence-based, and ready for synthesis.
+Avoid raw logs unless they are the evidence. Use absolute file paths and line
+numbers when referencing local code. Verification and verdict tasks must include
+a `cw:result` JSON fence with `findings` and `evidence`; CW rejects P0/P1/P2
+findings without evidence.
+
+## Release Discipline
+
+Run `npm run release:check` before tagging a release. It is a dry-run gate that
+builds, type-checks, runs tests, validates canonical apps and the golden path,
+checks old run fixtures, runs the multi-agent / topology / CLI-MCP / operator /
+trust-audit / eval-replay / dogfood smoke coverage, and verifies version
+synchronization — without tagging, pushing, publishing, or mutating fixtures.
+Use `npm run dogfood:release` to exercise the canonical `release-cut` app
+against this repo in dry-run mode. See `references/commands.md` for the full
+release/maintenance script list.