@curdx/flow 2.2.4 → 2.2.5

package/skills/cancel/references/state-recovery.md

@@ -0,0 +1,30 @@
+# Cancel State Recovery — Safe Rollback Without Deletion
+
+Default mode preserves all human-readable artifacts.
+
+## Recovery Steps
+
+1. Read `.flow/specs/<target>/.state.json`
+2. Set `phase` to `tasks`
+3. Set `phase_status.execute` to `cancelled`
+4. Remove `execute_state` and `strategy`
+5. If the state file is missing, print `No execution state for <target>. Nothing to cancel.`
+
+Use checkpoint-tracked `Edit` or `Write`, not ad-hoc Bash or Python writers.
+
+## Progress Entry
+
+Append to `.progress.md`:
+
+```markdown
+## Execution Cancelled YYYY-MM-DD
+- Cancelled by: /curdx-flow:cancel
+- Preserved: research.md, requirements.md, design.md, tasks.md, progress, reports
+- Resume: /curdx-flow:implement --strategy=subagent or /curdx-flow:spec --phase=tasks --regenerate
+```
+
+## Safety
+
+- never delete project-level `.flow` files
+- if `.state.json` is corrupt, rename it to `.state.json.corrupt.<timestamp>`
+- prefer `/curdx-flow:status` after cancel to confirm recovery state

package/skills/cancel/references/target-resolution.md

@@ -0,0 +1,7 @@
+# Cancel Target Resolution — Positional Spec Name or Active Spec
+
+1. If `$ARGUMENTS` includes a positional spec name, target `.flow/specs/<name>`
+2. Otherwise read `.flow/.active-spec`
+3. If no target exists, print `No active spec to cancel` and stop
+
+`cancel` uses a positional spec argument, not `--spec=<name>`.

package/skills/debug/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debug
-description: Debug bugs, test failures, and flaky behavior with a 4-phase root-cause workflow. Routes to flow-debugger.
+description: Debug a bug or failing test with the root-cause workflow.
 when_to_use: Use when the user reports a bug, failing test, regression, stack trace, flaky behavior, or wants root-cause analysis instead of trial-and-error edits.
 argument-hint: "\"<bug description>\""
 disable-model-invocation: true
@@ -10,100 +10,36 @@ agent: flow-debugger
 
 # Systematic Debug
 
-Debug the bug described below using the 4-phase methodology in
-`@${CLAUDE_PLUGIN_ROOT}/knowledge/systematic-debugging.md`. This is NOT
-"retry until green" — each phase has a stop condition.
+Use the 4-phase root-cause methodology in
+`@${CLAUDE_PLUGIN_ROOT}/knowledge/systematic-debugging.md`. Keep this entrypoint
+focused on bug intake, required context, and the hard-stop contract. Detailed
+debugging rules live in:
 
-**Bug description**: `$ARGUMENTS`
+- `references/intake.md`
+- `references/context-gathering.md`
+- `references/phase-workflow.md`
+- `references/failure-guard.md`
+- `references/reporting.md`
 
-If `$ARGUMENTS` is empty, print `Usage: /curdx-flow:debug "<bug description>"` and stop.
+## Intake
 
-## Context to gather before diagnosing
+Use `references/intake.md` to validate `$ARGUMENTS` and anchor the debugging
+target before entering diagnosis.
 
-- Recent commits: `git log --oneline -20`
-- Uncommitted changes: `git status --short`, `git diff --stat`
-- Active spec (if any): read `.flow/.active-spec`; if set, read
-  `.flow/specs/<active>/.progress.md` for related history.
+## Pre-Diagnosis Context
 
-## Phase 1 — Root-cause investigation
+Gather the baseline context from `references/context-gathering.md` before
+entering Phase 1.
 
-- Read the error carefully (stack trace + message + location).
-- Build a minimal reproduction.
-- Append `## Reality Check (BEFORE)` to `.flow/specs/<active>/.progress.md` with the exact reproduction command, observed failure output, and timestamp before changing code.
-- Check recent changes that could have introduced the bug.
-- Trace the data flow from cause to symptom.
-- **Exit condition**: state the root cause in **one sentence**.
-  "maybe it's..." is not allowed.
+## Four Phases
 
-## Phase 2 — Pattern analysis
+Use `references/phase-workflow.md` as the 4-phase contract.
 
-- Find a working counter-example in the codebase (same path, different
-  input or neighboring module that behaves correctly).
-- Pinpoint the difference from the failing case.
-- Classify: **isolated case** (one location) vs. **systemic pattern**
-  (multiple siblings). If systemic, Phase 4 must sweep for siblings.
+## Three-Failure Guard
 
-## Phase 3 — Hypothesis and test
+Use `references/failure-guard.md` for the stop contract and required failure
+report.
 
-- State ONE hypothesis.
-- Write the smallest test that distinguishes confirm vs. disprove.
-- Run the test in-memory (do not commit yet).
-- If disproved, return to Phase 1 with the new signal.
+## Output to User
 
