@curdx/flow 2.0.0-beta.9 → 2.0.0

package/cli/utils.js

@@ -1,13 +1,13 @@
 /**
  * Shared utilities for curdx-flow CLI.
- * Zero npm deps — only Node built-ins.
  */
 
 import { spawn, spawnSync } from "node:child_process";
 import { createInterface } from "node:readline";
-import { readFileSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, symlinkSync, lstatSync, unlinkSync, readlinkSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
+import { homedir } from "node:os";
 
 // Read version dynamically from package.json so `curdx-flow --version` always
 // reflects the installed package version (avoids drift after npm version bumps).
@@ -88,7 +88,154 @@ export function has(cmd) {
   return res.code === 0 && res.stdout.trim().length > 0;
 }
 
-// ---------- Interactive prompts (readline, no deps) ----------
+// ---------- @clack/prompts wrappers ----------
+let _clack = null;
+
+/**
+ * Lazy-load @clack/prompts (ESM module)
+ */
+async function getClack() {
+  if (!_clack) {
+    _clack = await import("@clack/prompts");
+  }
+  return _clack;
+}
+
+/**
+ * Handle user cancellation gracefully
+ */
+async function handleCancel(value, message = "Operation cancelled") {
+  const clack = await getClack();
+  if (clack.isCancel(value)) {
+    clack.cancel(message);
+    process.exit(0);
+  }
+  return false;
+}
+
+/**
+ * Single-select prompt with arrow key navigation
+ * @param {Object} options
+ * @param {string} options.message - Question to ask
+ * @param {Array} options.options - Array of {value, label, hint?}
+ * @param {any} [options.initialValue] - Default selected value
+ * @returns {Promise<any>} Selected value
+ */
+export async function select(options) {
+  const clack = await getClack();
+  const result = await clack.select({
+    message: options.message,
+    options: options.options,
+    initialValue: options.initialValue,
+  });
+  await handleCancel(result);
+  return result;
+}
+
+/**
+ * Multi-select prompt with checkboxes (arrow keys + space to toggle)
+ * @param {Object} options
+ * @param {string} options.message - Question to ask
+ * @param {Array} options.options - Array of {value, label, hint?}
+ * @param {Array} [options.initialValues] - Default selected values
+ * @param {boolean} [options.required] - Whether at least one must be selected
+ * @returns {Promise<Array>} Array of selected values
+ */
+export async function multiselectClack(options) {
+  const clack = await getClack();
+  const result = await clack.multiselect({
+    message: options.message,
+    options: options.options,
+    initialValues: options.initialValues || [],
+    required: options.required !== undefined ? options.required : false,
+  });
+  await handleCancel(result);
+  return result;
+}
+
+/**
+ * Text input prompt with validation
+ * @param {Object} options
+ * @param {string} options.message - Question to ask
+ * @param {string} [options.placeholder] - Placeholder text
+ * @param {string} [options.defaultValue] - Default value
+ * @param {Function} [options.validate] - Validation function (return string for error, undefined for success)
+ * @returns {Promise<string>} User input
+ */
+export async function text(options) {
+  const clack = await getClack();
+  const result = await clack.text({
+    message: options.message,
+    placeholder: options.placeholder,
+    defaultValue: options.defaultValue,
+    validate: options.validate,
+  });
+  await handleCancel(result);
+  return result;
+}
+
+/**
+ * Spinner for async operations
+ * @returns {Promise<Object>} Spinner controller
+ */
+export async function spinner() {
+  const clack = await getClack();
+  return clack.spinner();
+}
+
+/**
+ * Display intro message
+ */
+export async function intro(message) {
+  const clack = await getClack();
+  clack.intro(message);
+}
+
+/**
+ * Display outro message
+ */
+export async function outro(message) {
+  const clack = await getClack();
+  clack.outro(message);
+}
+
+/**
+ * Display a note/info box
+ */
+export async function note(message, title) {
+  const clack = await getClack();
+  clack.note(message, title);
+}
+
+// ---------- Config file helpers ----------
+const CONFIG_DIR = join(homedir(), ".claude");
+const CONFIG_FILE = join(CONFIG_DIR, "curdx-flow-config.json");
+
+/**
+ * Read curdx-flow config from ~/.claude/curdx-flow-config.json
+ */
+export function readConfig() {
+  if (!existsSync(CONFIG_FILE)) {
+    return {};
+  }
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Write curdx-flow config to ~/.claude/curdx-flow-config.json
+ */
+export function writeConfig(config) {
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8");
+}
+
+// ---------- Interactive prompts (readline, legacy) ----------
 /**
  * Ask user a yes/no question. Default applies on empty input.
  */
@@ -108,39 +255,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 +313,190 @@ 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 { id, name, marketplaceId, version, status, scope }.
+ */
 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.
+        id: String(p.id || ""),
+        name: String(p.id || "").split("@")[0],
+        marketplaceId: String(p.id || "").split("@")[1] || undefined,
+        version: p.version,
+        status: p.enabled === false ? "disabled" : "enabled",
+        scope: p.scope,
+        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 id = lines[0].trim();
+    const name = id.split("@")[0];
     const version = (block.match(/Version:\s*(\S+)/) || [])[1];
-    const status = block.includes("✔") ? "enabled" : block.includes("✘") ? "failed" : "unknown";
-    plugins.push({ name, version, status, raw: block });
+    const status = block.includes("✔")
+      ? "enabled"
+      : block.includes("✘")
+        ? "failed"
+        : "unknown";
+    plugins.push({ id, name, marketplaceId: id.split("@")[1], version, status, raw: block });
   }
   return plugins;
 }
 
