@curdx/flow 1.1.11 → 2.0.0-beta.10

package/agents/flow-ui-researcher.md

@@ -133,7 +133,7 @@ For this project (per CONTEXT.md):
 - Palette: follow project primary #6366F1
 - Font: keep Inter system
 
-## Suggested Direction for UX Designer (Emma / flow-ux-designer)
+## Suggested Direction for flow-ux-designer
 
 Generate 2-3 variants:
 1. Variant A: pure Stripe style (most conservative)
@@ -170,28 +170,28 @@ mkdir -p "$REF_DIR"
 /curdx-flow:ui-research "reference patterns for login form"
   ↓ outputs ui-research.md
   
-/curdx-flow:sketch
+the `ui-sketch` skill
   ↓ flow-ux-designer reads ui-research.md as input
   ↓ generates variants A/B/C based on research findings
 ```
 
 Division of labor:
 - **Me (UI Researcher)**: gather + classify, no design
-- **Emma (UX Designer)**: produces actual UI based on my research
+- **flow-ux-designer**: produces actual UI based on my research
 
 ---
 
 ## Forbidden
 
-- ✗ Doing actual UI design (that's Emma's job)
+- ✗ Doing actual UI design (that's flow-ux-designer's job)
 - ✗ Listing references from memory (must WebSearch or scan the codebase)
-- ✗ Providing only one reference (at least 3 categories)
+- ✗ Providing only one reference — aim for enough breadth across reference categories that the user has genuine alternatives to pick from
 - ✗ Ignoring CONTEXT.md preferences
 
 ## Quality Self-Check
 
 - [ ] Scanned codebase for existing patterns?
-- [ ] WebSearch covered at least 3 categories of references?
+- [ ] WebSearch covered enough reference categories that the user has genuine design alternatives?
 - [ ] sequential-thinking used to classify references?
 - [ ] Recommendation considers CONTEXT.md?
 - [ ] Asset files saved?
@@ -219,7 +219,7 @@ Report: .flow/specs/<name>/ui-research.md
 Assets: .flow/specs/<name>/ui-research/refs/
 
 Next step:
-  /curdx-flow:sketch — generate concrete UI variants based on research
+  the `ui-sketch` skill — generate concrete UI variants based on research
 ```
 
 ---

package/agents/flow-ux-designer.md

