@manhquy/flow-skill 0.1.0-rc.1

package/bin/cli.mjs

@@ -0,0 +1,382 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { join, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+
+import { TARGETS, TARGET_NAMES, PKG_VERSION } from '../src/constants.mjs';
+import { defaultSelection, detectAll } from '../src/detect.mjs';
+import { renderHelp } from '../src/help.mjs';
+import { install, installAntigravity } from '../src/installer.mjs';
+import { isInteractive } from '../src/tty.mjs';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const pkgRoot = resolve(__dirname, '..');
+const bundledSkillDir = join(pkgRoot, 'skills', 'flow');
+
+// F5 — runtime Node version guard. `engines` in package.json is advisory only; npm >=8 respects
+// it during install but `npx --yes` (and standalone `node`) do not. Fail loudly instead.
+// Floor is Node 22.14 for two reasons: (1) Node 20 EOL passed April 2026, (2) our publish
+// workflow requires npm >=11.5.1 which ships bundled with Node 22.14.0+ (needed for OIDC
+// Trusted Publisher handshake). Users on Node 20 will still install because npm engines is
+// advisory, but they get a loud error here rather than a mysterious runtime failure later.
+const MIN_NODE = [22, 14, 0];
+function checkNodeVersion() {
+  const parts = process.versions.node.split('.').map((n) => parseInt(n, 10));
+  for (let i = 0; i < MIN_NODE.length; i++) {
+    if (parts[i] > MIN_NODE[i]) return;
+    if (parts[i] < MIN_NODE[i]) {
+      process.stderr.write(
+        `flow-skill requires Node.js >=${MIN_NODE.join('.')} (running ${process.versions.node}).\n`
+      );
+      process.exit(2);
+    }
+  }
+}
+checkNodeVersion();
+
+function parseCliArgs(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    allowPositionals: false,
+    options: {
+      yes: { type: 'boolean', short: 'y', default: false },
+      target: { type: 'string', short: 't', multiple: true, default: [] },
+      all: { type: 'boolean', default: false },
+      project: { type: 'boolean', default: false },
+      dir: { type: 'string' },
+      json: { type: 'boolean', default: false },
+      'dry-run': { type: 'boolean', default: false },
+      help: { type: 'boolean', short: 'h', default: false },
+    },
+  });
+  // Split comma-form (-t claude,codex) into individual entries. mri wouldn't do this;
+  // parseArgs preserves the raw string, so we normalize here.
+  const targets = values.target
+    .flatMap((t) => String(t).split(','))
+    .map((t) => t.trim())
+    .filter(Boolean);
+  return {
+    yes: values.yes,
+    targets,
+    all: values.all,
+    project: values.project,
+    dir: values.dir,
+    json: values.json,
+    dryRun: values['dry-run'],
+    help: values.help,
+  };
+}
+
+function emit(event, jsonMode) {
+  if (jsonMode) {
+    process.stdout.write(JSON.stringify(event) + '\n');
+  }
+}
+
+function log(msg, jsonMode) {
+  if (!jsonMode) process.stdout.write(msg + '\n');
+}
+
+function warn(msg, jsonMode) {
+  if (!jsonMode) process.stderr.write(msg + '\n');
+}
+
+function errorExit(msg, code, jsonMode) {
+  if (jsonMode) {
+    process.stdout.write(
+      JSON.stringify({ event: 'error', message: msg, exitCode: code }) + '\n'
+    );
+  } else {
+    process.stderr.write(`Error: ${msg}\n`);
+  }
+  process.exit(code);
+}
+
+function validateTargetNames(names) {
+  const invalid = names.filter((n) => !TARGET_NAMES.includes(n));
+  if (invalid.length) {
+    return `unknown target(s): ${invalid.join(', ')}. Valid: ${TARGET_NAMES.join(', ')}`;
+  }
+  return null;
+}
+
+// Non-interactive selection: --all wins, else explicit -t, else default (alwaysInclude || detected).
+function selectNonInteractive({ entries, targets, all }) {
+  if (all) return entries.map((e) => e.name);
+  if (targets.length) return targets;
+  return defaultSelection(entries);
+}
+
+// L15/R2-A: project scope allows only projectScopeAllowed=true targets.
+function enforceProjectScope(selectedNames, project) {
+  if (!project) return { ok: true, kept: selectedNames, dropped: [] };
+  const kept = selectedNames.filter(
+    (n) => TARGETS.find((t) => t.name === n)?.projectScopeAllowed
+  );
+  const dropped = selectedNames.filter((n) => !kept.includes(n));
+  return { ok: kept.length > 0, kept, dropped };
+}
+
+// Build the concrete install plan (target -> destination list).
+function buildPlan(selectedNames, entries, { project, dir }) {
+  const projectDir = dir || process.cwd();
+  return selectedNames.map((name) => {
+    const t = entries.find((e) => e.name === name);
+    if (!t) throw new Error(`internal: no entry for ${name}`);
+    const dests = project ? [join(projectDir, '.claude', 'skills', 'flow')] : t.dests;
+    return { target: name, label: t.label, dests };
+  });
+}
+
+function humanPlan(plan, scope, dir) {
+  const lines = [`Install plan (scope: ${scope}${scope === 'project' ? `, dir: ${dir}` : ''})`];
+  for (const step of plan) {
+    lines.push(`  - ${step.target.padEnd(12)} ${step.label}`);
+    for (const d of step.dests) lines.push(`      -> ${d}`);
+  }
+  return lines.join('\n');
+}
+
+function humanResult(target, result) {
+  const status = result.success ? '✔' : '✗';
+  const dests = Array.isArray(result.dests)
+    ? result.dests.join(', ')
+    : result.dest || '';
+  const err = result.success ? '' : `  (${result.error})`;
+  return `${status} ${target} -> ${dests}${err}`;
+}
+
+async function main() {
+  const rawArgs = process.argv.slice(2);
+  let opts;
+  try {
+    opts = parseCliArgs(rawArgs);
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message}\nRun with --help for usage.\n`);
+    process.exit(2);
+  }
+
+  if (opts.help) {
+    process.stdout.write(renderHelp());
+    process.exit(0);
+  }
+
+  // Confirm the bundled skill exists — sync must have run before packaging.
+  if (!existsSync(join(bundledSkillDir, 'SKILL.md'))) {
+    errorExit(
+      `bundled skill not found at ${bundledSkillDir}. If running from a dev checkout, run 'npm run sync' first.`,
+      3,
+      opts.json
+    );
+  }
+
+  const invalid = validateTargetNames(opts.targets);
+  if (invalid) errorExit(invalid, 2, opts.json);
+
+  const entries = detectAll();
+
+  // Interactive path: only when no flags force a decision AND we have a real TTY on both ends.
+  // --dry-run + interactive is fine (we'll still prompt so the user can preview the plan).
+  const useInteractive =
+    !opts.yes &&
+    !opts.all &&
+    !opts.targets.length &&
+    !opts.project &&
+    !opts.json &&
+    isInteractive();
+
+  let selected;
+  let scope;
+  let projectDir;
+
+  if (useInteractive) {
+    const { promptTargets, promptScope, promptConfirm, filterProjectScope, intro, outro, cancel } =
+      await import('../src/prompt.mjs');
+    intro('flow-skill installer');
+
+    const t = await promptTargets(entries);
+    if (t.cancelled) {
+      cancel('cancelled');
+      process.exit(130);
+    }
+    selected = t.targets;
+
+    const s = await promptScope(process.cwd());
+    if (s.cancelled) {
+      cancel('cancelled');
+      process.exit(130);
+    }
+    scope = s.scope;
+    projectDir = process.cwd();
+
+    if (scope === 'project') {
+      const { kept, dropped } = filterProjectScope(selected);
+      if (dropped.length) {
+        warn(
+          `Project scope drops non-claude targets: ${dropped.join(', ')}`,
+          false
+        );
+      }
+      if (!kept.length) {
+        errorExit(
+          `--project scope supports only 'claude' target and no claude target selected.`,
+          2,
+          false
+        );
+      }
+      selected = kept;
+    }
+
+    const c = await promptConfirm({ count: selected.length });
+    if (c.cancelled || !c.ok) {
+      cancel('cancelled');
+      process.exit(0);
+    }
+    outro('installing...');
+  } else {
+    selected = selectNonInteractive({
+      entries,
+      targets: opts.targets,
+      all: opts.all,
+    });
+    const scopeCheck = enforceProjectScope(selected, opts.project);
+    if (!scopeCheck.ok) {
+      errorExit(
+        `--project scope supports only 'claude' target. Invalid: ${scopeCheck.dropped.join(', ') || '(none selected)'}.`,
+        2,
+        opts.json
+      );
+    }
+    if (scopeCheck.dropped.length && !opts.json) {
+      warn(
+        `Warning: project scope drops non-claude targets: ${scopeCheck.dropped.join(', ')}`,
+        false
+      );
+    }
+    selected = scopeCheck.kept;
+    scope = opts.project ? 'project' : 'global';
+    projectDir = opts.dir || process.cwd();
+  }
+
+  const plan = buildPlan(selected, entries, { project: scope === 'project', dir: projectDir });
+
+  emit(
+    {
+      event: 'plan',
+      version: PKG_VERSION,
+      dryRun: opts.dryRun,
+      scope,
+      targets: plan.map((p) => p.target),
+    },
+    opts.json
+  );
+
+  if (opts.dryRun) {
+    log(humanPlan(plan, scope, projectDir), opts.json);
+    process.exit(0);
+  }
+
+  // F4 — declare `results` BEFORE the SIGINT handler that closes over it. Const-after-handler
+  // would TDZ-throw if the user presses Ctrl+C before we ever get to the loop.
+  const results = [];
+  let aborted = false;
+
+  // SIGINT: flip a flag that the loop reads BETWEEN install() calls, after each install's
+  // finally-block has released its lock. We cannot preempt a synchronous cpSync/rmSync — Node
+  // signal handlers only fire when the JS stack unwinds. So this handler only affects
+  // multi-target runs (it stops the next iteration). Single-target Ctrl+C during copy relies
+  // on Node's default (exit 130 at loop unwind). No second-strike hard-exit — that was
+  // aspirational and would have leaked the current install's lock.
+  const onSigint = () => {
+    aborted = true;
+  };
+  process.on('SIGINT', onSigint);
+  for (const step of plan) {
+    if (aborted) break;
+    emit(
+      { event: 'install:start', target: step.target, dests: step.dests },
+      opts.json
+    );
+
+    let result;
+    if (step.target === 'antigravity') {
+      result = installAntigravity({ sourceDir: bundledSkillDir, dests: step.dests });
+    } else {
+      // Non-antigravity targets always have exactly one destination.
+      result = install({ sourceDir: bundledSkillDir, destDir: step.dests[0] });
+    }
+
+    results.push({ ...result, target: step.target, dests: step.dests });
+
+    emit(
+      {
+        event: 'install:done',
+        target: step.target,
+        dests: step.dests,
+        result: result.success ? 'success' : 'failed',
+        error: result.error ?? null,
+        warnings: result.warnings ?? [],
+      },
+      opts.json
+    );
+
+    log(humanResult(step.target, { ...result, dests: step.dests }), opts.json);
+
+    if (!result.success) break; // fail-fast
+    if (aborted) break; // Ctrl+C received; installer.mjs's finally already released the lock
+  }
+
+  process.off('SIGINT', onSigint);
+
+  const success =
+    !aborted && results.length === plan.length && results.every((r) => r.success);
+  emit(
+    {
+      event: 'summary',
+      success,
+      total: plan.length,
+      attempted: results.length,
+      installed: results.filter((r) => r.success).length,
+      failed: results.filter((r) => !r.success).length,
+      skipped: plan.length - results.length,
+      aborted,
+    },
+    opts.json
+  );
+
+  if (!opts.json && success) {
+    log(
+      '\nDone. Claude Code: type /flow  |  Codex CLI: type $flow (restart Codex once).',
+      false
+    );
+  }
+
+  // If aborted mid-loop, exit 130 (matches shell convention) instead of the generic failure.
+  if (aborted) process.exit(130);
+  process.exit(success ? 0 : 1);
+}
+
+main().catch((err) => {
+  // F2 — a crash inside main() must not truncate JSONL: emit a machine-parseable summary
+  // before exit so CI consumers can distinguish "crashed" from "hung".
+  const isJson = process.argv.includes('--json');
+  const message = err?.message ?? String(err);
+  if (isJson) {
+    process.stdout.write(
+      JSON.stringify({
+        event: 'summary',
+        success: false,
+        total: 0,
+        attempted: 0,
+        installed: 0,
+        failed: 0,
+        skipped: 0,
+        aborted: false,
+        error: message,
+      }) + '\n'
+    );
+  }
+  process.stderr.write(`Fatal: ${err?.stack ?? err}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@manhquy/flow-skill",
+  "version": "0.1.0-rc.1",
+  "description": "Install the flow skill (buildflow gated build process) into your coding agent(s) via one npx command",
+  "type": "module",
+  "bin": {
+    "flow-skill": "bin/cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skills/",
+    "skills-manifest.json",
+    "README.md",
+    "README_VN.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "scripts": {
+    "sync": "node scripts/sync.mjs",
+    "prepack": "node scripts/sync.mjs",
+    "test": "node --test test/installer.test.mjs test/detect.test.mjs test/cli.test.mjs test/lock-atomicity.test.mjs",
+    "smoke": "node scripts/smoke.mjs"
+  },
+  "dependencies": {
+    "@clack/prompts": "~0.11.0"
+  },
+  "keywords": [
+    "flow",
+    "skill",
+    "npx",
+    "installer",
+    "coding-agent",
+    "claude-code",
+    "codex",
+    "antigravity"
+  ],
+  "author": "manhquy <manhquy.mqy@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/manhquydev/flow-skill#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/manhquydev/flow-skill.git"
+  },
+  "bugs": {
+    "url": "https://github.com/manhquydev/flow-skill/issues"
+  }
+}

