@curdx/flow 2.0.0-beta.15 → 2.0.0-beta.17

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.15"
+    "version": "2.0.0-beta.17"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "curdx-flow",
-  "version": "2.0.0-beta.15",
+  "version": "2.0.0-beta.17",
   "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

@@ -4,6 +4,10 @@ All notable changes to CurDX-Flow will be documented here.
 
 ## [Unreleased]
 
+### Fixed
+
+- `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.
+
 ### BREAKING
 
 - **`context7` and `sequential-thinking` moved from plugin-bundled MCPs to user-level MCPs.** Previously `.claude-plugin/plugin.json` declared both in `mcpServers`, so Claude Code auto-registered them as `plugin:curdx-flow:context7` and `plugin:curdx-flow:sequential-thinking` when the plugin installed. This is no longer the case — the `mcpServers` block is gone. Instead, `curdx-flow install` now runs `claude mcp add context7 …` + `claude mcp add sequential-thinking …` against the user's `~/.claude.json`, which keeps them as standard user-level registrations named `context7` and `sequential-thinking`.

package/README.md

@@ -28,7 +28,7 @@ Not a framework. Not a methodology library. A discipline layer.
 npx @curdx/flow install --all
 ```
 
-This installs the Claude Code plugin (fully offline from the npm package — no GitHub fetch), the 3 auto-registered MCP servers, and three recommended companion plugins (pua, claude-mem, frontend-design).
+This installs the Claude Code plugin (fully offline from the npm package — no GitHub fetch), the official Context7 plugin, the required sequential-thinking MCP server, and four recommended companion plugins (pua, claude-mem, frontend-design, chrome-devtools-mcp).
 
 ## 9 slash commands, that's it
 
@@ -97,7 +97,8 @@ npm i -g @curdx/flow@^1.1
 - **8 composable gates** — Karpathy / Verification / TDD / Coverage / Adversarial / Edge-Case / Security / DevEx
 - **4 execution strategies** for `/curdx-flow:implement` (linear / subagent / stop-hook / wave, auto-routed)
 - **5 hook events** that enforce the discipline without user action
-- **3 auto-installed MCPs** — context7 (latest docs), sequential-thinking (structured reasoning), chrome-devtools (browser automation)
+- **Required docs/reasoning tools** — Context7 official plugin (MCP + skill + docs agent) and sequential-thinking MCP
+- **4 recommended companion plugins** — pua, claude-mem, frontend-design, chrome-devtools-mcp
 - **Offline-capable install** — the npm package ships the full plugin body; zero GitHub round-trips during install
 
 ## Documentation
