@curdx/flow 2.2.4 → 2.3.0

package/skills/epic/SKILL.md

@@ -9,63 +9,31 @@ agent: flow-triage-analyst
 
 # Epic Decomposition
 
-You are invoked when the user wants to break a large feature into multiple vertical-slice specs.
+This is a specialty orchestration skill for multi-spec planning. Keep the
+entrypoint focused on when to use epic decomposition and what artifacts it must
+leave behind. Detailed rules live in:
 
-## Preconditions
-
-1. A `.flow/` project must exist (run `/curdx-flow:init` first if missing).
-2. The user has stated a feature scope that is too large for a single spec.
-
-## Workflow
-
-### Step 1: Clarify the epic scope
-
-Ask the user (or infer from context) for:
-- **Epic name** (short identifier, kebab-case)
-- **One-sentence goal** of the whole epic
-- **Hard boundary**: what is explicitly out of scope for this epic
-
-### Step 2: Run via `flow-triage-analyst`
+- `references/epic-intake.md`
+- `references/epic-artifacts.md`
+- `references/slice-handoff.md`
 
-This skill executes in a forked context through `flow-triage-analyst`. The agent returns:
-- A vertical-slice decomposition (not horizontal by layer)
-- Dependency graph between slices
-- Shared interfaces that must be frozen before parallel work begins
-- Suggested slice ordering (MVP → iteration → polish)
-
-### Step 3: Write epic manifest
-
-Create `.flow/_epics/<epic-name>/epic.md` with:
-
-```markdown
-# Epic: <name>
-
-## Goal
-<one sentence>
-
-## Slices (vertical)
-| ID | Slice | Depends on | Shared interface |
-|----|-------|-----------|------------------|
-| S1 | ...   | —          | —                |
-| S2 | ...   | S1         | `types/auth.ts`  |
-| S3 | ...   | S1         | —                |
+## Preconditions
 
-## Frozen Interfaces
-(contracts that must not change once slices start)
+- a `.flow/` project exists
+- the feature scope is too large for a single spec
 
-## Out of Scope
-- ...
-```
+## Intake
 
-### Step 4: Scaffold sub-spec skeletons
+Use `references/epic-intake.md` to confirm the epic boundary before dispatching
+`flow-triage-analyst`.
 
-For each slice, create `.flow/specs/<epic-name>-<slice-id>/` with a minimal `.state.json` linking back to the epic manifest.
+## Artifact Contract
 
-### Step 5: Report to user
+Use `references/epic-artifacts.md` for the required outputs:
 
-Summarize: "Epic `<name>` decomposed into N vertical slices. Start any slice with `/curdx-flow:start <epic-name>-<slice-id>`. Suggested order: S1 → S2 → S3."
+- `.flow/_epics/<epic-name>/epic.md`
+- one `.flow/specs/<epic-name>-<slice-id>/` skeleton per slice
 
-## References
+## Handoff
 
-- Vertical-slice methodology: `@${CLAUDE_PLUGIN_ROOT}/knowledge/epic-decomposition.md`
-- Spec skeleton: `@${CLAUDE_PLUGIN_ROOT}/templates/`
+User-facing next-step routing lives in `references/slice-handoff.md`.

package/skills/epic/references/epic-artifacts.md

@@ -0,0 +1,20 @@
+# Epic Artifacts — What Must Be Written
+
+`flow-triage-analyst` must return:
+
+- a vertical-slice decomposition
+- a dependency graph between slices
+- shared interfaces that should freeze before parallel work
+- suggested ordering: MVP -> iteration -> polish
+
+## Required Files
+
+- `.flow/_epics/<epic-name>/epic.md`
+- `.flow/specs/<epic-name>-<slice-id>/` skeletons with minimal `.state.json`
+
+`epic.md` should include:
+
+- goal
+- slice table
+- frozen interfaces
+- out-of-scope list

package/skills/epic/references/epic-intake.md