@@ -28,7 +28,7 @@ Output: HTML files under `.flow/specs/<name>/ui-sketch/` (multiple variants allo
 **Fallback when skill is unavailable**:
 - Switch to Tailwind CSS + shadcn/ui default style
 - Clearly tell the user "frontend-design skill not installed, using generic styles"
-- Suggest `/curdx-flow:install-deps` to install frontend-design
+- Suggest `npx @curdx/flow install --all` to install frontend-design
 
 ---
 
@@ -201,7 +201,7 @@ View:
 
 Next:
 - Pick a variant → tell me which one → I'll turn it into production components
-- Or /curdx-flow:qa to verify interactions in-browser (chrome-devtools)
+- Or the `browser-qa` skill to verify interactions in-browser (chrome-devtools)
 ```
 
 ---
@@ -237,7 +237,7 @@ The sketch stage = HTML prototype. Convert to React/Vue/Svelte components only a
 ## Quality Self-Check
 
 - [ ] Invoked the frontend-design skill (if available)?
-- [ ] ≥ 2 variants?
+- [ ] Enough variants for the user to pick meaningful alternatives (omit if the brief clearly calls for one direction only)?
 - [ ] Each variant a single HTML file, zero dependencies?
 - [ ] decisions.md explains rationale for choices?
 - [ ] Considered CONTEXT.md user preferences?

package/agents/flow-verifier.md

@@ -85,33 +85,60 @@ for comp in design.components:
     assertions.append(("Comp", comp.name, f"{comp.name} must exist"))
 ```
 
-### Step 3: Find Evidence for Each Assertion
+### Step 3: Classify every AC — does it describe user-visible behavior?
+
+**BEFORE searching for evidence, classify each AC as either UI-facing or code-only.**
+
+An AC is **UI-facing** if any of these is true:
+- Contains words: "user sees", "displays", "renders", "shown", "visible", "click", "type into", "press", "hover", "select"
+- Names a UI element: "button", "input", "checkbox", "link", "list", "form", "label", "modal", "banner"
+- Describes a user flow: "the user can do X", "after X the user sees Y"
+- References a visual state: "strikethrough", "highlighted", "disabled", "focus ring"
+
+An AC is **code-only** if it describes internal behavior:
+- Schema shape, API response structure, data transformations
+- Performance ("p95 < 50ms"), reliability, security properties
+- Error-envelope shapes, database constraints
+
+### Step 3a: Find evidence for code-only ACs
 
 ```python
-for source, id, text in assertions:
+for source, id, text in code_only_assertions:
     evidence = []
-    
-    # Evidence 1: code implementation
     relevant_files = grep_codebase(extract_keywords(text))
     if relevant_files:
         evidence.append(("code", relevant_files))
-    
-    # Evidence 2: tests
     test_files = find_tests_mentioning(id)
     if test_files:
         evidence.append(("test", test_files))
-    
-    # Evidence 3: commit references
     commits = git_log_grep(id)
     if commits:
         evidence.append(("commit", commits))
-    
-    # Verdict
-    if evidence:
-        status = "verified" if all_evidence_strong(evidence) else "partial"
-    else:
-        status = "missing"
+    status = "verified" if evidence and all_evidence_strong(evidence) else ("partial" if evidence else "missing")
+```
+
+### Step 3b: UI-facing ACs REQUIRE browser verification (hard rule)
+
+Code inspection + unit tests are **insufficient** evidence for a UI-facing AC. A `beforeEach`-style DOM test using `jsdom` or `happy-dom` is also insufficient — those simulate the DOM but not the real browser (no actual paint, no real keyboard handling, no real focus ring, no real stylesheet application).
+
+For every UI-facing AC:
+
 ```
+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.
+   - Compare observed behavior against the AC text.
+   - Verdict: verified | partial | failed, with the screenshot as evidence.
+3. If chrome-devtools MCP is NOT available:
+   - Mark the AC as "unverified — browser MCP missing".
+   - Add a CRITICAL section in verification-report.md listing the UI-facing ACs that could not be verified.
+   - Do NOT silently pass the AC based on code reading.
+   - Do NOT accept "manual smoke" as sufficient evidence unless the user explicitly logged a D-NN decision in STATE.md waiving automated browser verification.
+```
+
+Manual-smoke evidence (comments in tasks.md saying "verified by manual smoke T-24") is equivalent to "unverified" for UI-facing ACs. Flag it. The whole point of goal-backward verification is that evidence must be reproducible; a one-off manual smoke is not.
 
 ### Step 4: Run Actual Tests (Decisive)
 
@@ -145,6 +172,12 @@ For each match, check:
 
 ### Step 6: Generate verification-report.md
 
+**CRITICAL (see L8 of the preamble):** your FIRST action in this step must be a `Write` tool call with the **complete report content**. Do NOT paste the report as assistant text before writing — doing so doubles output tokens and causes truncation inside the `Write` call. After the write succeeds, respond with a ≤ 5-line summary only (path, verdict counts, next step). Do not re-paste the report.
+
+If a single `Write` call would approach the sub-agent output-token budget (judge by section density, not line count), split into `verification-report.md` (short index + verdict) and `verification-details.md` (full findings table) — two `Write` calls. See preamble L8.
+
+Required structure (use this as the content passed to `Write`, not as preview text):
+
 ```markdown
 # Verification Report: <spec-name>
 

package/bin/curdx-flow.js

@@ -20,6 +20,8 @@
  *                 for the full command/workflow reference)
  */
 
+import { pathToFileURL } from "node:url";
+
 import { install } from "../cli/install.js";
 import { doctor } from "../cli/doctor.js";
 import { upgrade } from "../cli/upgrade.js";
@@ -128,4 +130,14 @@ async function main() {
   }
 }
 
-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) {
+  main();
+}

package/cli/doctor.js

@@ -13,6 +13,7 @@ import {
   listMcps,
   ensureClaudeMemRuntimes,
 } from "./utils.js";
+import { RECOMMENDED_PLUGINS } from "./registry.js";
 
 export async function doctor(args = []) {
   const verbose = args.includes("--verbose") || args.includes("-v");
@@ -50,13 +51,28 @@ export async function doctor(args = []) {
   }
 
   // ---------- 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:")}`);
   const mcps = cv ? listMcps() : [];