@@ -123,7 +124,7 @@ CurDX-Flow v2 is a distillation, not an invention. Ideas we depend on:
 - [**superpowers**](https://github.com/obra/superpowers) — subagent discipline + TDD + two-stage review
 - [**pua**](https://github.com/tanweai/pua) — the three red lines
 - [**claude-mem**](https://github.com/thedotmack/claude-mem) — cross-session memory
-- **Anthropic official** — context7 (Upstash), sequential-thinking, chrome-devtools-mcp, frontend-design skill
+- **MCP / plugin ecosystem** — context7 (Upstash), sequential-thinking, chrome-devtools-mcp (Chrome DevTools team), frontend-design skill
 
 ## License
 

package/README.zh.md

@@ -3,7 +3,7 @@
 > **Claude Code 的 AI 工程工作流元框架**
 > 把 Claude Code 变成有工程纪律的 AI 团队 — 编排 MCP 和插件，强制 Karpathy 4 原则，用规格驱动工作流交付高质量软件。
 
-[![Version](https://img.shields.io/badge/version-1.1.0-blue)](./CHANGELOG.md)
+[![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)
 [![Plugin](https://img.shields.io/badge/claude--code-plugin-purple)](https://code.claude.com)
 [![English](https://img.shields.io/badge/doc-English-red)](./README.md)
@@ -16,15 +16,15 @@ CurDX-Flow 是一个 Claude Code 插件，把 6 个验证过的 AI 工程工作
 
 **不重造轮子。编排好轮子。**
 
-## 一览（v1.1.0）
+## 一览（v2）
 
-- **31 个命令** — 初始化 / 研究 / 设计 / 执行 / 验证 / 审查 / 调试 / QA / 安全 / ...
-- **24 个代理** — 15 职能 + 9 人格（Mary / John / Winston / Amelia / Rachel / David / Oliver / Serena / Emma）
+- **9 个命令** — 初始化 / 启动规格 / 规格 / 执行 / 验证 / 审查 / 调试 / fast / 帮助
+- **15 个内部代理** — 由命令调度，不再暴露 v1 的人格角色
 - **8 个可组合 Gate** — Karpathy / Verification / TDD / Coverage / Adversarial / Edge-Case / Security / DevEx
 - **4 种执行策略** — linear / subagent / stop-hook / wave（自动路由）
 - **10 个知识文档** — 规格驱动 / POC-First / 原子提交 / 执行策略 / ...
-- **4 个 hook 事件** — SessionStart / InstructionsLoaded / Stop / PreToolUse
-- **2 个自动安装的 MCP + 1 个推荐插件** — context7 / sequential-thinking（plugin.json 内置）+ chrome-devtools-mcp（recommended，beta.8 解耦）
+- **5 个 hook 事件** — SessionStart / InstructionsLoaded / PostToolUseFailure / Stop / PreToolUse
+- **必需文档/推理工具 + 4 个推荐插件** — Context7 官方插件 / sequential-thinking MCP + pua / claude-mem / frontend-design / chrome-devtools-mcp
 - **优雅降级** — 依赖缺失时进入 fallback 模式并清晰告知
 
 ## 为什么用
@@ -41,23 +41,21 @@ CurDX-Flow 是一个 Claude Code 插件，把 6 个验证过的 AI 工程工作
 
 ## 安装
 
-### 从 marketplace（发布后）
-```
-/plugin marketplace add wdx/curdx-flow
-/plugin install curdx-flow
+```bash
+npx @curdx/flow install --all
 ```
 
+这会用 `claude plugin ...` 非交互 CLI 安装 CurDX-Flow 插件、Context7 官方插件、必需 MCP，并安装推荐插件。
+
 ### 本地 dev
 ```bash
-git clone https://github.com/wdx/curdx-flow
+git clone https://github.com/curdx/curdx-flow
 claude --plugin-dir ./curdx-flow
 ```
 
-3 个 MCP 自动装。然后运行：
+安装后在 Claude Code 内运行：
 
 ```
-/curdx-flow:install-deps    # 交互式安装 pua / claude-mem / frontend-design
-/curdx-flow:doctor          # 验证健康
 /curdx-flow:init            # 初始化你的项目
 ```
 
@@ -102,8 +100,8 @@ claude --plugin-dir ./curdx-flow
 | 文档 | 何时读 |
 |-----|------|
 | [`docs/getting-started.md`](./docs/getting-started.md) | 首次使用，5 分钟上手 |
-| [`docs/command-reference.md`](./docs/command-reference.md) | 31 个命令完整参考 |
-| [`docs/agent-reference.md`](./docs/agent-reference.md) | 24 个代理 + 人格 |
+| [`docs/command-reference.md`](./docs/command-reference.md) | 9 个命令完整参考 |
+| [`docs/agent-reference.md`](./docs/agent-reference.md) | 15 个内部代理 |
 | [`docs/workflows.md`](./docs/workflows.md) | 5 种典型场景（greenfield/brownfield/epic/fast/UI） |
 | [`docs/architecture.md`](./docs/architecture.md) | 内部设计（给扩展者） |
 | [`docs/ethos.md`](./docs/ethos.md) | 设计决策的理由 |
@@ -132,7 +130,7 @@ CurDX-Flow 是蒸馏，不是原创。深深致谢：
 - [**pua**](https://github.com/tanweai/pua) — 持续性 + 三条红线
 - [**claude-mem**](https://github.com/thedotmack/claude-mem) — 自动跨会话记忆
 - [**frontend-design skill**](https://claude.ai/skills/frontend-design) — distinctive UI（Anthropic 官方）
-- **context7**（Upstash）+ **sequential-thinking**（Anthropic）+ **chrome-devtools-mcp**（Chrome 团队）
+- **Context7**（Upstash）+ **sequential-thinking**（Anthropic）+ **chrome-devtools-mcp**（Chrome 团队）
 
 ## 许可
 
@@ -140,7 +138,7 @@ MIT。见 [`LICENSE`](./LICENSE)。
 
 ## 贡献
 
-- Issues: https://github.com/wdx/curdx-flow/issues
+- Issues: https://github.com/curdx/curdx-flow/issues
 - 欢迎 PR，但请先用 `/curdx-flow:spec` 自己走一遍（吃自己的狗粮）
 - 社区准则：友善 + 具体 + 不对着 LLM 发火
 

package/cli/README.md

@@ -24,9 +24,11 @@ npx @curdx/flow upgrade
 
 Steps:
 1. Verify the `claude` CLI is installed
-2. `claude plugin marketplace add curdx/curdx-flow`
-3. `claude plugin install curdx-flow@curdx-flow-marketplace` (auto-installs 3 MCPs)
-4. Interactively (or automatically) install recommended plugins: **pua**, **claude-mem**, **frontend-design**
+2. `claude plugin marketplace add --scope user curdx/curdx-flow`
+3. `claude plugin install --scope user curdx-flow@curdx-flow-marketplace`
+4. Install required companion plugin: **context7-plugin@context7-marketplace**
+5. Register required user-level MCP: **sequential-thinking**
+6. Interactively (or automatically) install recommended plugins: **pua**, **claude-mem**, **frontend-design**, **chrome-devtools-mcp**
 
 | Flag | Purpose |
 |------|---------|
@@ -35,7 +37,7 @@ Steps:
 
 ### `doctor [--verbose]`
 
-External diagnostics: claude CLI / curdx-flow / 3 MCPs / 3 recommended plugins / current directory `.flow/` state.
+External diagnostics: claude CLI / curdx-flow / required MCPs / recommended plugins / current directory `.flow/` state.
 
 ### Project initialization (not a CLI command)
 
@@ -50,11 +52,11 @@ This keeps the CLI scoped to install-time and lifecycle operations only — anyt
 
 ### `upgrade`
 
-`claude plugin marketplace update` + `claude plugin update` for every installed curdx-flow-related plugin.
+`claude plugin marketplace update` + `claude plugin update --scope user` for every installed curdx-flow-related plugin.
 
 ### `uninstall [-y] [--keep-recommended] [--purge]`
 
-Inverse of `install`. By default removes only the curdx-flow plugin. With `--purge`, also removes the `~/.local/bin/bun` and `~/.local/bin/uv` symlinks created by install.
+Inverse of `install`. By default removes only the curdx-flow plugin. Recommended plugins are kept unless selected interactively. With `--purge`, also removes third-party marketplaces and the `~/.local/bin/bun` / `~/.local/bin/uv` symlinks created by install.
 
 ## Why a CLI?
 

package/cli/doctor.js

@@ -10,12 +10,13 @@ import {
   runSync,
   claudeVersion,
   listPlugins,
+  listPluginMarketplaces,
   listMcps,
   ensureClaudeMemRuntimes,
   readUserMcpConfig,
   findDuplicateMcps,
 } from "./utils.js";
-import { RECOMMENDED_PLUGINS } from "./registry.js";
+import { BUNDLED_MCPS, REQUIRED_PLUGINS, RECOMMENDED_PLUGINS } from "./registry.js";
 
 export async function doctor(args = []) {
   const verbose = args.includes("--verbose") || args.includes("-v");
@@ -52,15 +53,37 @@ export async function doctor(args = []) {
     warnings++;
   }
 
+  const marketplaces = cv ? listPluginMarketplaces() : [];
+  const marketplaceNames = new Set(marketplaces.map((m) => m.name));
+
+  // ---------- Required plugins ----------
+  console.log(`\n${color.bold("Required plugins:")}`);
+  for (const r of REQUIRED_PLUGINS) {
+    const p = plugins.find((x) => x.id === r.id || x.name === r.name);
+    if (r.marketplaceSource && !marketplaceNames.has(r.marketplaceId)) {
+      log.warn(
+        `${r.marketplaceId.padEnd(22)} marketplace missing ${color.dim(`(run: claude plugin marketplace add --scope ${r.scope} ${r.marketplaceSource})`)}`
+      );
+      warnings++;
+    }
+    if (p && p.status === "enabled") {
+      log.ok(`${r.name.padEnd(22)} ${color.dim(`v${p.version || "unknown"}`)}`);
+    } 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: claude plugin install --scope ${r.scope} ${r.installSpec})`)}`
+      );
+      warnings++;
+    }
+  }
+
   // ---------- 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 (required by L2 mandatory tools):")}`);
   const mcps = cv ? listMcps() : [];
-  const expectedMcps = ["context7", "sequential-thinking"];
-  for (const m of expectedMcps) {
+  for (const expected of BUNDLED_MCPS) {
+    const m = expected.name;
     // Beta.12 onward: the required MCPs are registered at user-level
     // (via `claude mcp add`), NOT plugin-bundled. Both still show up in
     // `claude mcp list`. Accept a standalone user-level registration
@@ -80,7 +103,7 @@ export async function doctor(args = []) {
     } else {
       if (curdx) {
         log.warn(
-          `${m.padEnd(22)} missing. Run: ${color.cyan(`claude mcp add ${m} -- npx -y @upstash/context7-mcp@latest`).replace("context7-mcp", m === "context7" ? "context7-mcp" : "server-sequential-thinking")}`
+          `${m.padEnd(22)} missing. Run: ${color.cyan(`claude mcp add --scope user ${m} -- ${expected.command} ${expected.args.join(" ")}`)}`
         );
         warnings++;
       } else {
@@ -93,7 +116,13 @@ export async function doctor(args = []) {
   console.log(`\n${color.bold("Recommended plugins:")}`);
   let claudeMemEnabled = false;
   for (const r of RECOMMENDED_PLUGINS) {
-    const p = plugins.find((x) => x.name === r.name);
+    const p = plugins.find((x) => x.id === r.id || x.name === r.name);
+    if (r.marketplaceSource && !marketplaceNames.has(r.marketplaceId)) {
+      log.warn(
+        `${r.marketplaceId.padEnd(22)} marketplace missing ${color.dim(`(run: claude plugin marketplace add --scope ${r.scope} ${r.marketplaceSource})`)}`
+      );
+      warnings++;
+    }
     if (p && p.status === "enabled") {
       log.ok(`${r.name.padEnd(22)} ${color.dim(`v${p.version}`)}`);
       if (r.postInstall === "claude-mem-runtimes") claudeMemEnabled = true;
@@ -102,7 +131,7 @@ export async function doctor(args = []) {
       errors++;
     } else {
       log.warn(
-        `${r.name.padEnd(22)} not installed ${color.dim(`(run: claude plugin install ${r.installSpec})`)}`
+        `${r.name.padEnd(22)} not installed ${color.dim(`(run: claude plugin install --scope ${r.scope} ${r.installSpec})`)}`
       );
       warnings++;
     }

package/cli/install.js

@@ -17,7 +17,7 @@ import {
   ensureClaudeMemRuntimes,
 } from "./utils.js";
 import { injectGlobalProtocols, GLOBAL_CLAUDE_MD } from "./protocols.js";
-import { RECOMMENDED_PLUGINS, BUNDLED_MCPS } from "./registry.js";
+import { REQUIRED_PLUGINS, RECOMMENDED_PLUGINS, BUNDLED_MCPS } from "./registry.js";
 import { readUserMcpConfig } from "./utils.js";
 
 // When installed via npm, this CLI file lives at <pkg-root>/cli/install.js.
@@ -86,7 +86,7 @@ export async function install(args = []) {
 
   const addRes = await run(
     "claude",
-    ["plugin", "marketplace", "add", marketplaceSource],
+    ["plugin", "marketplace", "add", "--scope", "user", marketplaceSource],
     { silent: true }
   );
   if (addRes.code !== 0 && !addRes.stderr.includes("already")) {
@@ -121,12 +121,23 @@ export async function install(args = []) {
   const already = prevCurdxFlow;
 
   if (already && shippedVersion && already.version === shippedVersion) {
-    // Already on the exact version the tarball ships — no re-install needed.
-    // `claude plugin install` would succeed too but the fresh-install output
-    // is misleading here.
-    log.ok(
-      `curdx-flow already at v${already.version} ${color.dim("(no change)")}`
+    // Step 2 removes and re-adds the marketplace to rebind it to the current
+    // source. Claude Code removes plugins installed from that marketplace as
+    // part of `marketplace remove`, so even a same-version install must be
+    // re-registered here.
+    log.info(
+      `curdx-flow already at v${already.version}, re-registering...`
     );
+    const r = await run(
+      "claude",
+      ["plugin", "install", "--scope", "user", "curdx-flow@curdx-flow-marketplace"],
+      { silent: true }
+    );
+    if (r.code !== 0) {
+      log.err(`Install failed: ${r.stderr.trim() || r.stdout.trim()}`);
+      process.exit(1);
+    }
+    log.ok(`curdx-flow re-registered at v${shippedVersion}`);
   } else if (already && shippedVersion) {
     // Existing install, different version — frame as an upgrade.
     log.info(
@@ -134,7 +145,7 @@ export async function install(args = []) {
     );
     const r = await run(
       "claude",
-      ["plugin", "install", "curdx-flow@curdx-flow-marketplace"],
+      ["plugin", "install", "--scope", "user", "curdx-flow@curdx-flow-marketplace"],
       { silent: true }
     );
     if (r.code !== 0) {
@@ -151,7 +162,7 @@ export async function install(args = []) {
     );
     const r = await run(
       "claude",
-      ["plugin", "install", "curdx-flow@curdx-flow-marketplace"],
+      ["plugin", "install", "--scope", "user", "curdx-flow@curdx-flow-marketplace"],
       { silent: true }
     );
     if (r.code !== 0) {
@@ -162,7 +173,7 @@ export async function install(args = []) {
   } else {
     const r = await run(
       "claude",
-      ["plugin", "install", "curdx-flow@curdx-flow-marketplace"],
+      ["plugin", "install", "--scope", "user", "curdx-flow@curdx-flow-marketplace"],
       { silent: true }
     );
     if (r.code !== 0) {
@@ -176,10 +187,46 @@ export async function install(args = []) {
     }
   }
 
-  // ---------- Step 3.5: Register user-level MCPs (context7, sequential-thinking) ----------
-  // Beta.12: migrated from plugin.json bundling. See cli/registry.js for
-  // the rationale (avoids plugin:curdx-flow:context7 vs context7 duplicate
-  // registration + keeps tool names standard for third-party agent reuse).
+  // ---------- Step 3.5: Install required plugins + register user-level MCPs ----------
+  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 run(
+      "claude",
+      ["plugin", "marketplace", "add", "--scope", plugin.scope, plugin.marketplaceSource],
+      { silent: true }
+    );
+    if (ma.code !== 0 && !ma.stderr.includes("already")) {
+      log.warn(`     marketplace add warning: ${ma.stderr.trim().split("\n")[0]}`);
+    }
+
+    const ir = await run(
+      "claude",
+      ["plugin", "install", "--scope", plugin.scope, plugin.installSpec],
+      { silent: true }
+    );
+    if (ir.code === 0) {
+      console.log(`  ${color.green("✓")} ${plugin.name} installed`);
+    } else {
+      console.log(
+        `  ${color.red("✗")} ${plugin.name} install failed: ${ir.stderr.trim().split("\n").pop()}`
+      );
+      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}`
+        )
+      );
+    }
+  }
+
+  // Beta.12: direct MCPs migrated from plugin.json bundling. See cli/registry.js
+  // for the rationale. Context7 now uses Upstash's official plugin instead.
   log.blank();
   log.info("Registering required MCP servers (user-level)...");
   const existingUserMcps = readUserMcpConfig();
@@ -193,7 +240,7 @@ export async function install(args = []) {
     }
     const r = await run(
       "claude",
-      ["mcp", "add", mcp.name, "--", mcp.command, ...mcp.args],
+      ["mcp", "add", "--scope", "user", mcp.name, "--", mcp.command, ...mcp.args],
       { silent: true }
     );
     if (r.code === 0) {
@@ -205,7 +252,7 @@ export async function install(args = []) {
         `  ${mcp.name.padEnd(22)} registration failed: ${r.stderr.trim().split("\n").pop()}`
       );
       log.info(
-        `     Run manually: claude mcp add ${mcp.name} -- ${mcp.command} ${mcp.args.join(" ")}`
+        `     Run manually: claude mcp add --scope user ${mcp.name} -- ${mcp.command} ${mcp.args.join(" ")}`
       );
     }
   }
@@ -251,10 +298,10 @@ export async function install(args = []) {
     console.log(`  ${color.cyan("▸")} Installing ${color.bold(rec.name)}...`);
 
     // 1. Add marketplace (if needed)
-    if (rec.marketplace) {
+    if (rec.marketplaceSource) {
       const ma = await run(
         "claude",
-        ["plugin", "marketplace", "add", rec.marketplace],
+        ["plugin", "marketplace", "add", "--scope", rec.scope, rec.marketplaceSource],
         { silent: true }
       );
       if (ma.code !== 0 && !ma.stderr.includes("already")) {
@@ -264,7 +311,7 @@ export async function install(args = []) {
     }
 
     // 2. Install
-    const ir = await run("claude", ["plugin", "install", rec.installSpec], {
+    const ir = await run("claude", ["plugin", "install", "--scope", rec.scope, rec.installSpec], {
       silent: true,
     });
     if (ir.code === 0) {
@@ -298,7 +345,7 @@ export async function install(args = []) {
       );
       console.log(
         color.dim(
-          `     Run manually: claude plugin install ${rec.installSpec}`
+          `     Run manually: claude plugin install --scope ${rec.scope} ${rec.installSpec}`
         )
       );
     }

package/cli/registry.js

@@ -9,74 +9,89 @@
  * 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)
+ *   - install.js     → marketplaceSource + installSpec + hint (+ optional postInstall)
+ *   - uninstall.js   → uninstallSpec + uninstallArgs + marketplaceId
+ *   - upgrade.js     → updateSpec + marketplaceId
+ *   - doctor.js      → id + installSpec (for health checks and recovery hints)
  */
 
 export const RECOMMENDED_PLUGINS = [
   {
     name: "pua",
-    marketplace: "tanweai/pua",
-    marketplaceId: "pua",
+    id: "pua@pua-skills",
+    marketplaceSource: "tanweai/pua",
+    marketplaceId: "pua-skills",
     installSpec: "pua@pua-skills",
     uninstallSpec: "pua@pua-skills",
+    updateSpec: "pua@pua-skills",
+    scope: "user",
     hint: "no-give-up + three red lines",
   },
   {
     name: "claude-mem",
-    marketplace: "thedotmack/claude-mem",
+    id: "claude-mem@thedotmack",
+    marketplaceSource: "thedotmack/claude-mem",
     marketplaceId: "thedotmack",
     installSpec: "claude-mem@thedotmack",
     uninstallSpec: "claude-mem@thedotmack",
+    updateSpec: "claude-mem@thedotmack",
+    uninstallArgs: ["--keep-data"],
+    scope: "user",
     hint: "automatic cross-session memory",
     postInstall: "claude-mem-runtimes",
   },
   {
     name: "frontend-design",
     // Already in default marketplace claude-plugins-official, no add needed
-    marketplace: null,
+    id: "frontend-design@claude-plugins-official",
+    marketplaceSource: null,
     marketplaceId: "claude-plugins-official",
     installSpec: "frontend-design@claude-plugins-official",
     uninstallSpec: "frontend-design@claude-plugins-official",
+    updateSpec: "frontend-design@claude-plugins-official",
+    scope: "user",
     hint: "Anthropic official UI skill",
   },
   {
     name: "chrome-devtools-mcp",
-    marketplace: "ChromeDevTools/chrome-devtools-mcp",
+    id: "chrome-devtools-mcp@chrome-devtools-plugins",
+    marketplaceSource: "ChromeDevTools/chrome-devtools-mcp",
     marketplaceId: "chrome-devtools-plugins",
     installSpec: "chrome-devtools-mcp@chrome-devtools-plugins",
     uninstallSpec: "chrome-devtools-mcp@chrome-devtools-plugins",
+    updateSpec: "chrome-devtools-mcp@chrome-devtools-plugins",
+    scope: "user",
     hint: "Chrome DevTools + Puppeteer (Google official)",
   },
 ];
 
+export const REQUIRED_PLUGINS = [
+  {
+    name: "context7-plugin",
+    id: "context7-plugin@context7-marketplace",
+    marketplaceSource: "upstash/context7",
+    marketplaceId: "context7-marketplace",
+    installSpec: "context7-plugin@context7-marketplace",
+    uninstallSpec: "context7-plugin@context7-marketplace",
+    updateSpec: "context7-plugin@context7-marketplace",
+    scope: "user",
+    hint: "official Context7 plugin (MCP + skill + docs-researcher agent + /context7:docs)",
+  },
+];
+
 /**
- * Bundled MCP servers that curdx-flow depends on for its core discipline
- * rules (context7 for library docs in L2, sequential-thinking for
- * structured reasoning in L2). Starting beta.12 these are registered at
+ * MCP servers that curdx-flow depends on for its core discipline rules and
+ * still registers directly. Starting beta.12 these are registered at
  * USER-LEVEL via `claude mcp add` instead of plugin.json bundling, so:
  *
- *   - Tool names stay standard (mcp__context7__*, mcp__sequential-thinking__*)
+ *   - Tool names stay standard (mcp__sequential-thinking__*)
  *     — matching every agent's and knowledge doc's hardcoded references.
- *   - Users with a paid context7 API key can set it with --api-key in their
- *     own user-level entry; the install command will detect and respect the
- *     existing entry instead of overwriting it.
- *   - No more `plugin:curdx-flow:context7` + `context7` duplicate registration
- *     — the DX pitfall that bit every early adopter with a pre-existing
- *     `claude mcp add context7 …` history.
+ *
+ * Context7 is installed via Upstash's official Claude Code plugin instead
+ * of direct `claude mcp add`: context7-plugin@context7-marketplace includes
+ * the MCP server, skill, docs-researcher agent, and /context7:docs command.
  */
 export const BUNDLED_MCPS = [
-  {
-    name: "context7",
-    command: "npx",
-    args: ["-y", "@upstash/context7-mcp@latest"],
-    purpose: "library / framework docs lookup (L2 Mandatory Tool)",
-    // Respect any user-level entry with a custom `--api-key` or differing
-    // package spec — don't overwrite it on subsequent install runs.
-    preserveExisting: true,
-  },
   {
     name: "sequential-thinking",
     command: "npx",
@@ -92,9 +107,8 @@ export const BUNDLED_MCPS = [
  */
 export const MARKETPLACES_TO_REFRESH = [
   "curdx-flow-marketplace",
-  ...RECOMMENDED_PLUGINS
-    .filter((p) => p.marketplaceId && p.marketplaceId !== "claude-plugins-official")
-    .map((p) => p.marketplaceId),
+  ...REQUIRED_PLUGINS.map((p) => p.marketplaceId),
+  ...RECOMMENDED_PLUGINS.map((p) => p.marketplaceId),
 ];
 
 /**
@@ -103,5 +117,6 @@ export const MARKETPLACES_TO_REFRESH = [
  */
 export const PLUGINS_TO_UPDATE = [
   "curdx-flow@curdx-flow-marketplace",
-  ...RECOMMENDED_PLUGINS.map((p) => p.installSpec),
+  ...REQUIRED_PLUGINS.map((p) => p.updateSpec),
+  ...RECOMMENDED_PLUGINS.map((p) => p.updateSpec),
 ];

package/cli/uninstall.js

@@ -16,14 +16,24 @@ import {
   listPlugins,
 } from "./utils.js";
 import { removeGlobalProtocols, GLOBAL_CLAUDE_MD } from "./protocols.js";
-import { RECOMMENDED_PLUGINS, BUNDLED_MCPS } from "./registry.js";
+import { REQUIRED_PLUGINS, RECOMMENDED_PLUGINS, BUNDLED_MCPS } from "./registry.js";
 
 const HOME = homedir();
 
 // Pull uninstall-relevant subset from the single registry. See registry.js.
-const RECOMMENDED = RECOMMENDED_PLUGINS.map(({ name, uninstallSpec }) => ({
+const RECOMMENDED = RECOMMENDED_PLUGINS.map(({ name, uninstallSpec, uninstallArgs, marketplaceId, scope }) => ({
   name,
   uninstallSpec,
+  uninstallArgs: uninstallArgs || [],
+  marketplaceId,
+  scope,
+}));
+const REQUIRED = REQUIRED_PLUGINS.map(({ name, uninstallSpec, uninstallArgs, marketplaceId, scope }) => ({
+  name,
+  uninstallSpec,
+  uninstallArgs: uninstallArgs || [],
+  marketplaceId,
+  scope,
 }));
 
 // Symlinks created by install.js (only cleaned with --purge)
@@ -68,7 +78,7 @@ export async function uninstall(args = []) {
   } else {
     const r = await run(
       "claude",
-      ["plugin", "uninstall", "curdx-flow@curdx-flow-marketplace"],
+      ["plugin", "uninstall", "--scope", "user", "curdx-flow@curdx-flow-marketplace"],
       { silent: true }
     );
     if (r.code === 0) {
@@ -117,7 +127,7 @@ export async function uninstall(args = []) {
         console.log(`  ${color.cyan("▸")} Uninstalling ${color.bold(rec.name)}...`);
         const r = await run(
           "claude",
-          ["plugin", "uninstall", rec.uninstallSpec],
+          ["plugin", "uninstall", "--scope", rec.scope, ...rec.uninstallArgs, rec.uninstallSpec],
           { silent: true }
         );
         if (r.code === 0) {
@@ -163,9 +173,39 @@ export async function uninstall(args = []) {
     }
   }
 
+  // ---------- Step 4.75: uninstall required companion plugins ----------
+  log.blank();
+  log.info("Required companion plugins");
+  if (yes) {
+    log.info(
+      color.dim("--yes mode: keeping required companion plugins (use --purge to remove them)")
+    );
+  } else {
+    const removeRequired = await confirm(
+      `Remove required companion plugins (${REQUIRED.map((p) => p.name).join(", ")})? ${color.dim("(keeps shared tools available if other workflows depend on them)")}`,
+      false
+    );
+    if (removeRequired) {
+      for (const plugin of REQUIRED) {
+        const r = await run(
+          "claude",
+          ["plugin", "uninstall", "--scope", plugin.scope, ...plugin.uninstallArgs, plugin.uninstallSpec],
+          { silent: true }
+        );
+        if (r.code === 0) {
+          log.ok(`  ${plugin.name.padEnd(22)} uninstalled`);
+        } else {
+          log.info(`  ${plugin.name.padEnd(22)} ${color.dim("not present or already removed")}`);
+        }
+      }
+    } else {
+      log.info("Keeping required companion plugins");
+    }
+  }
+
   // ---------- Step 5: cleanup symlinks (only with --purge) ----------
   log.blank();
-  log.step(3, 4, "Runtime symlinks");
+  log.step(3, 4, "Runtime symlinks and marketplaces");
   if (!purge) {
     log.info(
       color.dim("Keeping ~/.local/bin/bun, ~/.local/bin/uv (use --purge to remove)")
@@ -174,6 +214,27 @@ export async function uninstall(args = []) {
       color.dim("Reason: these bun/uv binaries may be used by other tools — confirm before deleting")
     );
   } else {
+    const marketplaceIds = [
+      ...new Set(
+        RECOMMENDED
+          .concat(REQUIRED)
+          .map((r) => r.marketplaceId)
+          .filter((id) => id && id !== "claude-plugins-official")
+      ),
+    ];
+    for (const marketplaceId of marketplaceIds) {
+      const r = await run(
+        "claude",
+        ["plugin", "marketplace", "remove", marketplaceId],
+        { silent: true }
+      );
+      if (r.code === 0) {
+        log.ok(`Removed marketplace ${marketplaceId}`);
+      } else if (!r.stderr.includes("not found")) {
+        log.warn(`Failed to remove marketplace ${marketplaceId}: ${r.stderr.trim().split("\n").pop()}`);
+      }
+    }
+
     for (const link of MANAGED_SYMLINKS) {
       if (!existsSync(link) && !isBrokenSymlink(link)) {
         continue;

package/cli/upgrade.js

@@ -47,7 +47,7 @@ export async function upgrade(args = []) {
       continue;
     }
 
-    const r = await run("claude", ["plugin", "update", spec], { silent: true });
+    const r = await run("claude", ["plugin", "update", "--scope", "user", spec], { silent: true });
     if (r.code === 0) {
       const updated = r.stdout.includes("updated from");
       if (updated) {

package/cli/utils.js

@@ -172,7 +172,7 @@ export function claudeVersion() {
  * 2.1.117+). Falls back to parsing the human-readable stream-text output
  * for older CLI versions, but warns that parser is brittle.
  *
- * Returns array of { name, version, status }.
+ * Returns array of { id, name, marketplaceId, version, status, scope }.
  */
 export function listPlugins() {
   // Preferred: structured JSON output.
@@ -182,9 +182,12 @@ export function listPlugins() {
       const arr = JSON.parse(j.stdout);
       return arr.map((p) => ({
         // id has form "name@marketplace" — name is stable for dedup/lookup.
+        id: String(p.id || ""),
         name: String(p.id || "").split("@")[0],
+        marketplaceId: String(p.id || "").split("@")[1] || undefined,
         version: p.version,
         status: p.enabled === false ? "disabled" : "enabled",
+        scope: p.scope,
         raw: JSON.stringify(p),
       }));
     } catch {
@@ -203,18 +206,35 @@ export function listPlugins() {
   const blocks = res.stdout.split(/\n\s*❯\s*/).slice(1);
   for (const block of blocks) {
     const lines = block.split("\n");
-    const name = lines[0].trim().split("@")[0];
+    const id = lines[0].trim();
+    const name = id.split("@")[0];
     const version = (block.match(/Version:\s*(\S+)/) || [])[1];
     const status = block.includes("✔")
       ? "enabled"
       : block.includes("✘")
         ? "failed"
         : "unknown";
-    plugins.push({ name, version, status, raw: block });
+    plugins.push({ id, name, marketplaceId: id.split("@")[1], version, status, raw: block });
   }
   return plugins;
 }
 
+/**
+ * List configured Claude Code plugin marketplaces.
+ * Returns array of { name, source, repo, path } when `--json` is supported.
+ */
+export function listPluginMarketplaces() {
+  const j = runSync("claude", ["plugin", "marketplace", "list", "--json"]);
+  if (j.code === 0 && j.stdout.trim().startsWith("[")) {
+    try {
+      return JSON.parse(j.stdout);
+    } catch {
+      return [];
+    }
+  }
+  return [];
+}
+
 /**
  * Read the user-level MCP registrations from ~/.claude.json. These are the
  * MCPs the user added manually via `claude mcp add …` — distinct from

package/hooks/hooks.json

@@ -8,10 +8,9 @@
             "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/session-start.sh"
           }
         ]
-      }
-    ],
-    "InstructionsLoaded": [
+      },
       {
+        "matcher": "startup|clear|compact",
         "hooks": [
           {
             "type": "command",

package/hooks/scripts/inject-karpathy.sh

@@ -1,10 +1,13 @@
 #!/usr/bin/env bash
-# CurDX-Flow InstructionsLoaded Hook
+# CurDX-Flow SessionStart baseline injection
 # Injects the L1 baseline (Karpathy 4 principles + mandatory tool rules + 3 red lines)
-# into every session after CLAUDE.md is loaded.
+# as additionalContext at every session boot (startup, /clear, post-compact).
 #
-# This is what makes the baseline "always on" — it doesn't rely on CLAUDE.md being
-# present in every project, and it survives context compaction.
+# Wired under SessionStart rather than InstructionsLoaded because Claude Code's
+# InstructionsLoaded event is observability-only — its hook schema rejects
+# hookSpecificOutput / additionalContext. SessionStart with matcher
+# "startup|clear|compact" gives the same "baseline is always on, even after
+# compaction" property while staying within the supported schema.
 
 set -u
 
@@ -46,7 +49,7 @@ CONTEXT='## CurDX-Flow Mind Baseline (L1 — always on)
 # Emit JSON with safe encoding
 if command -v python3 >/dev/null 2>&1; then
   ESCAPED="$(printf '%s' "$CONTEXT" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')"
-  printf '{"hookSpecificOutput":{"hookEventName":"InstructionsLoaded","additionalContext":%s}}\n' "$ESCAPED"
+  printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":%s}}\n' "$ESCAPED"
 fi
 
 exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@curdx/flow",
-  "version": "2.0.0-beta.15",
+  "version": "2.0.0-beta.17",
   "description": "CLI installer for CurDX-Flow — AI engineering workflow meta-framework for Claude Code",
   "type": "module",
   "bin": {