@curdx/flow 2.2.4 → 2.2.5

package/skills/fast/references/execution-contract.md

@@ -0,0 +1,56 @@
+# Fast Execution Contract — Lookup, Verify, Commit
+
+## Lightweight Context
+
+```bash
+[ -f "CLAUDE.md" ] && cat CLAUDE.md | head -50
+[ -f ".flow/CONTEXT.md" ] && cat .flow/CONTEXT.md | head -30
+```
+
+Fast mode may run outside a `.flow/` project. Treat `.flow/CONTEXT.md` as
+optional.
+
+## Mandatory Tool Use
+
+1. If a library or API is involved: use Context7
+2. Use Grep/Glob to find the relevant code
+3. Read current files before editing
+4. Apply Karpathy's surgical principles
+5. Run validation commands before committing
+
+## Commit Requirement
+
+Even in fast mode, do not leave changes scattered:
+
+```bash
+git add <exact files>
+git commit -m "<type>(<scope>): <summary>"
+```
+
+The commit must conform to `atomic-commits.md`.
+
+## Output Shape
+
+```text
+✓ Fast execution complete
+
+Changes:
+  - src/foo.ts (+3 -1)
+  - src/foo.test.ts (+15)
+
+Verification:
+  npm test ✓
+  tsc --noEmit ✓
+
+Commit: abc123f — fix(foo): handle null case
+
+Consider the full flow next time?
+  /curdx-flow:start <name> "<goal>"
+```
+
+## Forbidden
+
+- committing without verification
+- letting the change sprawl across unrelated modules
+- writing library APIs from memory
+- skipping the clarification step

package/skills/help/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: help
-description: Show CurdX-Flow command list, workflow overview, or troubleshooting guide. With a command name, show that command's detail.
+description: Show command detail, workflow guidance, and troubleshooting.
 when_to_use: Use when the user asks how CurdX-Flow works, which command to run, what a workflow does, or how to troubleshoot common issues.
 argument-hint: "[<command-name> | workflow | troubleshoot]"
 disable-model-invocation: true
@@ -9,152 +9,46 @@ allowed-tools: [Read, Bash]
 
 # CurdX-Flow Help
 
-## No argument — quick overview
+Keep this skill focused on menuing and discovery. The canonical quick-overview,
+workflow, and troubleshooting payloads live in:
 
-Show the 11 core slash commands + 5 auto-invoked skills. Keep the table compact, use tabs for alignment.
+- `references/dispatch.md`
+- `references/overview.md`
+- `references/workflow.md`
+- `references/troubleshoot.md`
 
-```
-🚀 CurdX-Flow v2 — Claude Code Discipline Layer
-
-  11 slash commands (explicit control)
-  ────────────────────────────────────
-  /curdx-flow:init                  Initialize .flow/ in the current project
-  /curdx-flow:start                 Create / resume / switch a feature spec
-  /curdx-flow:status                Show active spec, phase, task progress, recovery hints
-  /curdx-flow:spec                  Write or refresh the spec (--phase, --review, --regenerate)
-  /curdx-flow:implement             Execute the tasks (auto-routed strategy)
-  /curdx-flow:cancel                Cancel execution loop safely; optional spec deletion
-  /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 detail
-
-When the argument matches a slash name — one of the 11 slash commands or one of the 5 auto-invoked skills — read the corresponding body and present it cleanly. The lookup tries the `skills/` layout first and falls back to the legacy `commands/` layout for older installed bundles:
-
-```bash
-CMD="$ARGUMENTS"
-[ -z "$CMD" ] && { echo "Usage: /curdx-flow:help <name>"; exit 1; }
-if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/${CMD}/SKILL.md" ]; then
-  cat "${CLAUDE_PLUGIN_ROOT}/skills/${CMD}/SKILL.md"
-elif [ -f "${CLAUDE_PLUGIN_ROOT}/commands/${CMD}.md" ]; then
-  cat "${CLAUDE_PLUGIN_ROOT}/commands/${CMD}.md"
-else
-  echo "Unknown: ${CMD}"
-  echo "Workflows: init start status spec implement cancel verify review fast debug help"
-  echo "Skills:    epic browser-qa ui-sketch security-audit brownfield-index"
-  exit 1
-fi
-```
-
-If the argument isn't a known slash name, the block above prints the 16 candidates.
+## No Argument — Quick Overview
 
-## `workflow` — standard workflow
+Render the compact command/skill/MCP summary from `references/overview.md`.
 
-```
-📐 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
+## `<command-name>` — Command Detail
 
