@curdx/flow 2.0.0-beta.11 → 2.0.0-beta.13

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

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "curdx-flow",
-  "version": "2.0.0-beta.11",
+  "version": "2.0.0-beta.13",
   "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,21 +16,5 @@
     "orchestration",
     "karpathy",
     "claude-code"
-  ],
-  "mcpServers": {
-    "context7": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@upstash/context7-mcp@latest"
-      ]
-    },
-    "sequential-thinking": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@modelcontextprotocol/server-sequential-thinking"
-      ]
-    }
-  }
+  ]
 }

package/CHANGELOG.md

@@ -4,10 +4,46 @@ All notable changes to CurDX-Flow will be documented here.
 
 ## [Unreleased]
 
+### 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`.
+
+  **Why**: every early adopter who ran `claude mcp add context7 -- npx -y @upstash/context7-mcp --api-key ctx7sk-…` before installing curdx-flow ended up with *both* entries side-by-side — doubling MCP processes, making API-key routing unpredictable (random between free-tier plugin copy and paid user copy), and forcing an awkward env-var migration path. User-level registration matches the way every other MCP in the ecosystem is installed, keeps tool names standard (`mcp__context7__*` instead of `mcp__plugin_curdx-flow_context7__*`), and lets users put an `--api-key` directly in their own entry without any env-var indirection. Every agent / knowledge doc / command in the repo already calls the standard tool-name form, so this is a **zero-change-for-callers** migration.
+
+  **Migration for existing users**:
+
+  ```bash
+  # Upgrade the plugin — this removes the plugin-bundled MCPs and
+  # registers them at user-level (preserving any existing user-level entry
+  # with a custom --api-key).
+  npx @curdx/flow@latest upgrade
+
+  # Restart Claude Code so the plugin manifest reloads.
+  ```
+
+  After upgrade, `claude mcp list` will show `context7` and
+  `sequential-thinking` (user-level) but NOT `plugin:curdx-flow:context7` etc.
+  `npx @curdx/flow doctor` confirms with "user-level (standard)" in the
+  "MCP Servers" section.
+
+### Added
+
+- `cli/registry.js` exports a new `BUNDLED_MCPS` constant — the source-of-truth list of MCPs that `install` registers at user-level and `uninstall` optionally removes.
+- `cli/install.js` Step 3.5 — registers the required MCPs via `claude mcp add`. Detects pre-existing user-level entries (e.g. your hand-configured context7 with an API key) and preserves them instead of overwriting.
+- `cli/uninstall.js` Step 4.5 — asks whether to `claude mcp remove` the registered MCPs (default: no, because other tools may depend on them).
+- `cli/doctor.js` — now reports "user-level (standard)" for each required MCP when it's registered the right way, and "(legacy)" with a migration hint when the old plugin-bundled form is still active.
+
+### Changed
+
+- The "Duplicate MCP" warning in `doctor` (added in beta.11) is now framed as "Legacy plugin-bundled MCPs still present" with a concrete migration command, since the new architecture reserves duplication strictly for the upgrade-transition window.
+- `docs/getting-started.md` "Optional: use your paid context7 API key" section rewritten around the user-level path (add `--api-key` to your `claude mcp add` command) since env-var indirection is no longer the only way to route a key to the plugin copy.
+
+## [2.0.0-beta.11] - 2026-04-22
+
 ### Added
 
