@curdx/flow 2.1.0 → 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.1.0"
+    "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.1.0",
+  "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

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

@@ -31,6 +31,7 @@ CurdX-Flow 是 Claude Code 之上的一层薄**纪律层**，只做三件事，
 - **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 模式并清晰告知
 
 ## 为什么用
@@ -47,6 +48,8 @@ CurdX-Flow 是 Claude Code 之上的一层薄**纪律层**，只做三件事，
 
 ## 安装
 
+需要 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"
 

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-companions.js

@@ -11,6 +11,9 @@
  *   install-context7-config.js    — context7 API-key prompt (private to required)
  */
 
-export { installRequiredPlugins } from "./install-required-plugins.js";
+export {
+  addRequiredPluginMarketplaces,
+  installRequiredPlugins,
+} from "./install-required-plugins.js";
 export { registerBundledMcps } from "./install-bundled-mcps.js";
 export { installRecommendedPlugins } from "./install-recommended-plugins.js";

package/cli/install-required-plugins.js

@@ -8,15 +8,28 @@ import { REQUIRED_PLUGINS } from "./registry.js";
 import { color, log, resultLastLine } from "./utils.js";
 import { installContext7Config } from "./install-context7-config.js";
 
-export async function installRequiredPlugins({ yes, language, config }) {
-  log.blank();
-  log.info("Installing required Claude Code plugins...");
+export async function addRequiredPluginMarketplaces({ logWarnings = true } = {}) {
   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")) {
+    if (ma.code !== 0 && !ma.stderr.includes("already") && logWarnings) {
       log.warn(`     marketplace add warning: ${ma.stderr.trim().split("\n")[0]}`);
     }
+  }
+}
+
+export async function installRequiredPlugins({
+  yes,
+  language,
+  config,
+  skipMarketplaceAdd = false,
+}) {
+  log.blank();
+  log.info("Installing required Claude Code plugins...");
+  if (!skipMarketplaceAdd) {
+    await addRequiredPluginMarketplaces();
+  }
+  for (const plugin of REQUIRED_PLUGINS) {
+    console.log(`  ${color.cyan("▸")} Installing ${color.bold(plugin.name)}...`);
 
     const ir = await installPlugin(plugin);
     if (ir.code === 0) {

package/cli/install-self-update.js

@@ -2,98 +2,9 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 
 import { log, run, runSync, VERSION } from "./utils.js";
+import { compareVersions, isVersionNewer } from "./lib/semver.js";
 
-function normalizeVersionToken(token) {
-  return /^\d+$/.test(token) ? Number(token) : token;
-}
-
-function parseVersion(version) {
-  const normalized = String(version || "").trim().replace(/^v/i, "");
-  const [coreRaw = "0", prereleaseRaw] = normalized.split("-", 2);
-  const core = coreRaw.split(".").map((part) => Number.parseInt(part, 10) || 0);
-  const prerelease = prereleaseRaw
-    ? prereleaseRaw.split(/[.-]/).filter(Boolean).map(normalizeVersionToken)
-    : [];
-
-  return { core, prerelease };
-}
-
-function compareIdentifier(left, right) {
-  if (left === right) {
-    return 0;
-  }
-
-  const leftIsNumber = typeof left === "number";
-  const rightIsNumber = typeof right === "number";
-
-  if (leftIsNumber && rightIsNumber) {
-    return left > right ? 1 : -1;
-  }
-
-  if (leftIsNumber) {
-    return -1;
-  }
-
-  if (rightIsNumber) {
-    return 1;
-  }
-
-  return left > right ? 1 : -1;
-}
-
-export function compareVersions(leftVersion, rightVersion) {
-  const left = parseVersion(leftVersion);
-  const right = parseVersion(rightVersion);
-  const coreLength = Math.max(left.core.length, right.core.length);
-
-  for (let index = 0; index < coreLength; index += 1) {
-    const leftPart = left.core[index] ?? 0;
-    const rightPart = right.core[index] ?? 0;
-    if (leftPart !== rightPart) {
-      return leftPart > rightPart ? 1 : -1;
-    }
-  }
-
-  const leftHasPrerelease = left.prerelease.length > 0;
-  const rightHasPrerelease = right.prerelease.length > 0;
-
-  if (!leftHasPrerelease && !rightHasPrerelease) {
-    return 0;
-  }
-
-  if (!leftHasPrerelease) {
-    return 1;
-  }
-
-  if (!rightHasPrerelease) {
-    return -1;
-  }
-
-  const prereleaseLength = Math.max(left.prerelease.length, right.prerelease.length);
-  for (let index = 0; index < prereleaseLength; index += 1) {
-    const leftPart = left.prerelease[index];
-    const rightPart = right.prerelease[index];
-
-    if (leftPart === undefined) {
-      return -1;
-    }
-
-    if (rightPart === undefined) {
-      return 1;
-    }
-
-    const comparison = compareIdentifier(leftPart, rightPart);
-    if (comparison !== 0) {
-      return comparison;
-    }
-  }
-
-  return 0;
-}
-
-export function isVersionNewer(latestVersion, currentVersion) {
-  return compareVersions(latestVersion, currentVersion) > 0;
-}
+export { compareVersions, isVersionNewer };
 
 /**
  * Check for CLI updates and auto-update if available.

package/cli/install.js

@@ -3,6 +3,7 @@
  */
 
 import {
+  addRequiredPluginMarketplaces,
   installRequiredPlugins,
   registerBundledMcps,
 } from "./install-companions.js";
@@ -60,6 +61,11 @@ export async function install(args = []) {
 
   await addCurdxMarketplace(context);
 
+  // Claude Code resolves plugin dependencies during install. Register
+  // required companion marketplaces before installing curdx-flow so its
+  // cross-marketplace dependency on Context7 can be satisfied immediately.
+  await addRequiredPluginMarketplaces({ logWarnings: false });
+
   // ---------- Step 3: Install curdx-flow plugin ----------
   // Read the version the marketplace is shipping so we can decide whether an
   // already-installed plugin needs an update (same name but stale version
@@ -68,7 +74,12 @@ export async function install(args = []) {
   await installCurdxFlowPlugin({ prevCurdxFlow, shippedVersion });
 
   // ---------- Step 3.5: Install required plugins + register user-level MCPs ----------
-  await installRequiredPlugins({ yes: context.yes, language, config });
+  await installRequiredPlugins({
+    yes: context.yes,
+    language,
+    config,
+    skipMarketplaceAdd: true,
+  });
 
   // Beta.12: direct MCPs migrated from plugin.json bundling. See cli/registry.js
   // for the rationale. Context7 now uses Upstash's official plugin instead.

package/cli/lib/claude.js

@@ -14,20 +14,51 @@ export function claudeVersion() {
   return m ? m[1] : res.stdout.trim().split("\n")[0];
 }
 
+function normalizePluginError(error) {
+  if (typeof error === "string") {
+    return error;
+  }
+  if (error && typeof error === "object") {
+    return error.message || error.code || JSON.stringify(error);
+  }
+  return String(error);
+}
+
+export function parsePluginListJson(output) {
+  const trimmed = String(output || "").trim();
+  if (!trimmed.startsWith("[")) {
+    return null;
+  }
+
+  const arr = JSON.parse(trimmed);
+  return arr.map((p) => {
+    const id = String(p.id || p.name || "");
+    const errors = Array.isArray(p.errors)
+      ? p.errors.map(normalizePluginError).filter(Boolean)
+      : [];
+    const enabled = p.enabled !== false;
+
+    return {
+      id,
+      name: id.split("@")[0],
+      marketplaceId: id.split("@")[1] || undefined,
+      version: p.version,
+      status: errors.length > 0 ? "failed" : enabled ? "enabled" : "disabled",
+      scope: p.scope,
+      errors,
+      raw: JSON.stringify(p),
+    };
+  });
+}
+
 export function listPlugins() {
   const j = runSync("claude", ["plugin", "list", "--json"]);
-  if (j.code === 0 && j.stdout.trim().startsWith("[")) {
+  if (j.code === 0) {
     try {
-      const arr = JSON.parse(j.stdout);
-      return arr.map((p) => ({
-        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),
-      }));
+      const plugins = parsePluginListJson(j.stdout);
+      if (plugins) {
+        return plugins;
+      }
     } catch {
       // JSON parse failed; fall through to legacy text parser.
     }

package/cli/lib/doctor-report.js

@@ -4,6 +4,13 @@ import {
   findPluginByRegistryEntry,
   hasMarketplace,
 } from "./claude.js";
+import { isVersionAtLeast } from "./semver.js";
+
+export const MIN_CLAUDE_VERSION = "2.1.110";
+
+function pluginErrorDetails(plugin) {
+  return Array.isArray(plugin?.errors) ? plugin.errors : [];
+}
 
 export function buildDoctorReport({
   claudeVersionValue,
@@ -37,6 +44,17 @@ export function buildDoctorReport({
 
   if (claudeVersionValue) {
     pushLine(lines, "ok", `claude CLI            ${claudeVersionValue}`);
+    if (!isVersionAtLeast(claudeVersionValue, MIN_CLAUDE_VERSION)) {
+      pushLine(
+        lines,
+        "warn",
+        `claude CLI            ${claudeVersionValue} below recommended ${MIN_CLAUDE_VERSION}`,
+        [
+          "curdx-flow uses modern Claude Code plugin dependency resolution and plugin bin/ PATH support",
+          "run: claude update",
+        ]
+      );
+    }
   } else {
     pushLine(lines, "err", "claude CLI            not found (install Claude Code)");
   }
@@ -47,7 +65,12 @@ export function buildDoctorReport({
     if (curdx.status === "enabled") {
       pushLine(lines, "ok", `curdx-flow            v${curdx.version} (enabled)`);
     } else {
-      pushLine(lines, "err", `curdx-flow            v${curdx.version} (${curdx.status})`);
+      pushLine(
+        lines,
+        "err",
+        `curdx-flow            v${curdx.version} (${curdx.status})`,
+        pluginErrorDetails(curdx)
+      );
     }
   } else {
     pushLine(lines, "warn", "curdx-flow            not installed → run curdx-flow install");
@@ -67,7 +90,12 @@ export function buildDoctorReport({
     if (plugin && plugin.status === "enabled") {
       pushSectionLine(requiredSection, "ok", `${entry.name.padEnd(22)} v${plugin.version || "unknown"}`);
     } else if (plugin && plugin.status === "failed") {
-      pushSectionLine(requiredSection, "err", `${entry.name.padEnd(22)} load failed`);
+      pushSectionLine(
+        requiredSection,
+        "err",
+        `${entry.name.padEnd(22)} load failed`,
+        pluginErrorDetails(plugin)
+      );
     } else {
       pushSectionLine(
         requiredSection,
@@ -120,7 +148,12 @@ export function buildDoctorReport({
       pushSectionLine(recommendedSection, "ok", `${entry.name.padEnd(22)} v${plugin.version}`);
       if (entry.postInstall === "claude-mem-runtimes") claudeMemEnabled = true;
     } else if (plugin && plugin.status === "failed") {
-      pushSectionLine(recommendedSection, "err", `${entry.name.padEnd(22)} load failed`);
+      pushSectionLine(
+        recommendedSection,
+        "err",
+        `${entry.name.padEnd(22)} load failed`,
+        pluginErrorDetails(plugin)
+      );
     } else {
       pushSectionLine(
         recommendedSection,
@@ -133,16 +166,22 @@ export function buildDoctorReport({
 
   const duplicates = findDuplicateMcps(mcps, userMcpConfig);
   if (duplicates.length > 0) {
-    const duplicateSection = createSection("Legacy plugin-bundled MCPs still present:");
+    const duplicateSection = createSection("Duplicate MCP registrations:");
     for (const duplicate of duplicates) {
+      const details = duplicate.pluginEntry.plugin === "curdx-flow"
+        ? [
+          "migration: claude plugin update curdx-flow@curdx-flow-marketplace",
+          "then restart Claude Code",
+        ]
+        : [
+          `remove the duplicate user-level server if plugin:${duplicate.pluginEntry.plugin} should own it`,
+          `run: claude mcp remove --scope user ${duplicate.name}`,
+        ];
       pushSectionLine(
         duplicateSection,
         "warn",
         `${duplicate.name.padEnd(22)} both user-level AND plugin:${duplicate.pluginEntry.plugin} active`,
-        [
-          "migration: claude plugin update curdx-flow@curdx-flow-marketplace",
-          "then restart Claude Code",
-        ]
+        details
       );
     }
   }