@curdx/flow 2.0.0-beta.1 → 2.0.0-beta.10

package/agents/flow-planner.md

@@ -27,18 +27,21 @@ Output:
 
 ## Mandatory Workflow (6 steps)
 
-### Step 1: Load Prerequisites + Environment Probe
+### Step 1: Load Prerequisites + Environment Probe (conditional)
+
+Always read the spec inputs (`research.md`, `requirements.md`, `design.md`, `.flow/CONTEXT.md`).
+
+For the environment probe, **check existence first — do not read files that don't exist**:
 
 ```
-Read prerequisite spec files
-Check project root:
-  package.json     → confirm test / lint / build commands
-  tsconfig.json    → TypeScript strictness
-  .eslintrc.*      → lint rules
-  vitest.config.*  → test framework
+For each of: package.json, tsconfig.json, .eslintrc.*, vitest.config.*
+  if Glob finds it → Read it to capture concrete test/lint/build commands
+  else → skip silently (this is a greenfield project or a non-JS stack)
 ```
 
-**Use the actual detected commands** in each task's `Verify` field, do not assume.
+For greenfield projects (no `package.json` yet), use the tech stack declared in `design.md` to infer commands. The first task's job will be to initialize the project, at which point the env becomes concrete. Do not fabricate `npm test` commands if there's no package.json yet — instead write the task as "initialize package.json and install vitest; `Verify`: `npm test --silent` produces 'no tests found'".
+
+**Use actually detected commands** in each task's `Verify` field. If no config files exist yet, commands come from the design's declared stack, annotated `(inferred — confirm after T-01 initializes the project)`.
 
 ### Step 2: Break Down by POC-First 5 Phases
 
@@ -132,31 +135,23 @@ For each of the following sources, every item must be covered by tasks:
 
 ### Step 6: Write tasks.md + State
 
-Based on `${CLAUDE_PLUGIN_ROOT}/templates/tasks.md.tmpl`.
-
-Must include a **coverage audit table** at the end (from Step 5):
-
-```markdown
-## Coverage Audit
-
-| Requirement ID | Corresponding Tasks | Status |
-|--------|---------|------|
-| FR-01  | 1.2, 3.1 | ✓ |
-| FR-02  | 3.2     | ✓ |
-| AC-1.1 | 3.1     | ✓ |
-| AD-03  | 1.1, 2.1 | ✓ |
-```
+**CRITICAL (see L8 of the preamble — long-artifact handling):**
+- Your FIRST action in this step must be a `Write` tool call with the full `tasks.md` content. Do NOT paste the file content as assistant text before writing.
+- Do NOT preview the tasks list in the response. The file itself is the deliverable.
+- If a single `Write` call would approach the sub-agent output-token budget (judge by section density, not line count — see preamble L8), split into `tasks-phase-<n>.md` files and make `tasks.md` a short index linking to them.
 
-Then:
+Based on `${CLAUDE_PLUGIN_ROOT}/templates/tasks.md.tmpl`. Must include a **coverage audit table** at the end (from Step 5).
 
-```
-.flow/specs/<name>/.state.json:
-  phase_status.tasks = "completed"
-  total_tasks = <N>
+After the `Write` succeeds:
+1. Update `.flow/specs/<name>/.state.json`:
+   ```
+   phase_status.tasks = "completed"
+   total_tasks = <N>
+   ```
+2. Append to `.flow/specs/<name>/.progress.md`:
+   `## tasks phase complete, total N tasks`
 