-- `cli/doctor.js` now detects when a user-level MCP in `~/.claude.json` (typically `context7` added via `claude mcp add …`) duplicates a plugin-bundled MCP from `plugin.json` (`plugin:curdx-flow:context7`). The two run as independent processes and Claude routes tool calls unpredictably between them. Doctor surfaces the overlap, shows the user-level command (with any `--api-key` flag) alongside the plugin command, and prints the exact remediation: `export CONTEXT7_API_KEY=…` + `claude mcp remove context7`. Backed by `cli/utils.js:readUserMcpConfig()` + `findDuplicateMcps()` and 3 new tests in `test/utils.test.js`.
-- `docs/getting-started.md` gained an "Optional: use your paid context7 API key" section documenting the env-var path (upstream `@upstash/context7-mcp` natively reads `process.env.CONTEXT7_API_KEY`) and the cleanup command for users with a pre-existing user-level registration.
+- `cli/doctor.js` detects when a user-level MCP in `~/.claude.json` (typically `context7` added via `claude mcp add …`) duplicates a plugin-bundled MCP from `plugin.json` (`plugin:curdx-flow:context7`). Backed by `cli/utils.js:readUserMcpConfig()` + `findDuplicateMcps()` and 3 new tests in `test/utils.test.js`.
+- `docs/getting-started.md` "Optional: use your paid context7 API key" section documenting the env-var path.
 
 ## [2.0.0-beta.10] - 2026-04-21
 

package/bin/curdx-flow.js

@@ -20,7 +20,8 @@
  *                 for the full command/workflow reference)
  */
 
-import { pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
+import { realpathSync } from "node:fs";
 
 import { install } from "../cli/install.js";
 import { doctor } from "../cli/doctor.js";
@@ -131,13 +132,29 @@ async function main() {
 }
 
 // Only execute main() when invoked directly (`node bin/curdx-flow.js ...`
-// or via the npm bin shim). When the file is imported by tests or tooling,
-// we want the module graph to load without side-effects. This idiom is
-// the ESM equivalent of Python's `if __name__ == "__main__"`.
-const invokedDirectly =
-  process.argv[1] &&
-  import.meta.url === pathToFileURL(process.argv[1]).href;
-
-if (invokedDirectly) {
+// or via the npm bin shim at node_modules/.bin/<name>). When the file is
+// imported by tests or tooling, we want the module graph to load without
+// side-effects.
+//
+// CRITICAL: compare RESOLVED real paths. npm installs the bin as a symlink
+// (node_modules/.bin/curdx-flow → ../@curdx/flow/bin/curdx-flow.js), so
+// process.argv[1] is the symlink path while import.meta.url resolves to
+// the real file. Comparing them directly (the pre-beta.13 behavior)
+// silently skipped main() for every single npx / global-install user,
+// producing a completely broken CLI that exited with no output. Regression
+// caught by user report + reproduced in CI via test/cli-entrypoints.test.js.
+function isInvokedDirectly() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    // argv[1] is not a real filesystem path (e.g. `node -e` eval forms or
+    // a worker pipe). Treat as "not invoked directly" — the caller is
+    // doing something non-standard.
+    return false;
+  }
+}
+
+if (isInvokedDirectly()) {
   main();
 }

package/cli/doctor.js

