@curdx/flow 2.0.4 → 2.0.7

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "curdx-flow",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "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",

package/agents/flow-architect.md

@@ -7,6 +7,23 @@ maxTurns: 40
 tools: [Read, Write, Grep, Glob, Bash, WebSearch]
 ---
 
+<output-discipline>
+**CRITICAL: Extreme concision required to prevent context overflow.**
+
+Your output must follow these rules:
+1. **Write first, explain never**: Your FIRST action must be calling the Write tool with the full design.md content. Do NOT paste content as assistant text.
+2. **No previews**: Do NOT preview the architecture decisions in your response. The file itself is the deliverable.
+3. **Minimal status updates**: Use bullets, not prose. One-line updates only.
+4. **Final output**: After Write succeeds, output EXACTLY 4 lines:
+   - Line 1: "✓ design.md generated"
+   - Line 2: "Architecture decisions: N"
+   - Line 3: "Components: N"
+   - Line 4: "Next: /curdx-flow:spec --phase=tasks"
+5. **No explanations**: Do NOT explain what you decided, why you decided it, or what the design contains. The file speaks for itself.
+
+**Violation of these rules = task failure.**
+</output-discipline>
+
 # Flow Architect — Architecture Design Agent
 
 @${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md
@@ -167,28 +184,17 @@ Required sections:
 
 ## Output to User
 
-```
-✓ Design complete: .flow/specs/<name>/design.md
-
-Core architecture decisions:
-  AD-01: Use X instead of Y (rationale summary)
-  AD-02: ...
-  AD-03: ...
-
-Tech stack fixed:
-  - library-A@1.x — used for ...
-  - library-B@2.x — used for ...
+**CRITICAL: Follow <output-discipline> rules exactly. Output template:**
 
+```
+✓ design.md generated
+Architecture decisions: N
 Components: N
-Error paths: cover M scenarios
-
-⚠ Project-level decisions synced to .flow/STATE.md: D-NN, D-NN
-
-Next:
-  - Review the design (especially AD-01/02/03)
-  - /curdx-flow:spec --phase=tasks — break down tasks
+Next: /curdx-flow:spec --phase=tasks
 ```
 
+**Forbidden output**: Core decisions summary, tech stack list, error path counts, warnings, review suggestions. The file speaks for itself.
+
 ## Design discipline (stop-condition, not length-target)
 
 Document only the genuinely novel architectural decisions. No target length. Stop when:
@@ -201,3 +207,17 @@ Document only the genuinely novel architectural decisions. No target length. Sto
 Well-known stack assemblies honestly compress to: stack list with one-line justification each, data model, API surface, a small number of real ADs, deviations from convention. Forcing a 13-section template to be filled adds nothing when the decisions don't exist.
 
 `sequential-thinking` is invoked to reason through tradeoffs. **The thinking is the work; the written design.md contains only the conclusions**, not the reasoning chain. If a paragraph explains why A beat B and the beat is obvious, delete the paragraph.
+
+---
+
+<bookend>
+**Restated critical rules (output discipline):**
+
+1. Write first, explain never. Your FIRST action = Write tool call with full design.md.
+2. No previews. Do NOT paste architecture decisions in your response.
+3. Minimal status. Bullets only, one line each.
+4. Fixed output. Exactly 4 lines (see Output to User section).
+5. No explanations. Do NOT explain decisions, tech stack, or design content.
+
+**Violation of these rules = task failure. The file is the deliverable, not your explanation.**
+</bookend>

package/agents/flow-planner.md

@@ -7,6 +7,24 @@ maxTurns: 30
 tools: [Read, Write, Grep, Glob, Bash]
 ---
 
+<output-discipline>
+**CRITICAL: Extreme concision required to prevent context overflow.**
+
+Your output must follow these rules:
+1. **Write first, explain never**: Your FIRST action must be calling the Write tool with the full tasks.md content. Do NOT paste content as assistant text.
+2. **No previews**: Do NOT preview the task list in your response. The file itself is the deliverable.
+3. **Minimal status updates**: Use bullets, not prose. One-line updates only.
+4. **Final output**: After Write succeeds, output EXACTLY 5 lines:
+   - Line 1: "✓ tasks.md generated"
+   - Line 2: "Total tasks: N"
+   - Line 3: "Coverage audit: [PASS/FAIL]"
+   - Line 4: "Phases: 1-5"
+   - Line 5: "Next: /curdx-flow:implement"
+5. **No explanations**: Do NOT explain what you did, why you did it, or what the tasks contain. The file speaks for itself.
+
+**Violation of these rules = task failure.**
+</output-discipline>
+
 # Flow Planner — Task Breakdown Agent
 
 @${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md
@@ -205,3 +223,17 @@ Then emit the 5-line summary (see "Output to User" below). No inline task listin
 ```
 
 **Do not re-paste the tasks.md content inline. Do not list every task. Just the summary.**
+
+---
+
+<bookend>
+**Restated critical rules (output discipline):**
+
+1. Write first, explain never. Your FIRST action = Write tool call with full file content.
+2. No previews. Do NOT paste content in your response.
+3. Minimal status. Bullets only, one line each.
+4. Fixed output. Exactly 3-5 lines (see output template in frontmatter).
+5. No explanations. Do NOT explain what you produced. The file is the deliverable.
+
+**Violation of these rules = task failure.**
+</bookend>

package/agents/flow-product-designer.md

@@ -7,6 +7,23 @@ maxTurns: 25
 tools: [Read, Write, AskUserQuestion, Grep, Bash]
 ---
 
+<output-discipline>
+**CRITICAL: Extreme concision required to prevent context overflow.**
+
+Your output must follow these rules:
+1. **Write first, explain never**: Your FIRST action must be calling the Write tool with the full requirements.md content. Do NOT paste content as assistant text.
+2. **No previews**: Do NOT preview the user stories or acceptance criteria in your response. The file itself is the deliverable.
+3. **Minimal status updates**: Use bullets, not prose. One-line updates only.
+4. **Final output**: After Write succeeds, output EXACTLY 4 lines:
+   - Line 1: "✓ requirements.md generated"
+   - Line 2: "User stories: N"
+   - Line 3: "Functional requirements: N"
+   - Line 4: "Next: /curdx-flow:spec --phase=design"
+5. **No explanations**: Do NOT explain what you defined, why you defined it, or what the requirements contain. The file speaks for itself.
+
+**Violation of these rules = task failure.**
+</output-discipline>
+
 # Flow Product Designer — Product Design Agent
 
 @${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md
@@ -157,3 +174,17 @@ Produce user stories and acceptance criteria that cover every distinct user-visi
 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.
+
+---
+
+<bookend>
+**Restated critical rules (output discipline):**
+
+1. Write first, explain never. Your FIRST action = Write tool call with full file content.
+2. No previews. Do NOT paste content in your response.
+3. Minimal status. Bullets only, one line each.
+4. Fixed output. Exactly 3-5 lines (see output template in frontmatter).
+5. No explanations. Do NOT explain what you produced. The file is the deliverable.
+
+**Violation of these rules = task failure.**
+</bookend>

package/agents/flow-researcher.md

@@ -7,6 +7,22 @@ maxTurns: 40
 tools: [Read, Write, WebSearch, WebFetch, Grep, Glob, Bash]
 ---
 
+<output-discipline>
+**CRITICAL: Extreme concision required to prevent context overflow.**
+
+Your output must follow these rules:
+1. **Write first, explain never**: Your FIRST action must be calling the Write tool with the full research.md content. Do NOT paste content as assistant text.
+2. **No previews**: Do NOT preview the research findings in your response. The file itself is the deliverable.
+3. **Minimal status updates**: Use bullets, not prose. One-line updates only.
+4. **Final output**: After Write succeeds, output EXACTLY 3 lines:
+   - Line 1: "✓ research.md generated"
+   - Line 2: "Recommendations: N"
+   - Line 3: "Next: /curdx-flow:spec --phase=requirements"
+5. **No explanations**: Do NOT explain what you found, why you recommend it, or what the research contains. The file speaks for itself.
+
+**Violation of these rules = task failure.**
+</output-discipline>
+
 # Flow Researcher — Research Analysis Agent
 
 @${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md
@@ -168,3 +184,17 @@ Length emerges naturally from real content. A well-known CRUD domain (Todo / blo
 **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.
+
+---
+
+<bookend>
+**Restated critical rules (output discipline):**
+
+1. Write first, explain never. Your FIRST action = Write tool call with full file content.
+2. No previews. Do NOT paste content in your response.
+3. Minimal status. Bullets only, one line each.
+4. Fixed output. Exactly 3-5 lines (see output template in frontmatter).
+5. No explanations. Do NOT explain what you produced. The file is the deliverable.
+
+**Violation of these rules = task failure.**
+</bookend>

package/cli/install-companions.js

@@ -0,0 +1,251 @@
+import { color, ensureClaudeMemRuntimes, listPlugins, log, multiselectClack, note, run, text, writeConfig } from "./utils.js";
+import { BUNDLED_MCPS, RECOMMENDED_PLUGINS, REQUIRED_PLUGINS } from "./registry.js";
+import { readUserMcpConfig } from "./utils.js";
+
+const RECOMMENDED = RECOMMENDED_PLUGINS;
+
+export async function installRequiredPlugins({ yes, language, config }) {
+  log.blank();
+  log.info("Installing required Claude Code plugins...");
+  for (const plugin of REQUIRED_PLUGINS) {
+    console.log(`  ${color.cyan("▸")} Installing ${color.bold(plugin.name)}...`);
+    const ma = await run(
+      "claude",
+      ["plugin", "marketplace", "add", "--scope", plugin.scope, plugin.marketplaceSource],
+      { silent: true }
+    );
+    if (ma.code !== 0 && !ma.stderr.includes("already")) {
+      log.warn(`     marketplace add warning: ${ma.stderr.trim().split("\n")[0]}`);
+    }
+
+    const ir = await run(
+      "claude",
+      ["plugin", "install", "--scope", plugin.scope, plugin.installSpec],
+      { silent: true }
+    );
+    if (ir.code === 0) {
+      console.log(`  ${color.green("✓")} ${plugin.name} installed`);
+
+      if (plugin.requiresConfig && plugin.configType === "apiKey" && !yes) {
+        await promptPluginConfig(plugin, language, config);
+      }
+    } else {
+      console.log(
+        `  ${color.red("✗")} ${plugin.name} install failed: ${ir.stderr.trim().split("\n").pop()}`
+      );
+      console.log(
+        color.dim(
+          `     Run manually: claude plugin marketplace add --scope ${plugin.scope} ${plugin.marketplaceSource}`
+        )
+      );
+      console.log(
+        color.dim(
+          `     Then: claude plugin install --scope ${plugin.scope} ${plugin.installSpec}`
+        )
+      );
+    }
+  }
+}
+
+export async function registerBundledMcps() {
+  log.blank();
+  log.info("Registering required MCP servers (user-level)...");
+  const existingUserMcps = readUserMcpConfig();
+  for (const mcp of BUNDLED_MCPS) {
+    if (mcp.preserveExisting && existingUserMcps.has(mcp.name)) {
+      const existing = existingUserMcps.get(mcp.name);
+      log.info(
+        `  ${mcp.name.padEnd(22)} ${color.dim(`already registered (${(existing.args || []).join(" ")}) — preserving`)}`
+      );
+      continue;
+    }
+    const r = await run(
+      "claude",
+      ["mcp", "add", "--scope", "user", 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 --scope user ${mcp.name} -- ${mcp.command} ${mcp.args.join(" ")}`
+      );
+    }
+  }
+}
+
+export async function installRecommendedPlugins({ all, yes, language }) {
+  log.blank();
+  log.step(4, 5, "Recommended plugins");
+
+  let toInstall;
+  if (all) {
+    toInstall = RECOMMENDED.map((r) => r.name);
+    log.info("--all mode: installing all recommended");
+  } else if (yes) {
+    const currentlyInstalled = new Set(listPlugins().map((p) => p.name));
+    toInstall = RECOMMENDED
+      .filter((r) => !currentlyInstalled.has(r.name))
+      .map((r) => r.name);
+    log.info(`--yes mode: installing ${toInstall.length} recommended plugins`);
+  } else {
+    const currentlyInstalled = new Set(listPlugins().map((p) => p.name));
+    const options = RECOMMENDED.map((r) => ({
+      value: r.name,
+      label: `${r.name}${currentlyInstalled.has(r.name) ? " (installed)" : ""}`,
+      hint: r.hint,
+    }));
+    const initialValues = RECOMMENDED.map((r) => r.name);
+
+    toInstall = await multiselectClack({
+      message: language === "zh"
+        ? "选择要安装的推荐插件（空格切换，回车确认）"
+        : "Select recommended plugins to install (space to toggle, enter to confirm)",
+      options,
+      initialValues,
+      required: false,
+    });
+  }
+
+  if (!toInstall || toInstall.length === 0) {
+    log.info("No recommended plugins selected, skipping");
+    return false;
+  }
+
+  for (const pluginName of toInstall) {
+    const rec = RECOMMENDED.find((r) => r.name === pluginName);
+    log.blank();
+    console.log(`  ${color.cyan("▸")} Installing ${color.bold(rec.name)}...`);
+
+    if (rec.marketplaceSource) {
+      const ma = await run(
+        "claude",
+        ["plugin", "marketplace", "add", "--scope", rec.scope, rec.marketplaceSource],
+        { silent: true }
+      );
+      if (ma.code !== 0 && !ma.stderr.includes("already")) {
+        log.warn(`     marketplace add warning: ${ma.stderr.trim().split("\n")[0]}`);
+      }
+    }
+
+    const ir = await run("claude", ["plugin", "install", "--scope", rec.scope, rec.installSpec], {
+      silent: true,
+    });
+    if (ir.code === 0) {
+      console.log(`  ${color.green("✓")} ${rec.name} installed`);
+
+      if (rec.postInstall === "claude-mem-runtimes") {
+        const r = ensureClaudeMemRuntimes();
+        for (const [name, res] of Object.entries(r)) {
+          if (res.status === "linked") {
+            console.log(
+              `  ${color.green("✓")} ${name} → PATH symlink created ${color.dim(`(${res.link} → ${res.path})`)}`
+            );
+          } else if (res.status === "missing") {
+            console.log(
+              `  ${color.yellow("⚠")} ${name} not installed ${color.dim("(claude-mem will auto-install on first run; or run: curdx-flow doctor)")}`
+            );
+          } else if (res.status === "path-unwritable") {
+            console.log(
+              `  ${color.yellow("⚠")} ${name} installed ${color.dim(`(${res.path}) but no writable PATH location — add export PATH=\"${res.path.split("/").slice(0,-1).join("/")}:$PATH\" to your shell rc`)}`
+            );
+          }
+        }
+      }
+    } else {
+      console.log(
+        `  ${color.red("✗")} ${rec.name} install failed: ${ir.stderr.trim().split("\n").pop()}`
+      );
+      console.log(
+        color.dim(
+          `     Run manually: claude plugin install --scope ${rec.scope} ${rec.installSpec}`
+        )
+      );
+    }
+  }
+  return true;
+}
+
+async function promptPluginConfig(plugin, language, config) {
+  if (plugin.name !== "context7-plugin") return;
+
+  log.blank();
+  await note(
+    language === "zh"
+      ? "Context7 需要 API key 才能使用。\n获取 API key: https://console.upstash.com/context7"
+      : "Context7 requires an API key to function.\nGet your API key at: https://console.upstash.com/context7",
+    language === "zh" ? "配置 Context7" : "Configure Context7"
+  );
+
+  const apiKey = await text({
+    message: language === "zh"
+      ? "输入你的 Context7 API key（或按 Enter 跳过）"
+      : "Enter your Context7 API key (or press Enter to skip)",
+    placeholder: "ctx7sk-...",
+    validate: (value) => {
+      if (!value) return;
+      if (!value.startsWith("ctx7sk-") && !value.startsWith("ctx7_")) {
+        return language === "zh"
+          ? "API key 应该以 ctx7sk- 或 ctx7_ 开头"
+          : "API key should start with ctx7sk- or ctx7_";
+      }
+    },
+  });
+
+  if (apiKey) {
+    config.context7ApiKey = apiKey;
+    writeConfig(config);
+
+    const r = await run(
+      "claude",
+      ["mcp", "add", "--scope", "user", "context7", "--env", `CONTEXT7_API_KEY=${apiKey}`, "--", "npx", "-y", "@upstash/context7-mcp"],
+      { silent: true }
+    );
+
+    if (r.code === 0) {
+      log.ok(
+        language === "zh"
+          ? "  Context7 API key 已配置"
+          : "  Context7 API key configured"
+      );
+    } else if (r.stderr.includes("already exists")) {
+      await run("claude", ["mcp", "remove", "--scope", "user", "context7"], { silent: true });
+      const r2 = await run(
+        "claude",
+        ["mcp", "add", "--scope", "user", "context7", "--env", `CONTEXT7_API_KEY=${apiKey}`, "--", "npx", "-y", "@upstash/context7-mcp"],
+        { silent: true }
+      );
+      if (r2.code === 0) {
+        log.ok(
+          language === "zh"
+            ? "  Context7 API key 已更新"
+            : "  Context7 API key updated"
+        );
+      }
+    } else {
+      log.warn(
+        language === "zh"
+          ? `  Context7 MCP 配置失败: ${r.stderr.trim().split("\n").pop()}`
+          : `  Context7 MCP configuration failed: ${r.stderr.trim().split("\n").pop()}`
+      );
+      log.info(
+        color.dim(
+          language === "zh"
+            ? `     手动运行: claude mcp add --scope user context7 --env CONTEXT7_API_KEY=${apiKey} -- npx -y @upstash/context7-mcp`
+            : `     Run manually: claude mcp add --scope user context7 --env CONTEXT7_API_KEY=${apiKey} -- npx -y @upstash/context7-mcp`
+        )
+      );
+    }
+  } else {
+    log.info(
+      language === "zh"
+        ? "  跳过 Context7 配置（稍后可运行 curdx-flow install 重新配置）"
+        : "  Skipped Context7 configuration (run curdx-flow install later to reconfigure)"
+    );
+  }
+}

package/cli/install-curdx-plugin.js

@@ -0,0 +1,102 @@
+import { color, log, run } from "./utils.js";
+
+export async function addCurdxMarketplace({ marketplaceSource, marketplaceLabel, useOffline }) {
+  log.blank();
+  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
+  // simply not exist yet).
+  await run(
+    "claude",
+    ["plugin", "marketplace", "remove", "curdx-flow-marketplace"],
+    { silent: true }
+  );
+
+  const addRes = await run(
+    "claude",
+    ["plugin", "marketplace", "add", "--scope", "user", marketplaceSource],
+    { silent: true }
+  );
+  if (addRes.code !== 0 && !addRes.stderr.includes("already")) {
+    log.warn(`marketplace add output: ${addRes.stderr.trim() || addRes.stdout.trim()}`);
+  } else {
+    log.ok(
+      `curdx-flow-marketplace added ${color.dim(useOffline ? "(offline, no GitHub fetch)" : "(from GitHub)")}`
+    );
+  }
+}
+
+export async function installCurdxFlowPlugin({ prevCurdxFlow, shippedVersion }) {
+  log.blank();
+  log.step(3, 5, "Installing curdx-flow plugin...");
+
+  // Use the pre-Step-2 snapshot — by this point `claude plugin marketplace
+  // remove` has already evicted the plugin, so listPlugins() here would
+  // always return undefined for curdx-flow and we'd mis-report "installed"
+  // when we actually upgraded (the bug reported by @wdx's beta.14 log).
+  const already = prevCurdxFlow;
+
+  if (already && shippedVersion && already.version === shippedVersion) {
+    // Step 2 removes and re-adds the marketplace to rebind it to the current
+    // source. Claude Code removes plugins installed from that marketplace as
+    // part of `marketplace remove`, so even a same-version install must be
+    // re-registered here.
+    log.info(
+      `curdx-flow already at v${already.version}, re-registering...`
+    );
+    const r = await run(
+      "claude",
+      ["plugin", "install", "--scope", "user", "curdx-flow@curdx-flow-marketplace"],
+      { silent: true }
+    );
+    if (r.code !== 0) {
+      log.err(`Install failed: ${r.stderr.trim() || r.stdout.trim()}`);
+      process.exit(1);
+    }
+    log.ok(`curdx-flow re-registered at v${shippedVersion}`);
+  } else if (already && shippedVersion) {
+    log.info(
+      `curdx-flow v${already.version} → v${shippedVersion}, installing...`
+    );
+    const r = await run(
+      "claude",
+      ["plugin", "install", "--scope", "user", "curdx-flow@curdx-flow-marketplace"],
+      { silent: true }
+    );
+    if (r.code !== 0) {
+      log.err(`Install failed: ${r.stderr.trim() || r.stdout.trim()}`);
+      process.exit(1);
+    }
+    log.ok(`curdx-flow upgraded to v${shippedVersion}`);
+  } else if (already) {
+    log.info(
+      `curdx-flow v${already.version} detected, re-registering...`
+    );
+    const r = await run(
+      "claude",
+      ["plugin", "install", "--scope", "user", "curdx-flow@curdx-flow-marketplace"],
+      { silent: true }
+    );
+    if (r.code !== 0) {
+      log.err(`Install failed: ${r.stderr.trim() || r.stdout.trim()}`);
+      process.exit(1);
+    }
+    log.ok("curdx-flow re-registered");
+  } else {
+    const r = await run(
+      "claude",
+      ["plugin", "install", "--scope", "user", "curdx-flow@curdx-flow-marketplace"],
+      { silent: true }
+    );
+    if (r.code !== 0) {
+      log.err(`Install failed: ${r.stderr.trim() || r.stdout.trim()}`);
+      process.exit(1);
+    }
+    if (shippedVersion) {
+      log.ok(`curdx-flow v${shippedVersion} installed`);
+    } else {
+      log.ok("curdx-flow installed");
+    }
+  }
+}

package/cli/install-language.js

@@ -0,0 +1,35 @@
+import { log, readConfig, select, writeConfig } from "./utils.js";
+
+export async function resolveInstallLanguage({ yes }) {
+  const config = readConfig();
+  let language = config.language;
+
+  if (!language && !yes) {
+    log.blank();
+    language = await select({
+      message: "Choose your preferred language / 选择语言",
+      options: [
+        {
+          value: "en",
+          label: "English",
+          hint: "CLI output and documentation in English",
+        },
+        {
+          value: "zh",
+          label: "简体中文",
+          hint: "CLI 输出和文档使用简体中文",
+        },
+      ],
+      initialValue: "en",
+    });
+    config.language = language;
+    writeConfig(config);
+    log.ok(`Language set to ${language === "zh" ? "简体中文" : "English"}`);
+  } else if (!language) {
+    language = "en";
+    config.language = language;
+    writeConfig(config);
+  }
+
+  return { language, config };
+}

package/cli/install-next-steps.js

@@ -0,0 +1,25 @@
+import { color, has } from "./utils.js";
+
+export function printNextSteps() {
+  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(`  ${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: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/install-options.js

@@ -0,0 +1,9 @@
+export function parseInstallOptions(args = []) {
+  return {
+    all: args.includes("--all"),
+    noDeps: args.includes("--no-deps"),
+    forceOnline: args.includes("--online") || args.includes("--from-github"),
+    yes: args.includes("--yes") || args.includes("-y"),
+    skipSelfUpdate: args.includes("--skip-self-update"),
+  };
+}

package/cli/install-paths.js

@@ -0,0 +1,39 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// When installed via npm, this CLI file lives at <pkg-root>/cli/*.js.
+// The npm package bundles the full plugin body (.claude-plugin/, agents/,
+// commands/, etc.) so install can register <pkg-root> as a local marketplace
+// and avoid fetching anything from GitHub.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export const PKG_ROOT = dirname(__dirname);
+export const LOCAL_MARKETPLACE_MANIFEST = join(
+  PKG_ROOT,
+  ".claude-plugin",
+  "marketplace.json"
+);
+
+export function shouldUseOfflineInstall({ forceOnline }) {
+  return !forceOnline && existsSync(LOCAL_MARKETPLACE_MANIFEST);
+}
+
+export function getMarketplaceSource(useOffline) {
+  return useOffline ? PKG_ROOT : "curdx/curdx-flow";
+}
+
+export function getMarketplaceLabel(useOffline) {
+  return useOffline
+    ? `local npm package (${PKG_ROOT})`
+    : "GitHub curdx/curdx-flow";
+}
+
+export function readShippedVersion() {
+  try {
+    const mf = JSON.parse(readFileSync(LOCAL_MARKETPLACE_MANIFEST, "utf-8"));
+    return mf?.metadata?.version || null;
+  } catch {
+    // marketplace not local (online install) or unreadable
+    return null;
+  }
+}