-3. Per feature — the main loop
-   ├─ /curdx-flow:start my-feature "one-line goal"
-   ├─ /curdx-flow:status                        ← optional: see active spec + recovery hints
-   ├─ /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
+Plugin skills are namespaced. When guiding users toward specialty skills, refer
+to them as `/curdx-flow:<name>`, not bare `/name`. E.g., /curdx-flow:security-audit.
+Canonical specialty paths: /curdx-flow:epic, /curdx-flow:browser-qa,
+/curdx-flow:ui-sketch, /curdx-flow:security-audit, /curdx-flow:brownfield-index.
 
-4. Big feature (breaks into multiple specs)
-   └─ Say "this feature is too big, break it down" → epic skill auto-invokes
+Use `references/dispatch.md` for:
 
-5. One-off task (skip the spec)
-   └─ /curdx-flow:fast "rename foo to bar in src/"
+- `<command-name>` lookup against the shipped `skills/` layout
+- unknown-command fallback text
+- zero-argument usage guidance for detail mode
 
-6. Stuck on a bug
-   └─ /curdx-flow:debug "tests fail intermittently after 3rd run"
+The canonical shipped lookup path is:
 
-Modes (set via /curdx-flow:start --mode=...)
-  fast        One-off task paths
-  standard    Default — spec + gates + review
-  enterprise  Standard + adversarial + edge-case + security-audit
+```text
+${CLAUDE_PLUGIN_ROOT}/skills/${CMD}/SKILL.md
 ```
 
-## `troubleshoot` — common issues
-
-```
-🛠️  Common issues
+## `workflow` — Standard Workflow
 
-Q: After install, /curdx-flow:* commands are not found.
-A: Restart Claude Code. The plugin needs a fresh session to register.
+Render the standard workflow from `references/workflow.md`.
 
-Q: MCP servers not starting?
-A: Check Node >= 18: node --version
-   Check MCPs:      claude mcp list
-   Health overall:  npx @curdx/flow doctor
+## `troubleshoot` — Common Issues
 
-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: claude-mem MCP keeps failing?
-A: It needs bun. Run: npx @curdx/flow doctor
-   If doctor reports bun/uv is installed but not on PATH, run:
-   npx @curdx/flow doctor --fix
-
-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: Skills don't auto-invoke reliably?
-A: Invoke explicitly — plugin skills are namespaced. E.g., /curdx-flow:security-audit.
-
-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: Too many gates blocking progress?
-A: Your spec mode decides gate strictness. Lower via:
-   /curdx-flow:start <name> "<goal>" --mode=fast
-
-Q: Where are decisions logged?
-A: .flow/STATE.md (D-NN entries). Edit directly — no slash command needed.
-
-Q: Stop-hook or execution loop seems stuck?
-A: Run /curdx-flow:status. If state/tasks disagree, run /curdx-flow:cancel, then resume with:
-   /curdx-flow:implement --strategy=subagent
-
-Q: File a bug / request feature
-A: https://github.com/curdx/curdx-flow/issues
-```
+Render the troubleshooting guide from `references/troubleshoot.md`.
 
-## Output principles
+## Output Principles
 
 - Keep it compact. Use tables and lists, not prose.
 - Always point at a concrete next action, not "see the docs".

package/skills/help/references/dispatch.md

@@ -0,0 +1,20 @@
+# Help Dispatch — Command Detail Routing
+
+When `$ARGUMENTS` is a command or skill name, resolve it from the shipped
+plugin layout:
+
+```bash
+CMD="$ARGUMENTS"
+[ -z "$CMD" ] && { echo "Usage: /curdx-flow:help <name>"; exit 1; }
+if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/${CMD}/SKILL.md" ]; then
+  cat "${CLAUDE_PLUGIN_ROOT}/skills/${CMD}/SKILL.md"
+else
+  echo "Unknown: ${CMD}"
+  echo "Workflows: init start status spec implement cancel verify review fast debug help"
+  echo "Skills:    epic browser-qa ui-sketch security-audit brownfield-index"
+  exit 1
+fi
+```
+
+This lookup must stay inside `${CLAUDE_PLUGIN_ROOT}/skills/`. Do not fall back
+to any removed `commands/` layout or plugin-cache globbing.