@@ -57,27 +57,31 @@ export async function doctor(args = []) {
   // 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:")}`);
+  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) {
-    // `claude mcp list` reports plugin-bundled MCPs as
-    // "plugin:curdx-flow:<name>" and standalone MCPs as "<name>". Accept
-    // either form — previously this was a bare .name === m check, so a
-    // plugin MCP named "plugin:curdx-flow:context7" would silently report
-    // as not-installed even though it was running (the same class of bug
-    // that bit chrome-devtools in beta.7).
-    const found = mcps.find(
-      (x) =>
-        x.name === m &&
-        (x.plugin === null || x.plugin === "curdx-flow")
-    );
-    if (found) {
-      const via = found.plugin ? `via plugin:${found.plugin}` : "standalone";
-      log.ok(`${m.padEnd(22)} ${color.dim(`auto-loaded (${via})`)}`);
+    // 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
+    // as the primary form, and warn if only a plugin-bundled copy exists
+    // (because that's the legacy layout that beta.11 had).
+    const userLevel = mcps.find((x) => x.name === m && x.plugin === null);
+    const pluginLevel = mcps.find((x) => x.name === m && x.plugin !== null);
+
+    if (userLevel) {
+      log.ok(`${m.padEnd(22)} ${color.dim("user-level (standard)")}`);
+    } else if (pluginLevel) {
+      log.warn(
+        `${m.padEnd(22)} registered via plugin:${pluginLevel.plugin} (legacy). ` +
+          `Run ${color.cyan("npx @curdx/flow install --all")} to migrate to user-level.`
+      );
+      warnings++;
     } else {
       if (curdx) {
-        log.warn(`${m.padEnd(22)} not shown in claude mcp list (restart Claude Code may fix)`);
+        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")}`
+        );
         warnings++;
       } else {
         log.info(`${m.padEnd(22)} waiting for curdx-flow install`);
@@ -104,44 +108,28 @@ export async function doctor(args = []) {
     }
   }
 
-  // ---------- Duplicate user-level / plugin-level MCPs ----------
-  // Context: the bundled context7 + sequential-thinking MCPs (registered
-  // via plugin.json) show up as `plugin:curdx-flow:<name>`. If the user
-  // also added `<name>` manually via `claude mcp add …` at some earlier
-  // point (common with context7 + a personal API key), both instances
-  // run side-by-side. That's not a correctness bug — tool namespaces
-  // differ — but it doubles MCP processes and makes API-key routing
-  // unpredictable. Surface the duplicates + concrete remediation.
+  // ---------- Legacy plugin-bundled MCP residue (beta.11 and earlier) ----------
+  // Beta.12 moved context7 + sequential-thinking to user-level registration.
+  // If both a user-level and a plugin-bundled copy are visible, the user
+  // was likely installed from an older beta.7-beta.11 that still had
+  // mcpServers in plugin.json and a `claude mcp update` hasn't refreshed
+  // the plugin cache yet. Point them at the migration command.
   if (cv) {
     const userCfg = readUserMcpConfig();
     const duplicates = findDuplicateMcps(mcps, userCfg);
     if (duplicates.length > 0) {
-      console.log(`\n${color.bold("Duplicate MCP servers (user-level vs plugin-bundled):")}`);
+      console.log(`\n${color.bold("Legacy plugin-bundled MCPs still present:")}`);
       for (const d of duplicates) {
-        const userArgs = (d.userConfig.args || []).join(" ");
-        const hasApiKey = userArgs.includes("api-key") || userArgs.includes("ctx7sk");
         log.warn(
-          `${d.name.padEnd(22)} registered BOTH in ~/.claude.json AND via plugin:${d.pluginEntry.plugin}`
-        );
-        console.log(
-          color.dim(`     user-level : ${d.userConfig.command || "?"} ${userArgs}`)
+          `${d.name.padEnd(22)} both user-level AND plugin:${d.pluginEntry.plugin} active`
         );
         console.log(
-          color.dim(`     plugin     : ${d.pluginEntry.command || "?"}`)
+          color.dim(
+            `     → Migration: ${color.cyan(`claude plugin update curdx-flow@curdx-flow-marketplace`)}\n` +
+              `                  then restart Claude Code. Beta.12+ removes plugin-bundled\n` +
+              `                  versions in favor of the user-level entry you already have.`
+          )
         );
-        if (hasApiKey && d.name === "context7") {
-          console.log(
-            color.dim(
-              `     → Fix: export CONTEXT7_API_KEY=<your-key> in your shell rc,\n` +
-                `              then: claude mcp remove ${d.name}\n` +
-                `              (plugin MCP will inherit the env var — no key is lost)`
-            )
-          );
-        } else {
-          console.log(
-            color.dim(`     → Fix: claude mcp remove ${d.name}`)
-          );
-        }
         warnings++;
       }
     }

package/cli/install.js

@@ -17,7 +17,8 @@ import {
   ensureClaudeMemRuntimes,
 } from "./utils.js";
 import { injectGlobalProtocols, GLOBAL_CLAUDE_MD } from "./protocols.js";
-import { RECOMMENDED_PLUGINS } from "./registry.js";
+import { 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.
 // The npm package bundles the full plugin body (.claude-plugin/, agents/,
@@ -90,7 +91,7 @@ export async function install(args = []) {
 
   // ---------- Step 3: Install curdx-flow plugin ----------
   log.blank();
-  log.step(3, 5, "Installing curdx-flow plugin (2 MCPs will auto-start)...");
+  log.step(3, 5, "Installing 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
   // previously silently skipped the upgrade — caused the beta.1 → beta.7 drift).
@@ -136,6 +137,40 @@ export async function install(args = []) {
     log.ok("curdx-flow installed");
   }
 
+  // ---------- 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).
+  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 run(
+      "claude",
+      ["mcp", "add", mcp.name, "--", mcp.command, ...mcp.args],
+      { silent: true }
+    );
+    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: ${r.stderr.trim().split("\n").pop()}`
+      );
+      log.info(
+        `     Run manually: claude mcp add ${mcp.name} -- ${mcp.command} ${mcp.args.join(" ")}`
+      );
+    }
+  }
+
   // ---------- Step 4: Recommended plugins ----------
   log.blank();
   log.step(4, 5, "Recommended plugins");

package/cli/registry.js

@@ -52,6 +52,40 @@ export const RECOMMENDED_PLUGINS = [
   },
 ];
 
+/**
+ * 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
+ * USER-LEVEL via `claude mcp add` instead of plugin.json bundling, so:
+ *
+ *   - Tool names stay standard (mcp__context7__*, 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.
+ */
+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",
+    args: ["-y", "@modelcontextprotocol/server-sequential-thinking"],
+    purpose: "structured reasoning for design / review (L2 Mandatory Tool)",
+    preserveExisting: true,
+  },
+];
+
 /**
  * Marketplaces to refresh during `upgrade`. Derived from RECOMMENDED_PLUGINS
  * plus the curdx-flow marketplace itself.

package/cli/uninstall.js

@@ -16,7 +16,7 @@ import {
   listPlugins,
 } from "./utils.js";
 import { removeGlobalProtocols, GLOBAL_CLAUDE_MD } from "./protocols.js";
-import { RECOMMENDED_PLUGINS } from "./registry.js";
+import { RECOMMENDED_PLUGINS, BUNDLED_MCPS } from "./registry.js";
 
 const HOME = homedir();
 
@@ -131,6 +131,38 @@ export async function uninstall(args = []) {
     }
   }
 
+  // ---------- Step 4.5: optionally remove user-level MCPs ----------
+  // Starting beta.12, the install command registers context7 +
+  // sequential-thinking at user-level (not plugin-bundled). Ask before
+  // removing because the user may have customised args (e.g. --api-key)
+  // or still be using these MCPs outside curdx-flow.
+  log.blank();
+  log.info("Required MCP servers (context7, sequential-thinking)");
+  if (keepRecommended || yes) {
+    log.info(
+      color.dim("--yes or --keep-recommended: keeping user-level MCPs (remove manually with `claude mcp remove <name>`)")
+    );
+  } else {
+    const removeMcps = await confirm(
+      `Remove user-level MCPs registered by install (${BUNDLED_MCPS.map((m) => m.name).join(", ")})? ${color.dim("(keeps them if other tools depend on them)")}`,
+      false
+    );
+    if (removeMcps) {
+      for (const mcp of BUNDLED_MCPS) {
+        const r = await run("claude", ["mcp", "remove", mcp.name], {
+          silent: true,
+        });
+        if (r.code === 0) {
+          log.ok(`  ${mcp.name.padEnd(22)} removed`);
+        } else {
+          log.info(`  ${mcp.name.padEnd(22)} ${color.dim("not present or already removed")}`);
+        }
+      }
+    } else {
+      log.info("Keeping user-level MCPs");
+    }
+  }
+
   // ---------- Step 5: cleanup symlinks (only with --purge) ----------
   log.blank();
   log.step(3, 4, "Runtime symlinks");

package/package.json

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