@curdx/flow 2.0.21 → 2.1.0

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.21"
+    "version": "2.1.0"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "curdx-flow",
-  "version": "2.0.21",
+  "version": "2.1.0",
   "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",

package/CHANGELOG.md

@@ -9,9 +9,80 @@ All notable changes to CurdX-Flow will be documented here.
 - `cli/install-workflow.js` + `cli/install-self-update.js` — after `npm install -g @curdx/flow@latest`, the self-update restart spawned a bare `curdx-flow`, which fails under `npx` (PATH not guaranteed) or when the global bin dir isn't on PATH, surfacing as `sh: curdx-flow: command not found`. `checkAndUpdateSelf` now returns the absolute entry path of the freshly installed package, and the restart re-launches with `process.execPath` + that absolute script path. No PATH dependency, no shell involvement. Two new unit tests assert the spawn contract.
 - `README.zh.md` — corrected the `smart-ralph` credit URL. The previously listed `Nibzard/smart-ralph` 404s; the repo matching the described feature set ("Spec-driven + Ralph Wiggum loop + Claude Code plugin") is `tzachbon/smart-ralph`.
 
-## [Unreleased]
-
-### Fixed
+## [2.1.0] - 2026-04-23
+
+### Changed (commands → skills migration; zero user-visible change)
+
+All 9 slash workflows migrate from `commands/*.md` to
+`skills/<name>/SKILL.md`, per Anthropic's recommended plugin layout.
+`/curdx-flow:<name>` still resolves to the same slash paths with the
+same arguments and output. File history is preserved via `git mv`.
+
+- `skills/implement/SKILL.md` — progressive-disclosure split to
+  `skills/implement/references/wave-execution.md`; body reduced
+  from 381 to 240 lines.
+- `/curdx-flow:verify` and `/curdx-flow:debug` — route via
+  Anthropic's native `context: fork + agent:` mechanism instead of
+  hand-rolled `Task()` dispatch prose. `agents/flow-verifier.md`
+  and `agents/flow-debugger.md` are unchanged.
+- `/curdx-flow:review --devex` — new optional flag; wires the
+  previously caller-less `gates/devex-gate.md` into the reviewer
+  dispatch.
+- `cli/install-companions.js` — split by concern into four modules
+  (`install-required-plugins.js`, `install-bundled-mcps.js`,
+  `install-recommended-plugins.js`, `install-context7-config.js`).
+  `install-companions.js` becomes a re-export barrel; callers in
+  `cli/install.js` and `cli/install-workflow.js` unchanged.
+- `package.json.files` — drops `"commands/"` (directory removed);
+  `"skills/"` retained.
+- `.gitignore` — anchors the `references/` pattern to the repo root
+  (`/references/`) so `skills/<name>/references/` progressive-disclosure
+  directories ship with the plugin.
+
+### Added (internal test coverage)
+
+- `test/skill-surface-parity.test.js` — snapshot of 14 unqualified
+  slash names (9 migrated + 5 pre-existing); pins the public
+  command surface across every refactor stage.
+- `test/schema-drift.test.js` — strict equality between
+  `schemas/*.json` mode enum and documented v2 modes.
+- `test/registry-session-start-parity.test.js` — strict equality
+  between `hooks/scripts/session-start.sh` plugin list and
+  `cli/registry.js` RECOMMENDED_PLUGINS.
+- `test/language-rule-scan.test.js` — no CJK characters outside
+  `cli/**` and an explicit small allow-list.
+- `test/install-required-plugins.test.js`,
+  `test/install-bundled-mcps.test.js`,
+  `test/install-recommended-plugins.test.js`,
+  `test/install-context7-config.test.js` — module-import smoke
+  tests for the four split install modules.
+- `test/pack-tarball-smoke.test.js` — `npm pack --dry-run`
+  assertions that `commands/` is absent, 14 SKILL.md files and
+  `skills/implement/references/` ship, and every top-level
+  infrastructure directory is present in the tarball (Acceptance
+  #18 from `docs/refactor-plan.md`).
+
+Total test count: 85 → 104, all green.
+
+### Fixed (drift cleanup)
+
+- `schemas/spec-state.schema.json`, `schemas/config.schema.json` —
+  remove unreachable `sketch` and `autonomous` mode enum values.
+  Both were retired on the user-facing surface in v2 but never
+  cleaned from the schemas (see `MIGRATION.md`).
+- `hooks/scripts/session-start.sh` — adds `chrome-devtools-mcp` to
+  the dependency-check list, closing the beta.8 drift that
+  `cli/registry.js` was supposed to prevent.
+- `agent-preamble/preamble.md` — removes an empty
+  `| Task | Guideline |` table header left behind by a prior edit.
+- `README.zh.md` — masthead paragraph rewritten from the pre-v2
+  "meta-framework" positioning to the current "discipline layer"
+  framing, parallel to `README.md`.
+- `cli/protocols-body.md` — explicit carve-out paragraph allowing
+  `cli/` installer menus to be bilingual; every other layer stays
+  English for AI / agent adaptation.
+
+### Fixed (hooks — previously pending)
 
 - `hooks/hooks.json` + `hooks/scripts/inject-karpathy.sh` — migrated the L1 baseline injector from the `InstructionsLoaded` event to `SessionStart` with `matcher: "startup|clear|compact"`. Per the Claude Code hooks docs (code.claude.com/docs/en/hooks), `InstructionsLoaded` is an observability-only event: its hook schema has no `hookSpecificOutput` field, so the injector's `{"hookSpecificOutput":{"hookEventName":"InstructionsLoaded","additionalContext":…}}` payload was rejected at session boot with `Hook JSON output validation failed — (root): Invalid input`, producing the `SessionStart:startup hook error` banner on every Claude Code launch. The `startup|clear|compact` matcher preserves the original "baseline survives compaction" intent. Also updated `docs/architecture.md` and `README.zh.md` hook-event inventories.
 

package/README.zh.md

@@ -1,7 +1,7 @@
 # CurdX-Flow
 
-> **Claude Code 的 AI 工程工作流元框架**
-> 把 Claude Code 变成有工程纪律的 AI 团队 — 编排 MCP 和插件，强制 Karpathy 4 原则，用规格驱动工作流交付高质量软件。
+> **让 Claude Code 不再假装"完成"。**
+> 规格驱动工作流 + 目标反向验证 + Karpathy 4 原则。
 
 [![Version](https://img.shields.io/npm/v/@curdx/flow.svg)](https://www.npmjs.com/package/@curdx/flow)
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
@@ -10,11 +10,17 @@
 
 ---
 
-## 是什么
+## 为什么存在
 
-CurdX-Flow 是一个 Claude Code 插件，把 6 个验证过的 AI 工程工作流（Karpathy guidelines / BMAD / get-shit-done / gstack / smart-ralph / superpowers）蒸馏成一个可组合系统，然后把基础设施委托给专业的第三方插件（context7 / sequential-thinking / chrome-devtools / claude-mem / pua / frontend-design）。
+Claude Code 会漂——声称功能跑通但从未跑过测试、用训练数据里陈旧的库 API、把三个问题的代码量塞进六问。
 
-**不重造轮子。编排好轮子。**
+CurdX-Flow 是 Claude Code 之上的一层薄**纪律层**，只做三件事，拒绝做更多：
+
+1. **一套规格工作流**（研究 → 需求 → 设计 → 任务），用于超出一次性 vibe-code 尺度的特性。
+2. **目标反向验证**——扫描实现是否对齐每一条 FR / AC / AD，揪出桩代码、假完成、未被测试覆盖的验收标准。
+3. **Karpathy 4 原则**（先思考再编码 / 简单优先 / 外科式修改 / 目标驱动）通过常开 hook 和 gate 强制执行。
+
+不是框架。不是方法论库。就是一层纪律。
 
 ## 一览（v2）
 

package/agent-preamble/preamble.md

@@ -74,10 +74,7 @@ Do NOT query context7 for:
 
 ### Structured thinking → sequential-thinking MCP
 
-Use `sequential-thinking` proportional to **decision complexity**, not a fixed quota. The numbers below are **ceilings for genuinely hard cases**, not floors to hit:
-
-| Task | Guideline |
-|------|-----------|
+Use `sequential-thinking` proportional to **decision complexity**, not a fixed quota. Any thought count is a **ceiling for genuinely hard cases**, not a floor to hit.
 
 **Principle**: running 8 thoughts to pick between Vue and React for a Todo is waste. Running 1 thought to architect a distributed queue is irresponsible. Match effort to stakes.
 

package/cli/install-bundled-mcps.js

@@ -0,0 +1,37 @@
+/**
+ * Register MCP servers that curdx-flow depends on at user level via
+ * `claude mcp add`. Source-of-truth list: cli/registry.js BUNDLED_MCPS.
+ * Preserves existing user-level entries when mcp.preserveExisting is set.
+ */
+
+import { addMcp } from "./lib/claude-ops.js";
+import { BUNDLED_MCPS } from "./registry.js";
+import { color, log, readUserMcpConfig, resultLastLine } from "./utils.js";
+
+export async function registerBundledMcps() {
+  log.blank();
+  log.info("Registering required MCP servers (user-level)...");
+  const existingUserMcps = readUserMcpConfig();
+  for (const mcp of BUNDLED_MCPS) {
+    if (mcp.preserveExisting && existingUserMcps.has(mcp.name)) {
+      const existing = existingUserMcps.get(mcp.name);
+      log.info(
+        `  ${mcp.name.padEnd(22)} ${color.dim(`already registered (${(existing.args || []).join(" ")}) — preserving`)}`
+      );
+      continue;
+    }
+    const r = await addMcp(mcp);
+    if (r.code === 0) {
+      log.ok(`  ${mcp.name.padEnd(22)} ${color.dim("registered")}`);
+    } else if (r.stderr.includes("already exists")) {
+      log.info(`  ${mcp.name.padEnd(22)} ${color.dim("already exists — skipped")}`);
+    } else {
+      log.warn(
+        `  ${mcp.name.padEnd(22)} registration failed: ${resultLastLine(r)}`
+      );
+      log.info(
+        `     Run manually: claude mcp add --scope user ${mcp.name} -- ${mcp.command} ${mcp.args.join(" ")}`
+      );
+    }
+  }
+}

package/cli/install-companions.js

@@ -1,252 +1,16 @@
-import {
-  color,
-  ensureClaudeMemRuntimes,
-  listPlugins,
-  log,
-  multiselectClack,
-  note,
-  resultLastLine,
-  text,
-  writeConfig,
-} from "./utils.js";
-import { BUNDLED_MCPS, RECOMMENDED_PLUGINS, REQUIRED_PLUGINS } from "./registry.js";
-import { readUserMcpConfig } from "./utils.js";
-import {
-  addMcp,
-  addPluginMarketplace,
-  installPlugin,
-  removeMcp,
-} from "./lib/claude-ops.js";
-
-const RECOMMENDED = RECOMMENDED_PLUGINS;
-const CONTEXT7_COMMAND = "npx";
-const CONTEXT7_ARGS = ["-y", "@upstash/context7-mcp"];
-
-export async function installRequiredPlugins({ yes, language, config }) {
-  log.blank();
-  log.info("Installing required Claude Code plugins...");
-  for (const plugin of REQUIRED_PLUGINS) {
-    console.log(`  ${color.cyan("▸")} Installing ${color.bold(plugin.name)}...`);
-    const ma = await addPluginMarketplace(plugin);
-    if (ma.code !== 0 && !ma.stderr.includes("already")) {
-      log.warn(`     marketplace add warning: ${ma.stderr.trim().split("\n")[0]}`);
-    }
-
-    const ir = await installPlugin(plugin);
-    if (ir.code === 0) {
-      console.log(`  ${color.green("✓")} ${plugin.name} installed`);
-
-      if (plugin.requiresConfig && plugin.configType === "apiKey" && !yes) {
-        await promptPluginConfig(plugin, language, config);
-      }
-    } else {
-      console.log(
-        `  ${color.red("✗")} ${plugin.name} install failed: ${resultLastLine(ir)}`
-      );
-      console.log(
-        color.dim(
-          `     Run manually: claude plugin marketplace add --scope ${plugin.scope} ${plugin.marketplaceSource}`
-        )
-      );
-      console.log(
-        color.dim(
-          `     Then: claude plugin install --scope ${plugin.scope} ${plugin.installSpec}`
-        )
-      );
-    }
-  }
-}
-
-export async function registerBundledMcps() {
-  log.blank();
-  log.info("Registering required MCP servers (user-level)...");
-  const existingUserMcps = readUserMcpConfig();
-  for (const mcp of BUNDLED_MCPS) {
-    if (mcp.preserveExisting && existingUserMcps.has(mcp.name)) {
-      const existing = existingUserMcps.get(mcp.name);
-      log.info(
-        `  ${mcp.name.padEnd(22)} ${color.dim(`already registered (${(existing.args || []).join(" ")}) — preserving`)}`
-      );
-      continue;
-    }
-    const r = await addMcp(mcp);
-    if (r.code === 0) {
-      log.ok(`  ${mcp.name.padEnd(22)} ${color.dim("registered")}`);
-    } else if (r.stderr.includes("already exists")) {
-      log.info(`  ${mcp.name.padEnd(22)} ${color.dim("already exists — skipped")}`);
-    } else {
-      log.warn(
-        `  ${mcp.name.padEnd(22)} registration failed: ${resultLastLine(r)}`
-      );
-      log.info(
-        `     Run manually: claude mcp add --scope user ${mcp.name} -- ${mcp.command} ${mcp.args.join(" ")}`
-      );
-    }
-  }
-}
-
-export async function installRecommendedPlugins({ all, yes, language }) {
-  log.blank();
-  log.step(4, 5, "Recommended plugins");
-
-  let toInstall;
-  if (all) {
-    toInstall = RECOMMENDED.map((r) => r.name);
-    log.info("--all mode: installing all recommended");
-  } else if (yes) {
-    const currentlyInstalled = new Set(listPlugins().map((p) => p.name));
-    toInstall = RECOMMENDED
-      .filter((r) => !currentlyInstalled.has(r.name))
-      .map((r) => r.name);
-    log.info(`--yes mode: installing ${toInstall.length} recommended plugins`);
-  } else {
-    const currentlyInstalled = new Set(listPlugins().map((p) => p.name));
-    const options = RECOMMENDED.map((r) => ({
-      value: r.name,
-      label: `${r.name}${currentlyInstalled.has(r.name) ? " (installed)" : ""}`,
-      hint: r.hint,
-    }));
-    const initialValues = RECOMMENDED.map((r) => r.name);
-
-    toInstall = await multiselectClack({
-      message: language === "zh"
-        ? "选择要安装的推荐插件（空格切换，回车确认）"
-        : "Select recommended plugins to install (space to toggle, enter to confirm)",
-      options,
-      initialValues,
-      required: false,
-    });
-  }
-
-  if (!toInstall || toInstall.length === 0) {
-    log.info("No recommended plugins selected, skipping");
-    return false;
-  }
-
-  for (const pluginName of toInstall) {
-    const rec = RECOMMENDED.find((r) => r.name === pluginName);
-    log.blank();
-    console.log(`  ${color.cyan("▸")} Installing ${color.bold(rec.name)}...`);
-
-    if (rec.marketplaceSource) {
-      const ma = await addPluginMarketplace(rec);
-      if (ma.code !== 0 && !ma.stderr.includes("already")) {
-        log.warn(`     marketplace add warning: ${ma.stderr.trim().split("\n")[0]}`);
-      }
-    }
-
-    const ir = await installPlugin(rec);
-    if (ir.code === 0) {
-      console.log(`  ${color.green("✓")} ${rec.name} installed`);
-
-      if (rec.postInstall === "claude-mem-runtimes") {
-        const r = ensureClaudeMemRuntimes();
-        for (const [name, res] of Object.entries(r)) {
-          if (res.status === "linked") {
-            console.log(
-              `  ${color.green("✓")} ${name} → PATH symlink created ${color.dim(`(${res.link} → ${res.path})`)}`
-            );
-          } else if (res.status === "missing") {
-            console.log(
-              `  ${color.yellow("⚠")} ${name} not installed ${color.dim("(claude-mem will auto-install on first run; or run: curdx-flow doctor)")}`
-            );
-          } else if (res.status === "path-unwritable") {
-            console.log(
-              `  ${color.yellow("⚠")} ${name} installed ${color.dim(`(${res.path}) but no writable PATH location — add export PATH=\"${res.path.split("/").slice(0,-1).join("/")}:$PATH\" to your shell rc`)}`
-            );
-          }
-        }
-      }
-    } else {
-      console.log(
-        `  ${color.red("✗")} ${rec.name} install failed: ${resultLastLine(ir)}`
-      );
-      console.log(
-        color.dim(
-          `     Run manually: claude plugin install --scope ${rec.scope} ${rec.installSpec}`
-        )
-      );
-    }
-  }
-  return true;
-}
-
-async function promptPluginConfig(plugin, language, config) {
-  if (plugin.name !== "context7-plugin") return;
-
-  log.blank();
-  await note(
-    language === "zh"
-      ? "Context7 需要 API key 才能使用。\n获取 API key: https://console.upstash.com/context7"
-      : "Context7 requires an API key to function.\nGet your API key at: https://console.upstash.com/context7",
-    language === "zh" ? "配置 Context7" : "Configure Context7"
-  );
-
-  const apiKey = await text({
-    message: language === "zh"
-      ? "输入你的 Context7 API key（或按 Enter 跳过）"
-      : "Enter your Context7 API key (or press Enter to skip)",
-    placeholder: "ctx7sk-...",
-    validate: (value) => {
-      if (!value) return;
-      if (!value.startsWith("ctx7sk-") && !value.startsWith("ctx7_")) {
-        return language === "zh"
-          ? "API key 应该以 ctx7sk- 或 ctx7_ 开头"
-          : "API key should start with ctx7sk- or ctx7_";
-      }
-    },
-  });
-
-  if (apiKey) {
-    config.context7ApiKey = apiKey;
-    writeConfig(config);
-
-    const r = await addMcp(buildContext7Mcp(apiKey));
-
-    if (r.code === 0) {
-      log.ok(
-        language === "zh"
-          ? "  Context7 API key 已配置"
-          : "  Context7 API key configured"
-      );
-    } else if (r.stderr.includes("already exists")) {
-      await removeMcp({ name: "context7" });
-      const r2 = await addMcp(buildContext7Mcp(apiKey));
-      if (r2.code === 0) {
-        log.ok(
-          language === "zh"
-            ? "  Context7 API key 已更新"
-            : "  Context7 API key updated"
-        );
-      }
-    } else {
-      log.warn(
-        language === "zh"
-          ? `  Context7 MCP 配置失败: ${resultLastLine(r)}`
-          : `  Context7 MCP configuration failed: ${resultLastLine(r)}`
-      );
-      log.info(
-        color.dim(
-          language === "zh"
-            ? `     手动运行: claude mcp add --scope user context7 --env CONTEXT7_API_KEY=${apiKey} -- ${CONTEXT7_COMMAND} ${CONTEXT7_ARGS.join(" ")}`
-            : `     Run manually: claude mcp add --scope user context7 --env CONTEXT7_API_KEY=${apiKey} -- ${CONTEXT7_COMMAND} ${CONTEXT7_ARGS.join(" ")}`
-        )
-      );
-    }
-  } else {
-    log.info(
-      language === "zh"
-        ? "  跳过 Context7 配置（稍后可运行 curdx-flow install 重新配置）"
-        : "  Skipped Context7 configuration (run curdx-flow install later to reconfigure)"
-    );
-  }
-}
-
-function buildContext7Mcp(apiKey) {
-  return {
-    name: "context7",
-    env: [`CONTEXT7_API_KEY=${apiKey}`],
-    command: CONTEXT7_COMMAND,
-    args: CONTEXT7_ARGS,
-  };
-}
+/**
+ * Re-export barrel preserving the pre-Stage-7 import surface. New callers
+ * should import directly from the concern-specific modules below instead
+ * of going through this barrel. Kept in place so existing imports in
+ * cli/install.js and cli/install-workflow.js keep working unchanged.
+ *
+ * Concern split (see docs/refactor-plan.md Stage 7):
+ *   install-required-plugins.js   — required Claude Code companion plugins
+ *   install-bundled-mcps.js       — user-level MCP registration
+ *   install-recommended-plugins.js — optional recommended plugins
+ *   install-context7-config.js    — context7 API-key prompt (private to required)
+ */
+
+export { installRequiredPlugins } from "./install-required-plugins.js";
+export { registerBundledMcps } from "./install-bundled-mcps.js";
+export { installRecommendedPlugins } from "./install-recommended-plugins.js";

package/cli/install-context7-config.js

@@ -0,0 +1,97 @@
+/**
+ * Context7 API-key configuration during install. Private to the
+ * required-plugins concern; not re-exported from install-companions.js.
+ */
+
+import { addMcp, removeMcp } from "./lib/claude-ops.js";
+import {
+  color,
+  log,
+  note,
+  resultLastLine,
+  text,
+  writeConfig,
+} from "./utils.js";
+
+const CONTEXT7_COMMAND = "npx";
+const CONTEXT7_ARGS = ["-y", "@upstash/context7-mcp"];
+
+export async function installContext7Config(plugin, language, config) {
+  if (plugin.name !== "context7-plugin") return;
+
+  log.blank();
+  await note(
+    language === "zh"
+      ? "Context7 需要 API key 才能使用。\n获取 API key: https://console.upstash.com/context7"
+      : "Context7 requires an API key to function.\nGet your API key at: https://console.upstash.com/context7",
+    language === "zh" ? "配置 Context7" : "Configure Context7"
+  );
+
+  const apiKey = await text({
+    message: language === "zh"
+      ? "输入你的 Context7 API key（或按 Enter 跳过）"
+      : "Enter your Context7 API key (or press Enter to skip)",
+    placeholder: "ctx7sk-...",
+    validate: (value) => {
+      if (!value) return;
+      if (!value.startsWith("ctx7sk-") && !value.startsWith("ctx7_")) {
+        return language === "zh"
+          ? "API key 应该以 ctx7sk- 或 ctx7_ 开头"
+          : "API key should start with ctx7sk- or ctx7_";
+      }
+    },
+  });
+
+  if (apiKey) {
+    config.context7ApiKey = apiKey;
+    writeConfig(config);
+
+    const r = await addMcp(buildContext7Mcp(apiKey));
+
+    if (r.code === 0) {
+      log.ok(
+        language === "zh"
+          ? "  Context7 API key 已配置"
+          : "  Context7 API key configured"
+      );
+    } else if (r.stderr.includes("already exists")) {
+      await removeMcp({ name: "context7" });
+      const r2 = await addMcp(buildContext7Mcp(apiKey));
+      if (r2.code === 0) {
+        log.ok(
+          language === "zh"
+            ? "  Context7 API key 已更新"
+            : "  Context7 API key updated"
+        );
+      }
+    } else {
+      log.warn(
+        language === "zh"
+          ? `  Context7 MCP 配置失败: ${resultLastLine(r)}`
+          : `  Context7 MCP configuration failed: ${resultLastLine(r)}`
+      );
+      log.info(
+        color.dim(
+          language === "zh"
+            ? `     手动运行: claude mcp add --scope user context7 --env CONTEXT7_API_KEY=${apiKey} -- ${CONTEXT7_COMMAND} ${CONTEXT7_ARGS.join(" ")}`
+            : `     Run manually: claude mcp add --scope user context7 --env CONTEXT7_API_KEY=${apiKey} -- ${CONTEXT7_COMMAND} ${CONTEXT7_ARGS.join(" ")}`
+        )
+      );
+    }
+  } else {
+    log.info(
+      language === "zh"
+        ? "  跳过 Context7 配置（稍后可运行 curdx-flow install 重新配置）"
+        : "  Skipped Context7 configuration (run curdx-flow install later to reconfigure)"
+    );
+  }
+}
+
+function buildContext7Mcp(apiKey) {
+  return {
+    name: "context7",
+    env: [`CONTEXT7_API_KEY=${apiKey}`],
+    command: CONTEXT7_COMMAND,
+    args: CONTEXT7_ARGS,
+  };
+}

package/cli/install-recommended-plugins.js

@@ -0,0 +1,104 @@
+/**
+ * Install optional recommended companion plugins. List source-of-truth:
+ * cli/registry.js RECOMMENDED_PLUGINS. Handles --all / --yes / interactive
+ * multiselect and the claude-mem bun/uv PATH symlink post-install step.
+ */
+
+import { addPluginMarketplace, installPlugin } from "./lib/claude-ops.js";
+import { RECOMMENDED_PLUGINS } from "./registry.js";
+import {
+  color,
+  ensureClaudeMemRuntimes,
+  listPlugins,
+  log,
+  multiselectClack,
+  resultLastLine,
+} from "./utils.js";
+
+const RECOMMENDED = RECOMMENDED_PLUGINS;
+
+export async function installRecommendedPlugins({ all, yes, language }) {
+  log.blank();
+  log.step(4, 5, "Recommended plugins");
+
+  let toInstall;
+  if (all) {
+    toInstall = RECOMMENDED.map((r) => r.name);
+    log.info("--all mode: installing all recommended");
+  } else if (yes) {
+    const currentlyInstalled = new Set(listPlugins().map((p) => p.name));
+    toInstall = RECOMMENDED
+      .filter((r) => !currentlyInstalled.has(r.name))
+      .map((r) => r.name);
+    log.info(`--yes mode: installing ${toInstall.length} recommended plugins`);
+  } else {
+    const currentlyInstalled = new Set(listPlugins().map((p) => p.name));
+    const options = RECOMMENDED.map((r) => ({
+      value: r.name,
+      label: `${r.name}${currentlyInstalled.has(r.name) ? " (installed)" : ""}`,
+      hint: r.hint,
+    }));
+    const initialValues = RECOMMENDED.map((r) => r.name);
+
+    toInstall = await multiselectClack({
+      message: language === "zh"
+        ? "选择要安装的推荐插件（空格切换，回车确认）"
+        : "Select recommended plugins to install (space to toggle, enter to confirm)",
+      options,
+      initialValues,
+      required: false,
+    });
+  }
+
+  if (!toInstall || toInstall.length === 0) {
+    log.info("No recommended plugins selected, skipping");
+    return false;
+  }
+
+  for (const pluginName of toInstall) {
+    const rec = RECOMMENDED.find((r) => r.name === pluginName);
+    log.blank();
+    console.log(`  ${color.cyan("▸")} Installing ${color.bold(rec.name)}...`);
+
+    if (rec.marketplaceSource) {
+      const ma = await addPluginMarketplace(rec);
+      if (ma.code !== 0 && !ma.stderr.includes("already")) {
+        log.warn(`     marketplace add warning: ${ma.stderr.trim().split("\n")[0]}`);
+      }
+    }
+
+    const ir = await installPlugin(rec);
+    if (ir.code === 0) {
+      console.log(`  ${color.green("✓")} ${rec.name} installed`);
+
+      if (rec.postInstall === "claude-mem-runtimes") {
+        const r = ensureClaudeMemRuntimes();
+        for (const [name, res] of Object.entries(r)) {
+          if (res.status === "linked") {
+            console.log(
+              `  ${color.green("✓")} ${name} → PATH symlink created ${color.dim(`(${res.link} → ${res.path})`)}`
+            );
+          } else if (res.status === "missing") {
+            console.log(
+              `  ${color.yellow("⚠")} ${name} not installed ${color.dim("(claude-mem will auto-install on first run; or run: curdx-flow doctor)")}`
+            );
+          } else if (res.status === "path-unwritable") {
+            console.log(
+              `  ${color.yellow("⚠")} ${name} installed ${color.dim(`(${res.path}) but no writable PATH location — add export PATH="${res.path.split("/").slice(0,-1).join("/")}:$PATH" to your shell rc`)}`
+            );
+          }
+        }
+      }
+    } else {
+      console.log(
+        `  ${color.red("✗")} ${rec.name} install failed: ${resultLastLine(ir)}`
+      );
+      console.log(
+        color.dim(
+          `     Run manually: claude plugin install --scope ${rec.scope} ${rec.installSpec}`
+        )
+      );
+    }
+  }
+  return true;
+}