@curdx/flow 2.0.0-beta.7 → 2.0.0-beta.9

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Claude Code Discipline Layer — spec-driven workflow + goal-backward verification + Karpathy 4 principles enforced via gates. Stops Claude from faking \"done\" on non-trivial features.",
-    "version": "2.0.0-beta.7"
+    "version": "2.0.0-beta.9"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "curdx-flow",
-  "version": "2.0.0-beta.7",
+  "version": "2.0.0-beta.9",
   "description": "Claude Code Discipline Layer — spec-driven workflow + goal-backward verification + Karpathy 4 principles enforced via gates. Stops Claude from faking \"done\" on non-trivial features.",
   "author": {
     "name": "wdx",
@@ -31,13 +31,6 @@
         "-y",
         "@modelcontextprotocol/server-sequential-thinking"
       ]
-    },
-    "chrome-devtools": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "chrome-devtools-mcp@latest"
-      ]
     }
   }
 }

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to CurDX-Flow will be documented here.
 
+## [Unreleased]
+
+### Fixed (P0)
+
+- `cli/utils.js` — `findRuntime()` referenced `existsSync` without importing it; any user whose `bun`/`uv` was not on PATH hit `ReferenceError` during install or doctor.
+- `hooks/scripts/stop-watcher.sh` — `export STATE_FILE` was placed after the python heredoc, so the stop-hook execution strategy never activated. Moved the export before the heredoc.
+- `package.json` — `skills/` directory was missing from `files[]`; the 5 bundled skills were stripped from the published tarball.
+- `cli/uninstall.js` + `cli/upgrade.js` — `chrome-devtools-mcp` (added as a recommended plugin in beta.8) was missing from uninstall/upgrade lists, making it installable but uninstallable.
+- `cli/protocols.js` — `injectGlobalProtocols()` returned action `"created"` on both ternary branches, silently collapsing the append-to-existing-file case. Atomic write + corrupted-block detection added.
+
+### Changed (structural)
+
+- New `cli/registry.js` is the single source of truth for recommended plugins. `install.js`, `uninstall.js`, `upgrade.js`, and `doctor.js` all import from it.
+- `commands/start.md` and `commands/spec.md` now produce `.state.json` files that match `schemas/spec-state.schema.json` (field names: `spec_name` / `created` / `updated` / `version`; initial phase is `research`, not the undefined `created`).
+- All python heredocs inside hook scripts use quoted delimiters (`<<'PY'`) and read `STATE_FILE` via `os.environ`, closing a shell→python code-injection surface triggered by unusual spec names.
+
+### Removed
+
+- `hooks/scripts/fail-tracker.sh` and its `PostToolUseFailure` registration — the counter was written but never read by any consumer (the intended pua escalation was never implemented). Can be reintroduced when the consumer exists.
+
 ## [2.0.0-beta.1] - 2026-04-20
 
 ### BREAKING — Major redesign: Discipline Layer, not meta-framework

package/README.zh.md

@@ -23,8 +23,8 @@ CurDX-Flow 是一个 Claude Code 插件，把 6 个验证过的 AI 工程工作
 - **8 个可组合 Gate** — Karpathy / Verification / TDD / Coverage / Adversarial / Edge-Case / Security / DevEx
 - **4 种执行策略** — linear / subagent / stop-hook / wave（自动路由）
 - **10 个知识文档** — 规格驱动 / POC-First / 原子提交 / 执行策略 / ...
-- **5 个 hook 事件** — SessionStart / InstructionsLoaded / Stop / PreToolUse / PostToolUseFailure
-- **3 个自动安装的 MCP** — context7 / sequential-thinking / chrome-devtools
+- **4 个 hook 事件** — SessionStart / InstructionsLoaded / Stop / PreToolUse
+- **2 个自动安装的 MCP + 1 个推荐插件** — context7 / sequential-thinking（plugin.json 内置）+ chrome-devtools-mcp（recommended，beta.8 解耦）
 - **优雅降级** — 依赖缺失时进入 fallback 模式并清晰告知
 
 ## 为什么用

package/cli/doctor.js

@@ -13,6 +13,7 @@ import {
   listMcps,
   ensureClaudeMemRuntimes,
 } from "./utils.js";
