@curdx/flow 2.0.21 → 2.2.0

package/.claude-plugin/marketplace.json

@@ -6,20 +6,43 @@
   },
   "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.2.0"
   },
+  "allowCrossMarketplaceDependenciesOn": [
+    "context7-marketplace"
+  ],
   "plugins": [
     {
       "name": "curdx-flow",
       "source": "./",
       "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.2.0",
+      "author": {
+        "name": "wdx",
+        "email": "bydongxin@gmail.com"
+      },
+      "homepage": "https://github.com/curdx/curdx-flow",
+      "repository": "https://github.com/curdx/curdx-flow",
+      "license": "MIT",
       "keywords": [
         "workflow",
         "spec-driven",
         "ai-engineering",
         "orchestration"
       ],
-      "category": "productivity"
+      "tags": [
+        "claude-code",
+        "spec-driven",
+        "verification",
+        "workflow"
+      ],
+      "category": "productivity",
+      "dependencies": [
+        {
+          "name": "context7-plugin",
+          "marketplace": "context7-marketplace"
+        }
+      ]
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "curdx-flow",
-  "version": "2.0.21",
+  "version": "2.2.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",
@@ -16,5 +16,14 @@
     "orchestration",
     "karpathy",
     "claude-code"
+  ],
+  "skills": "./skills/",
+  "agents": "./agents/",
+  "hooks": "./hooks/hooks.json",
+  "dependencies": [
+    {
+      "name": "context7-plugin",
+      "marketplace": "context7-marketplace"
+    }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to CurdX-Flow will be documented here.
 
+## [2.2.0] - 2026-04-24
+
+### Added
+
+- **Plugin manifest dependency declaration** — `.claude-plugin/plugin.json` declares `skills/`, `agents/`, `hooks/hooks.json`, and a cross-marketplace dependency on `context7-plugin`. `marketplace.json` opts into `allowCrossMarketplaceDependenciesOn: ["context7-marketplace"]` and mirrors the dependency on the plugin entry. Claude Code resolves the dependency during install.
+- **Plugin `bin/` PATH wrapper** — new `bin/curdx-flow` POSIX `sh` wrapper exposes the CLI on the Claude Code plugin `bin/` PATH, so the in-session Bash tool can invoke `curdx-flow` without `npx`.
+- **Extension contract layer** — five JSON schemas (`plugin-manifest`, `skill-frontmatter`, `agent-frontmatter`, `gate-frontmatter`, `hooks`) plus `scripts/validate-plugin-contracts.mjs` and four contract test suites enforce structural correctness in CI. `prepublishOnly` runs the validator before `npm test`.
+- **`addRequiredPluginMarketplaces`** — split out of `installRequiredPlugins`. The install flow now pre-registers required companion marketplaces immediately after `curdx-flow-marketplace`, so the cross-marketplace dependency resolves cleanly during the curdx-flow plugin install step.
+- **Doctor: stale Claude Code warning + plugin error surfacing** — `curdx-flow doctor` warns when the local `claude` CLI is below `2.1.110` (the minimum version with modern plugin dependency resolution and `bin/` PATH support), and surfaces per-plugin load errors propagated from `claude plugin list --json`.
+- **`cli/lib/semver.js`** — extracted from `install-self-update.js`. Adds `isVersionAtLeast` for the doctor warning. The updater re-exports for backward compat.
+
+### Changed
+
+- **Skill spec alignment** — primary slash workflows (`init`, `start`, `spec`, `implement`, `verify`, `review`, `fast`, `debug`, `help`) gain `disable-model-invocation: true` so the model cannot auto-trigger them outside an explicit slash. Specialty skills (`epic`, `browser-qa`, `ui-sketch`, `security-audit`, `brownfield-index`) split trigger phrases into `when_to_use` and keep `description` short.
+- **`Task` → `Agent` tool naming** — every `allowed-tools`, `Task(...)` call site, and prose mention in `skills/`, `knowledge/`, and `templates/` updated to the current Claude Code `Agent` tool nomenclature.
+- **chrome-devtools MCP namespace** — `agents/flow-{qa-engineer,ui-researcher,verifier}.md` and `skills/{browser-qa,verify}` updated to `mcp__chrome_devtools__*` (underscore namespace) and the renamed tool surface (`new_page`, `navigate_page`, `take_screenshot`, `list_console_messages`, `list_network_requests`, `take_snapshot`, `lighthouse_audit`).
+- **Doctor: duplicate-MCP section** renamed from "Legacy plugin-bundled MCPs still present" to "Duplicate MCP registrations", with ownership-aware remediation (the official Context7 plugin gets `claude mcp remove --scope user` guidance, the migrated curdx-flow MCPs get the `claude plugin update` guidance).
+- **Templates** — `templates/{CONTEXT,PROJECT,progress,config}.md.tmpl` reference the current `/curdx-flow:*` slash names; `templates/config.json.tmpl` removes the retired `sketch` / `autonomous` modes and the retired `simplicity-gate` / `hard-gate` gates, and adds `wave_fail_policy`.
+- **`schemas/config.schema.json`** — new `gateName` definition enumerates the eight real gates; `gates.always_on / standard_mode / enterprise_mode` switch to `$ref` on it. Added `execution.wave_fail_policy`.
+- **`schemas/spec-state.schema.json`** — added `quickMode` boolean (the hook-controlled no-ask flag); fixed `goal` description to reference `/curdx-flow:start`.
+- **`hooks/scripts/quick-mode-guard.sh`** — stop treating the retired `mode=autonomous` as quick mode. Only `quickMode=true` denies `AskUserQuestion`. Regression test added.
+- **`agent-preamble/preamble.md`** — drops the "commands" wording and documents the quick-mode `AskUserQuestion` behavior.
+
+### Removed
+
+- **`CLAUDE.md`** — blanked. The L1 mind baseline now lives in `hooks/scripts/inject-karpathy.sh` (injected on every SessionStart) and the protocol section that the installer writes to `~/.claude/CLAUDE.md`. The repo file added drift surface without adding signal. The matching `language-rule-scan` allow-list entry is removed.
+- **`mode=autonomous`** — fully retired. The hook no longer treats it as quick mode, the templates no longer advertise it, and `schema-drift.test.js` regression-locks both.
+
+### Required
+
+- **Claude Code 2.1.110+** — the plugin dependency resolution and the plugin `bin/` PATH support require this baseline. The installer warns if your local `claude` is older.
+
 ## [2.0.21] - 2026-04-23
 
 ### Fixed
@@ -9,9 +41,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.md

@@ -24,6 +24,8 @@ Not a framework. Not a methodology library. A discipline layer.
 
 ## Install (one command)
 
+Requires Claude Code v2.1.110+ (latest recommended). The installer checks your local `claude` binary and `curdx-flow doctor` warns if the version is too old for modern plugin dependency handling.
+
 ```bash
 npx @curdx/flow install --all
 ```
@@ -101,6 +103,7 @@ npm i -g @curdx/flow@^1.1
 - **5 hook events** that enforce the discipline without user action
 - **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
+- **Plugin PATH helper** — `curdx-flow` is available inside Claude Code Bash sessions via the plugin `bin/` directory on modern Claude Code
 - **Offline-capable install** — the npm package ships the full plugin body; zero GitHub round-trips during install
 
 ## Documentation

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）
 
@@ -25,6 +31,7 @@ CurdX-Flow 是一个 Claude Code 插件，把 6 个验证过的 AI 工程工作
 - **10 个知识文档** — 规格驱动 / POC-First / 原子提交 / 执行策略 / ...
 - **4 个 hook 事件** — SessionStart / SessionStart(startup|clear|compact) / Stop / PreToolUse
 - **必需文档/推理工具 + 4 个推荐插件** — Context7 官方插件 / sequential-thinking MCP + pua / claude-mem / frontend-design / chrome-devtools-mcp
+- **插件 PATH helper** — 在新版 Claude Code 的 Bash 工具里可直接调用 `curdx-flow`
 - **优雅降级** — 依赖缺失时进入 fallback 模式并清晰告知
 
 ## 为什么用
@@ -41,6 +48,8 @@ CurdX-Flow 是一个 Claude Code 插件，把 6 个验证过的 AI 工程工作
 
 ## 安装
 
+需要 Claude Code v2.1.110+（推荐最新版）。安装器会检查本机 `claude`，`curdx-flow doctor` 会在版本过旧、无法完整支持新版插件依赖解析时给出警告。
+
 ```bash
 npx @curdx/flow install --all
 ```

package/agent-preamble/preamble.md

@@ -1,6 +1,6 @@
 # CurdX-Flow Agent Shared Preamble
 
-> All `flow-*` agents and commands inherit this file via `@${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md`.
+> All `flow-*` agents inherit this file via `@${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md`.
 > This is a behavioral baseline, not a suggestion. Violation counts as agent failure.
 
 ---
@@ -9,7 +9,7 @@
 
 ### 1. Think Before Coding
 - State your assumptions before starting
-- When uncertain, use AskUserQuestion — do not silently assume
+- When uncertainty changes product/business direction, use AskUserQuestion unless the current mode forbids it; in quick mode, state the best assumption and continue
 - Offer multiple interpretations and let the user choose
 - Never skip "understanding" and jump straight to "implementation"
 
@@ -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/agents/flow-qa-engineer.md

@@ -34,19 +34,20 @@ Output: `.flow/specs/<name>/qa-report.md`.
 
 ## Core Tool: chrome-devtools MCP
 
-What you can do via `mcp__chrome-devtools__*` (29 tools):
+What you can do via `mcp__chrome_devtools__*`:
 
 ### Navigation and Interaction
-- `navigate` — open URL
-- `click` / `type` / `fill` — interact
-- `screenshot` — take screenshot
-- `wait_for` — wait for element
+- `new_page` / `navigate_page` — open or change URL
+- `click` / `type_text` / `fill` — interact
+- `take_screenshot` — take screenshot
+- `wait_for` — wait for visible text
 
 ### Diagnostics
-- `console_messages` — capture console errors
-- `network_requests` — list of network requests (including failed)
+- `list_console_messages` — capture console errors
+- `list_network_requests` — list of network requests (including failed)
 - `performance_start_trace` / `performance_stop_trace` — performance trace
-- `accessibility_snapshot` — accessibility tree
+- `take_snapshot` — accessibility tree snapshot
+- `lighthouse_audit` — accessibility, SEO, and best-practice audit
 
 ---
 
@@ -78,17 +79,17 @@ Read from `design.md`:
 For each core AC, run through it in the browser:
 
 ```
-navigate → localhost:3000
+mcp__chrome_devtools__navigate_page → localhost:3000
 click → login button
 fill → email / password
 click → submit
 wait_for → redirect to dashboard
-screenshot
+mcp__chrome_devtools__take_screenshot
 ```
 
 Capture:
-- Console errors (console_messages)
-- Network failures (non-2xx in network_requests)
+- Console errors (`list_console_messages`)
+- Network failures (non-2xx in `list_network_requests`)
 - Performance data (e.g. LCP, INP)
 - Final URL / page state
 
@@ -122,7 +123,7 @@ Capture:
 ### Step 5: Accessibility Review
 
 ```
-mcp__chrome-devtools__accessibility_snapshot
+mcp__chrome_devtools__take_snapshot
 ```
 
 Check:
@@ -134,9 +135,9 @@ Check:
 ### Step 6: Performance Review
 
 ```
-mcp__chrome-devtools__performance_start_trace
+mcp__chrome_devtools__performance_start_trace
 # run through user flow
-mcp__chrome-devtools__performance_stop_trace
+mcp__chrome_devtools__performance_stop_trace
 ```
 
 Check:

package/agents/flow-ui-researcher.md

@@ -62,8 +62,8 @@ WebSearch: "<competitor> <feature> screenshot"
 
 If chrome-devtools MCP is available:
 ```
-navigate → <competitor URL>
-screenshot → save to .flow/specs/<name>/ui-research/refs/
+mcp__chrome_devtools__navigate_page → <competitor URL>
+mcp__chrome_devtools__take_screenshot → save to .flow/specs/<name>/ui-research/refs/
 ```
 
 ### Step 4: Classify with sequential-thinking

package/agents/flow-verifier.md

@@ -124,11 +124,11 @@ Code inspection + unit tests are **insufficient** evidence for a UI-facing AC. A
 For every UI-facing AC:
 
 ```
-1. Check chrome-devtools MCP availability (mcp__chrome-devtools__*).
+1. Check chrome-devtools MCP availability (`mcp__chrome_devtools__*`).
 2. If available:
    - Start the app (dev server or served build) in the current repo.
-   - Drive the flow described in the AC: click / type / navigate.
-   - Capture screenshot + list_console_messages + list_network_requests.
+   - Drive the flow described in the AC: `click` / `type_text` / `fill` / `navigate_page`.
+   - Capture evidence with `take_screenshot`, `list_console_messages`, and `list_network_requests`.
    - Compare observed behavior against the AC text.
    - Verdict: verified | partial | failed, with the screenshot as evidence.
 3. If chrome-devtools MCP is NOT available:

package/bin/curdx-flow

@@ -0,0 +1,5 @@
+#!/usr/bin/env sh
+set -eu
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+exec node "$SCRIPT_DIR/curdx-flow.js" "$@"

package/cli/README.md

@@ -1,6 +1,6 @@
 # curdx-flow CLI
 
-One-shot installer + external diagnostics + external init. Zero npm deps, pure Node.js.
+One-shot installer + external diagnostics + external init. Requires Node.js 18+ and Claude Code v2.1.110+.
 
 ## Quick Start
 
@@ -25,10 +25,11 @@ npx @curdx/flow upgrade
 Steps:
 1. Verify the `claude` CLI is installed
 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**
+3. Pre-register required companion marketplaces so plugin dependencies can resolve
+4. `claude plugin install --scope user curdx-flow@curdx-flow-marketplace`
+5. Install required companion plugin: **context7-plugin@context7-marketplace**
+6. Register required user-level MCP: **sequential-thinking**
+7. Interactively (or automatically) install recommended plugins: **pua**, **claude-mem**, **frontend-design**, **chrome-devtools-mcp**
 
 | Flag | Purpose |
 |------|---------|
@@ -66,12 +67,12 @@ The **core workflow** still lives inside Claude Code (`/curdx-flow:*` commands).
 - **External diagnostics**: check health without entering Claude Code
 - **Batch deployment**: write a script for your team — `for host in ...; do ssh $host npx github:curdx/curdx-flow install; done`
 
-## Zero-dependency design
+## Small-dependency design
 
 - Pure ES Modules (Node 18+)
-- Only Node built-ins (`child_process`, `fs/promises`, `readline`)
-- No `chalk` / `commander` / `inquirer` / `execa`
-- Fast `npx` (no `node_modules` to download)
+- Tiny runtime dependency surface (`@clack/prompts`, `picocolors`)
+- No `commander` / `inquirer` / `execa`
+- Fast `npx` and offline-capable plugin install
 
 ## Local development
 

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(" ")}`
+      );
+    }
+  }
+}