-  const expectedMcps = ["context7", "sequential-thinking", "chrome-devtools"];
+  const expectedMcps = ["context7", "sequential-thinking"];
   for (const m of expectedMcps) {
-    const found = mcps.find((x) => x.name === m);
+    // `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) {
-      log.ok(`${m.padEnd(22)} ${color.dim("auto-loaded")}`);
+      const via = found.plugin ? `via plugin:${found.plugin}` : "standalone";
+      log.ok(`${m.padEnd(22)} ${color.dim(`auto-loaded (${via})`)}`);
     } else {
       if (curdx) {
         log.warn(`${m.padEnd(22)} not shown in claude mcp list (restart Claude Code may fix)`);
@@ -67,24 +83,21 @@ export async function doctor(args = []) {
     }
   }
 
-  // ---------- Recommended plugins ----------
+  // ---------- Recommended plugins (single registry; see cli/registry.js) ----------
   console.log(`\n${color.bold("Recommended plugins:")}`);
-  const recommended = [
-    { name: "pua", installCmd: "claude plugin install pua@pua-skills" },
-    { name: "claude-mem", installCmd: "claude plugin install claude-mem@thedotmack" },
-    { name: "frontend-design", installCmd: "claude plugin install frontend-design@claude-plugins-official" },
-  ];
   let claudeMemEnabled = false;
-  for (const r of recommended) {
+  for (const r of RECOMMENDED_PLUGINS) {
     const p = plugins.find((x) => x.name === r.name);
     if (p && p.status === "enabled") {
       log.ok(`${r.name.padEnd(22)} ${color.dim(`v${p.version}`)}`);
-      if (r.name === "claude-mem") claudeMemEnabled = true;
+      if (r.postInstall === "claude-mem-runtimes") claudeMemEnabled = true;
     } 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: curdx-flow install --all)")}`);
+      log.warn(
+        `${r.name.padEnd(22)} not installed ${color.dim(`(run: claude plugin install ${r.installSpec})`)}`
+      );
       warnings++;
     }
   }
@@ -147,7 +160,9 @@ export async function doctor(args = []) {
     console.log(color.green("Summary: all healthy ✓"));
   }
 