package/skills/flow/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: flow
+description: Run the buildflow gated build process from idea to real done-evidence. Walk gated stages (Idea->Research->Scope->PRD->ADR->Contract->Cards->Build->Review->Deploy/Ship->Verify->Retro), each with a honest gate that must pass before advancing. Adapts to project type (web|cli|library|skill). Use when starting or driving a real product build, when the user types /flow, /flow next, /flow card, /flow check, or asks to scope/plan/ship a project through gates. Kill at any gate is a valid outcome.
+user-invocable: true
+when_to_use: "User wants to build a real product end-to-end with discipline (idea -> a deployed URL for web, or installs+runs for a CLI/library/skill), or types any /flow command, or asks for a gated build process, scope decision, contract-first plan, or card-based shipping."
+argument-hint: "[ resume | next | card | check C-NNN | project-type web|cli|library|skill | mode teach|work | skip <stage> | ready | workspace add|list|enter|remove|check|doctor | auto | doctor | retro | eval --stage 01|02|card --fixture <id> --n 3 --keep-going --report ]"
+keywords: [flow, buildflow, gate, build, ship, scope, prd, contract, card, deploy, vertical-slice, cli, library, skill, worktree, parallel-agents, workspace, multi-agent]
+license: MIT
+metadata:
+  author: flow-skill
+  version: "0.21.0"
+  attribution: "Methodology from ai20k-build-phase/buildflow (Tony, arealisticdreamer.com); harness/agent layers from repository-harness, claudekit-engineer, BMAD-METHOD."
+---
+
+# /flow — buildflow gated build harness
+
+Idea to a **deployed URL**, not idea to paperwork. You walk gated stages; each has an
+**output artifact** and a **GATE** — a checklist that must be honestly satisfied before
+you advance. **Kill at any gate is a valid, honored outcome** (killing a weak idea at
+Scope is cheap and smart).
+
+```
+Idea -> Research -> Scope -> PRD -> ADR -> Contract -> Cards -> Build -> Review -> Deploy -> Verify-live -> Retro
+|------------------ planning (files in flow/) ------------------|  |------- shipping (inside cards/) -------|
+```
+
+## Two-layer harness (this is the core idea)
+
+`/flow` is **two layers working together**:
+
+1. **Mechanical layer — `runner/flow.sh`** (deterministic, exit 0/1). It manages the
+   stage/card lifecycle and checks the *cheatable* things: unchecked gate boxes,
+   leftover `[FILL]` placeholders, card status validity, empty done-evidence. Always run
+   it first — its exit code is ground truth, never your own judgment.
+2. **Semantic layer — YOU (Claude), via this skill** (quality gatekeeper). The script
+   cannot tell a real competitor quote from a fabricated one, or a grade-laundered C
+   feature from an honest B. **That is your job.** After the script passes, apply the
+   per-stage challenges in `references/gate-rules.md` before you let the operator advance.
+
+A gate is only truly passed when **both** layers agree. The script can pass while the
+content is hollow — catch that.
+
+## Running the mechanical layer
+
+From the **project root** (where `flow/` and `cards/` live), run the runner that ships
+with this skill:
+
+```
+# macOS / Linux / Windows Git Bash:
+bash <skill-dir>/runner/flow.sh <command>          # e.g. bash ~/.claude/skills/flow/runner/flow.sh next
+
+# Windows PowerShell or cmd (INCLUDING inside Codex): use the .cmd launcher, NOT bare `bash`.
+<skill-dir>\runner\flow.cmd <command>              # e.g. ...\.codex\skills\flow\runner\flow.cmd status
+# from PowerShell call it directly:  & "<skill-dir>\runner\flow.cmd" status
+```
+
+**Windows / Codex gotcha (read this):** in PowerShell/Codex a bare `bash` usually resolves to
+**WSL** (`C:\WINDOWS\system32\bash.exe`), which **cannot** read `C:/...` or `/c/...` paths and
+fails with `No such file or directory` — the mechanical layer then looks "broken" when it is not.
+**Always invoke `runner/flow.cmd`** on Windows; it locates Git Bash and runs the engine with a
+path Git Bash accepts. Only call `bash flow.sh` directly when you've confirmed `bash` is Git Bash.
+
+`<skill-dir>` is wherever this skill is installed (`~/.claude/skills/flow`, `~/.codex/skills/flow`,
+`~/.agents/skills/flow`, the Antigravity homes `~/.gemini/antigravity-cli/skills/flow` (CLI) /
+`~/.gemini/config/skills/flow` (IDE), or a project `.claude/skills/flow`). The runner reads/writes
+`flow/` and `cards/` under the current directory (override with `FLOW_PROJECT_ROOT`).
+
+**Antigravity (`agy` CLI / IDE):** flow installs as the same `SKILL.md` bundle; run `agy inspect` to
+confirm Antigravity discovered it. The mechanical layer is the **same** `bash flow.sh` / `flow.cmd`
+runner — the Windows WSL-bash trap below applies identically (use `flow.cmd` from a Windows shell).
+The Antigravity agent invokes shell tools, so it drives `flow.sh` like any other harness.
+
+**One session per project (concurrency lock).** Two `/flow` sessions sharing one project
+will stomp each other's plan. The runner keeps a `flow/.lock` (auto-reclaimed after
+`FLOW_LOCK_TTL`, default 900s): mutating commands (`next`/`card`/`skip`/`auto`) refuse a
+fresh **foreign** lock and `status` warns. For hard protection, **export a stable
+`FLOW_SESSION_ID` once per session** and pass it on every call (e.g.
+`FLOW_SESSION_ID=$mysid bash <skill-dir>/runner/flow.sh next`) — without it the runner can
+only warn (it can't prove a different session, so it never self-blocks). `FLOW_FORCE=1`
+takes over a lock you're sure is dead; `/flow unlock` clears it.
+
+## Commands
+
+| You type | Skill does |
+|---|---|
+| `/flow` | `flow.sh status` — where am I, what's blocking, card states |
+| `/flow resume` | `flow.sh resume` — **read-only session-story brief for entering a project mid-cycle**: last session (command names only, never raw args), in-flight card + dwell, gate state, one `NEXT ->` line. No lock. Run this FIRST when picking up an existing project (see the dispatch rule below). |
+| `/flow next` | `flow.sh next` — gate-check current stage; on pass, unlock next stage. **Then** you apply the semantic challenge for the stage just passed. |
+| `/flow assess` | `flow.sh assess` — **brownfield**: scaffold + gate a current-state assessment (`flow/00-inspect.md`, auto-scan seeded) for an EXISTING codebase before planning. Operator-reviewed. |
+| `/flow card` | `flow.sh card` — create next build card (only after all 6 planning gates pass) |
+| `/flow card start C-NNN` | `flow.sh card start` — mark a card **in flight** (operator-visible in-progress; shown in `/flow status`). Tracked in a portable `cards/.inflight` registry, never touches the gated `status:` field. Optional convenience — coexists with hand-editing. |
+| `/flow card done C-NNN` | `flow.sh card done` — CLI-owned flip of a card to `done`, gated by the SAME done-rules as `check` (real Evidence + checked Verify); **reverts** if the gate fails (never a hollow done). Coexists with hand-editing `status: done` + `/flow check`. |
+| `/flow check C-NNN` | `flow.sh check C-NNN` — validate a card; **then** you review diff-vs-scope, allowed-files drift, contract shapes, DESIGN.md for UI, and that evidence is real world-state |
+| `/flow mode teach\|work` | set who writes the artifacts (default `teach`) |
+| `/flow ready` | `flow.sh ready` — which todo cards are buildable + parallel-safety hint |
+| `/flow workspace add\|list\|enter\|remove\|check\|doctor` | `flow.sh workspace …` — **multi-agent worktree isolation** for running several agents (Claude/Codex/Antigravity, many terminals) in parallel WITHOUT the "one agent switches branch → every terminal flips" trap. Each agent gets its own `git worktree` (own HEAD/index/files, shared object store); git is the live registry (`git worktree list`) and a 10-field JSONL side-file (`.flow/workspaces.jsonl`) adds vendor/card/port/task. `add <branch> [--card C-NNN] [--vendor …] [--task …] [--copy-env]` provisions a worktree + distinct port-offset + paste-ready cd/env block; `list` shows who-is-where; `enter <branch>` re-prints a crashed terminal's env; `check <branch> [--card]` flags branch-claim + allowed-files overlap before you launch; `remove <branch> [--force]` tears down safely (never auto-forces); `doctor` reconciles orphan trees/records. Advisory layer; git's refusal to check out one branch twice is the real lock. |
+| `/flow auto` | `flow.sh auto` preflight, then drive the autonomous run (see AUTO principles) |
+| `/flow recall` | `flow.sh recall` — read back durable memory (open debt, recent retro, previous-card scope, harness friction/backlog, playbooks) **at the start of a stage/card** so you don't re-learn known pain |
+| `/flow usage` | `flow.sh usage` — roll up the mechanical usage log (JSONL flight-recorder of every invocation) into `usage_event` and print build analytics: cycle-time, gate fail-rate, per-stage dwell, cycle completion, command breakdown. `--global` for the device-wide view; `--prune [--keep N]` caps the log (crash-safe). Local-only; disable with `FLOW_LOG_DISABLE=1`/`DO_NOT_TRACK=1`. `recall` now surfaces a one-line usage digest and `retro`'s `propose` flags chronically-failing stages. |
+| `/flow contract` | `flow.sh contract` — flag client base-URL vs served-path prefix drift (web; advisory; run after the contract gate) |
+| `/flow tokens` | `flow.sh tokens` — flag DESIGN.md vs CSS design-token drift: unused tokens + value mismatches + orphan vars (advisory; UI cards) |
+| `/flow coherence` | `flow.sh coherence` — flag version drift across declared version fields (doc-vs-code coherence; advisory) |
+| `/flow consistency` | `flow.sh consistency` — audit cross-artifact coverage: every PRD `FRn` is claimed by a card (`implements:`) and served by a contract interface; numeric success metric; no leftover placeholders (advisory; run after the contract gate, before cards) |
+| `/flow constitution` | `flow.sh constitution` — check operator-authored per-project invariants in `flow/constitution.md` (structure + optional grep-markers); **advisory and NOT a `next` gate** — run it at the scope/PRD/contract seam, then apply the semantic challenge in `gate-rules.md` |
+| `/flow eval [--stage 01\|02\|card] [--fixture <id>] [--n 3] [--timeout <s>] [--keep-going]` | `flow.sh eval` — **behavioral eval**: does the LLM semantic gate (`gate-rules.md`) actually flag a hollow-but-mechanically-clean fixture? Opt-in, **billable** (skips cleanly, zero calls, if `claude` CLI absent); prints a per-stage scorecard. v0.21: on a final-INVALID vote, raw stdout + stderr + rc are persisted to `.flow/eval-raw/<run_id>/` (git-ignored, envelope-stripped) so an INVALID storm is postmortemable; the first UNRELIABLE fixture aborts the batch (`--keep-going` forces full-batch, worst-case ~37 calls at `--n 3`); the retry backoff is env-injectable (`FLOW_EVAL_RETRY_BACKOFF`, default 5s, set 0 in tests). See `references/gate-eval.md` for scope/cost/limitations. |
+| `/flow eval --report` | `flow.sh eval --report` — **offline**, zero calls: last complete batch's scorecard + drift vs the prior complete batch |
+| `/flow promote <file>` | `flow.sh promote <file>` — copy a playbook into the cross-project KB (`~/.claude/flow/playbooks`); `recall` then surfaces it everywhere |
+| `/flow project-type <web\|cli\|library\|skill>` | `flow.sh project-type` — set/read the project type that selects the per-type gate lens (`references/project-types.md`) |
+| `/flow skip <stage>` | `flow.sh skip` — advance past a gate that has a matching open `DEBT.md` line; **security-class skips are operator-only and HALT** (never auto-skipped) |
+| `/flow doctor` | `flow.sh doctor` — environment/install self-check (paths, runner, Git Bash) |
+| `/flow harness … \| debt … \| design` | runner subsystems: `harness` (durable intake/story/trace/decision/backlog — see `harness/README.md`), `debt` (record/list deliberate gate-skips), `design` (mechanical UI-token check) |
+| `/flow unlock` | `flow.sh unlock` — clear this project's concurrency lock after a crashed/abandoned session |
+| `/flow retro` | the 3 retro questions; the operator writes the line, never you |
+
+## Dispatch rules (how to behave for each command)
+
+1. **Entering a project mid-cycle? Run `/flow resume` before any other flow verb.** If this is
+   a fresh session (no prior context in this conversation) and the project already has a
+   `flow/` or `cards/` dir, `resume` is the read-only session-story brief that replaces
+   re-deriving state from scratch — last session, in-flight card + dwell, gate state, one
+   `NEXT ->` line. Skip this only when you already have live context (e.g. you were the one who
+   just ran `next`/`card` this same session) — running it every single command is unnecessary.
+2. **Always call `flow.sh` first** and read its exit code + output. Relay it faithfully. If it
+   reports **BLOCKED by another session's lock**, STOP and coordinate — never `FLOW_FORCE` past a
+   live session; concurrent `/flow` runs corrupt the plan.
+3. **On `next`:** if the script FAILS, stop — report exactly what it listed (line numbers),
+   and offer to help fill, but **never check a box or write an artifact on the operator's
+   behalf** in `teach` mode. If the script PASSES, run the **semantic gate** for the stage
+   just completed (see `references/gate-rules.md`). If you find hollow content (fabricated
+   quotes, grade-laundering, a pain with no feature, an endpoint with no auth), tell the
+   operator it mechanically passed but is qualitatively weak, and let them decide. Do not
+   silently advance past a hollow artifact; do not silently block a sound one.
+4. **On `card`/`check`:** enforce the build-session laws in `law/CLAUDE.md` — one card per
+   session, touch only `## Allowed files`, contract is the seam, done = world-state proof.
+   **Before authoring a new stage or card, run `/flow recall`** and treat its output (prior
+   debt / retro / friction / previous-card scope) as context to apply, not noise.
+5. **Mode `work`:** interview the operator once, draft stages 00–05 yourself, pause only
+   for scope sign-off, deliver the card set as one summary. Gates and done-rules are
+   identical to `teach` — you still must pass every gate, you just also author.
+6. **Never** edit `_templates/` or `runner/flow.sh` during a project run. Read any file the
+   runner just created before editing it.
+
+## The three rules under everything (from law/CLAUDE.md)
+
+1. **Inspect first.** Before planning, look at what already exists (competitors, live
+   systems, code). Evidence, not vibes.
+2. **Contract is the seam.** The API contract (stage 05) is written before any code.
+   Backend builds TO it, UI consumes FROM it. Never improvise a shape; amend the contract
+   first, then code. Honor a shape now (null/stub) even when its value ships in a later card.
+3. **Done = proof in the world.** Every card names its done-evidence up front. Verify on
+   the live URL as a user. "Tests pass" / "code merged" are mid-pipeline, never done.
+
+## Agent orchestration
+
+Each stage can delegate to a specialist agent, and degrades to built-in behavior when none
+exist — `/flow` stays portable. Priority: **ck: agents first, bmad-* skills as alternative,
+built-in fallback** (`references/agent-detection.md`). When the `openai-codex` plugin is present
+**and usable**, a cross-vendor **Codex (GPT-5.x) second engine** unlocks — used at three gated
+moments: two-strikes rescue, cross-model adversarial review (a different *model*, not just a
+different context), and opt-in primary drafter at research/build (default stays ck:). It detects
+and degrades like every other tier (installed≠usable; absence never breaks a run). Full seam,
+cost gate, and shapes: **`references/codex-integration.md`**. When `agy`/the Antigravity IDE is
+present **and usable**, a cross-vendor **Antigravity (Gemini-3) third engine** unlocks too — same
+high-value moments, giving a **three-model** adversarial gate. Antigravity needs the strictest
+usability check (`agy -p` returns exit 0 + empty stdout even when unauthenticated, so route only on
+non-empty expected output, never exit code; headless capture is unreliable → interactive review is
+the supported default). Full seam: **`references/antigravity-integration.md`**. The stage→agent map, scoped prompt
+template, and durable-record hooks are in `references/agent-stage-mapping.md`:
+research→`researcher`, scope/PRD→`planner`, ADR→`architect`, contract→`bmad-spec` kernel,
+build→`fullstack-developer`, review→`code-reviewer` or `bmad-code-review` (3-layer
+adversarial), verify-live→`tester`. **The gate is identical on every path** — an agent
+drafts, the gate still judges. Give each subagent ONLY task + files + acceptance + relevant
+law/contract excerpts (no session history); each returns DONE/DONE_WITH_CONCERNS/BLOCKED/
+NEEDS_CONTEXT. After a delegation: run the gate, apply the semantic challenge, write the
+durable hook (`flow.sh harness ...`), announce which path ran.
+
+Mode `work` (`references/mode-work.md`): interview once → draft 00-05 → one scope pause →
+deliver the card set as one summary. Gates bind the same as `teach`.
+
+## AUTO principles
+
+`/flow auto` drives the build phase autonomously (`references/auto-run.md`). Operator
+setting: **Tier-A auto-merge green cards; halt at security-class.** Per card: tier-classify
+→ one scoped subagent in its own worktree → build to contract → adversarial review →
+`flow.sh check` PASS → merge in card order → deploy → **verify on the LIVE URL** (merge ≠
+shipped) → world-state evidence → `status: done` → durable trace + `AUTO-LOG.md`.
+- **Tier A**: green + no security-class → auto-merge, no ask.
+- **Tier B**: fixable issues → one repair by a FRESH subagent (two-strikes), else escalate.
+  If the fix needs >1 experimental attempt against a single numeric target (not a review
+  disagreement), reach for `flow.sh loop-prep` + the `ck-loop` skill instead — see
+  "Loop vs two-strikes" in `references/claudekit-skills.md`.
+- **Tier C**: security-class (auth, authorization, admin exposure, tenancy, payments, data
+  migration, removing validation) → **HALT.** Operator accepts the exposure in `DEBT.md`,
+  in writing. Never planner-decided.
+Hard stops (iteration/token/time caps) and ground-truth gates (`flow.sh` exit, real
+`## Verify` runs, live check — never an agent's self-assessment) are mandatory.
+
+## Law & reference files
+
+- `law/CLAUDE.md` — build-session discipline, card sequence, PR/merge, debt, worktree, forbidden. **Read before building any card.**
+- `law/DESIGN.md` — UI law for every mock/frontend card (tokens, affordance ladder, object-first, never-do list).
+- `law/RETRO.md` — one honest line per run.
+- `references/gate-rules.md` — the per-stage semantic challenges (the heart of your gatekeeping).
+- `references/stage-state-machine.md` — stage order, unlock conditions, what each artifact must contain.
+- `references/project-types.md` — per-type (web|cli|library|skill) adaptations of the stages, gate lenses, and done-evidence.
+- `references/command-dispatch.md` — exact mapping of each `/flow` command to runner call + your duties.
+- `references/agent-detection.md` — detect ck:/bmad agents + priority + fallback.
+- `references/agent-stage-mapping.md` — stage→agent map, scoped prompt template, durable hooks.
+- `references/claudekit-skills.md` — the **skill layer** on top of the agents: the curated per-stage ck-skill whitelist ("what to use when"), the 6 deep-wired high-ROI skills (ck-predict@ADR, ck-scenario@Contract, review-pr@Review/Ship, ck-security@security-cards, retro@Retro, ck-loop@Build/Verify), the binding rules (skill INFORMS / gate JUDGES; Claude-side detection + silent degrade; opt-in-with-prompt, off the hot path), and the loop-vs-two-strikes decision matrix (`flow.sh loop-prep`/`loop-log` plumbing, ck-loop as the untouched execution engine).
+- `references/codex-integration.md` — the Codex cross-vendor second-engine seam: detection (installed≠usable), cost gate, invocation surfaces, ReviewResult shape, gate parity.
+- `references/antigravity-integration.md` — the Antigravity (Gemini-3) cross-vendor third-engine seam: install homes, strict usability (exit code lies → route on non-empty output), interactive-default review, cost/data gate, gate parity.
+- `references/gate-rules.md` → "Cross-artifact consistency" — the semantic passes behind `/flow consistency` (hollow coverage, conflicting requirements, cut-list contradiction, terminology drift) that the runner's ID-based check can't judge.
+- `references/mode-work.md` — work-mode script (interview once → draft → one scope pause → summary).
+- `references/auto-run.md` — `/flow auto` tiers, worktree loop, AUTO-LOG, security-class halt.
+- `references/loop-harness-2026-principles.md` — harness-first, hard stops, ground-truth, context isolation.
+- `references/ground-truth-gates.md` — the mechanical signal each gate decides on (never self-assessment).
+- `references/adversarial-review.md` — the 3-layer "must find issues" Review gate + triage.
+- `references/debt-and-halts.md` — `DEBT.md` ledger, security-class Tier-C halt, when a run halts.
+- `references/design-review-checklist.md` — UI card review (mechanical `flow.sh design` + semantic DESIGN.md).
+- `references/ui-patterns-tcr.md` — 7 UI patterns + T-C-R frame + pattern-choice priority rules.
+- `references/gate-eval.md` — `/flow eval` behavioral proof for the semantic layer: what it
+  measures (a fresh-judge lower bound, NOT the work-mode self-challenge), cost, thresholds,
+  and the honest authorship-bias limitation. Read before running or relaying a scorecard.
+- `harness/` — durable layer (`flow.sh harness ...`): intake/story/trace/decision/backlog. See `harness/README.md`. Read it back with `/flow recall` (open debt, retro, previous-card, friction, backlog, playbooks) — this is the capture→reuse loop.
+- `playbooks/` — paid-for stack knowledge: read before building a card on that stack, harvest the lesson after.
+- `_templates/` — the 7 artifacts the runner copies into `flow/` and `cards/`. Never edit during a run.
+
+## Forbidden
+
+- Checking a gate box or writing a planning artifact on the operator's behalf (in `teach` mode).
+- Setting a card `done` without pasted world-state evidence.
+- Building two cards in one session, or in parallel before `/flow ready` marks them safe.
+- Frontend code before the UI mock card is approved.
+- Editing `_templates/` or `runner/flow.sh` during a project run.