@@ -0,0 +1,9 @@
+# Epic Intake — Confirm the Scope Boundary
+
+Before decomposing, confirm:
+
+- epic name (short kebab-case identifier)
+- one-sentence goal
+- hard out-of-scope boundary
+
+This skill is for vertical-slice decomposition, not horizontal layer splitting.

package/skills/epic/references/slice-handoff.md

@@ -0,0 +1,16 @@
+# Epic Handoff — What the User Does Next
+
+Report:
+
+- epic name
+- slice count
+- suggested slice order
+
+Then route the user to a concrete slice:
+
+```text
+/curdx-flow:start <epic-name>-<slice-id>
+```
+
+Do not tell the user to use `/curdx-flow:start --resume <slice-id>`; slice
+selection is by explicit spec name.

package/skills/fast/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fast
-description: Ultra-fast execution — skip all spec phases and implement directly per the description. Suited for one-shot small tasks.
+description: Execute a one-shot small task without creating a spec.
 when_to_use: Use when the task is small, surgical, low-ambiguity, and not worth a full spec workflow.
 argument-hint: "\"<task description>\""
 disable-model-invocation: true
@@ -12,119 +12,51 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
 @${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md
 @${CLAUDE_PLUGIN_ROOT}/knowledge/atomic-commits.md
 
-**Fast Mode**: skip research / requirements / design / tasks, just do it.
+Fast is a bypass workflow, not a replacement for the main spec pipeline. Keep
+this entrypoint focused on scope gating, lightweight clarification, and the
+final execution contract. Detailed fast-mode rules live in:
 
-## Applicable Scenarios
+- `references/applicability.md`
+- `references/clarification.md`
+- `references/execution-contract.md`
 
-- ✓ One-shot scripts (e.g., "add a CLI command that prints the version number")
-- ✓ Clear small changes (e.g., "swap the deprecated API in foo.ts to bar")
-- ✓ Single-file modifications
-- ✓ Bug fixes (simple types)
+## Arguments
 
-## Not Applicable
-
-- ✗ Production feature development (run the full /curdx-flow:start → /curdx-flow:spec → /curdx-flow:implement)
-- ✗ Architecture-level changes spanning multiple files
-- ✗ User-story-driven requirements
-
-**Cost of using this command**: no spec files are left behind; nobody will know later why it was changed this way. If that cost is unacceptable, run the full flow.
-
-## Step 1: Parse Input
-
-```bash
-TASK_DESC="$ARGUMENTS"
-[ -z "$TASK_DESC" ] && { echo "Usage: /curdx-flow:fast \"task description\""; exit 1; }
-```
-
-## Step 2: 5-Question Quick Clarification (Karpathy Principle 1)
-
-Even in fast mode, do not skip thinking. Before executing, explicitly state:
+`$ARGUMENTS` must contain the one-shot task description. If it is empty, stop
+with the direct usage hint:
 
+```text
+/curdx-flow:fast "<task description>"
 ```
-Quick understanding (please confirm or amend):
 
-1. Task: <restate in your own words>
-2. Files involved: <preliminary assessment>
-3. Expected effect: <success criteria>
-4. Known constraints: <if any>
-5. Assumptions: <list explicitly>
+## Applicability
 
-Any ambiguity? (yes: amend then continue / no: proceed directly)
-```
+Use `references/applicability.md` to decide whether the task qualifies for the
+fast path.
 
-Use AskUserQuestion. If the user picks `no`, go straight to Step 3.
+- If the change is feature-sized, architecture-heavy, or requirement-driven,
+  route the user back to `/curdx-flow:start` -> `/curdx-flow:spec`
+- If the task stays surgical, continue with the fast contract
 
-## Step 3: Context Loading (Lightweight)
-
-```bash
-# Read project's CLAUDE.md (if any) and .flow/CONTEXT.md (if any)
-# but do not require a flow project — fast mode is allowed in any project
-[ -f "CLAUDE.md" ] && cat CLAUDE.md | head -50
-[ -f ".flow/CONTEXT.md" ] && cat .flow/CONTEXT.md | head -30
-```
-
-## Step 4: Explore + Execute
-
-**Mandatory tool use** (do not rely on training memory):
-
-```
-1. If library/API is involved: mcp__context7__query-docs
-2. Use Grep/Glob to find relevant code
-3. Read files to understand the current state
-4. Apply Karpathy's surgical principles
-5. Run validation commands (tsc/lint/test, per project)
-```
-
-## Step 5: Atomic Commit
-
-Even in fast mode, commit (do not leave changes scattered):
-
-```bash
-git add <exact files>
-git commit -m "<type>(<scope>): <summary>
-
-<body if any>
-"
-```
-
-The commit message must conform to `atomic-commits.md`.
-
-## Step 6: Output
-
-```
-✓ Fast execution complete
-
-Changes:
-  - src/foo.ts (+3 -1)
-  - src/foo.test.ts (+15)
-
-Verification:
-  npm test ✓ 12/12 passed
-  tsc --noEmit ✓
-
-Commit: abc123f — fix(foo): handle null case
-
-Consider the full flow next time?
-  /curdx-flow:start <name> "<goal>"  — if this type of task will recur
-```
+## Clarification
 
-## Downgrade Comparison
+Run the quick clarification flow from `references/clarification.md` before
+editing. This path still requires explicit assumptions; "obvious" tasks do not
+skip that step.
 
-Fast vs Standard:
+## Execution Contract
 
-| Dimension | Fast | Standard |
-|-----------|------|----------|
-| Time | 5-15 minutes | 1-4 hours |
-| Files | No spec residue | .flow/specs/<name>/*.md |
-| Traceability | git log only | git log + spec docs |
-| Quality | Relies on agent discipline | Multi-Gate enforced |
-| Suited for | Simple & known | Complex / team collaboration |
+Use `references/execution-contract.md` for:
 
-Choosing the right scenario matters more than forcing the flow.
+- lightweight context loading
+- mandatory code/doc lookup before edits
+- surgical execution rules
+- verification requirements
+- atomic commit and final output shape
 
-## Forbidden
+## Boundary
 
-- ✗ Committing without running verification
-- ✗ 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)
+- `fast` leaves no `.flow/specs/<name>/` audit trail
+- use it only when that traceability tradeoff is acceptable
+- if the work starts expanding, stop treating it as `fast` and switch to the
+  main workflow

package/skills/fast/references/applicability.md

@@ -0,0 +1,25 @@
+# Fast Applicability — When to Use and When to Abort
+
+## Good Fit
+
+- one-shot scripts
+- clear small changes
+- single-file or tightly bounded edits
+- simple bug fixes with low ambiguity
+
+## Not a Fit
+
+- production feature development
+- architecture-level or multi-module changes
+- user-story or acceptance-criteria driven work
+- anything that clearly needs spec artifacts for future traceability
+
+## Decision Rule
+
+If the task no longer looks surgical after initial exploration, stop calling it
+`fast` and route back to:
+
+```text
+/curdx-flow:start <name> "<goal>"
+/curdx-flow:spec
+```

package/skills/fast/references/clarification.md

@@ -0,0 +1,20 @@
+# Fast Clarification — Five Quick Questions
+
+Even in fast mode, do not skip explicit understanding.
+
+## Ask Before Editing
+
+```text
+Quick understanding (please confirm or amend):
+
+1. Task: <restate in your own words>
+2. Files involved: <preliminary assessment>
+3. Expected effect: <success criteria>
+4. Known constraints: <if any>
+5. Assumptions: <list explicitly>
+
+Any ambiguity? (yes: amend then continue / no: proceed directly)
+```
+
+Use `AskUserQuestion`. If the user confirms there is no ambiguity, continue
+directly to execution.

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
+```