@manhquy/flow-skill 0.1.0-rc.1

package/skills-manifest.json

@@ -0,0 +1,70 @@
+{
+  "source": "D:\\project\\flow\\flow-skill\\skills\\flow",
+  "destRelative": "skills/flow",
+  "fileCount": 62,
+  "syncedAt": "2026-07-12T04:37:28.869Z",
+  "fileList": [
+    "SKILL.md",
+    "_templates/00-idea.md",
+    "_templates/00-inspect.md",
+    "_templates/01-research.md",
+    "_templates/02-scope.md",
+    "_templates/03-prd.md",
+    "_templates/04-adr.md",
+    "_templates/05-contract.md",
+    "_templates/card.md",
+    "_templates/constitution.md",
+    "eval/fixtures/f01a/flow/01-research.md",
+    "eval/fixtures/f01b/flow/01-research.md",
+    "eval/fixtures/f02a/flow/02-scope.md",
+    "eval/fixtures/f02b/flow/02-scope.md",
+    "eval/fixtures/fcda/.flow/.gitkeep",
+    "eval/fixtures/fcda/cards/C-001.md",
+    "eval/fixtures/fcdb/.flow/.gitkeep",
+    "eval/fixtures/fcdb/cards/C-001.md",
+    "eval/manifest.tsv",
+    "harness/README.md",
+    "harness/_db.py",
+    "harness/_domain.py",
+    "harness/_presence.py",
+    "harness/flow_harness.py",
+    "harness/repo_map.py",
+    "harness/schema/001-init.sql",
+    "harness/schema/002-story-verify.sql",
+    "harness/schema/003-tool-registry.sql",
+    "harness/schema/004-intervention.sql",
+    "harness/schema/005-tool-extensions.sql",
+    "harness/schema/009-accessed-count.sql",
+    "harness/schema/010-usage-event.sql",
+    "harness/schema/011-usage-gate-reason.sql",
+    "harness/schema/012-usage-ephemeral.sql",
+    "law/CLAUDE.md",
+    "law/DESIGN.md",
+    "law/RETRO.md",
+    "playbooks/README.md",
+    "playbooks/cloudflare-ai-gateway-qwen.md",
+    "playbooks/docker-deploy-stale-cache.md",
+    "playbooks/rag-lite-postgres-cloudflare.md",
+    "playbooks/windows-gitbash-jsonl-telemetry.md",
+    "references/adversarial-review.md",
+    "references/agent-detection.md",
+    "references/agent-stage-mapping.md",
+    "references/antigravity-integration.md",
+    "references/auto-run.md",
+    "references/claudekit-skills.md",
+    "references/codex-integration.md",
+    "references/command-dispatch.md",
+    "references/debt-and-halts.md",
+    "references/design-review-checklist.md",
+    "references/gate-eval.md",
+    "references/gate-rules.md",
+    "references/ground-truth-gates.md",
+    "references/loop-harness-2026-principles.md",
+    "references/mode-work.md",
+    "references/project-types.md",
+    "references/stage-state-machine.md",
+    "references/ui-patterns-tcr.md",
+    "runner/flow.cmd",
+    "runner/flow.sh"
+  ]
+}

package/src/constants.mjs