-## Phase 4 — Implement the fix
-
-1. Write a failing test; confirm it fails. Commit `test(<scope>): red - ...`.
-2. Fix the root cause (not the symptom). Confirm the failing test now
-   passes. Commit `fix(<scope>): green - ...`.
-3. Run the full regression suite; no regressions allowed.
-4. Re-run the original reproduction command and append `## Reality Check (AFTER)` to `.progress.md`; write `Verified: Issue resolved` only when BEFORE failed and AFTER passes or no longer shows the original failure.
-5. If Phase 2 classified as systemic, sweep for sibling occurrences and
-   fix them in the same stage. Optional third commit
-   `fix(<scope>): sweep - N similar cases`.
-
-## Three-failure guard (hard stop)
-
-If Phase 4 has tried 3 genuinely different approaches and all failed,
-**stop**. Do not try a 4th. Output the structured failure report:
-
-```
-⚠ Systematic debug halted after 3 attempts
-
-Attempts:
-  1. <approach 1>: <why it failed>
-  2. <approach 2>: <why it failed>
-  3. <approach 3>: <why it failed>
-
-Root-issue hypothesis: architecture | dependency | data | unknown
-Recommended next step: <user action — review architecture, ship a
-                       STATE.md D-NN deferral with @ts-expect-error,
-                       or request pairing>
-```
-
-## Forbidden
-
-- Prayer-driven programming (retry without a new hypothesis each round)
-- "Maybe it's ..." as a Phase 1 conclusion
-- A fix commit without a corresponding failing-test commit
-- A fix claim without BEFORE/AFTER reality verification in `.progress.md`
-- Masking the root cause with null checks / try-catch
-- Fixing multiple unrelated things in one commit (one task = one commit)
-
-## Output to user (on success, ≤ 15 lines)
-
-```
-✓ Debug complete
-
-Root cause: <Phase 1 — one sentence>
-Pattern:    <Phase 2 — isolated or systemic>
-
-Fix commits:
-  - <sha>: test(<scope>): red - failing test
-  - <sha>: fix(<scope>): green - root-cause fix
-  - <sha>: fix(<scope>): sweep - N sibling cases    (if systemic)
-
-Verification: failing test now PASS ✓; full suite green ✓
-
-Learnings (candidate for .progress.md):
-  - <lesson>
-```
+Use `references/reporting.md` for the compact completion summary.

package/skills/debug/references/context-gathering.md

@@ -0,0 +1,11 @@
+# Debug Context Gathering — Baseline Before Diagnosis
+
+Gather these before diagnosing:
+
+- recent commits: `git log --oneline -20`
+- uncommitted changes: `git status --short`, `git diff --stat`
+- active spec, if any:
+  - read `.flow/.active-spec`
+  - if set, read `.flow/specs/<active>/.progress.md`
+
+The point is to debug against observed repo state, not assumptions.

package/skills/debug/references/failure-guard.md

@@ -0,0 +1,25 @@
+# Debug Failure Guard — Stop After Three Real Attempts
+
+If Phase 4 has tried three genuinely different approaches and all failed, stop.
+Do not try a fourth.
+
+## Required Failure Report
+
+```text
+⚠ Systematic debug halted after 3 attempts
+
+Attempts:
+  1. <approach 1>: <why it failed>
+  2. <approach 2>: <why it failed>
+  3. <approach 3>: <why it failed>
+
+Root-issue hypothesis: architecture | dependency | data | unknown
+Recommended next step: <user action>
+```
+
+## Forbidden
+
+- prayer-driven retries
+- "maybe it's..." as a Phase 1 conclusion
+- green fix commits without a corresponding red test commit
+- fix claims without BEFORE/AFTER reality evidence

package/skills/debug/references/intake.md

@@ -0,0 +1,12 @@
+# Debug Intake — Require a Concrete Bug Target
+
+The debug target is `$ARGUMENTS`.
+
+If `$ARGUMENTS` is empty, print:
+
+```text
+Usage: /curdx-flow:debug "<bug description>"
+```
+
+Do not begin diagnosis until the failing behavior, test, or regression target is
+concrete enough to reproduce.

package/skills/debug/references/phase-workflow.md

@@ -0,0 +1,34 @@
+# Debug Phases — Root Cause, Pattern, Hypothesis, Fix
+
+## Phase 1 — Root-Cause Investigation
+
+- read the error carefully
+- build a minimal reproduction
+- append `Reality Check (BEFORE)` to `.progress.md` when a spec is active
+- trace recent changes and data flow
+- exit only when the root cause fits in one sentence
+
+## Phase 2 — Pattern Analysis
+
+- find a working counter-example nearby
+- identify the difference from the failing case
+- classify the issue as `isolated` or `systemic`
+
+If systemic, Phase 4 must sweep sibling cases.
+
+## Phase 3 — Hypothesis and Test
+
+- state one hypothesis
+- write the smallest distinguishing test
+- run it before committing
+- if disproved, return to Phase 1 with the new signal
+
+## Phase 4 — Implement the Fix
+
+1. write a failing test and confirm it fails
+2. fix the root cause and confirm the test now passes
+3. run the full regression suite
+4. re-run the original reproduction command and append `Reality Check (AFTER)`
+5. if systemic, sweep sibling occurrences in the same stage
+
+Do not mask the issue with defensive noise that leaves the root cause intact.

package/skills/debug/references/reporting.md

@@ -0,0 +1,20 @@
+# Debug Reporting — Compact Root-Cause Closeout
+
+End with:
+
+```text
+✓ Debug complete
+
+Root cause: <Phase 1 — one sentence>
+Pattern:    <Phase 2 — isolated or systemic>
+
+Fix commits:
+  - <sha>: test(<scope>): red - failing test
+  - <sha>: fix(<scope>): green - root-cause fix
+  - <sha>: fix(<scope>): sweep - N sibling cases    (if systemic)
+
+Verification: failing test now PASS ✓; full suite green ✓
+```
+
+Keep the closeout evidence-first. The root cause and verification outcome
+matter more than narrative.

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.