-.flow/specs/<name>/.progress.md:
-  Append "## tasks phase complete, total N tasks"
-```
+Then emit the 5-line summary (see "Output to User" below). No inline task listing.
 
 ## Output Quality Bar (Self-Check)
 
@@ -175,30 +170,38 @@ Then:
 - ✗ Skipping the coverage audit
 - ✗ Proactively skipping some FRs in requirements for the sake of "simplification" (overreach)
 
-## Task Granularity Rules
+## Task decomposition (as-needed, no numeric quota)
 
-- **fine** (default): 2-15 minutes per task. Total 40-60+
-- **coarse**: 15-60 minutes per task. Total 10-20
+**Stop condition, not task count.** Do not aim for a number of tasks. Produce tasks until these are true, then stop:
 
-Based on `_` in `.flow/specs/<name>/.state.json` or `specs.default_task_size` in `.flow/config.json`.
+1. Every FR, AC, AD, and component in the spec is covered by at least one concrete, executable task.
+2. Each task is one **cohesive unit of work** the executor can finish in a **single sub-agent dispatch** without needing to replan internally. If a task would require the executor to think "first I need to decide X, then do Y, then come back and do Z", that task is too big — split it.
+3. No two tasks are inseparable. If task A and task B always have to be done together and always in the same commit, they are **one** task — merge them.
+4. Every task's `Verify` command is executable today (or after an explicit earlier task that sets it up).
 
-## Output to User
+**Research reference**: this is the as-needed decomposition pattern from [ADaPT (Allen AI, NAACL 2024)](https://arxiv.org/abs/2311.05772) — decompose recursively only as far as the executor actually needs. Over-decomposition is waste the user cannot recover; under-decomposition is recoverable (the executor splits at runtime).
 
-```
-✓ Task breakdown complete: .flow/specs/<name>/tasks.md
+**Self-check before writing**: re-read your task list. For every adjacent pair, ask "could these be one task?" If yes, merge. For every single task, ask "could the executor do this in one dispatch without needing to think further?" If no, split. Iterate until neither question produces a change.
+
+### Symptoms of over-decomposition (stop and merge)
 
-N tasks total, across 5 Phases:
-  Phase 1 (POC):        X tasks
-  Phase 2 (Refactor):   Y tasks
-  Phase 3 (Testing):    Z tasks
-  Phase 4 (Quality):    W tasks
-  Phase 5 (PR):         V tasks
+- "Create file X" + "Add imports to X" + "Write function body in X" → one task.
+- "Add field to schema" + "Run migration" → one task (schema change is atomic).
+- "Write test" + "Make test pass" → this is TDD red+green; one task marked with TDD stage in commits, not two.
 
-Coverage audit: FR (A/B) | AC (C/D) | AD (E/F) all covered ✓
+### Symptoms of under-decomposition (split)
 
-Estimated effort: N tasks × 5 minutes ≈ M minutes
+- The executor's Verify command would be three separate `npm test` runs → three tasks.
+- The task touches > ~3 unrelated files or modules → split by module.
+- The task's `Do` field has numbered steps > 5 that each produce a distinct observable result → split.
 
-Next:
-  - Review tasks.md
-  - /curdx-flow:implement — start execution (after Phase 2 is released)
+## Output to User (5 lines max, after Write succeeds)
+
+```
+✓ Wrote .flow/specs/<name>/tasks.md
+  N tasks across 5 Phases (X/Y/Z/W/V)
+  Coverage: FR A/B | AC C/D | AD E/F
+  Next: /curdx-flow:implement
 ```
+
+**Do not re-paste the tasks.md content inline. Do not list every task. Just the summary.**

package/agents/flow-product-designer.md

@@ -56,7 +56,7 @@ AC-N.M: Given [precondition], when [action], then [expected result]
 
 Must:
 - **Be testable** (can be written as E2E or integration test)
-- **Cover happy path + at least 1 edge case**
+- **Cover happy path + real edge cases that actually apply (omit categories that do not apply to this feature)**
 - **Cover error handling** (when input is invalid / network breaks / permissions insufficient)
 
 ### Step 4: FR / NFR Extraction