@@ -0,0 +1,65 @@
+// 4 install targets. Antigravity has 2 destinations (CLI + IDE) driven by one target.
+// Marker paths are relative to os.homedir() — no leading slash/backslash.
+export const TARGETS = [
+  {
+    name: 'claude',
+    label: 'Claude Code',
+    // any presence of ~/.claude counts — Claude is `alwaysInclude` regardless
+    markers: ['.claude'],
+    destTemplates: ['~/.claude/skills/flow'],
+    alwaysInclude: true,
+    projectScopeAllowed: true,
+  },
+  {
+    name: 'codex',
+    label: 'Codex CLI',
+    markers: ['.codex/skills'],
+    destTemplates: ['~/.codex/skills/flow'],
+    alwaysInclude: false,
+    projectScopeAllowed: false,
+  },
+  {
+    name: 'agents',
+    label: 'Agents home (~/.agents)',
+    markers: ['.agents/skills'],
+    destTemplates: ['~/.agents/skills/flow'],
+    alwaysInclude: false,
+    projectScopeAllowed: false,
+  },
+  {
+    name: 'antigravity',
+    label: 'Antigravity (CLI + IDE)',
+    // Never stat bare ~/.gemini — that dir is shared by non-Antigravity Google Gemini CLI.
+    markers: ['.gemini/antigravity-cli', '.gemini/config/skills'],
+    destTemplates: [
+      '~/.gemini/antigravity-cli/skills/flow',
+      '~/.gemini/config/skills/flow',
+    ],
+    alwaysInclude: false,
+    projectScopeAllowed: false,
+  },
+];
+
+// Subdirs the installer cleans out before merge-copying — parity with install.sh:25.
+export const CLEANUP_SUBDIRS = [
+  'runner',
+  '_templates',
+  'law',
+  'references',
+  'harness',
+  'playbooks',
+];
+
+export const TARGET_NAMES = TARGETS.map((t) => t.name);
+export const CLI_NAME = 'flow-skill';
+
+// F3 fix: read version from package.json at runtime so `npm version` bumps propagate to the
+// JSON `plan` event without a hand-edit here.
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgJson = JSON.parse(
+  readFileSync(resolve(__dirname, '..', 'package.json'), 'utf8')
+);
+export const PKG_VERSION = pkgJson.version;

package/src/detect.mjs