package/skills/help/references/overview.md

@@ -0,0 +1,39 @@
+# Help Overview — Quick Surface Summary
+
+```text
+🚀 CurdX-Flow v2 — Claude Code Discipline Layer
+
+  11 slash commands (explicit control)
+  ────────────────────────────────────
+  /curdx-flow:init                  Initialize the .flow scaffold for the current repository.
+  /curdx-flow:start                 Create, resume, list, or switch the active feature spec.
+  /curdx-flow:status                Show active spec health, progress, artifacts, and recovery hints.
+  /curdx-flow:spec                  Generate or refresh research, requirements, design, and tasks for the active spec.
+  /curdx-flow:implement             Execute active-spec tasks with strategy routing and atomic progress.
+  /curdx-flow:cancel                Cancel the active execution loop or delete a spec with explicit confirmation.
+  /curdx-flow:verify                Verify the active spec against code, tests, and browser evidence.
+  /curdx-flow:review                Run two-stage review with optional adversarial, edge-case, and DevEx passes.
+  /curdx-flow:fast                  Execute a one-shot small task without creating a spec.
+  /curdx-flow:debug                 Debug a bug or failing test with the root-cause workflow.
+  /curdx-flow:help                  Show command detail, workflow guidance, and troubleshooting.
+
+  5 skills (auto-invoked by Claude based on context)
+  ────────────────────────────────────
+  /curdx-flow:epic                Decompose a large feature into vertical-slice sub-specs
+  /curdx-flow:browser-qa          Real-browser test via chrome-devtools MCP
+  /curdx-flow:ui-sketch           Generate UI design variants (via frontend-design skill)
+  /curdx-flow:security-audit      OWASP + STRIDE + CVE scan
+  /curdx-flow:brownfield-index    Map an unfamiliar / inherited 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
+    /curdx-flow:review --devex    Add the DevEx lens to review
+```

package/skills/help/references/troubleshoot.md

@@ -0,0 +1,47 @@
+# Help Troubleshoot — Common Issues
+
+```text
+🛠️  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: claude-mem MCP keeps failing?
+A: It needs bun. Run: npx @curdx/flow doctor
+   If doctor reports bun/uv is installed but not on PATH, run:
+   npx @curdx/flow doctor --fix
+
+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: Skills don't auto-invoke reliably?
+A: Invoke explicitly — plugin skills are namespaced. E.g., /curdx-flow:security-audit.
+
+Q: I want the old v1 commands (research, plan-ceo, party…).
+A: They're removed in v2. Use /curdx-flow:help workflow for the current paths, or stay on 1.x:
+   npm i -g @curdx/flow@^1.1
+
+Q: Too many gates blocking progress?
+A: Your spec mode decides gate strictness. Lower via:
+   /curdx-flow:start <name> "<goal>" --mode=fast
+
+Q: Where are decisions logged?
+A: .flow/STATE.md (D-NN entries). Edit directly — no slash command needed.
+
+Q: Stop-hook or execution loop seems stuck?
+A: Run /curdx-flow:status. If state/tasks disagree, run /curdx-flow:cancel, then resume with:
+   /curdx-flow:implement --strategy=subagent
+
+Q: File a bug / request feature
+A: https://github.com/curdx/curdx-flow/issues
+```

package/skills/help/references/workflow.md

@@ -0,0 +1,37 @@
+# Help Workflow — Canonical Main Loop
+
+```text
+📐 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:status                        ← optional: see active spec + recovery hints
+   ├─ /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. Evidence-backed handoff
+   └─ verification-report.md + review-report.md + atomic commits → human PR/release work
+
+5. Big feature (breaks into multiple specs)
+   └─ Say "this feature is too big, break it down" → epic skill auto-invokes
+
+6. One-off task (skip the spec)
+   └─ /curdx-flow:fast "rename foo to bar in src/"
+
+7. 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 + devex + security-audit
+```