-/** List MCPs via `claude mcp list`. Returns array of { name, status }. */
+/**
+ * List configured Claude Code plugin marketplaces.
+ * Returns array of { name, source, repo, path } when `--json` is supported.
+ */
+export function listPluginMarketplaces() {
+  const j = runSync("claude", ["plugin", "marketplace", "list", "--json"]);
+  if (j.code === 0 && j.stdout.trim().startsWith("[")) {
+    try {
+      return JSON.parse(j.stdout);
+    } catch {
+      return [];
+    }
+  }
+  return [];
+}
+
+/**
+ * Read the user-level MCP registrations from ~/.claude.json. These are the
+ * MCPs the user added manually via `claude mcp add …` — distinct from
+ * plugin-bundled MCPs (which live in plugin.json).
+ *
+ * Returns a Map keyed by server name with the raw config object. Returns
+ * an empty Map if the file is missing / unreadable / has no mcpServers
+ * section — all of which are normal states and not errors.
+ */
+export function readUserMcpConfig() {
+  try {
+    const path = join(HOME, ".claude.json");
+    if (!existsSync(path)) return new Map();
+    const cfg = JSON.parse(readFileSync(path, "utf-8"));
+    const servers = cfg?.mcpServers || {};
+    return new Map(Object.entries(servers));
+  } catch {
+    return new Map();
+  }
+}
+
+/**
+ * Given the output of listMcps() and a user-level MCP config map, find
+ * MCPs that are registered BOTH as user-level AND as plugin-bundled.
+ * The plugin-bundled form shows up as `plugin:<plugin>:<name>` in
+ * listMcps output, so a user-level "context7" and a plugin-level
+ * "plugin:curdx-flow:context7" are a duplicate pair.
+ *
+ * Returns array of { name, userConfig, pluginEntry }.
+ */
+export function findDuplicateMcps(mcps, userConfig) {
+  const duplicates = [];
+  for (const m of mcps) {
+    // Only look at plugin-prefixed entries — they're the reference for
+    // what's bundled. Check if user has their own non-prefixed version.
+    if (m.plugin && userConfig.has(m.name)) {
+      duplicates.push({
+        name: m.name,
+        userConfig: userConfig.get(m.name),
+        pluginEntry: m,
+      });
+    }
+  }
+  return duplicates;
+}
+
+/**
+ * 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 +504,13 @@ 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 { existsSync, mkdirSync, symlinkSync, lstatSync, unlinkSync, readlinkSync } from "node:fs";
-// `join` already imported at the top of this file.
+// Note: existsSync, mkdirSync, symlinkSync, lstatSync, unlinkSync, readlinkSync, homedir, join
+// are 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/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:spec first (or /curdx-flow:spec --phase=tasks to rebuild just the tasks phase)"; 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

package/commands/init.md

@@ -71,9 +71,20 @@ Append (if not already present):
 
 ### Step 5: Health Check
 
-Run `npx @curdx/flow doctor` (or inline its checks) to verify:
-- 2 bundled MCPs started (context7 / sequential-thinking)
-- Recommended plugins status (pua / claude-mem / frontend-design / chrome-devtools-mcp)
+Do NOT shell out to a new terminal for this step — you are already inside
+Claude Code. Verify inline via the information the plugin already has:
+
+- Read `~/.claude/plugins/data/curdx-flow/.deps-checked` (optional — the
+  SessionStart hook already refreshes this once per day).
+- If the user asks for the full report, suggest they run
+  `npx @curdx/flow doctor` in a separate terminal — don't try to spawn
+  it from inside the Claude Code session (output won't render cleanly
+  and the user has to alt-tab to see it).
+
+Items the CLI doctor covers (for user reference):
+- 2 bundled MCPs (context7 / sequential-thinking) — visible in `claude mcp list`
+- 4 recommended plugins (pua / claude-mem / frontend-design / chrome-devtools-mcp)
+- Runtime PATH guards for `bun` / `uv` (relevant only when claude-mem is installed)
 
 ### Step 6: Prompt Next Steps
 

package/commands/start.md

@@ -32,18 +32,40 @@ Entry point for every feature. Works in four modes depending on flags and existi
 
 ## Flag parsing
 
-```bash
-FLAG_RESUME=$(echo "$ARGUMENTS" | grep -q -- '--resume' && echo 1 || echo 0)
-FLAG_LIST=$(echo "$ARGUMENTS" | grep -q -- '--list' && echo 1 || echo 0)
-FLAG_MODE=$(echo "$ARGUMENTS" | grep -oP -- '--mode=\K[^\s]+' || echo "standard")
-
-# Strip flags from ARGUMENTS to leave the positional args
-POS=$(echo "$ARGUMENTS" | sed -E 's/--[a-z-]+(=[^ ]+)?//g' | xargs)
-SPEC_NAME=$(echo "$POS" | awk '{print $1}')
-GOAL=$(echo "$POS" | awk '{$1=""; print $0}' | sed 's/^"//; s/"$//' | xargs)
-```
-
-Mode must be `fast`, `standard`, or `enterprise`. Invalid → default to `standard` with a warning.
+**Do not shell-split `$ARGUMENTS`.** It is a user-supplied string that may
+contain quoted substrings with spaces, `$`-signs, or embedded quotes.
+`xargs`, naive `awk`, and `sed`-based quote stripping all mis-parse at
+least one of those cases (e.g. `my-feature "Fix user's login bug"` breaks
+`xargs: unmatched quote`). Parse the string as a model task instead:
+
+1. **Flags** (order-independent, each is self-delimited):
+   - `--resume` / `--list` — boolean presence
+   - `--mode=<fast|standard|enterprise>` — value after `=`
+   Detect each with a single regex over the full `$ARGUMENTS` string and
+   remove the matched span from your working copy. Flags not in the list
+   above are errors — surface them to the user.
+
+2. **Positional args** (after flags removed):
+   - First whitespace-separated token → `SPEC_NAME` (kebab-case `[a-z0-9-]+`).
+   - Remainder of the string, trimmed and with one layer of outer `"..."`
+     or `'...'` quotes stripped → `GOAL`. Preserve inner quotes as-is.
+
+3. If `SPEC_NAME` does not match `^[a-z0-9][a-z0-9-]*$` (per
+   `schemas/spec-state.schema.json`), stop and ask the user to pick a
+   valid kebab-case name.
+
+Mode must be `fast`, `standard`, or `enterprise`. Invalid → default to
+`standard` with a warning.
+
+Example inputs and their parse:
+
+| `$ARGUMENTS`                                    | SPEC_NAME    | GOAL                          | flags         |
+|-------------------------------------------------|--------------|-------------------------------|---------------|
+| `my-feature "Add JWT auth"`                     | `my-feature` | `Add JWT auth`                | —             |
+| `my-feature --mode=fast "Add JWT auth"`         | `my-feature` | `Add JWT auth`                | mode=fast     |
+| `my-feature "Fix user's login bug"`             | `my-feature` | `Fix user's login bug`        | —             |
+| `--list`                                        | —            | —                             | list=true     |
+| `--resume`                                      | —            | —                             | resume=true   |
 
 ## Branch logic
 

package/hooks/hooks.json

@@ -8,10 +8,9 @@
             "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/session-start.sh"
           }
         ]
-      }
-    ],
-    "InstructionsLoaded": [
+      },
       {
+        "matcher": "startup|clear|compact",
         "hooks": [
           {
             "type": "command",

package/hooks/scripts/inject-karpathy.sh

@@ -1,10 +1,13 @@
 #!/usr/bin/env bash
-# CurDX-Flow InstructionsLoaded Hook
+# CurDX-Flow SessionStart baseline injection
 # Injects the L1 baseline (Karpathy 4 principles + mandatory tool rules + 3 red lines)
-# into every session after CLAUDE.md is loaded.
+# as additionalContext at every session boot (startup, /clear, post-compact).
 #
-# This is what makes the baseline "always on" — it doesn't rely on CLAUDE.md being
-# present in every project, and it survives context compaction.
+# Wired under SessionStart rather than InstructionsLoaded because Claude Code's
+# InstructionsLoaded event is observability-only — its hook schema rejects
+# hookSpecificOutput / additionalContext. SessionStart with matcher
+# "startup|clear|compact" gives the same "baseline is always on, even after
+# compaction" property while staying within the supported schema.
 
 set -u
 
@@ -46,7 +49,7 @@ CONTEXT='## CurDX-Flow Mind Baseline (L1 — always on)
 # Emit JSON with safe encoding
 if command -v python3 >/dev/null 2>&1; then
   ESCAPED="$(printf '%s' "$CONTEXT" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')"
-  printf '{"hookSpecificOutput":{"hookEventName":"InstructionsLoaded","additionalContext":%s}}\n' "$ESCAPED"
+  printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":%s}}\n' "$ESCAPED"
 fi
 
 exit 0

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@curdx/flow",
-  "version": "2.0.0-beta.9",
+  "version": "2.0.0",
   "description": "CLI installer for CurDX-Flow — AI engineering workflow meta-framework for Claude Code",
   "type": "module",
   "bin": {
-    "flow": "bin/curdx-flow.js",
     "curdx-flow": "bin/curdx-flow.js"
   },
   "scripts": {
-    "prepublishOnly": "node bin/curdx-flow.js --version"
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "node --test test/*.test.js && node bin/curdx-flow.js --version"
   },
   "files": [
     "bin/",
@@ -44,5 +44,9 @@
     "installer",
     "ai-engineering",
     "curdx-flow"
-  ]
+  ],
+  "dependencies": {
+    "@clack/prompts": "^0.8.2",
+    "picocolors": "^1.1.1"
+  }
 }

package/skills/brownfield-index/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brownfield-index
-description: Invoke when the user is new to an unfamiliar / legacy / brownfield codebase and wants a structural understanding — module map, component inventory, API surface, data flow. Triggers on "legacy code", "brownfield", "unfamiliar", "new to this code", "new to this project", "just joined", "inherited codebase", "explore codebase", "understand structure", "index code", "map modules", "tour", "onboard", "what is this project", "老代码", "棕地", "不熟悉", "新接手", "新项目", "代码探索", "结构理解", "索引", "模块地图", "先了解下", "先熟悉一下".
+description: Invoke when the user is new to an unfamiliar / legacy / brownfield codebase and wants a structural understanding — module map, component inventory, API surface, data flow. Triggers on "legacy code", "brownfield", "unfamiliar", "new to this code", "new to this project", "just joined", "inherited codebase", "explore codebase", "understand structure", "index code", "map modules", "tour", "onboard", "what is this project".
 allowed-tools: [Read, Grep, Glob, Bash]
 ---
 

package/skills/browser-qa/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: browser-qa
-description: Invoke when the user wants to test a UI/frontend in a real browser — accessibility, performance, console errors, network traffic, visual regression. Triggers on "browser test", "test in browser", "UI test", "e2e test", "frontend test", "accessibility", "a11y", "WCAG", "lighthouse", "performance audit", "console error", "network request", "cross-browser", "responsive", "mobile test", "visual regression", "screenshot", "浏览器测试", "UI 测试", "可访问性", "性能", "控制台错误", "截图", "移动端", "兼容性", "在浏览器里跑", "看看 console".
+description: Invoke when the user wants to test a UI/frontend in a real browser — accessibility, performance, console errors, network traffic, visual regression. Triggers on "browser test", "test in browser", "UI test", "e2e test", "frontend test", "accessibility", "a11y", "WCAG", "lighthouse", "performance audit", "console error", "network request", "cross-browser", "responsive", "mobile test", "visual regression", "screenshot".
 allowed-tools: [Read, Write, Bash, Grep, Glob, WebFetch]
 ---
 

package/skills/epic/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: epic
-description: Invoke when user wants to break a large feature into multiple smaller specs with a dependency graph. Triggers on "epic", "big feature", "too big", "decompose", "break down", "break into", "split into", "multi-spec", "multiple features", "sub-features", "vertical slice", "parent feature", "large scope", "大功能", "太大", "拆分", "拆解", "分解", "多个规格", "子功能", "垂直切片", "史诗级", "分几个做", "一个 sprint 做不完", "需要拆".
+description: Invoke when user wants to break a large feature into multiple smaller specs with a dependency graph. Triggers on "epic", "big feature", "too big", "decompose", "break down", "break into", "split into", "multi-spec", "multiple features", "sub-features", "vertical slice", "parent feature", "large scope", "won't fit in one sprint", "needs splitting".
 allowed-tools: [Read, Write, Grep, Glob, Bash]
 ---
 

package/skills/security-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: security-audit
-description: Invoke when the user wants a security review — OWASP Top 10, STRIDE threat modeling, credential handling, injection, secrets, sensitive data handling. Triggers on "security", "auth", "authentication", "credential", "password", "secret", "API key", "token", "OWASP", "STRIDE", "CVE", "vulnerability", "injection", "XSS", "CSRF", "SSRF", "SQL injection", "hardcoded secret", "sensitive data", "leak", "安全", "认证", "凭证", "密码", "密钥", "令牌", "漏洞", "注入", "硬编码", "敏感数据", "泄露", "API key 会不会泄", "有没有安全问题".
+description: Invoke when the user wants a security review — OWASP Top 10, STRIDE threat modeling, credential handling, injection, secrets, sensitive data handling. Triggers on "security", "auth", "authentication", "credential", "password", "secret", "API key", "token", "OWASP", "STRIDE", "CVE", "vulnerability", "injection", "XSS", "CSRF", "SSRF", "SQL injection", "hardcoded secret", "sensitive data", "leak", "will my API key leak", "is this safe".
 allowed-tools: [Read, Grep, Glob, Bash, WebSearch]
 ---