@@ -0,0 +1,36 @@
+import { statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { TARGETS } from './constants.mjs';
+
+// Resolve a `~/foo/bar` template against a home dir using OS-native separators.
+// String `.replace('~', home)` would leave a mixed-separator path on Windows
+// (`C:\Users\x/.claude/skills/flow`) which then leaks into `--json` output and
+// breaks downstream CI consumers that key on path strings.
+function resolveDest(template, home) {
+  if (!template.startsWith('~/')) return template;
+  const rest = template.slice(2).split('/');
+  return join(home, ...rest);
+}
+
+// Return one entry per target with marker-based detection + resolved absolute destinations.
+export function detectAll({ home = homedir() } = {}) {
+  return TARGETS.map((t) => {
+    const detected = t.markers.some((m) => {
+      try {
+        statSync(join(home, m));
+        return true;
+      } catch {
+        return false;
+      }
+    });
+    const dests = t.destTemplates.map((d) => resolveDest(d, home));
+    return { ...t, detected, dests };
+  });
+}
+
+// alwaysInclude || detected — mirrors install.sh:40 contract for Claude and preserves user-facing detection for others.
+export function defaultSelection(entries) {
+  return entries.filter((e) => e.alwaysInclude || e.detected).map((e) => e.name);
+}

package/src/help.mjs

@@ -0,0 +1,42 @@
+import { CLI_NAME, PKG_VERSION, TARGETS } from './constants.mjs';
+
+export function renderHelp() {
+  const targetRows = TARGETS.map((t) => `    ${t.name.padEnd(12)} ${t.label}`).join('\n');
+  return `${CLI_NAME} v${PKG_VERSION}
+
+Install the flow skill into your coding agent(s).
+
+USAGE
+  npx @manhquy/flow-skill [options]
+
+OPTIONS
+  -y, --yes                    Skip prompts; install to default selection (detected + Claude)
+  -t, --target <name>          Explicit target (repeatable, comma-separated also OK)
+      --all                    Install to all 4 targets regardless of detection
+      --project                Project scope (Claude only) — writes to <dir>/.claude/skills/flow
+      --dir <path>             Project directory (implies --project). Default: cwd
+      --json                   Emit JSONL events (plan, install:start, install:done, summary)
+      --dry-run                Print the plan; do not touch disk
+  -h, --help                   Show this help
+
+TARGETS
+${targetRows}
+
+  Notes:
+  - Antigravity target writes 2 destinations: ~/.gemini/antigravity-cli/skills/flow AND ~/.gemini/config/skills/flow.
+  - --project scope supports only "claude" (agent-contract limitation).
+  - Non-detected targets can still be forced via --target or --all.
+
+EXAMPLES
+  npx @manhquy/flow-skill                                  # interactive multi-select
+  npx @manhquy/flow-skill --yes                            # non-interactive; default selection
+  npx @manhquy/flow-skill --yes --all                      # force all 4 targets
+  npx @manhquy/flow-skill --yes -t claude -t codex         # explicit targets
+  npx @manhquy/flow-skill --project --dir .                # project-scoped install (Claude only)
+  npx @manhquy/flow-skill --yes --all --dry-run --json     # CI JSONL preview
+
+MORE
+  Docs:     https://github.com/manhquydev/flow-skill#readme
+  Security: https://github.com/manhquydev/flow-skill/blob/main/SECURITY.md
+`;
+}

package/src/installer.mjs

@@ -0,0 +1,231 @@
+import {
+  chmodSync,
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { CLEANUP_SUBDIRS } from './constants.mjs';
+
+// L24 — Retry the codes Windows emits when an agent (Claude Code, Codex, Antigravity) holds an
+// open handle inside the destination. EACCES is intentionally excluded: on POSIX it is almost
+// always a hard permission denial (stale sudo install, wrong owner) that will not clear in
+// under a second. Retrying it just delays the honest error message.
+export function withRetry(fn, opts = {}) {
+  const attempts = opts.attempts ?? 3;
+  const initialMs = opts.initialMs ?? 100;
+  const retryableCodes = opts.codes ?? ['EBUSY', 'EPERM', 'ENOTEMPTY'];
+  let lastErr;
+  for (let i = 0; i < attempts; i++) {
+    try {
+      return fn();
+    } catch (err) {
+      lastErr = err;
+      if (!retryableCodes.includes(err?.code) || i === attempts - 1) throw err;
+      // Blocking sleep — installer runs sequentially, this is fine.
+      const wait = initialMs * Math.pow(3, i);
+      const sab = new SharedArrayBuffer(4);
+      Atomics.wait(new Int32Array(sab), 0, 0, wait);
+    }
+  }
+  throw lastErr;
+}
+
+export function rmRecursiveWithRetry(target) {
+  return withRetry(() => rmSync(target, { recursive: true, force: true }));
+}
+
+// L23 — Reject any symlink recursively. Defense against upstream skill-content symlink smuggling
+// (e.g. symlink → /etc/passwd smuggled into skills/flow via compromised upstream).
+export function assertNoSymlinks(root) {
+  for (const entry of readdirSync(root)) {
+    const p = join(root, entry);
+    const st = lstatSync(p);
+    if (st.isSymbolicLink()) {
+      const err = new Error(`symlink rejected: ${p}`);
+      err.code = 'ESYMLINK';
+      throw err;
+    }
+    if (st.isDirectory()) assertNoSymlinks(p);
+  }
+}
+
+// L29 — Advisory lock: best-effort concurrent-run prevention.
+// Uses `writeFileSync` with `flag: 'wx'` (exclusive-create — fails with EEXIST if the file
+// already exists) so the check + acquire are atomic. The previous TOCTOU version could have
+// two `npx` processes both observe "no lock" and both acquire.
+// Stale-lock recovery: on EEXIST, read the recorded PID; if that PID is dead (ESRCH), remove
+// the file and retry the exclusive-create once. `process.kill(pid, 0)` on a live PID always
+// succeeds, including our own PID — so a re-entrant call sees "held" and refuses, which is
+// the correct behavior (install() is not re-entrant-safe).
+export function acquireLock(lockPath) {
+  mkdirSync(dirname(lockPath), { recursive: true });
+  try {
+    writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
+    return { held: false };
+  } catch (err) {
+    if (err?.code !== 'EEXIST') throw err;
+  }
+  // Lock exists — decide stale vs. held.
+  let pid = null;
+  try {
+    pid = Number(readFileSync(lockPath, 'utf8').trim());
+  } catch {
+    // corrupted lock content — treat as stale
+  }
+  if (Number.isFinite(pid) && pid > 0) {
+    try {
+      process.kill(pid, 0);
+      return { held: true, pid };
+    } catch (killErr) {
+      if (killErr?.code !== 'ESRCH') return { held: true, pid };
+    }
+  }
+  // Stale — remove and retry the exclusive-create exactly once.
+  try {
+    rmSync(lockPath, { force: true });
+  } catch {
+    /* ignore */
+  }
+  try {
+    writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
+    return { held: false };
+  } catch (retryErr) {
+    // Something else raced in between our rm and our retry — treat as held.
+    if (retryErr?.code === 'EEXIST') return { held: true, pid: null };
+    throw retryErr;
+  }
+}
+
+export function releaseLock(lockPath) {
+  try {
+    rmSync(lockPath, { force: true });
+  } catch {
+    /* ignore */
+  }
+}
+
+// Core install — parity with install.sh:24-27:
+//   rm -rf <dest>/{runner,_templates,law,references,harness,playbooks}
+//   cp -r <sourceDir>/. <dest>/
+//   chmod +x <dest>/runner/flow.sh
+// This intentionally preserves any user files in <dest> outside the 6 cleanup subdirs.
+export function install({
+  sourceDir,
+  destDir,
+  cleanupSubdirs = CLEANUP_SUBDIRS,
+  dryRun = false,
+}) {
+  if (dryRun) return { success: true, dest: destDir, dryRun: true, warnings: [] };
+
+  const lockPath = join(dirname(destDir), '.flow-skill.installing.lock');
+  const warnings = [];
+  let lockHeld = false;
+
+  try {
+    const lock = acquireLock(lockPath);
+    if (lock.held) {
+      return {
+        success: false,
+        dest: destDir,
+        error: `another install in progress (pid ${lock.pid}); wait or remove ${lockPath}`,
+        warnings,
+      };
+    }
+    lockHeld = true;
+
+    if (!existsSync(join(sourceDir, 'SKILL.md'))) {
+      throw new Error(
+        `SKILL.md missing in sourceDir=${sourceDir} (did you run 'npm run sync'?)`
+      );
+    }
+    // Pre-scan source before touching dest.
+    assertNoSymlinks(sourceDir);
+
+    mkdirSync(destDir, { recursive: true });
+
+    // Cleanup the 6 subdirs — matches install.sh:25.
+    for (const sub of cleanupSubdirs) {
+      const p = join(destDir, sub);
+      if (existsSync(p)) rmRecursiveWithRetry(p);
+    }
+
+    // Merge copy — matches install.sh:26. External files outside CLEANUP_SUBDIRS are preserved.
+    withRetry(() =>
+      cpSync(sourceDir, destDir, {
+        recursive: true,
+        force: true,
+        dereference: false,
+        errorOnBrokenSymbolicLinks: true,
+        preserveTimestamps: true,
+      })
+    );
+
+    // (Post-copy symlink rescan removed) — the source scan above already vets every file we
+    // wrote; scanning the destination additionally rejects legitimate NTFS junctions users
+    // may have placed under `~/.claude/skills/flow/` for their own reasons. install.sh does
+    // not have this restriction (`cp -r` merges over junctions fine) and the parity contract
+    // says we don't either.
+
+    // chmod +x runner/flow.sh — matches install.sh:27. No-op on Windows (NTFS ignores the bit).
+    const runnerScript = join(destDir, 'runner', 'flow.sh');
+    if (existsSync(runnerScript)) {
+      try {
+        chmodSync(runnerScript, 0o755);
+      } catch (err) {
+        warnings.push(`chmod +x runner/flow.sh failed: ${err.message}`);
+      }
+    }
+
+    return { success: true, dest: destDir, warnings };
+  } catch (err) {
+    return {
+      success: false,
+      dest: destDir,
+      error: String(err?.message ?? err),
+      warnings: [
+        ...warnings,
+        'state may be inconsistent (partial write); re-run to fix',
+      ],
+    };
+  } finally {
+    if (lockHeld) releaseLock(lockPath);
+  }
+}
+
+// L28 (revised per phase-01 review F1) — Antigravity has 2 destinations under one target.
+// install.sh:52-53 makes 2 separate install_to calls with no rollback if the 2nd fails; we
+// mirror that. Rolling back dest 1 destroys the freshly-installed content there and also
+// risks harming anything the user had before install started, so we intentionally do NOT roll
+// back. On dest-2 failure we report partial success and let the user re-run.
+export function installAntigravity({ sourceDir, dests, dryRun = false }) {
+  if (!Array.isArray(dests) || dests.length === 0) {
+    return { success: false, error: 'no destinations provided' };
+  }
+  if (dryRun) return { success: true, dests, dryRun: true, warnings: [] };
+
+  const attempts = [];
+  for (let i = 0; i < dests.length; i++) {
+    const r = install({ sourceDir, destDir: dests[i] });
+    attempts.push({ dest: dests[i], success: r.success, error: r.error ?? null });
+    if (!r.success) {
+      const warnings = attempts.flatMap((a, idx) =>
+        idx < i ? [`dest ${idx + 1} (${dests[idx]}) already installed; not rolled back`] : []
+      );
+      return {
+        success: false,
+        dests,
+        attempts,
+        error: `dest ${i + 1} failed: ${r.error}`,
+        warnings,
+      };
+    }
+  }
+  return { success: true, dests, attempts, warnings: [] };
+}

package/src/prompt.mjs

@@ -0,0 +1,60 @@
+// @clack/prompts wrapper — kept small so Phase-1 non-interactive path never has to load it.
+import { cancel, confirm, intro, isCancel, multiselect, outro, select } from '@clack/prompts';
+
+import { TARGETS } from './constants.mjs';
+
+// Present the 4 targets as a checkbox list. Detected targets (and Claude via alwaysInclude) are
+// pre-checked. Not-detected entries still appear so the user can force-add.
+export async function promptTargets(entries) {
+  const options = entries.map((e) => ({
+    value: e.name,
+    label: `${e.label}${e.detected || e.alwaysInclude ? '' : ' (not detected)'}`,
+    hint: e.dests.join(', '),
+  }));
+  const initialValues = entries
+    .filter((e) => e.alwaysInclude || e.detected)
+    .map((e) => e.name);
+
+  const selected = await multiselect({
+    message: 'Install to which harnesses?',
+    options,
+    initialValues,
+    required: true,
+  });
+  if (isCancel(selected)) return { cancelled: true };
+  return { cancelled: false, targets: selected };
+}
+
+// Global vs project scope. Project scope is Claude-only (agent contract).
+export async function promptScope(defaultDir = process.cwd()) {
+  const scope = await select({
+    message: 'Scope?',
+    options: [
+      { value: 'global', label: 'Global (all agents that were selected)' },
+      { value: 'project', label: `Project (${defaultDir}) — Claude only` },
+    ],
+    initialValue: 'global',
+  });
+  if (isCancel(scope)) return { cancelled: true };
+  return { cancelled: false, scope };
+}
+
+// Apply project-scope filtering with a visible warning about dropped targets.
+export function filterProjectScope(selected) {
+  const kept = selected.filter(
+    (n) => TARGETS.find((t) => t.name === n)?.projectScopeAllowed
+  );
+  const dropped = selected.filter((n) => !kept.includes(n));
+  return { kept, dropped };
+}
+
+export async function promptConfirm(summary) {
+  const ok = await confirm({
+    message: `Install ${summary.count} target(s)?`,
+    initialValue: true,
+  });
+  if (isCancel(ok)) return { cancelled: true };
+  return { cancelled: false, ok };
+}
+
+export { cancel, intro, isCancel, outro };

package/src/tty.mjs

@@ -0,0 +1,11 @@
+// Interactive-mode gate. Both stdio streams must be TTY and no CI env override in effect.
+// `NON_INTERACTIVE=1` is a documented escape hatch for edge terminals (some VS Code integrated
+// shells report isTTY=true but do not render prompt UI correctly).
+export function isInteractive({
+  stdin = process.stdin,
+  stdout = process.stdout,
+  env = process.env,
+} = {}) {
+  if (env.CI === 'true' || env.NON_INTERACTIVE === '1') return false;
+  return Boolean(stdin.isTTY && stdout.isTTY);
+}