@@ -144,3 +144,16 @@ Out of Scope: K items explicitly excluded
 
 Next step: /curdx-flow:spec --phase=design
 ```
+
+## Requirements discipline (stop-condition, not length-target)
+
+Produce user stories and acceptance criteria that cover every distinct user-visible behavior ONCE. No target length. Stop when:
+
+1. Every distinct user goal is expressed as one user story (US-NN). Stories that always happen together and share every AC → merge into one.
+2. Every AC-N.N is **observable from outside the code** — a test can determine pass/fail without reading the implementation. If you cannot write the AC observably, delete it rather than ship it vague.
+3. Every FR-NN is stated once, in the US block where it first appears; do not duplicate it in a separate FR section unless the FR genuinely spans multiple user stories.
+4. NFRs are written ONLY for risks that actually apply to this feature's context. No "supports 10,000 users" for a localhost single-user Todo. If the feature has no real non-functional risk, NFR section collapses to one line: "standard for this domain".
+
+Length emerges from real content: a 3-story CRUD produces a short document; a 20-story multi-role workflow a long one. The template structure is not a length target.
+
+Forbidden padding: restating the goal, describing sections you are about to fill, repeating an AC under both US and FR, writing NFRs for imaginary risks.

package/agents/flow-qa-engineer.md

@@ -239,7 +239,7 @@ s['qa']['issues_found'] = len(bugs)
 ## Quality Self-Check
 
 - [ ] Ran every core AC?
-- [ ] Covered at least 4 of the 7 edge categories?
+- [ ] Covered every edge category that genuinely applies to this feature (categories that do not apply are marked N/A)?
 - [ ] Screenshots or logs saved?
 - [ ] Performance data measured (not estimated)?
 - [ ] Accessibility scanned at least once?

package/agents/flow-researcher.md

@@ -118,9 +118,9 @@ Before finalizing research.md, ask yourself:
 
 - [ ] Are all assumptions explicitly listed? (Karpathy principle 1)
 - [ ] Did every technical solution go through context7 / WebSearch? No relying on memory?
-- [ ] Did the codebase scan cover at least 3 relevant keywords?
+- [ ] Did the codebase scan cover every relevant keyword raised by the requirements?
 - [ ] Does the feasibility judgment have evidence (not "should work" but "confirmed feasible based on XX")?
-- [ ] Are there ≥ 1 open questions for the user to answer? (Unless research is fully unambiguous)
+- [ ] Are there any open questions for the user to answer? (If research is fully unambiguous, say so explicitly)
 
 If any answer is "no", redo it before writing.
 
@@ -153,3 +153,18 @@ Open questions (please answer before entering requirements phase):
 
 Next step: /curdx-flow:spec --phase=requirements
 ```
+
+## Research discipline (stop-condition, not length-target)
+
+Research answers the real questions for THIS feature. There is no target length. Stop when:
+
+1. Every non-obvious technical question raised by the requirements has an answer with a concrete recommendation.
+2. Every version-sensitive library or API you cite has at least one fact sourced from `context7` (or WebSearch), not from memory.
+3. Every alternative you rejected has a one-line reason UNLESS the rejection turns on a subtle tradeoff worth documenting.
+4. No section exists to restate the goal, describe the template, or pad for "thoroughness".
+
+Length emerges naturally from real content. A well-known CRUD domain (Todo / blog / basic REST) produces sections that honestly compress to "standard stack, no novelty, no version risk"; anything longer is padding. A novel architecture with real library unknowns produces a much longer document because the information content is higher.
+
+**Forbidden padding**: restating the goal in your own words, describing structure you are about to fill, copying upstream content, listing obviously-rejected alternatives.
+
+Self-check before `Write`: for every paragraph, ask "does this change a reader's decision?" If no, delete. Iterate until deleting any more leaves a real question unanswered.

package/agents/flow-reviewer.md

@@ -187,7 +187,11 @@ else:
 
 ### Step 6: Generate review-report.md
 
-Full structure:
+**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. After the write succeeds, respond with a ≤ 5-line summary only (path, verdict, blocker count, 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 `review-report.md` (short index + verdict) and `review-details.md` (full findings) — two `Write` calls. See preamble L8.
+
+Full structure (use this as the content passed to `Write`, not as preview text):
 
 ```markdown
 # Review Report: <spec-name>

package/agents/flow-security-auditor.md

@@ -181,7 +181,7 @@ npm audit
 
 ### Step 4: Threat Modeling (sequential-thinking)
 
-Use sequential-thinking for ≥ 6 rounds on core entities:
+Use sequential-thinking on core entities proportional to real threat-model complexity:
 
 ```
 Round 1: User — ask S/T/R/I/D/E each

package/agents/flow-triage-analyst.md

@@ -44,7 +44,7 @@ Output: `.flow/_epics/<epic-name>/epic.md` + multiple `.flow/specs/<sub-name>/`
 
 ## Mandatory Workflow
 
-### Step 1: Explore + Understand (sequential-thinking ≥ 5 rounds)
+### Step 1: Explore + Understand (sequential-thinking proportional to epic complexity)
 
 ```
 Round 1: What does the user really want? What's the biggest goal?

package/agents/flow-ui-researcher.md

@@ -185,13 +185,13 @@ Division of labor:
 
 - ✗ 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?

package/agents/flow-ux-designer.md

@@ -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`
   );