@curdx/flow 1.1.11 → 2.0.0-beta.10

package/cli/uninstall.js

@@ -4,6 +4,7 @@
 
 import { existsSync, lstatSync, unlinkSync, rmSync, readlinkSync } from "node:fs";
 import { join } from "node:path";
+import { homedir } from "node:os";
 
 import {
   color,
@@ -15,18 +16,15 @@ import {
   listPlugins,
 } from "./utils.js";
 import { removeGlobalProtocols, GLOBAL_CLAUDE_MD } from "./protocols.js";
+import { RECOMMENDED_PLUGINS } from "./registry.js";
 
-const HOME = process.env.HOME || "";
+const HOME = homedir();
 
-// Keep aligned with install.js
-const RECOMMENDED = [
-  { name: "pua", uninstallSpec: "pua@pua-skills" },
-  { name: "claude-mem", uninstallSpec: "claude-mem@thedotmack" },
-  {
-    name: "frontend-design",
-    uninstallSpec: "frontend-design@claude-plugins-official",
-  },
-];
+// Pull uninstall-relevant subset from the single registry. See registry.js.
+const RECOMMENDED = RECOMMENDED_PLUGINS.map(({ name, uninstallSpec }) => ({
+  name,
+  uninstallSpec,
+}));
 
 // Symlinks created by install.js (only cleaned with --purge)
 const MANAGED_SYMLINKS = [
@@ -116,7 +114,7 @@ export async function uninstall(args = []) {
       for (const name of toRemove) {
         const rec = presentRecs.find((r) => r.name === name);
         log.blank();
-        console.log(`  ${color.cyan("⏳")} Uninstalling ${color.bold(rec.name)}...`);
+        console.log(`  ${color.cyan("▸")} Uninstalling ${color.bold(rec.name)}...`);
         const r = await run(
           "claude",
           ["plugin", "uninstall", rec.uninstallSpec],

package/cli/upgrade.js

@@ -3,13 +3,10 @@
  */
 
 import { color, log, run, listPlugins, claudeVersion } from "./utils.js";
-
-const PLUGINS_TO_UPDATE = [
-  "curdx-flow@curdx-flow-marketplace",
-  "pua@pua-skills",
-  "claude-mem@thedotmack",
-  "frontend-design@claude-plugins-official",
-];
+import {
+  PLUGINS_TO_UPDATE,
+  MARKETPLACES_TO_REFRESH,
+} from "./registry.js";
 
 export async function upgrade(args = []) {
   log.title("⬆️  CurDX-Flow upgrade");
@@ -19,10 +16,9 @@ export async function upgrade(args = []) {
     process.exit(1);
   }
 
-  // Refresh marketplaces first
+  // Refresh marketplaces first (derived from cli/registry.js)
   log.step(1, 2, "Refreshing marketplaces...");
-  const marketplaces = ["curdx-flow-marketplace", "pua", "thedotmack"];
-  for (const mp of marketplaces) {
+  for (const mp of MARKETPLACES_TO_REFRESH) {
     const r = await run(
       "claude",
       ["plugin", "marketplace", "update", mp],

package/cli/utils.js

@@ -108,39 +108,6 @@ export function confirm(message, defaultYes = true) {
   });
 }
 
-/**
- * Ask user to pick from a list. Returns selected value or null if aborted.
- */
-export function select(message, choices, defaultIndex = 0) {
-  return new Promise((resolve) => {
-    console.log(`${color.cyan("?")}  ${message}`);
-    choices.forEach((ch, i) => {
-      const marker = i === defaultIndex ? color.green("▸") : " ";
-      console.log(`   ${marker} ${color.bold(String(i + 1))}. ${ch.label}`);
-    });
-
-    const rl = createInterface({
-      input: process.stdin,
-      output: process.stdout,
-    });
-    rl.question(
-      `   ${color.dim(`(default: ${defaultIndex + 1}, q to abort) `)}`,
-      (ans) => {
-        rl.close();
-        const v = ans.trim().toLowerCase();
-        if (v === "q") return resolve(null);
-        if (v === "") return resolve(choices[defaultIndex].value);
-        const n = parseInt(v, 10);
-        if (Number.isInteger(n) && n >= 1 && n <= choices.length) {
-          return resolve(choices[n - 1].value);
-        }
-        console.log(color.yellow("  (invalid, using default)"));
-        resolve(choices[defaultIndex].value);
-      }
-    );
-  });
-}
-
 /**
  * Multi-select (checkbox-style via comma-separated input).
  * Returns array of selected values.
@@ -199,47 +166,124 @@ export function claudeVersion() {
   return m ? m[1] : res.stdout.trim().split("\n")[0];
 }
 
-/** List installed plugins via `claude plugin list`. Returns array of { name, version, status }. */
+/**
+ * List installed plugins. Prefers the structured `claude plugin list --json`
+ * output (stable machine-readable format; confirmed present in claude
+ * 2.1.117+). Falls back to parsing the human-readable stream-text output
+ * for older CLI versions, but warns that parser is brittle.
+ *
+ * Returns array of { name, version, status }.
+ */
 export function listPlugins() {
-  const res = runSync("claude", ["plugin", "list"]);
-  if (res.code !== 0) return [];
-  const out = res.stdout;
-  const plugins = [];
-  // Parse format like:
+  // Preferred: structured JSON output.
+  const j = runSync("claude", ["plugin", "list", "--json"]);
+  if (j.code === 0 && j.stdout.trim().startsWith("[")) {
+    try {
+      const arr = JSON.parse(j.stdout);
+      return arr.map((p) => ({
+        // id has form "name@marketplace" — name is stable for dedup/lookup.
+        name: String(p.id || "").split("@")[0],
+        version: p.version,
+        status: p.enabled === false ? "disabled" : "enabled",
+        raw: JSON.stringify(p),
+      }));
+    } catch {
+      // JSON parse failed — fall through to legacy text parser.
+    }
+  }
+
+  // Legacy fallback: parse the human-readable format.
   //   ❯ curdx-flow@curdx-flow-marketplace
   //     Version: 1.1.1
-  //     Scope: user
   //     Status: ✔ enabled
-  const blocks = out.split(/\n\s*❯\s*/).slice(1);
+  // Fragile — matches unicode markers. Kept only for older claude CLIs.
+  const res = runSync("claude", ["plugin", "list"]);
+  if (res.code !== 0) return [];
+  const plugins = [];
+  const blocks = res.stdout.split(/\n\s*❯\s*/).slice(1);
   for (const block of blocks) {
     const lines = block.split("\n");
     const name = lines[0].trim().split("@")[0];
     const version = (block.match(/Version:\s*(\S+)/) || [])[1];
-    const status = block.includes("✔") ? "enabled" : block.includes("✘") ? "failed" : "unknown";
+    const status = block.includes("✔")
+      ? "enabled"
+      : block.includes("✘")
+        ? "failed"
+        : "unknown";
     plugins.push({ name, version, status, raw: block });
   }
   return plugins;
 }
 
-/** List MCPs via `claude mcp list`. Returns array of { name, status }. */
+/**
+ * List MCP servers registered with the `claude` CLI. Returns array of
+ *   { name, plugin, fullName, status, command }
+ * where `plugin` is set when the MCP came from a plugin (real name is
+ * `plugin:<plugin>:<mcp>`), `name` is the trailing segment, and `fullName`
+ * is the original as reported by claude.
+ *
+ * Fixture captured from `claude mcp list` (2.1.117):
+ *   Checking MCP server health…
+ *
+ *   plugin:curdx-flow:context7: npx -y @upstash/context7-mcp@latest - ✓ Connected
+ *   context7: npx -y @upstash/context7-mcp --api-key ... - ✓ Connected
+ *   claude.ai Gmail: https://gmailmcp... - ✓ Connected
+ *
+ * `claude mcp list --json` does not exist on 2.1.117 (verified), so this
+ * parser is the primary path. It is fixture-tested in test/utils.test.js
+ * so format regressions get caught in CI.
+ */
 export function listMcps() {
   const res = runSync("claude", ["mcp", "list"]);
   if (res.code !== 0) return [];
-  const lines = res.stdout.split("\n");
+  return parseMcpList(res.stdout);
+}
+
+/** Exported for testing against a fixed input. */
+export function parseMcpList(output) {
   const mcps = [];
-  for (const line of lines) {
-    // Rough parse — adjust if format differs
-    const m = line.match(/^\s*([a-z0-9-]+)\s*[:\-]/i);
-    if (m) mcps.push({ name: m[1], status: "registered" });
+  for (const raw of output.split("\n")) {
+    const line = raw.trimEnd();
+    if (!line) continue;
+    // skip the health-check header line
+    if (line.startsWith("Checking") || line.startsWith("checking")) continue;
+    // Expected format: "<fullName>: <command-or-url> - <status>"
+    // fullName may itself contain colons when prefixed with "plugin:<p>:<m>".
+    // Match from the end to find the status sentinel " - ", then split off
+    // the name at the first ": " after the identifier prefix.
+    const statusSplit = line.lastIndexOf(" - ");
+    if (statusSplit === -1) continue;
+    const statusRaw = line.slice(statusSplit + 3).trim();
+    const beforeStatus = line.slice(0, statusSplit);
+    // Find the first ": " that separates name from command. Note the space
+    // after the colon — this disambiguates from the colons inside
+    // "plugin:foo:bar".
+    const nameSplit = beforeStatus.indexOf(": ");
+    if (nameSplit === -1) continue;
+    const fullName = beforeStatus.slice(0, nameSplit).trim();
+    const command = beforeStatus.slice(nameSplit + 2).trim();
+
+    let plugin = null;
+    let name = fullName;
+    if (fullName.startsWith("plugin:")) {
+      const parts = fullName.split(":");
+      if (parts.length >= 3) {
+        plugin = parts[1];
+        name = parts.slice(2).join(":");
+      }
+    }
+
+    const status = /Connected|✓/.test(statusRaw)
+      ? "connected"
+      : /Failed|✗/.test(statusRaw)
+        ? "failed"
+        : "unknown";
+
+    mcps.push({ name, plugin, fullName, status, command });
   }
   return mcps;
 }
 
-// ---------- Paths ----------
-export function pluginCacheDir(pluginName = "curdx-flow", marketplace = "curdx-flow-marketplace") {
-  return `${process.env.HOME}/.claude/plugins/cache/${marketplace}/${pluginName}`;
-}
-
 // ---------- Runtime PATH guards (bun / uv) ----------
 // claude-mem hard-codes `command: "bun"` in its .mcp.json, but bun installs to
 // ~/.bun/bin which is not on PATH when Claude Code spawns MCP servers
@@ -247,10 +291,14 @@ export function pluginCacheDir(pluginName = "curdx-flow", marketplace = "curdx-f
 // detection + self-healing: create a symlink to the user-level bun install
 // in a PATH-visible directory.
 
-import { mkdirSync, symlinkSync, lstatSync, unlinkSync, readlinkSync } from "node:fs";
-// `existsSync` and `join` already imported at the top of this file.
+import { existsSync, mkdirSync, symlinkSync, lstatSync, unlinkSync, readlinkSync } from "node:fs";
+import { homedir } from "node:os";
+// `join` already imported at the top of this file.
 
-const HOME = process.env.HOME || "";
+// os.homedir() is sourced from the OS-level user record and works even
+// when $HOME is empty (non-login shells, some CI containers). See the
+// same rationale in cli/protocols.js.
+const HOME = homedir();
 
 /** Candidate bun install locations (priority order) */
 const BUN_CANDIDATES = [

package/commands/debug.md

@@ -1,6 +1,6 @@
 ---
 name: debug
-description: Systematic debugging — 4-phase methodology (root cause → pattern → hypothesis → fix); ≥3 failures triggers architectural questioning. Dispatches flow-debugger (David).
+description: Systematic debugging — 4-phase methodology (root cause → pattern → hypothesis → fix); ≥3 failures triggers architectural questioning. Dispatches flow-debugger.
 argument-hint: "\"<bug description>\""
 allowed-tools: [Read, Write, Edit, Bash, Task, Grep, Glob]
 ---
@@ -9,7 +9,7 @@ allowed-tools: [Read, Write, Edit, Bash, Task, Grep, Glob]
 
 @${CLAUDE_PLUGIN_ROOT}/knowledge/systematic-debugging.md
 
-Dispatches the `flow-debugger` (David) agent to perform systematic 4-phase debugging.
+Dispatches the `flow-debugger` agent to perform systematic 4-phase debugging.
 
 ## When to use
 
@@ -21,7 +21,7 @@ Dispatches the `flow-debugger` (David) agent to perform systematic 4-phase debug
 ## When not to use
 
 - Still in coding phase → use the normal flow-executor flow
-- Question needs investigation → use /curdx-flow:spike
+- Question needs investigation → use `/curdx-flow:fast` with a prompt like "spike: verify X with minimal tests"
 - Performance issue needing benchmarks → performance tuning is not debug
 
 ## Step 1: Parse bug description
@@ -33,7 +33,7 @@ BUG_DESC="$ARGUMENTS"
 
 ## Step 2: Collect prerequisites (main agent, no dispatch)
 
-Before dispatching David, the main agent (you) collects first:
+Before dispatching the debugger, the main agent (you) collects first:
 
 ```bash
 # 1. Recent commit history (bug may be introduced by a new commit)
@@ -47,14 +47,14 @@ git diff --stat
 ACTIVE=$(cat .flow/.active-spec 2>/dev/null)
 ```
 
-## Step 3: Dispatch flow-debugger (David)
+## Step 3: Dispatch flow-debugger
 
 ```
 Task:
   subagent_type: general-purpose
   description: "Debug: $BUG_DESC"
   prompt: |
-    You are the flow-debugger agent (David). Full definition:
+    You are the flow-debugger agent. Full definition:
     ${CLAUDE_PLUGIN_ROOT}/agents/flow-debugger.md
     
     Methodology knowledge base:
@@ -150,7 +150,7 @@ Next steps:
 
 ## Special case: 3 failures
 
-If David reports 3 failures:
+If the debugger reports 3 failures:
 
 ```
 ⚠ Systematic debugging failed (3 attempts)
@@ -166,8 +166,8 @@ Possible root issues:
   - Data-layer issue
 
 Suggestions:
-  - Review David's detailed report analysis
-  - /curdx-flow:party winston david "what architectural issue does this bug hint at?"
+  - Review the debugger's detailed report analysis
+  - Ask Claude directly: "from an architect's and debugger's perspective, what architectural issue does this bug hint at?"
   - Or temporarily @ts-ignore / skip test and record as tech debt in STATE.md
 ```
 
@@ -175,7 +175,7 @@ Suggestions:
 
 - ✗ Omitting the bug description
 - ✗ Expecting "one-shot fix" (debug is a process, not an event)
-- ✗ Skipping David and editing code yourself (loses the systematic methodology)
+- ✗ Skipping the debugger and editing code yourself (loses the systematic methodology)
 - ✗ Accepting "maybe it's..." as a root cause
 
 ## Relationship to other commands

package/commands/fast.md

@@ -123,6 +123,6 @@ Choosing the right scenario matters more than forcing the flow.
 ## Forbidden
 
 - ✗ Committing without running verification
-- ✗ Changes touching more than 5 files (means it is no longer fast — run the full flow)
+- ✗ Changes touching many unrelated files or modules (means it is no longer fast — run the full flow)
 - ✗ Writing library APIs from memory
 - ✗ Skipping the Step 2 5-question clarification (even when "obvious," explicit statement still has value)

package/commands/help.md

@@ -1,119 +1,141 @@
 ---
 name: help
-description: CurDX-Flow help (command list, workflow overview, troubleshooting)
+description: Show CurDX-Flow command list, workflow overview, or troubleshooting guide. With a command name, show that command's detail.
 argument-hint: "[<command-name> | workflow | troubleshoot]"
-allowed-tools: [Read]
+allowed-tools: [Read, Bash]
 ---
 
 # CurDX-Flow Help
 
-## No Arguments — Quick Overview
+## No argument — quick overview
+
+Show the 9 core slash commands + 5 auto-invoked skills. Keep the table compact, use tabs for alignment.
 
 ```
-🚀 CurDX-Flow — AI Engineering Workflow Meta-Framework
-
-Current version: 0.1.0 (Phase 0 — Foundation)
-
-╔══════════════════════════════════════════════════════════════╗
-║ Command overview (Phase 0 implemented)                        ║
-╠══════════════════════════════════════════════════════════════╣
-║ /curdx-flow:init            Initialize .flow/ project structure     ║
-║ /curdx-flow:install-deps    One-shot install of recommended plugins ║
-║ /curdx-flow:doctor          Health check (deps + project config)    ║
-║ /curdx-flow:status          View spec and phase status              ║
-║ /curdx-flow:help            This help                               ║
-╚══════════════════════════════════════════════════════════════╝
-
-Coming soon (Phase 1+):
-  /curdx-flow:start / /curdx-flow:research / /curdx-flow:requirements / /curdx-flow:design
-  /curdx-flow:tasks / /curdx-flow:implement / /curdx-flow:verify / /curdx-flow:review
-  /curdx-flow:triage / /curdx-flow:party / /curdx-flow:debug / /curdx-flow:qa / /curdx-flow:sketch
-  /curdx-flow:ship / /curdx-flow:land / /curdx-flow:canary / /curdx-flow:retro ...
-
-Usage:
-  /curdx-flow:help <command>       View detailed usage for a command
-  /curdx-flow:help workflow        Introduce the full workflow
-  /curdx-flow:help troubleshoot    Common troubleshooting
+🚀 CurDX-Flow v2 — Claude Code Discipline Layer
+
+  9 slash commands (explicit control)
+  ────────────────────────────────────
+  /curdx-flow:init                  Initialize .flow/ in the current project
+  /curdx-flow:start                 Create / resume / switch a feature spec
+  /curdx-flow:spec                  Write or refresh the spec (--phase, --review, --regenerate)
+  /curdx-flow:implement             Execute the tasks (auto-routed strategy)
+  /curdx-flow:verify                Goal-backward verification — the differentiator
+  /curdx-flow:review                Two-stage code review (+ --adversarial, --edge-case)
+  /curdx-flow:fast                  Skip the spec — one-shot small task
+  /curdx-flow:debug                 Systematic 4-stage debugging
+  /curdx-flow:help                  This help
+
+  5 skills (auto-invoked by Claude based on context)
+  ────────────────────────────────────
+  epic                Decompose a large feature into vertical-slice sub-specs
+  browser-qa          Real-browser test via chrome-devtools MCP
+  ui-sketch           Generate UI design variants (via frontend-design skill)
+  security-audit      OWASP + STRIDE + CVE scan
+  brownfield-index    Map an unfamiliar / legacy codebase
+
+  3 MCP servers auto-installed
+  ────────────────────────────────────
+  context7                 Latest library docs
+  sequential-thinking      Structured reasoning
+  chrome-devtools          Browser automation
+
+  Usage:
+    /curdx-flow:help <command>    Detail for one command
+    /curdx-flow:help workflow     Standard workflow walkthrough
+    /curdx-flow:help troubleshoot Common problems
 ```
 
-## `<command-name>` — Command Details
+## `<command-name>` — command detail
 
-Based on the argument, read and display the corresponding command file (in a user-friendly format):
+When the argument matches one of the 9 commands, read the corresponding `commands/<name>.md` from the plugin cache and present it cleanly:
 
 ```bash
-cat "${CLAUDE_PLUGIN_ROOT}/commands/${COMMAND}.md"
+PLUGIN=$(ls -dt "$HOME/.claude/plugins/cache/curdx-flow-marketplace/curdx-flow/"*/ 2>/dev/null | head -1)
+CMD="$1"
+cat "$PLUGIN/commands/$CMD.md"
 ```
 
-## `workflow` — Workflow Overview
+If the argument isn't a known command, list the 9 candidates and the 5 skill names.
+
+## `workflow` — standard workflow
 
 ```
-📐 CurDX-Flow Standard Workflow
-
-1. Foundation (one-time)
-   └─ /curdx-flow:install-deps → /curdx-flow:init → /curdx-flow:doctor
-
-2. Per feature (Feature Workflow)
-   ├─ Research     /curdx-flow:research       (optional)
-   ├─ Requirements /curdx-flow:requirements   (required)
-   ├─ Design       /curdx-flow:design         (required)
-   ├─ Tasks        /curdx-flow:tasks          (required)
-   ├─ Execute      /curdx-flow:implement      (required)
-   ├─ Verify       /curdx-flow:verify         (required)
-   ├─ Review       /curdx-flow:review         (recommended)
-   └─ Ship         /curdx-flow:ship           (recommended)
-
-3. Large feature (Epic Workflow)
-   └─ /curdx-flow:triage → split into multiple specs advanced in parallel
-
-4. Ultra-fast path (Fast Path)
-   └─ /curdx-flow:fast "description"  — skip specs and execute directly
-
-5. Prototype exploration (Sketch Path)
-   └─ /curdx-flow:sketch "description" — UI design drafts
-
-Five modes (configured via .flow/config.json):
-  sketch      — Rapid prototyping
-  fast        — One-shot tasks
-  standard    — Regular features (default)
-  enterprise  — Full SDLC + multi-agent collaboration
-  autonomous  — Overnight automation
+📐 CurDX-Flow v2 Standard Workflow
+
+1. One-time setup (outside Claude Code)
+   └─ npx @curdx/flow install --all
+
+2. Per project (in Claude Code)
+   └─ /curdx-flow:init
+
+3. Per feature — the main loop
+   ├─ /curdx-flow:start my-feature "one-line goal"
+   ├─ /curdx-flow:spec                          ← research → requirements → design → tasks
+   ├─ (optional) /curdx-flow:spec --review      ← add multi-dim planning review
+   ├─ /curdx-flow:implement                     ← execute tasks
+   ├─ /curdx-flow:verify                        ← goal-backward check
+   └─ /curdx-flow:review                        ← code review
+
+4. Big feature (breaks into multiple specs)
+   └─ Say "this feature is too big, break it down" → epic skill auto-invokes
+
+5. One-off task (skip the spec)
+   └─ /curdx-flow:fast "rename foo to bar in src/"
+
+6. Stuck on a bug
+   └─ /curdx-flow:debug "tests fail intermittently after 3rd run"
+
+Modes (set via /curdx-flow:start --mode=...)
+  fast        One-off task paths
+  standard    Default — spec + gates + review
+  enterprise  Standard + adversarial + edge-case + security-audit
 ```
 
-## `troubleshoot` — Common Issues
+## `troubleshoot` — common issues
 
 ```
-🛠️ Common Troubleshooting
+🛠️  Common issues
+
+Q: After install, /curdx-flow:* commands are not found.
+A: Restart Claude Code. The plugin needs a fresh session to register.
+
+Q: MCP servers not starting?
+A: Check Node >= 18: node --version
+   Check MCPs:      claude mcp list
+   Health overall:  npx @curdx/flow doctor
+
+Q: GitHub slow / blocked during install?
+A: v1.1.5+ defaults to offline install (bundled plugin body).
+   Force-offline:  npx @curdx/flow install --no-deps
+   Force-online:   npx @curdx/flow install --online
 
-Q: 3 MCPs did not start?
-A: Check Node.js >= 18: `node --version`
-   View MCP status: `claude mcp list`
-   Restart Claude Code
+Q: claude-mem MCP keeps failing?
+A: It needs bun. Run: npx @curdx/flow doctor — it auto-symlinks bun if installed.
 
-Q: Recommended-plugins prompt keeps appearing?
-A: Run /curdx-flow:install-deps to install, or create the marker file manually:
-   touch "${CLAUDE_PLUGIN_DATA}/.deps-checked"
+Q: /curdx-flow:init says .flow/ already exists?
+A: Use --force, or run /curdx-flow:start directly to begin a new spec in the existing .flow/.
 
-Q: /curdx-flow:init reports "directory already exists"?
-A: An existing .flow/ is already initialized. Run /curdx-flow:status to view, or use --force to overwrite.
+Q: Skills don't auto-invoke reliably?
+A: Invoke explicitly — every skill also has a /skill-name slash. E.g., /curdx-flow:security-audit.
 
-Q: Agents do not call context7 / sequential-thinking?
-A: Make sure preamble.md is loaded (InstructionsLoaded hook).
-   Run /curdx-flow:doctor to check MCP status.
+Q: I want the old v1 commands (research, plan-ceo, party…).
+A: They're removed in v2. See MIGRATION.md for mappings, or stay on 1.x:
+   npm i -g @curdx/flow@^1.1
 
-Q: Do claude-mem and .flow/STATE.md conflict?
-A: No. claude-mem lives at ~/.claude-mem/ (SQLite), curdx-flow lives at .flow/ (JSON+MD).
-   Division of duties: claude-mem for automatic implicit memory, STATE.md for explicit decisions.
+Q: Too many gates blocking progress?
+A: Your spec mode decides gate strictness. Lower via:
+   /curdx-flow:start <name> "<goal>" --mode=fast
 
-Q: pua is too aggressive, can it be turned off?
-A: pua is an independent plugin, you can /plugin disable pua.
-   Enabling pua does not affect curdx-flow's core features (the three red lines are built into preamble).
+Q: Where are decisions logged?
+A: .flow/STATE.md (D-NN entries). Edit directly — no slash command needed.
 
-Q: Want to contribute / report a bug?
-A: https://github.com/wdx/curdx-flow/issues
+Q: File a bug / request feature
+A: https://github.com/curdx/curdx-flow/issues
 ```
 
-## Output Principles
+## Output principles
 
-- Stay concise; use tables and lists instead of long prose
-- Every answer points to a specific command; avoid filler like "please consult the docs"
-- Prioritize showing the user's next actionable step
+- Keep it compact. Use tables and lists, not prose.
+- Always point at a concrete next action, not "see the docs".
+- Version number should come from `cli/utils.js` dynamic read, not hard-coded.

package/commands/implement.md

@@ -15,7 +15,7 @@ Execute spec tasks per tasks.md. Select the best execution strategy based on arg
 ## Step 1: Preflight Checks
 
 ```bash
-[ ! -d ".flow" ] && { echo "❌ Not a CurDX-Flow project. Run /curdx-flow:init first"; exit 1; }
+[ ! -d ".flow" ] && { echo "✗ Not a CurDX-Flow project. Run /curdx-flow:init first"; exit 1; }
 
 ARGS="$ARGUMENTS"
 SPEC_NAME=""
@@ -35,10 +35,10 @@ for arg in $ARGS; do
 done
 
 [ -z "$SPEC_NAME" ] && SPEC_NAME=$(cat .flow/.active-spec 2>/dev/null)
-[ -z "$SPEC_NAME" ] && { echo "❌ No active spec. Run /curdx-flow:start first"; exit 1; }
+[ -z "$SPEC_NAME" ] && { echo "✗ No active spec. Run /curdx-flow:start first"; exit 1; }
 
 DIR=".flow/specs/$SPEC_NAME"
-[ ! -f "$DIR/tasks.md" ] && { echo "❌ Missing tasks.md. Run /curdx-flow:tasks first"; exit 1; }
+[ ! -f "$DIR/tasks.md" ] && { echo "✗ Missing tasks.md. Run /curdx-flow:spec first (or /curdx-flow:spec --phase=tasks to rebuild just the tasks phase)"; exit 1; }
 ```
 
 ## Step 2: Parse Task Characteristics from tasks.md
@@ -275,7 +275,7 @@ len(failed) == 1:
 
 len(failed) >= 2:
   → likely environment issue (missing deps/tsc error/permissions)
-  → stop immediately, suggest /curdx-flow:doctor
+  → stop immediately, suggest npx @curdx/flow doctor
   
 failed_attempts >= 3 (cumulative):
   → stop, user intervention required
@@ -330,7 +330,7 @@ Prerequisites:
 
 ## Step 6: Progress Feedback
 
-Every 5 tasks or every wave, print status:
+At each wave boundary (or periodically during long linear runs), print status:
 
 ```
 ═════ Progress ═════
@@ -357,10 +357,10 @@ if all tasks done:
 
 ## Error Recovery
 
-- Verify field in tasks.md is "manual" → stop, suggest re-running /curdx-flow:tasks to fix
+- Verify field in tasks.md is "manual" → stop, suggest re-running `/curdx-flow:spec --phase=tasks --regenerate` to fix
 - 3 consecutive TASK_FAILED → stop, prompt for user intervention
 - git operation failure → stop immediately, do not continue (avoid state corruption)
-- Test framework not found (npm test not found) → stop, suggest running /curdx-flow:doctor
+- Test framework not found (npm test not found) → stop, suggest running npx @curdx/flow doctor
 
 ## Output to User