@curdx/flow 7.1.17 → 7.1.19

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to `@curdx/flow` are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/) and the project follows [Semantic Versioning](https://semver.org/).
 
+## 7.1.19 — 2026-05-11
+
+### Added
+
+- **Third-party capability graph for smart routing.** New `hooks/scripts/lib/tool-capabilities.mjs` maps installed companion capabilities (`claude-mem`, `context7`, `sequential-thinking`, `chrome-devtools-mcp`, `frontend-design`, and `pua`) to concrete AI-facing triggers, phases, skip rules, and invocations.
+- **Capability recommendations in `smart-route`.** Route output now includes `recommendedCapabilities` so `/curdx-flow:start` can choose docs lookup, memory search, UI design, browser verification, structured reasoning, or retry tooling from goal/topology facts without forcing every task through every tool.
+
+### Changed
+
+- **Global CLAUDE.md guidance is generated from the capability graph.** The managed block now emits concise installed-tool routing rules and a decision tree instead of hand-maintained duplicated plugin/MCP prose.
+- **Start workflow stores tool hints with spec state.** New specs can persist compact `recommendedCapabilities` next to `projectTopology`, and the state schema/reference docs now declare both fields so later phases can reuse the original routing context without re-deriving it.
+
+### Tests
+
+- Added capability-router unit coverage, smart-route capability filtering checks, CLAUDE.md rendering regression coverage, and claudecc smoke assertions for empty direct-change hints and frontend/browser/docs recommendations.
+
+## 7.1.18 — 2026-05-11
+
+### Added
+
+- **Dev-context project topology detection.** New `hooks/scripts/lib/project-topology.mjs` reads short `CLAUDE.md` Dev sections, optional `.claude/curdx-flow.local.md` `code_roots`, cheap manifests, and obvious sibling repo names to classify roots such as Vue/React frontends, Spring Boot/Spring Cloud backends, shared libraries, CLIs, infra, and Claude Code plugins.
+- **Topology-aware smart routing.** `/curdx-flow:start` now blocks early when a goal needs a related code root outside current Claude Code access and returns an exact `/add-dir <path>` fix instead of asking users to understand `--add-dir`.
+- **Topology cache guidance for indexing.** `/curdx-flow:index` now generates `specs/.index/project-topology.json` and `specs/.index/context-map.md` before component scanning, and stops with the access fix when related roots are missing.
+
+### Changed
+
+- **Settings and start guidance now favor user-friendly Dev context.** The settings template documents the recommended minimal `CLAUDE.md` form (`frontend`, `backend`, `database`) while keeping structured `code_roots` as an optional advanced override.
+- **Sensitive local-service data is omitted from topology output.** Database and credential-looking lines in Dev context produce only a generic warning; real passwords, tokens, and production URLs are not copied into topology JSON or context maps.
+
+### Tests
+
+- Added split-repo topology tests for Vue/React frontends, Spring Boot/Spring Cloud backends, missing frontend access, configured `additionalDirectories`, context-map redaction, and the bundled `project-topology` CLI.
+
 ## 7.1.17 — 2026-05-11
 
 ### Added

package/dist/index.mjs

@@ -845,6 +845,261 @@ import { promises as fs2 } from "fs";
 import path4 from "path";
 import os2 from "os";
 import * as p4 from "@clack/prompts";
+
+// src/hooks/lib/tool-capabilities.ts
+import { basename } from "path";
+import { fileURLToPath } from "url";
+var CAPABILITIES = {
+  "context7": {
+    id: "context7",
+    name: "Context7",
+    type: "mcp",
+    invocation: "Context7 MCP",
+    summary: "current official docs for libraries, SDKs, APIs, and Claude Code",
+    useWhen: "use the Context7 MCP before implementation when external library, SDK, API, framework, or Claude Code behavior matters.",
+    skipWhen: "Skip for pure local logic, typos, and code paths fully understood from this repository."
+  },
+  "claude-mem": {
+    id: "claude-mem",
+    name: "claude-mem",
+    type: "plugin",
+    invocation: "/claude-mem:mem-search",
+    summary: "cross-session memory search and phased plan/execution commands",
+    useWhen: "Use /claude-mem:mem-search when similar work, prior decisions, or repeated failures may exist; use /claude-mem:make-plan only for genuinely phased work.",
+    skipWhen: "Skip when the task is new, obvious, and smaller than a short local edit."
+  },
+  "sequential-thinking": {
+    id: "sequential-thinking",
+    name: "sequential-thinking",
+    type: "mcp",
+    invocation: "sequential-thinking MCP",
+    summary: "structured hypothesis breakdown for hard architecture and debugging problems",
+    useWhen: "Use for architecture tradeoffs, migrations, security/data/release risk, or debugging where assumptions may change.",
+    skipWhen: "Skip for direct edits, simple lookups, and deterministic fixes."
+  },
+  "chrome-devtools-mcp": {
+    id: "chrome-devtools-mcp",
+    name: "Chrome DevTools MCP",
+    type: "plugin",
+    invocation: "Chrome DevTools MCP",
+    summary: "real browser console, network, DOM, performance, and screenshot/snapshot verification",
+    useWhen: "Use for browser runtime behavior, UI regressions, DOM/CSS issues, network failures, and frontend verification.",
+    skipWhen: "Skip for backend-only code with no browser-facing behavior."
+  },
+  "frontend-design": {
+    id: "frontend-design",
+    name: "frontend-design",
+    type: "plugin",
+    invocation: "frontend-design plugin skills",
+    summary: "frontend UX/design guidance for UI pages, components, and interaction polish",
+    useWhen: "Use when building or changing visible UI, interaction design, frontend layout, or visual quality.",
+    skipWhen: "Skip for backend-only changes, copy-only edits, and internal CLI/library work."
+  },
+  "pua": {
+    id: "pua",
+    name: "pua",
+    type: "plugin",
+    invocation: "/pua:pua-loop or /pua:p9",
+    summary: "structured retries and parallel task decomposition",
+    useWhen: "Use after multiple failed attempts or for truly independent parallel work slices.",
+    skipWhen: "Skip on first-attempt failures, known fixes, and work that is sequential by dependency."
+  }
+};
+var ORDER = [
+  "context7",
+  "claude-mem",
+  "frontend-design",
+  "chrome-devtools-mcp",
+  "sequential-thinking",
+  "pua"
+];
+var DOCS_RE = /\b(api|sdk|library|libraries|framework|docs?|documentation|version|upgrade|dependency|dependencies|claude code|plugin|mcp|hook|hooks|skill|skills|agent|agents|react|vue|spring|spring boot|spring cloud|next\.?js|vite|webpack|npm|node)\b|最新|文档|依赖|框架|插件|官方|联网|搜索/i;
+var MEMORY_RE = /\b(previous|before|again|remember|memory|history|similar|repeated|regression|already solved|same bug|past decision)\b|之前|上次|记得|历史|做过|又|重复|老问题/i;
+var UI_RE = /\b(ui|ux|frontend|front-end|browser|chrome|dom|css|html|layout|component|page|form|modal|responsive|visual|render|react|vue|vite|next\.?js|screenshot|interaction)\b|前端|页面|浏览器|样式|交互|组件|布局|视觉|截图/i;
+var BROWSER_VERIFY_RE = /\b(browser|chrome|dom|css|network|console|performance|render|screenshot|e2e|playwright|visual regression|interaction)\b|浏览器|控制台|网络|性能|渲染|截图|端到端/i;
+var COMPLEX_RE = /\b(architecture|architect|migration|migrate|security|auth|authentication|authorization|permission|oauth|payment|billing|database|schema|release|publish|npm|tag|hook|subagent|multi[- ]?repo|monorepo|cross[- ]?system|concurrency|race|cache|rewrite|refactor)\b|架构|迁移|安全|权限|认证|数据库|发布|重写|并发|跨仓库|多仓库/i;
+var STUCK_RE = /\b(stuck|failed|failure|fails|flaky|retry|debug|investigate|root cause|not working|broken|regression)\b|卡住|失败|报错|不行|修不好|定位|排查/i;
+var PARALLEL_RE = /\b(parallel|multi-agent|team|decompose|split|epic|multiple subsystems|large refactor)\b|并行|多智能体|拆分|史诗|多模块/i;
+var LOW_RISK_LOCAL_RE = /\b(typo|readme|docs?|comment|comments|copy|wording|rename label|format text)\b|错别字|注释|文案/i;
+function normalize(input) {
+  return (input ?? "").trim().replace(/\s+/g, " ");
+}
+function hasAny(values, candidates) {
+  const set = new Set((values ?? []).map((v) => v.toLowerCase()));
+  return candidates.some((candidate) => set.has(candidate.toLowerCase()));
+}
+function capabilityAllowed(id, available) {
+  return available === null || available.has(id);
+}
+function pushRecommendation(out, available, id, phase, reason, instruction) {
+  if (!capabilityAllowed(id, available)) return;
+  if (out.some((rec) => rec.id === id)) return;
+  const cap = CAPABILITIES[id];
+  out.push({
+    id,
+    name: cap.name,
+    type: cap.type,
+    invocation: cap.invocation,
+    phase,
+    reason,
+    instruction
+  });
+}
+function sortRecommendations(recs) {
+  return [...recs].sort((a, b) => ORDER.indexOf(a.id) - ORDER.indexOf(b.id));
+}
+function recommendToolCapabilities(input) {
+  const goal = normalize(input.goal);
+  const route = normalize(input.route);
+  const risk = normalize(input.risk);
+  const topologyKinds = input.topologyKinds ?? [];
+  const topologyFrameworks = input.topologyFrameworks ?? [];
+  const missingRoots = input.missingRoots ?? 0;
+  const available = input.availableCapabilities === void 0 ? null : new Set(input.availableCapabilities.filter(Boolean));
+  const recs = [];
+  if (missingRoots > 0) {
+    return recs;
+  }
+  const localLowRisk = LOW_RISK_LOCAL_RE.test(goal) && route === "direct-change";
+  if (localLowRisk) {
+    return recs;
+  }
+  const hasFrontend = UI_RE.test(goal) || hasAny(topologyKinds, ["frontend-app"]) || hasAny(topologyFrameworks, ["react", "vue", "next.js", "vite"]);
+  const browserRuntime = BROWSER_VERIFY_RE.test(goal) || hasFrontend;
+  const complex = COMPLEX_RE.test(goal) || risk === "high" || risk === "critical" || route === "full-spec" || route === "epic-split";
+  const stuck = STUCK_RE.test(goal);
+  const parallel = PARALLEL_RE.test(goal) || route === "epic-split";
+  if (DOCS_RE.test(goal)) {
+    pushRecommendation(
+      recs,
+      available,
+      "context7",
+      "before-coding",
+      "external documentation or current API behavior is likely relevant",
+      "Use Context7 before editing so version-specific behavior is grounded in current docs."
+    );
+  }
+  if (MEMORY_RE.test(goal) || stuck || route === "full-spec" || route === "epic-split") {
+    pushRecommendation(
+      recs,
+      available,
+      "claude-mem",
+      "planning",
+      "similar prior work or longer-running plan may exist",
+      "Search memory before planning; use make-plan only when the work is genuinely phased."
+    );
+  }
+  if (hasFrontend) {
+    pushRecommendation(
+      recs,
+      available,
+      "frontend-design",
+      "implementation",
+      "visible frontend behavior or UI quality is in scope",
+      "Use frontend-design guidance for UI structure, interaction, responsive behavior, and visual polish."
+    );
+  }
+  if (browserRuntime) {
+    pushRecommendation(
+      recs,
+      available,
+      "chrome-devtools-mcp",
+      "verification",
+      "browser runtime behavior should be verified in a real browser",
+      "Use Chrome DevTools MCP for console, network, DOM, performance, or visual proof after implementation."
+    );
+  }
+  if (complex || stuck) {
+    pushRecommendation(
+      recs,
+      available,
+      "sequential-thinking",
+      "planning",
+      "risk or uncertainty requires explicit hypothesis management",
+      "Use sequential-thinking to break assumptions before choosing the implementation path."
+    );
+  }
+  if (stuck || parallel) {
+    pushRecommendation(
+      recs,
+      available,
+      "pua",
+      stuck ? "recovery" : "planning",
+      stuck ? "the goal indicates repeated failure or debugging difficulty" : "large work may contain independent parallel slices",
+      stuck ? "Use /pua:pua-loop only after local triage confirms the first fix path is not working." : "Use /pua:p9 only after dependencies prove the slices can run independently."
+    );
+  }
+  return sortRecommendations(recs);
+}
+function renderInstalledCapabilityRules(availableCapabilities) {
+  const available = new Set(availableCapabilities);
+  const lines = [
+    "Use installed capabilities by trigger, not by habit. Prefer the first matching rule; skip absent capabilities."
+  ];
+  for (const id of ORDER) {
+    if (!available.has(id)) continue;
+    const cap = CAPABILITIES[id];
+    lines.push(`- ${cap.invocation}: ${cap.useWhen} ${cap.skipWhen}`);
+  }
+  return lines;
+}
+function renderCapabilityDecisionTree(availableCapabilities) {
+  const available = new Set(availableCapabilities);
+  const lines = [
+    "1. Can the edit be finished safely from local code in 1-2 steps? -> Do it directly."
+  ];
+  if (available.has("context7")) {
+    lines.push("2. Does correctness depend on external docs, SDKs, APIs, or Claude Code behavior? -> use the Context7 MCP before editing.");
+  }
+  if (available.has("claude-mem")) {
+    lines.push("3. Might similar work, a prior decision, or a repeated failure exist? -> Start with `/claude-mem:mem-search`.");
+  }
+  if (available.has("frontend-design") || available.has("chrome-devtools-mcp")) {
+    lines.push("4. Is visible frontend behavior in scope? -> Use frontend-design for UI decisions and Chrome DevTools MCP for runtime proof when installed.");
+  }
+  if (available.has("sequential-thinking")) {
+    lines.push("5. Is the work high-risk, architectural, or assumption-heavy? -> Use sequential-thinking after reading the relevant code.");
+  }
+  if (available.has("pua")) {
+    lines.push("6. Are there multiple failed attempts or truly independent parallel slices? -> Use `/pua:pua-loop` for recovery or `/pua:p9` for bounded parallel planning.");
+  }
+  return lines;
+}
+function parseList(value) {
+  if (!value) return [];
+  return value.split(/[,;\n]/).map((s) => s.trim()).filter(Boolean);
+}
+function readArg(name, argv2) {
+  const idx = argv2.indexOf(name);
+  if (idx === -1) return void 0;
+  return argv2[idx + 1];
+}
+function main() {
+  const argv2 = process.argv.slice(2);
+  const recommendations = recommendToolCapabilities({
+    goal: readArg("--goal", argv2),
+    route: readArg("--route", argv2),
+    risk: readArg("--risk", argv2),
+    topologyKinds: parseList(readArg("--topology-kinds", argv2)),
+    topologyFrameworks: parseList(readArg("--topology-frameworks", argv2)),
+    missingRoots: Number(readArg("--missing-roots", argv2) ?? 0),
+    availableCapabilities: readArg("--available-capabilities", argv2) ? parseList(readArg("--available-capabilities", argv2)) : void 0
+  });
+  process.stdout.write(JSON.stringify(recommendations, null, 2) + "\n");
+}
+function isDirectRun() {
+  try {
+    const entry = fileURLToPath(import.meta.url);
+    return process.argv[1] === entry && basename(entry).startsWith("tool-capabilities.");
+  } catch {
+    return false;
+  }
+}
+if (isDirectRun()) {
+  main();
+}
+
+// src/runner/claudeMd.ts
 var BEGIN_MARKER = "<!-- BEGIN @curdx/flow v1 -->";
 var END_MARKER = "<!-- END @curdx/flow v1 -->";
 var BLOCK_RE = /<!-- BEGIN @curdx\/flow v\d+[^>]*-->[\s\S]*?<!-- END @curdx\/flow v\d+ -->/;
@@ -852,63 +1107,11 @@ function claudeMdPath() {
   return path4.join(os2.homedir(), ".claude", "CLAUDE.md");
 }
 function buildCombinationPatterns(ids) {
-  const has = (k) => ids.has(k);
-  const out = [
-    "Combine tools by capability. Keep slash commands, MCP tools, and plugin skills distinct.",
-    ""
-  ];
-  if (has("context7") || has("curdx-flow") || has("claude-mem")) {
-    out.push("- **Starting a new feature**");
-    let step = 1;
-    if (has("context7")) {
-      out.push(`  ${step++}. If external libraries, SDKs, frameworks, or APIs are involved, use the Context7 MCP to pull current official docs.`);
-    }
-    const planners = [];
-    if (has("claude-mem")) planners.push("`/claude-mem:make-plan` for a phased plan");
-    if (has("curdx-flow")) planners.push("`/curdx-flow:new` or the spec flow for a full specification");
-    if (planners.length > 0) {
-      out.push(`  ${step++}. Only move into ${planners.join(" or ")} when the work is multi-step, cross-cutting, or uncertain.`);
-    }
-    out.push(`  ${step++}. For small, clear one-shot changes, implement directly instead of forcing the full workflow.`);
-    out.push("");
-  }
-  const stuckLines = [];
-  let s = 1;
-  if (has("chrome-devtools-mcp")) {
-    stuckLines.push(`  ${s++}. For browser-side issues, use the Chrome DevTools MCP for network, console, performance, and DOM snapshots.`);
-  }
-  if (has("context7")) {
-    stuckLines.push(`  ${s++}. If the issue may come from library or API behavior, use the Context7 MCP instead of relying on memory.`);
-  }
-  const stillStuck = [];
-  if (has("sequential-thinking")) stillStuck.push("switch to the sequential-thinking MCP to break down hypotheses");
-  if (has("pua")) stillStuck.push("enter `/pua:pua-loop` for structured retries");
-  if (stillStuck.length > 0) {
-    stuckLines.push(`  ${s++}. If you are still stuck after multiple attempts, ${stillStuck.join(" or ")}.`);
-  }
-  if (stuckLines.length > 0) {
-    out.push("- **Debugging and repeated failures**", ...stuckLines, "");
-  }
-  if (has("frontend-design") || has("chrome-devtools-mcp")) {
-    out.push("- **UI and frontend work**");
-    if (has("frontend-design")) {
-      out.push("  - Prioritize the `frontend-design` plugin skills for UI work; if they do not trigger automatically, invoke the relevant skill explicitly.");
-    }
-    if (has("chrome-devtools-mcp")) {
-      out.push("  - For rendering issues, interaction bugs, or visual regressions, verify with the Chrome DevTools MCP instead of relying on visual guesswork alone.");
-    }
-    out.push("");
+  const out = renderInstalledCapabilityRules([...ids]);
+  if (ids.has("curdx-flow")) {
+    out.push("- /curdx-flow:start: Use for ambiguous, cross-cutting, phase-based, or multi-root work; skip for small direct edits.");
+    out.push("- /curdx-flow:triage: Use when one request is too large for a single coherent spec.");
   }
-  if (has("pua") || has("curdx-flow")) {
-    out.push("- **Large, cross-cutting, or multi-agent work**");
-    if (has("pua")) {
-      out.push("  - Use `/pua:p9` for parallel task decomposition and team coordination; reserve `/pua:p10` for higher-level strategy work.");
-    }
-    if (has("curdx-flow")) {
-      out.push("  - Use `/curdx-flow:triage` when one large feature needs to be split into multiple dependent specs.");
-    }
-  }
-  while (out.length > 0 && out[out.length - 1] === "") out.pop();
   return out;
 }
 function buildSkipRules(ids) {
@@ -928,18 +1131,9 @@ function buildSkipRules(ids) {
   return out;
 }
 function buildDecisionTree(ids) {
-  const has = (k) => ids.has(k);
-  const out = [];
-  out.push("1. Can it be finished in 1-2 steps? -> Do it directly.");
-  out.push("2. Is it multi-step but still clear? -> Break it into a short task list and execute without defaulting to the full spec flow.");
-  const planners = [];
-  if (has("curdx-flow")) planners.push("`/curdx-flow:new`");
-  if (has("claude-mem")) planners.push("`/claude-mem:make-plan`");
-  if (planners.length > 0) {
-    out.push(`3. Is the request ambiguous, cross-cutting, or phase-based? -> ${planners.join(" or ")}.`);
-  }
-  if (has("claude-mem")) {
-    out.push("4. Might this work have been done before? -> Start with `/claude-mem:mem-search`.");
+  const out = renderCapabilityDecisionTree([...ids]);
+  if (ids.has("curdx-flow")) {
+    out.push("7. Is the request ambiguous, cross-cutting, phase-based, or multi-root? -> Run /curdx-flow:start.");
   }
   return out;
 }
@@ -1677,8 +1871,8 @@ var analyze_default = analyzeCmd;
 // src/runner/buildFreshness.ts
 import { readdirSync, statSync, existsSync as existsSync3 } from "fs";
 import path5 from "path";
-import { fileURLToPath } from "url";
-var SELF_PATH = fileURLToPath(import.meta.url);
+import { fileURLToPath as fileURLToPath2 } from "url";
+var SELF_PATH = fileURLToPath2(import.meta.url);
 var RUNNER_DIR = path5.dirname(SELF_PATH);
 var PROJECT_ROOT = path5.resolve(RUNNER_DIR, "..", "..");
 var SRC_DIR = path5.join(PROJECT_ROOT, "src");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@curdx/flow",
-  "version": "7.1.17",
+  "version": "7.1.19",
   "description": "Interactive installer for Claude Code plugins and MCP servers",
   "type": "module",
   "bin": "./dist/index.mjs",