+import { RECOMMENDED_PLUGINS } from "./registry.js";
 
 export async function doctor(args = []) {
   const verbose = args.includes("--verbose") || args.includes("-v");
@@ -50,9 +51,13 @@ export async function doctor(args = []) {
   }
 
   // ---------- MCPs ----------
+  // Bundled by curdx-flow plugin via .claude-plugin/plugin.json mcpServers.
+  // chrome-devtools is NOT here anymore — it was extracted into its own
+  // recommended plugin (see below) to align with the "each MCP owned by one
+  // plugin" model and avoid double-spawning the chrome-devtools-mcp process.
   console.log(`\n${color.bold("MCP Servers:")}`);
   const mcps = cv ? listMcps() : [];
-  const expectedMcps = ["context7", "sequential-thinking", "chrome-devtools"];
+  const expectedMcps = ["context7", "sequential-thinking"];
   for (const m of expectedMcps) {
     const found = mcps.find((x) => x.name === m);
     if (found) {
@@ -67,24 +72,21 @@ export async function doctor(args = []) {
     }
   }
 
-  // ---------- Recommended plugins ----------
+  // ---------- Recommended plugins (single registry; see cli/registry.js) ----------
   console.log(`\n${color.bold("Recommended plugins:")}`);
-  const recommended = [
-    { name: "pua", installCmd: "claude plugin install pua@pua-skills" },
-    { name: "claude-mem", installCmd: "claude plugin install claude-mem@thedotmack" },
-    { name: "frontend-design", installCmd: "claude plugin install frontend-design@claude-plugins-official" },
-  ];
   let claudeMemEnabled = false;
-  for (const r of recommended) {
+  for (const r of RECOMMENDED_PLUGINS) {
     const p = plugins.find((x) => x.name === r.name);
     if (p && p.status === "enabled") {
       log.ok(`${r.name.padEnd(22)} ${color.dim(`v${p.version}`)}`);
-      if (r.name === "claude-mem") claudeMemEnabled = true;
+      if (r.postInstall === "claude-mem-runtimes") claudeMemEnabled = true;
     } else if (p && p.status === "failed") {
       log.err(`${r.name.padEnd(22)} load failed`);
       errors++;
     } else {
-      log.warn(`${r.name.padEnd(22)} not installed ${color.dim("(run: curdx-flow install --all)")}`);
+      log.warn(
+        `${r.name.padEnd(22)} not installed ${color.dim(`(run: claude plugin install ${r.installSpec})`)}`
+      );
       warnings++;
     }
   }

package/cli/install.js

@@ -2,7 +2,7 @@
  * install command — install curdx-flow plugin + optional recommended plugins.
  */
 
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -17,6 +17,7 @@ import {
   ensureClaudeMemRuntimes,
 } from "./utils.js";
 import { injectGlobalProtocols, GLOBAL_CLAUDE_MD } from "./protocols.js";
+import { RECOMMENDED_PLUGINS } from "./registry.js";
 
 // When installed via npm, this CLI file lives at <pkg-root>/cli/install.js.
 // The npm package bundles the full plugin body (.claude-plugin/, agents/,
@@ -28,27 +29,11 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = dirname(__dirname);
 const LOCAL_MARKETPLACE_MANIFEST = join(PKG_ROOT, ".claude-plugin", "marketplace.json");
 
-// Recommended plugins with their marketplace source + install identifier
-const RECOMMENDED = [
-  {
-    name: "pua",
-    marketplace: "tanweai/pua",
-    installSpec: "pua@pua-skills",
-    hint: "no-give-up + three red lines",
-  },
-  {
-    name: "claude-mem",
-    marketplace: "thedotmack/claude-mem",
-    installSpec: "claude-mem@thedotmack",
-    hint: "automatic cross-session memory",
-  },
-  {
-    name: "frontend-design",
-    marketplace: null, // already in default marketplace claude-plugins-official
-    installSpec: "frontend-design@claude-plugins-official",
-    hint: "Anthropic official UI skill",
-  },
-];
+// Recommended plugins: single source of truth is cli/registry.js.
+// See registry.js for the rationale — this list used to drift across
+// install/uninstall/upgrade/doctor, producing the chrome-devtools-mcp
+// orphan-plugin bug (installable but uninstallable).
+const RECOMMENDED = RECOMMENDED_PLUGINS;
 
 export async function install(args = []) {
   const all = args.includes("--all");
@@ -105,10 +90,38 @@ export async function install(args = []) {
 
   // ---------- Step 3: Install curdx-flow plugin ----------
   log.blank();
-  log.step(3, 4, "Installing curdx-flow plugin (3 MCPs will auto-start)...");
+  log.step(3, 4, "Installing curdx-flow plugin (2 MCPs will auto-start)...");
+  // Read the version the marketplace is shipping so we can decide whether an
+  // already-installed plugin needs an update (same name but stale version
+  // previously silently skipped the upgrade — caused the beta.1 → beta.7 drift).
+  let shippedVersion = null;
+  try {
+    const mf = JSON.parse(
+      readFileSync(LOCAL_MARKETPLACE_MANIFEST, "utf-8")
+    );
+    shippedVersion = mf?.metadata?.version || null;
+  } catch {
+    // marketplace not local (online install) or unreadable — fall through
+  }
+
   const installed = listPlugins();
   const already = installed.find((p) => p.name === "curdx-flow");
-  if (already) {
+  if (already && shippedVersion && already.version !== shippedVersion) {
+    log.info(
+      `curdx-flow installed at v${already.version}, marketplace ships v${shippedVersion} — updating...`
+    );
+    const r = await run(
+      "claude",
+      ["plugin", "update", "curdx-flow@curdx-flow-marketplace"],
+      { silent: true }
+    );
+    if (r.code !== 0) {
+      log.warn(`Update returned non-zero: ${r.stderr.trim() || r.stdout.trim()}`);
+      log.info(`If the version stays on v${already.version}, run: claude plugin uninstall curdx-flow@curdx-flow-marketplace && retry`);
+    } else {
+      log.ok(`curdx-flow updated to v${shippedVersion}`);
+    }
+  } else if (already) {
     log.ok(`curdx-flow already installed (v${already.version}, ${already.status})`);
   } else {
     const r = await run(
@@ -186,7 +199,7 @@ export async function install(args = []) {
       // 3. Post-install hook for claude-mem: its .mcp.json hard-codes `bun`,
       // but ~/.bun/bin is not on PATH when Claude Code spawns the MCP server.
       // Auto-create a PATH-visible symlink to fix it.
-      if (rec.name === "claude-mem") {
+      if (rec.postInstall === "claude-mem-runtimes") {
         const r = ensureClaudeMemRuntimes();
         for (const [name, res] of Object.entries(r)) {
           if (res.status === "linked") {
@@ -224,6 +237,8 @@ export async function install(args = []) {
     const r = injectGlobalProtocols();
     if (r.action === "created") {
       log.ok(`Global protocols injected ${color.dim(`(${GLOBAL_CLAUDE_MD})`)}`);
+    } else if (r.action === "appended") {
+      log.ok(`Global protocols appended ${color.dim(`(${GLOBAL_CLAUDE_MD})`)}`);
     } else if (r.action === "upgraded") {
       log.ok(`Global protocols upgraded ${color.dim(`(${GLOBAL_CLAUDE_MD})`)}`);
     } else {

package/cli/protocols.js

@@ -5,7 +5,14 @@
  * and reversible (uninstall removes it cleanly without touching user content).
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+  renameSync,
+  unlinkSync,
+} from "node:fs";
 import { join, dirname } from "node:path";
 
 const HOME = process.env.HOME || "";
@@ -53,16 +60,56 @@ function readGlobalMd() {
 
 /**
  * Locate the sentinel block in the content.
- * Returns { start, end } indices into content, or null if not found.
+ * Returns { start, end } indices into content, `null` if neither sentinel is
+ * present, or throws if the block is corrupted (begin without matching end).
+ * The throw is intentional — previously the corrupted case silently returned
+ * null, so the next run would append a SECOND block, producing drift.
  */
 function findBlock(content) {
   const start = content.indexOf(SENTINEL_BEGIN);
-  if (start === -1) return null;
+  if (start === -1) {
+    // Also check for a dangling END without BEGIN — that is also corrupted.
+    if (content.indexOf(SENTINEL_END) !== -1) {
+      throw new Error(
+        `Corrupted protocol block in ${GLOBAL_CLAUDE_MD}: END sentinel found without BEGIN. ` +
+          `Manually inspect the file and remove the dangling END line, then re-run.`
+      );
+    }
+    return null;
+  }
   const endIdx = content.indexOf(SENTINEL_END, start);
-  if (endIdx === -1) return null;
+  if (endIdx === -1) {
+    throw new Error(
+      `Corrupted protocol block in ${GLOBAL_CLAUDE_MD}: BEGIN sentinel found without END. ` +
+        `Manually remove the orphan BEGIN line (or restore the END), then re-run.`
+    );
+  }
   return { start, end: endIdx + SENTINEL_END.length };
 }
 
+/**
+ * Write `content` to `path` atomically: write to a sibling temp file first,
+ * then rename. This prevents a half-written CLAUDE.md if the process is
+ * interrupted mid-write, and avoids races between concurrent install /
+ * uninstall invocations.
+ */
+function atomicWrite(path, content) {
+  const tmp = `${path}.curdx-flow.tmp.${process.pid}`;
+  try {
+    writeFileSync(tmp, content, "utf-8");
+    renameSync(tmp, path);
+  } catch (err) {
+    // Best-effort cleanup of the temp file; swallow errors here since we
+    // are already re-throwing the real failure.
+    try {
+      if (existsSync(tmp)) unlinkSync(tmp);
+    } catch {
+      // ignore
+    }
+    throw err;
+  }
+}
+
 /**
  * Inject (or upgrade) the protocol block in ~/.claude/CLAUDE.md.
  * @returns {{action:"created"|"upgraded"|"unchanged", path:string}}
@@ -81,8 +128,8 @@ export function injectGlobalProtocols() {
       ? (existing.endsWith("\n") ? "\n" : "\n\n")
       : "";
     const next = existing + sep + FULL_BLOCK + "\n";
-    writeFileSync(path, next, "utf-8");
-    return { action: existing.length === 0 ? "created" : "created", path };
+    atomicWrite(path, next);
+    return { action: existing.length === 0 ? "created" : "appended", path };
   }
 
   // Replace existing block (handle upgrade-in-place)
@@ -92,7 +139,7 @@ export function injectGlobalProtocols() {
   }
   const next =
     existing.slice(0, block.start) + FULL_BLOCK + existing.slice(block.end);
-  writeFileSync(path, next, "utf-8");
+  atomicWrite(path, next);
   return { action: "upgraded", path };
 }
 
@@ -119,6 +166,6 @@ export function removeGlobalProtocols() {
   }
 
   const next = existing.slice(0, start) + existing.slice(end);
-  writeFileSync(path, next, "utf-8");
+  atomicWrite(path, next);
   return { action: "removed", path };
 }

package/cli/registry.js

@@ -0,0 +1,73 @@
+/**
+ * Single source of truth for recommended companion plugins.
+ *
+ * Background: before this file existed, the list of recommended plugins lived
+ * in FOUR independent places (install.js, uninstall.js, upgrade.js,
+ * doctor.js). They drifted — chrome-devtools-mcp was added to install.js
+ * during the beta.8 MCP decoupling but forgotten in the other three,
+ * making it installable but uninstallable. This registry exists so adding
+ * or removing a plugin is a one-file change.
+ *
+ * Every consumer pulls what it needs via property access:
+ *   - install.js     → marketplace + installSpec + hint (+ optional postInstall)
+ *   - uninstall.js   → uninstallSpec
+ *   - upgrade.js     → installSpec (for `claude plugin update`) + marketplaceId
+ *   - doctor.js      → name + installSpec (for manual recovery hints)
+ */
+
+export const RECOMMENDED_PLUGINS = [
+  {
+    name: "pua",
+    marketplace: "tanweai/pua",
+    marketplaceId: "pua",
+    installSpec: "pua@pua-skills",
+    uninstallSpec: "pua@pua-skills",
+    hint: "no-give-up + three red lines",
+  },
+  {
+    name: "claude-mem",
+    marketplace: "thedotmack/claude-mem",
+    marketplaceId: "thedotmack",
+    installSpec: "claude-mem@thedotmack",
+    uninstallSpec: "claude-mem@thedotmack",
+    hint: "automatic cross-session memory",
+    postInstall: "claude-mem-runtimes",
+  },
+  {
+    name: "frontend-design",
+    // Already in default marketplace claude-plugins-official, no add needed
+    marketplace: null,
+    marketplaceId: "claude-plugins-official",
+    installSpec: "frontend-design@claude-plugins-official",
+    uninstallSpec: "frontend-design@claude-plugins-official",
+    hint: "Anthropic official UI skill",
+  },
+  {
+    name: "chrome-devtools-mcp",
+    marketplace: "ChromeDevTools/chrome-devtools-mcp",
+    marketplaceId: "chrome-devtools-plugins",
+    installSpec: "chrome-devtools-mcp@chrome-devtools-plugins",
+    uninstallSpec: "chrome-devtools-mcp@chrome-devtools-plugins",
+    hint: "Chrome DevTools + Puppeteer (Google official)",
+  },
+];
+
+/**
+ * Marketplaces to refresh during `upgrade`. Derived from RECOMMENDED_PLUGINS
+ * plus the curdx-flow marketplace itself.
+ */
+export const MARKETPLACES_TO_REFRESH = [
+  "curdx-flow-marketplace",
+  ...RECOMMENDED_PLUGINS
+    .filter((p) => p.marketplaceId && p.marketplaceId !== "claude-plugins-official")
+    .map((p) => p.marketplaceId),
+];
+
+/**
+ * Plugin install specs to update during `upgrade` — includes curdx-flow
+ * itself plus every recommended plugin.
+ */
+export const PLUGINS_TO_UPDATE = [
+  "curdx-flow@curdx-flow-marketplace",
+  ...RECOMMENDED_PLUGINS.map((p) => p.installSpec),
+];

package/cli/uninstall.js

@@ -15,18 +15,15 @@ import {
   listPlugins,
 } from "./utils.js";
 import { removeGlobalProtocols, GLOBAL_CLAUDE_MD } from "./protocols.js";
+import { RECOMMENDED_PLUGINS } from "./registry.js";
 
 const HOME = process.env.HOME || "";
 
-// Keep aligned with install.js
-const RECOMMENDED = [
-  { name: "pua", uninstallSpec: "pua@pua-skills" },
-  { name: "claude-mem", uninstallSpec: "claude-mem@thedotmack" },
-  {
-    name: "frontend-design",
-    uninstallSpec: "frontend-design@claude-plugins-official",
-  },
-];
+// Pull uninstall-relevant subset from the single registry. See registry.js.
+const RECOMMENDED = RECOMMENDED_PLUGINS.map(({ name, uninstallSpec }) => ({
+  name,
+  uninstallSpec,
+}));
 
 // Symlinks created by install.js (only cleaned with --purge)
 const MANAGED_SYMLINKS = [

package/cli/upgrade.js

@@ -3,13 +3,10 @@
  */
 
 import { color, log, run, listPlugins, claudeVersion } from "./utils.js";
-
-const PLUGINS_TO_UPDATE = [
-  "curdx-flow@curdx-flow-marketplace",
-  "pua@pua-skills",
-  "claude-mem@thedotmack",
-  "frontend-design@claude-plugins-official",
-];
+import {
+  PLUGINS_TO_UPDATE,
+  MARKETPLACES_TO_REFRESH,
+} from "./registry.js";
 
 export async function upgrade(args = []) {
   log.title("⬆️  CurDX-Flow upgrade");
@@ -19,10 +16,9 @@ export async function upgrade(args = []) {
     process.exit(1);
   }
 
-  // Refresh marketplaces first
+  // Refresh marketplaces first (derived from cli/registry.js)
   log.step(1, 2, "Refreshing marketplaces...");
-  const marketplaces = ["curdx-flow-marketplace", "pua", "thedotmack"];
-  for (const mp of marketplaces) {
+  for (const mp of MARKETPLACES_TO_REFRESH) {
     const r = await run(
       "claude",
       ["plugin", "marketplace", "update", mp],

package/cli/utils.js

@@ -247,8 +247,8 @@ export function pluginCacheDir(pluginName = "curdx-flow", marketplace = "curdx-f
 // detection + self-healing: create a symlink to the user-level bun install
 // in a PATH-visible directory.
 
-import { mkdirSync, symlinkSync, lstatSync, unlinkSync, readlinkSync } from "node:fs";
-// `existsSync` and `join` already imported at the top of this file.
+import { existsSync, mkdirSync, symlinkSync, lstatSync, unlinkSync, readlinkSync } from "node:fs";
+// `join` already imported at the top of this file.
 
 const HOME = process.env.HOME || "";
 

package/commands/init.md

@@ -72,8 +72,8 @@ Append (if not already present):
 ### Step 5: Health Check
 
 Run `npx @curdx/flow doctor` (or inline its checks) to verify:
-- 3 MCPs started (context7 / sequential-thinking / chrome-devtools)
-- Recommended plugins status (pua / claude-mem / frontend-design)
+- 2 bundled MCPs started (context7 / sequential-thinking)
+- Recommended plugins status (pua / claude-mem / frontend-design / chrome-devtools-mcp)
 
 ### Step 6: Prompt Next Steps
 

package/commands/spec.md

@@ -94,7 +94,7 @@ After each phase completes successfully, update `.state.json`:
 {
   "phase": "<just-completed-phase>",
   "phase_status": { "<phase>": "completed" },
-  "updated_at": "<ISO8601 timestamp>"
+  "updated": "<ISO8601 timestamp>"
 }
 ```
 

package/commands/start.md

@@ -48,7 +48,7 @@ Mode must be `fast`, `standard`, or `enterprise`. Invalid → default to `standa
 ## Branch logic
 
 ### Branch A: `--list`
-Enumerate every directory under `.flow/specs/`, read each `.state.json` for `phase` and `updated_at`, print a numbered list, then `AskUserQuestion` to pick one. Picking sets `.flow/.active-spec` and exits.
+Enumerate every directory under `.flow/specs/`, read each `.state.json` for `phase` and `updated` (per `schemas/spec-state.schema.json`), print a numbered list, then `AskUserQuestion` to pick one. Picking sets `.flow/.active-spec` and exits.
 
 ### Branch B: `--resume` (no name)
 Read `.flow/.active-spec`. If it points to a valid spec dir, report its current phase and next suggested command (`/curdx-flow:spec` if incomplete, `/curdx-flow:implement` if tasks ready). If `.active-spec` is empty or stale, fall back to Branch A.
@@ -61,17 +61,25 @@ Create a new spec:
 
 ```bash
 mkdir -p ".flow/specs/$SPEC_NAME"
+# NOTE: field names MUST match schemas/spec-state.schema.json:
+#   - spec_name (not "spec")
+#   - created (date, not "created_at")
+#   - updated (date-time, not "updated_at")
+#   - phase must be one of the enum values; the initial phase is "research"
+#     (there is no "created" phase — that was schema drift pre-beta.9)
+#   - version is required
 cat > ".flow/specs/$SPEC_NAME/.state.json" <<JSON
 {
-  "spec": "$SPEC_NAME",
+  "version": "1.0",
+  "spec_name": "$SPEC_NAME",
   "goal": "$GOAL",
   "mode": "$FLAG_MODE",
-  "phase": "created",
+  "phase": "research",
   "phase_status": {},
   "strategy": "auto",
   "execute_state": {},
-  "created_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
-  "updated_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  "created": "$(date -u +%Y-%m-%d)",
+  "updated": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 }
 JSON
 echo "$SPEC_NAME" > .flow/.active-spec

package/hooks/hooks.json

@@ -20,17 +20,6 @@
         ]
       }
     ],
-    "PostToolUseFailure": [
-      {
-        "matcher": "Bash|Edit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/fail-tracker.sh"
-          }
-        ]
-      }
-    ],
     "Stop": [
       {
         "hooks": [

package/hooks/scripts/quick-mode-guard.sh

@@ -40,17 +40,20 @@ ACTIVE=$(cat .flow/.active-spec 2>/dev/null)
 STATE_FILE=".flow/specs/$ACTIVE/.state.json"
 [ ! -f "$STATE_FILE" ] && exit 0
 
-# Read quickMode + mode
-QUICK_MODE=$(python3 -c "
-import json
+# Read quickMode + mode. Pass STATE_FILE via env (NOT shell interpolation
+# into the python source) so an active-spec name containing quotes/$ cannot
+# inject python code.
+export STATE_FILE
+QUICK_MODE=$(python3 -c '
+import json, os
 try:
-    s = json.load(open('$STATE_FILE'))
-    qm = s.get('quickMode', False)
-    mode = s.get('mode', '')
-    print('true' if (qm or mode == 'autonomous') else 'false')
+    s = json.load(open(os.environ["STATE_FILE"]))
+    qm = s.get("quickMode", False)
+    mode = s.get("mode", "")
+    print("true" if (qm or mode == "autonomous") else "false")
 except Exception:
-    print('false')
-" 2>/dev/null)
+    print("false")
+' 2>/dev/null)
 
 if [ "$QUICK_MODE" = "true" ]; then
   # Block and inject guidance

package/hooks/scripts/session-start.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # CurDX-Flow SessionStart Hook
 # Duties:
-#   1. Daily dependency check — nudge user to /flow-install-deps if recommended plugins missing
+#   1. Daily dependency check — nudge user to `npx @curdx/flow install --all` if recommended plugins missing
 #   2. Load active spec progress into session context
 #
 # Design notes:

package/hooks/scripts/stop-watcher.sh

@@ -56,6 +56,12 @@ if ! command -v python3 >/dev/null 2>&1; then
   allow_stop
 fi
 
+# Export STATE_FILE BEFORE invoking python3 — the heredoc-based parser reads
+# os.environ["STATE_FILE"]. Previously the export was placed after the
+# heredoc, so python3 always got None, json.load(None) silently failed, and
+# the stop-hook strategy never activated.
+export STATE_FILE
+
 read STRATEGY PHASE TASK_INDEX TOTAL_TASKS FAILED ROUNDS <<EOF
 $(python3 <<'PY'
 import json, os, sys
@@ -75,7 +81,6 @@ print(strategy, phase, ti, tt, failed, rounds)
 PY
 )
 EOF
-export STATE_FILE
 
 # Only activate for stop-hook strategy + execute phase
 [ "$STRATEGY" != "stop-hook" ] && allow_stop
@@ -95,12 +100,17 @@ if [ -n "$TRANSCRIPT_PATH" ] && [ -f "$TRANSCRIPT_PATH" ]; then
   TRANSCRIPT_TAIL=$(tail -c 51200 "$TRANSCRIPT_PATH" 2>/dev/null || echo "")
 fi
 
+# Python state-file updates: use quoted heredocs (<<'PY') + os.environ so
+# the spec-name-derived STATE_FILE path is NEVER interpolated into the
+# python source text. Previously a spec name containing single quotes or
+# $-signs could break the script or inject arbitrary code.
+
 # Check for explicit completion signals
 if echo "$TRANSCRIPT_TAIL" | grep -q "ALL_TASKS_COMPLETE"; then
   # Cleanup: mark phase completed
-  python3 <<PY 2>/dev/null
-import json
-p = "$STATE_FILE"
+  python3 <<'PY' 2>/dev/null
+import json, os
+p = os.environ["STATE_FILE"]
 s = json.load(open(p))
 s.setdefault("phase_status", {})["execute"] = "completed"
 s["phase"] = "verify"  # move to verify phase
@@ -112,16 +122,16 @@ fi
 # Check for fail signal (accumulate; actual stop decision below)
 if echo "$TRANSCRIPT_TAIL" | grep -q "TASK_FAILED"; then
   # Increment failed_attempts
-  python3 <<PY 2>/dev/null
-import json
-p = "$STATE_FILE"
+  python3 <<'PY' 2>/dev/null
+import json, os
+p = os.environ["STATE_FILE"]
 s = json.load(open(p))
 s.setdefault("execute_state", {})
 s["execute_state"]["failed_attempts"] = s["execute_state"].get("failed_attempts", 0) + 1
 json.dump(s, open(p, "w"), indent=2, ensure_ascii=False)
 PY
-  # Re-read
-  FAILED=$(python3 -c "import json; print(json.load(open('$STATE_FILE'))['execute_state']['failed_attempts'])" 2>/dev/null || echo 0)
+  # Re-read — again via os.environ, no shell interpolation into python.
+  FAILED=$(python3 -c 'import json, os; print(json.load(open(os.environ["STATE_FILE"]))["execute_state"]["failed_attempts"])' 2>/dev/null || echo 0)
 fi
 
 # ---------- 6. Safety brakes ----------
@@ -138,9 +148,9 @@ fi
 # Check if all tasks done
 if [ "$TASK_INDEX" -ge "$TOTAL_TASKS" ] && [ "$TOTAL_TASKS" -gt 0 ]; then
   # Mark complete
-  python3 <<PY 2>/dev/null
-import json
-p = "$STATE_FILE"
+  python3 <<'PY' 2>/dev/null
+import json, os
+p = os.environ["STATE_FILE"]
 s = json.load(open(p))
 s.setdefault("phase_status", {})["execute"] = "completed"
 s["phase"] = "verify"
@@ -151,9 +161,9 @@ fi
 
 # ---------- 7. Block and continue ----------
 # Increment round counter
-python3 <<PY 2>/dev/null
-import json
-p = "$STATE_FILE"
+python3 <<'PY' 2>/dev/null
+import json, os
+p = os.environ["STATE_FILE"]
 s = json.load(open(p))
 s.setdefault("execute_state", {})
 s["execute_state"]["global_iteration"] = s["execute_state"].get("global_iteration", 0) + 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@curdx/flow",
-  "version": "2.0.0-beta.7",
+  "version": "2.0.0-beta.9",
   "description": "CLI installer for CurDX-Flow — AI engineering workflow meta-framework for Claude Code",
   "type": "module",
   "bin": {
@@ -22,6 +22,7 @@
     "agent-preamble/",
     "templates/",
     "schemas/",
+    "skills/",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"

package/skills/brownfield-index/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: brownfield-index
+description: Invoke when the user is new to an unfamiliar / legacy / brownfield codebase and wants a structural understanding — module map, component inventory, API surface, data flow. Triggers on "legacy code", "brownfield", "unfamiliar", "new to this code", "new to this project", "just joined", "inherited codebase", "explore codebase", "understand structure", "index code", "map modules", "tour", "onboard", "what is this project", "老代码", "棕地", "不熟悉", "新接手", "新项目", "代码探索", "结构理解", "索引", "模块地图", "先了解下", "先熟悉一下".
+allowed-tools: [Read, Grep, Glob, Bash]
+---
+
+# Brownfield Index
+
+You are invoked when the user needs a structural map of an existing codebase they are not yet familiar with.
+
+## Preconditions
+
+1. The repository root is the current working directory (or a path the user specifies).
+2. The project is not a new `/curdx-flow:init`-ed greenfield project (if it is, direct the user to `/curdx-flow:start` instead).
+
+## Workflow
+
+### Step 1: Detect project type
+
+Read `package.json` / `Cargo.toml` / `pyproject.toml` / `go.mod` / `pom.xml` to classify the ecosystem and build tool. This determines which directory conventions to apply.
+
+### Step 2: Scan directory structure
+
+Produce a top-level inventory:
+- **Entry points** (main / index / bin scripts)
+- **Module directories** (src/, lib/, internal/, pkg/ …)
+- **Test directories**
+- **Config files**
+- **Tooling** (CI, lint, format configs)
+
+### Step 3: Component inventory
+
+For each module directory, list:
+- Files and their apparent role (inferred from names + top-of-file comments)
+- Public exports / exported symbols
+- Third-party dependencies imported
+
+### Step 4: API surface
+
+If HTTP / RPC endpoints exist, index them: route → handler → middleware. For CLI tools, index commands → handlers.
+
+### Step 5: Write index document
+
+Output `.flow/codebase-index.md` containing:
+- **Overview** (project purpose, build tool, runtime)
+- **Directory tree** (with per-directory one-liner descriptions)
+- **Entry points** (where execution starts)
+- **Key abstractions** (core types, interfaces, classes that everything else hangs off)
+- **External dependencies** (grouped: prod runtime / dev tooling / transitive)
+- **Known gaps / red flags** (missing tests, TODOs, suspicious patterns)
+
+### Step 6: Hand off
+
+Point the user at the next useful action:
+- "Looking to add a feature here? Run `/curdx-flow:start <name>` to begin a spec."
+- "Debugging something specific? Run `/curdx-flow:debug '<symptom>'`."
+
+## Notes
+
+This skill uses Read + Grep + Glob + Bash with no specialized agent — general tools are enough for structural discovery. The index is meant to be quick (5–10 minutes), not exhaustive.
+
+For deep research into a specific library or framework, use `context7` MCP directly.

package/skills/browser-qa/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: browser-qa
+description: Invoke when the user wants to test a UI/frontend in a real browser — accessibility, performance, console errors, network traffic, visual regression. Triggers on "browser test", "test in browser", "UI test", "e2e test", "frontend test", "accessibility", "a11y", "WCAG", "lighthouse", "performance audit", "console error", "network request", "cross-browser", "responsive", "mobile test", "visual regression", "screenshot", "浏览器测试", "UI 测试", "可访问性", "性能", "控制台错误", "截图", "移动端", "兼容性", "在浏览器里跑", "看看 console".
+allowed-tools: [Read, Write, Bash, Grep, Glob, WebFetch]
+---
+
+# Browser QA
+
+You are invoked when the user wants real-browser QA of a UI flow.
+
+## Preconditions
+
+1. `chrome-devtools` MCP is available (`mcp__chrome-devtools__*`). If missing, fall back to a manual checklist.
+2. A URL (dev server or deployed) is available. Prompt for it if not provided.
+
+## Workflow
+
+### Step 1: Clarify scope
+
+Confirm with the user:
+- **URL under test** (local `http://localhost:3000` or remote)
+- **Flow to test** (e.g., "sign up → dashboard → logout")
+- **What success looks like** (accessibility / performance / zero console errors / visual match)
+
+### Step 2: Dispatch `flow-qa-engineer`
+
+Delegate to the `flow-qa-engineer` agent. It will:
+1. Open the target URL via `mcp__chrome-devtools__new_page`
+2. Drive the flow with `mcp__chrome-devtools__click` / `fill` / `navigate`
+3. Capture `list_console_messages`, `list_network_requests`, `take_screenshot`, optionally `lighthouse_audit`
+4. Compare against expected behavior
+
+### Step 3: Report findings
+
+Produce `.flow/specs/<active>/qa-report.md` with:
+- **Bugs** (reproducible, severity P1/P2/P3)
+- **Performance** (LCP / INP / CLS from Lighthouse)
+- **Accessibility** (axe violations with WCAG references)
+- **Console errors** (full stack traces)
+- **Screenshots** (attached)
+
+### Step 4: Hand off
+
+If bugs found: suggest `/curdx-flow:debug "<bug title>"` for systematic root-cause analysis.
+If accessibility violations: suggest fixes inline with WCAG refs.
+
+## References
+
+- `flow-qa-engineer` agent: `@${CLAUDE_PLUGIN_ROOT}/agents/flow-qa-engineer.md`
+- chrome-devtools MCP docs: https://github.com/ChromeDevTools/chrome-devtools-mcp

package/skills/epic/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: epic
+description: Invoke when user wants to break a large feature into multiple smaller specs with a dependency graph. Triggers on "epic", "big feature", "too big", "decompose", "break down", "break into", "split into", "multi-spec", "multiple features", "sub-features", "vertical slice", "parent feature", "large scope", "大功能", "太大", "拆分", "拆解", "分解", "多个规格", "子功能", "垂直切片", "史诗级", "分几个做", "一个 sprint 做不完", "需要拆".
+allowed-tools: [Read, Write, Grep, Glob, Bash]
+---
+
+# Epic Decomposition
+
+You are invoked when the user wants to break a large feature into multiple vertical-slice specs.
+
+## Preconditions
+
+1. A `.flow/` project must exist (run `/curdx-flow:init` first if missing).
+2. The user has stated a feature scope that is too large for a single spec.
+
+## Workflow
+
+### Step 1: Clarify the epic scope
+
+Ask the user (or infer from context) for:
+- **Epic name** (short identifier, kebab-case)
+- **One-sentence goal** of the whole epic
+- **Hard boundary**: what is explicitly out of scope for this epic
+
+### Step 2: Dispatch `flow-triage-analyst`
+
+Delegate to the `flow-triage-analyst` agent with the epic name + goal + boundary. The agent returns:
+- A vertical-slice decomposition (not horizontal by layer)
+- Dependency graph between slices
+- Shared interfaces that must be frozen before parallel work begins
+- Suggested slice ordering (MVP → iteration → polish)
+
+### Step 3: Write epic manifest
+
+Create `.flow/_epics/<epic-name>/epic.md` with:
+
+```markdown
+# Epic: <name>
+
+## Goal
+<one sentence>
+
+## Slices (vertical)
+| ID | Slice | Depends on | Shared interface |
+|----|-------|-----------|------------------|
+| S1 | ...   | —          | —                |
+| S2 | ...   | S1         | `types/auth.ts`  |
+| S3 | ...   | S1         | —                |
+
+## Frozen Interfaces
+(contracts that must not change once slices start)
+
+## Out of Scope
+- ...
+```
+
+### Step 4: Scaffold sub-spec skeletons
+
+For each slice, create `.flow/specs/<epic-name>-<slice-id>/` with a minimal `.state.json` linking back to the epic manifest.
+
+### Step 5: Report to user
+
+Summarize: "Epic `<name>` decomposed into N vertical slices. Start any slice with `/curdx-flow:start <epic-name>-<slice-id>`. Suggested order: S1 → S2 → S3."
+
+## References
+
+- Vertical-slice methodology: `@${CLAUDE_PLUGIN_ROOT}/knowledge/epic-decomposition.md`
+- Spec skeleton: `@${CLAUDE_PLUGIN_ROOT}/templates/`

package/skills/security-audit/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: security-audit
+description: Invoke when the user wants a security review — OWASP Top 10, STRIDE threat modeling, credential handling, injection, secrets, sensitive data handling. Triggers on "security", "auth", "authentication", "credential", "password", "secret", "API key", "token", "OWASP", "STRIDE", "CVE", "vulnerability", "injection", "XSS", "CSRF", "SSRF", "SQL injection", "hardcoded secret", "sensitive data", "leak", "安全", "认证", "凭证", "密码", "密钥", "令牌", "漏洞", "注入", "硬编码", "敏感数据", "泄露", "API key 会不会泄", "有没有安全问题".
+allowed-tools: [Read, Grep, Glob, Bash, WebSearch]
+---
+
+# Security Audit
+
+You are invoked when the user wants a systematic security review of the current spec or codebase.
+
+## Preconditions
+
+1. The code or spec under review is reachable from the current working directory.
+2. The user has identified the scope (current spec, specific module, or whole repo).
+
+## Workflow
+
+### Step 1: Clarify audit scope
+
+Confirm:
+- **Scope** (current spec / specific paths / whole repo)
+- **Depth** (OWASP-only / OWASP + STRIDE / + dependency CVE scan)
+- **Risk tolerance** (block on any SR / only block on SR with POC / advisory only)
+
+### Step 2: Dispatch `flow-security-auditor`
+
+Delegate to the `flow-security-auditor` agent. It will:
+1. Scan for hardcoded secrets, weak crypto, unsanitized inputs
+2. Apply OWASP Top 10 (A01 Broken Access Control → A10 SSRF)
+3. Apply STRIDE threat modeling (Spoofing, Tampering, Repudiation, Information disclosure, DoS, Elevation)
+4. Run dependency CVE scan (`npm audit` / equivalent)
+5. Produce a findings report with severity labels (SR = Blocking Red line, SW = Warning, SM = Mandatory-to-address)
+
+### Step 3: Write security report
+
+Output `.flow/specs/<active>/security-audit.md` containing:
+- **SR (blocking)** — must fix before ship
+- **SW (warning)** — should fix, won't block
+- **SM (mandatory)** — baseline items that must be present
+- **CVE hits** — direct / transitive dependencies with known vulns
+- **Recommended fixes** — concrete patches, not generic advice
+
+### Step 4: Enforce gate
+
+Apply the `security-gate` (`@${CLAUDE_PLUGIN_ROOT}/gates/security-gate.md`) — if any SR findings exist, block completion until remediated or explicitly waived with a D-NN decision in STATE.md.
+
+## References
+
+- `flow-security-auditor` agent: `@${CLAUDE_PLUGIN_ROOT}/agents/flow-security-auditor.md`
+- security-gate: `@${CLAUDE_PLUGIN_ROOT}/gates/security-gate.md`

package/skills/ui-sketch/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: ui-sketch
+description: Invoke when the user wants UI design drafts — components, layouts, variants, mockups, CSS/theme/styling decisions. Triggers on "design UI", "UI design", "component layout", "variants", "wireframe", "mockup", "prototype", "sketch", "draft layout", "visual design", "styling", "CSS", "theming", "dark mode", "responsive design", "color scheme", "UI 设计", "界面", "组件", "布局", "变体", "原型", "草图", "样式", "主题", "暗色模式", "做个 UI", "出几个版本", "换几种颜色".
+allowed-tools: [Read, Write, Bash, WebSearch]
+---
+
+# UI Sketch
+
+You are invoked when the user wants fresh UI design drafts — typically 2–4 variants for comparison, or a single iterative refinement.
+
+## Preconditions
+
+1. The `frontend-design` skill (Anthropic official) should be installed. Without it, fall back to Tailwind + shadcn/ui defaults.
+2. The user provides a description of the UI goal (component, page, or flow).
+
+## Workflow
+
+### Step 1: Clarify design brief
+
+Confirm with the user:
+- **What is being designed** (component / page / full screen)
+- **Context** (consumer product / enterprise tool / marketing site / internal dashboard)
+- **Must-haves** (brand colors / existing design system / responsive breakpoints)
+- **Variant count** (default: 3 variants with distinct design directions)
+
+### Step 2: Dispatch `flow-ux-designer`
+
+Delegate to the `flow-ux-designer` agent with the brief. It will:
+1. Invoke the `frontend-design` skill with the brief
+2. Generate N variant HTML/JSX files under `.flow/specs/<active>/sketches/`
+3. For each variant, produce a rationale: typography, color, layout decisions
+4. Open the variants for user preview if a dev server is running
+
+### Step 3: Present variants
+
+Show the user:
+- **Variant preview URLs** or file paths
+- **Design rationale** per variant (what's different, why)
+- **Accessibility notes** (contrast ratios, focus states)
+
+### Step 4: Iterate or finalize
+
+- If user picks a variant: move the chosen file into the spec's `design.md` asset section.
+- If user wants a hybrid: dispatch `flow-ux-designer` again with "merge variant A layout + variant B color scheme".
+
+## References
+
+- `flow-ux-designer` agent: `@${CLAUDE_PLUGIN_ROOT}/agents/flow-ux-designer.md`
+- `flow-ui-researcher` agent (for competitive reference scraping): `@${CLAUDE_PLUGIN_ROOT}/agents/flow-ui-researcher.md`

package/hooks/scripts/fail-tracker.sh

@@ -1,31 +0,0 @@
-#!/usr/bin/env bash
-# CurDX-Flow PostToolUseFailure Hook
-# Tracks consecutive tool failures to enable pua integration (Phase 4+).
-# For now, just maintains a counter in plugin data directory.
-#
-# Future: when pua is installed and fail_count >= threshold, auto-invoke /pua:pua.
-
-set -u
-
-DATA_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.claude/plugins/data/curdx-flow}"
-COUNTER="$DATA_DIR/fail-count"
-
-mkdir -p "$DATA_DIR" 2>/dev/null || true
-
-# Read current count
-CURRENT=0
-[ -f "$COUNTER" ] && CURRENT="$(cat "$COUNTER" 2>/dev/null || echo 0)"
-
-# Increment
-NEXT=$((CURRENT + 1))
-echo "$NEXT" > "$COUNTER" 2>/dev/null || true
-
-# Placeholder for future pua escalation (Phase 4+):
-# if [ "$NEXT" -ge 2 ] && command -v claude >/dev/null 2>&1; then
-#   if claude plugin list 2>/dev/null | grep -q 'pua'; then
-#     # Inject escalation suggestion via hook output
-#     ...
-#   fi
-# fi
-
-exit 0