-  if (verbose) {
+  if (verbose && cv) {
+    // Only call claude when it is actually on PATH; otherwise we spawn a
+    // child that fails silently and print a blank block.
     console.log(`\n${color.bold("Details:")}`);
     console.log(color.dim(`  Plugins raw:`));
     console.log(runSync("claude", ["plugin", "list"]).stdout);

package/cli/install.js

@@ -2,7 +2,7 @@
  * install command — install curdx-flow plugin + optional recommended plugins.
  */
 
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -17,6 +17,7 @@ import {
   ensureClaudeMemRuntimes,
 } from "./utils.js";
 import { injectGlobalProtocols, GLOBAL_CLAUDE_MD } from "./protocols.js";
+import { RECOMMENDED_PLUGINS } from "./registry.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/,
@@ -28,27 +29,11 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = dirname(__dirname);
 const LOCAL_MARKETPLACE_MANIFEST = join(PKG_ROOT, ".claude-plugin", "marketplace.json");
 
-// Recommended plugins with their marketplace source + install identifier
-const RECOMMENDED = [
-  {
-    name: "pua",
-    marketplace: "tanweai/pua",
-    installSpec: "pua@pua-skills",
-    hint: "no-give-up + three red lines",
-  },
-  {
-    name: "claude-mem",
-    marketplace: "thedotmack/claude-mem",
-    installSpec: "claude-mem@thedotmack",
-    hint: "automatic cross-session memory",
-  },
-  {
-    name: "frontend-design",
-    marketplace: null, // already in default marketplace claude-plugins-official
-    installSpec: "frontend-design@claude-plugins-official",
-    hint: "Anthropic official UI skill",
-  },
-];
+// Recommended plugins: single source of truth is cli/registry.js.
+// See registry.js for the rationale — this list used to drift across
+// install/uninstall/upgrade/doctor, producing the chrome-devtools-mcp
+// orphan-plugin bug (installable but uninstallable).
+const RECOMMENDED = RECOMMENDED_PLUGINS;
 
 export async function install(args = []) {
   const all = args.includes("--all");
@@ -64,7 +49,7 @@ export async function install(args = []) {
   log.title("🚀 CurDX-Flow Installer");
 
   // ---------- Step 1: Check claude CLI ----------
-  log.step(1, 4, "Checking claude CLI...");
+  log.step(1, 5, "Checking claude CLI...");
   const ver = claudeVersion();
   if (!ver) {
     log.err("claude CLI not found. Install Claude Code from https://code.claude.com first.");
@@ -78,7 +63,7 @@ export async function install(args = []) {
   const marketplaceLabel = useOffline
     ? `local npm package (${PKG_ROOT})`
     : "GitHub curdx/curdx-flow";
-  log.step(2, 4, `Adding curdx-flow marketplace from ${marketplaceLabel}...`);
+  log.step(2, 5, `Adding curdx-flow marketplace from ${marketplaceLabel}...`);
 
   // Remove any existing marketplace with the same name so we get a clean
   // rebind to the chosen source. Errors are non-fatal (marketplace may
@@ -105,10 +90,38 @@ export async function install(args = []) {
 
   // ---------- Step 3: Install curdx-flow plugin ----------
   log.blank();
-  log.step(3, 4, "Installing curdx-flow plugin (3 MCPs will auto-start)...");
+  log.step(3, 5, "Installing curdx-flow plugin (2 MCPs will auto-start)...");
+  // 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).
+  let shippedVersion = null;
+  try {
+    const mf = JSON.parse(
+      readFileSync(LOCAL_MARKETPLACE_MANIFEST, "utf-8")
+    );
+    shippedVersion = mf?.metadata?.version || null;
+  } catch {
+    // marketplace not local (online install) or unreadable — fall through
+  }
+
   const installed = listPlugins();
   const already = installed.find((p) => p.name === "curdx-flow");
-  if (already) {
+  if (already && shippedVersion && already.version !== shippedVersion) {
+    log.info(
+      `curdx-flow installed at v${already.version}, marketplace ships v${shippedVersion} — updating...`
+    );
+    const r = await run(
+      "claude",
+      ["plugin", "update", "curdx-flow@curdx-flow-marketplace"],
+      { silent: true }
+    );
+    if (r.code !== 0) {
+      log.warn(`Update returned non-zero: ${r.stderr.trim() || r.stdout.trim()}`);
+      log.info(`If the version stays on v${already.version}, run: claude plugin uninstall curdx-flow@curdx-flow-marketplace && retry`);
+    } else {
+      log.ok(`curdx-flow updated to v${shippedVersion}`);
+    }
+  } else if (already) {
     log.ok(`curdx-flow already installed (v${already.version}, ${already.status})`);
   } else {
     const r = await run(
@@ -125,7 +138,7 @@ export async function install(args = []) {
 
   // ---------- Step 4: Recommended plugins ----------
   log.blank();
-  log.step(4, 4, "Recommended plugins");
+  log.step(4, 5, "Recommended plugins");
 
   if (noDeps) {
     log.info("Skipping recommended plugins (--no-deps)");
@@ -161,7 +174,7 @@ export async function install(args = []) {
   for (const pluginName of toInstall) {
     const rec = RECOMMENDED.find((r) => r.name === pluginName);
     log.blank();
-    console.log(`  ${color.cyan("⏳")} Installing ${color.bold(rec.name)}...`);
+    console.log(`  ${color.cyan("▸")} Installing ${color.bold(rec.name)}...`);
 
     // 1. Add marketplace (if needed)
     if (rec.marketplace) {
@@ -186,7 +199,7 @@ export async function install(args = []) {
       // 3. Post-install hook for claude-mem: its .mcp.json hard-codes `bun`,
       // but ~/.bun/bin is not on PATH when Claude Code spawns the MCP server.
       // Auto-create a PATH-visible symlink to fix it.
-      if (rec.name === "claude-mem") {
+      if (rec.postInstall === "claude-mem-runtimes") {
         const r = ensureClaudeMemRuntimes();
         for (const [name, res] of Object.entries(r)) {
           if (res.status === "linked") {
@@ -219,11 +232,13 @@ export async function install(args = []) {
 
   // ---------- Step 5: inject global protocols ----------
   log.blank();
-  console.log(color.dim("Injecting global protocols into ~/.claude/CLAUDE.md..."));
+  log.step(5, 5, "Injecting global protocols into ~/.claude/CLAUDE.md...");
   try {
     const r = injectGlobalProtocols();
     if (r.action === "created") {
       log.ok(`Global protocols injected ${color.dim(`(${GLOBAL_CLAUDE_MD})`)}`);
+    } else if (r.action === "appended") {
+      log.ok(`Global protocols appended ${color.dim(`(${GLOBAL_CLAUDE_MD})`)}`);
     } else if (r.action === "upgraded") {
       log.ok(`Global protocols upgraded ${color.dim(`(${GLOBAL_CLAUDE_MD})`)}`);
     } else {
@@ -237,15 +252,26 @@ export async function install(args = []) {
 }
 
 function printNextSteps() {
-  console.log(`\n${color.bold("✅ Install complete")}\n`);
+  // Detect whether the CLI is globally installed (curdx-flow on PATH) or
+  // the user ran us via npx. Tell them the right invocation each time.
+  const cliOnPath = has("curdx-flow");
+  const cliCmd = cliOnPath ? "curdx-flow" : "npx @curdx/flow";
+
+  console.log(`\n${color.bold(`${color.green("✓")} Install complete`)}\n`);
+  console.log(`${color.bold("Restart Claude Code")} so the plugin registers all its commands and hooks.\n`);
   console.log(`${color.bold("Next steps")}:\n`);
   console.log(`  ${color.dim("# Verify health")}`);
-  console.log(`  curdx-flow doctor\n`);
-  console.log(`  ${color.dim("# Initialize .flow/ in your project")}`);
-  console.log(`  cd ~/your-project && curdx-flow init\n`);
-  console.log(`  ${color.dim("# Start using it (inside Claude Code)")}`);
+  console.log(`  ${cliCmd} doctor\n`);
+  console.log(`  ${color.dim("# Inside any project, initialize and start a feature spec")}`);
+  console.log(`  ${color.cyan("cd ~/your-project")}`);
   console.log(`  ${color.cyan("claude")}`);
-  console.log(`  ${color.cyan("/curdx-flow:start my-feature \"<describe what to build>\"")}\n`);
+  console.log(`  ${color.cyan("/curdx-flow:init")}`);
+  console.log(`  ${color.cyan("/curdx-flow:start my-feature \"<one-line goal>\"")}\n`);
+  if (!cliOnPath) {
+    console.log(
+      `${color.dim("Tip: install the CLI globally for shorter commands —")} ${color.cyan("npm i -g @curdx/flow")}\n`
+    );
+  }
   console.log(
     `${color.bold("Learn more")}: https://github.com/curdx/curdx-flow/blob/main/docs/getting-started.md\n`
   );

package/cli/protocols.js

@@ -5,10 +5,23 @@
  * and reversible (uninstall removes it cleanly without touching user content).
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+  renameSync,
+  unlinkSync,
+} from "node:fs";
 import { join, dirname } from "node:path";
-
-const HOME = process.env.HOME || "";
+import { homedir } from "node:os";
+
+// Use os.homedir() instead of process.env.HOME — HOME can be empty inside
+// non-login shells (CI containers, some spawned child envs), which would
+// resolve GLOBAL_CLAUDE_MD to "/.claude/CLAUDE.md" (filesystem root) and
+// cause mkdir/writeFileSync to fail with EACCES. homedir() falls back to
+// the effective user's passwd entry on POSIX and USERPROFILE on Windows.
+const HOME = homedir();
 export const GLOBAL_CLAUDE_MD = join(HOME, ".claude", "CLAUDE.md");
 
 const SENTINEL_BEGIN =
@@ -53,16 +66,56 @@ function readGlobalMd() {
 
 /**
  * Locate the sentinel block in the content.
- * Returns { start, end } indices into content, or null if not found.
+ * Returns { start, end } indices into content, `null` if neither sentinel is
+ * present, or throws if the block is corrupted (begin without matching end).
+ * The throw is intentional — previously the corrupted case silently returned
+ * null, so the next run would append a SECOND block, producing drift.
  */
 function findBlock(content) {
   const start = content.indexOf(SENTINEL_BEGIN);
-  if (start === -1) return null;
+  if (start === -1) {
+    // Also check for a dangling END without BEGIN — that is also corrupted.
+    if (content.indexOf(SENTINEL_END) !== -1) {
+      throw new Error(
+        `Corrupted protocol block in ${GLOBAL_CLAUDE_MD}: END sentinel found without BEGIN. ` +
+          `Manually inspect the file and remove the dangling END line, then re-run.`
+      );
+    }
+    return null;
+  }
   const endIdx = content.indexOf(SENTINEL_END, start);
-  if (endIdx === -1) return null;
+  if (endIdx === -1) {
+    throw new Error(
+      `Corrupted protocol block in ${GLOBAL_CLAUDE_MD}: BEGIN sentinel found without END. ` +
+        `Manually remove the orphan BEGIN line (or restore the END), then re-run.`
+    );
+  }
   return { start, end: endIdx + SENTINEL_END.length };
 }
 
+/**
+ * Write `content` to `path` atomically: write to a sibling temp file first,
+ * then rename. This prevents a half-written CLAUDE.md if the process is
+ * interrupted mid-write, and avoids races between concurrent install /
+ * uninstall invocations.
+ */
+function atomicWrite(path, content) {
+  const tmp = `${path}.curdx-flow.tmp.${process.pid}`;
+  try {
+    writeFileSync(tmp, content, "utf-8");
+    renameSync(tmp, path);
+  } catch (err) {
+    // Best-effort cleanup of the temp file; swallow errors here since we
+    // are already re-throwing the real failure.
+    try {
+      if (existsSync(tmp)) unlinkSync(tmp);
+    } catch {
+      // ignore
+    }
+    throw err;
+  }
+}
+
 /**
  * Inject (or upgrade) the protocol block in ~/.claude/CLAUDE.md.
  * @returns {{action:"created"|"upgraded"|"unchanged", path:string}}
@@ -81,8 +134,8 @@ export function injectGlobalProtocols() {
       ? (existing.endsWith("\n") ? "\n" : "\n\n")
       : "";
     const next = existing + sep + FULL_BLOCK + "\n";
-    writeFileSync(path, next, "utf-8");
-    return { action: existing.length === 0 ? "created" : "created", path };
+    atomicWrite(path, next);
+    return { action: existing.length === 0 ? "created" : "appended", path };
   }
 
   // Replace existing block (handle upgrade-in-place)
@@ -92,7 +145,7 @@ export function injectGlobalProtocols() {
   }
   const next =
     existing.slice(0, block.start) + FULL_BLOCK + existing.slice(block.end);
-  writeFileSync(path, next, "utf-8");
+  atomicWrite(path, next);
   return { action: "upgraded", path };
 }
 
@@ -119,6 +172,6 @@ export function removeGlobalProtocols() {
   }
 
   const next = existing.slice(0, start) + existing.slice(end);
-  writeFileSync(path, next, "utf-8");
+  atomicWrite(path, next);
   return { action: "removed", path };
 }

package/cli/registry.js

@@ -0,0 +1,73 @@
+/**
+ * Single source of truth for recommended companion plugins.
+ *
+ * Background: before this file existed, the list of recommended plugins lived
+ * in FOUR independent places (install.js, uninstall.js, upgrade.js,
+ * doctor.js). They drifted — chrome-devtools-mcp was added to install.js
+ * during the beta.8 MCP decoupling but forgotten in the other three,
+ * making it installable but uninstallable. This registry exists so adding
+ * 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)
+ */
+
+export const RECOMMENDED_PLUGINS = [
+  {
+    name: "pua",
+    marketplace: "tanweai/pua",
+    marketplaceId: "pua",
+    installSpec: "pua@pua-skills",
+    uninstallSpec: "pua@pua-skills",
+    hint: "no-give-up + three red lines",
+  },
+  {
+    name: "claude-mem",
+    marketplace: "thedotmack/claude-mem",
+    marketplaceId: "thedotmack",
+    installSpec: "claude-mem@thedotmack",
+    uninstallSpec: "claude-mem@thedotmack",
+    hint: "automatic cross-session memory",
+    postInstall: "claude-mem-runtimes",
+  },
+  {
+    name: "frontend-design",
+    // Already in default marketplace claude-plugins-official, no add needed
+    marketplace: null,
+    marketplaceId: "claude-plugins-official",
+    installSpec: "frontend-design@claude-plugins-official",
+    uninstallSpec: "frontend-design@claude-plugins-official",
+    hint: "Anthropic official UI skill",
+  },
+  {
+    name: "chrome-devtools-mcp",
+    marketplace: "ChromeDevTools/chrome-devtools-mcp",
+    marketplaceId: "chrome-devtools-plugins",
+    installSpec: "chrome-devtools-mcp@chrome-devtools-plugins",
+    uninstallSpec: "chrome-devtools-mcp@chrome-devtools-plugins",
+    hint: "Chrome DevTools + Puppeteer (Google official)",
+  },
+];
+
+/**
+ * Marketplaces to refresh during `upgrade`. Derived from RECOMMENDED_PLUGINS
+ * plus the curdx-flow marketplace itself.
+ */
+export const MARKETPLACES_TO_REFRESH = [
+  "curdx-flow-marketplace",
+  ...RECOMMENDED_PLUGINS
+    .filter((p) => p.marketplaceId && p.marketplaceId !== "claude-plugins-official")
+    .map((p) => p.marketplaceId),
+];
+
+/**
+ * Plugin install specs to update during `upgrade` — includes curdx-flow
+ * itself plus every recommended plugin.
+ */
+export const PLUGINS_TO_UPDATE = [
+  "curdx-flow@curdx-flow-marketplace",
+  ...RECOMMENDED_PLUGINS.map((p) => p.installSpec),
+];