@curdx/flow 2.2.3 → 2.2.5

package/skills/browser-qa/SKILL.md

@@ -15,45 +15,25 @@ paths:
 
 # Browser QA
 
-You are invoked when the user wants real-browser QA of a UI flow.
+This skill orchestrates real-browser validation, not a generic UI review. Keep
+the entrypoint focused on prerequisites, QA artifact requirements, and the
+handoff after findings. Detailed rules live in:
 
-## Preconditions
-
-1. `chrome-devtools` MCP is available (`mcp__chrome_devtools__*`). If missing, fall back to a manual checklist.
-2. A URL (dev server or deployed) is available. Prompt for it if not provided.
-
-## Workflow
-
-### Step 1: Clarify scope
+- `references/prerequisites.md`
+- `references/qa-contract.md`
+- `references/handoff.md`
 
-Confirm with the user:
-- **URL under test** (local `http://localhost:3000` or remote)
-- **Flow to test** (e.g., "sign up → dashboard → logout")
-- **What success looks like** (accessibility / performance / zero console errors / visual match)
-
-### Step 2: Run via `flow-qa-engineer`
-
-This skill executes in a forked context through `flow-qa-engineer`. The agent will:
-1. Open the target URL via `mcp__chrome_devtools__new_page`
-2. Drive the flow with `mcp__chrome_devtools__click` / `fill` / `navigate_page`
-3. Capture `list_console_messages`, `list_network_requests`, `take_screenshot`, optionally `lighthouse_audit`
-4. Compare against expected behavior
-
-### Step 3: Report findings
+## Preconditions
 
-Produce `.flow/specs/<active>/qa-report.md` with:
-- **Bugs** (reproducible, severity P1/P2/P3)
-- **Performance** (LCP / INP / CLS from Lighthouse)
-- **Accessibility** (axe violations with WCAG references)
-- **Console errors** (full stack traces)
-- **Screenshots** (attached)
+Use `references/prerequisites.md` to confirm browser MCP availability and the
+URL or flow under test. Real browser execution in this skill depends on
+`mcp__chrome_devtools__*`.
 
-### Step 4: Hand off
+## QA Contract
 
-If bugs found: suggest `/curdx-flow:debug "<bug title>"` for systematic root-cause analysis.
-If accessibility violations: suggest fixes inline with WCAG refs.
+`flow-qa-engineer` should execute the browser workflow in
+`references/qa-contract.md`.
 
-## References
+## Handoff
 
-- `flow-qa-engineer` agent: `@${CLAUDE_PLUGIN_ROOT}/agents/flow-qa-engineer.md`
-- chrome-devtools MCP docs: https://github.com/ChromeDevTools/chrome-devtools-mcp
+Post-QA routing and bug follow-up live in `references/handoff.md`.

package/skills/browser-qa/references/handoff.md

@@ -0,0 +1,6 @@
+# Browser QA Handoff — Where Findings Go Next
+
+- if reproducible bugs are found -> `/curdx-flow:debug "<bug title>"`
+- if accessibility issues are found -> report concrete WCAG-linked fixes
+- if the flow is clean -> hand off `qa-report.md` as additional evidence, not a
+  replacement for `verify` or `review`

package/skills/browser-qa/references/prerequisites.md

@@ -0,0 +1,10 @@
+# Browser QA Prerequisites — Browser and URL Required
+
+Before dispatching:
+
+- confirm `mcp__chrome_devtools__*` is available
+- confirm a URL under test exists
+- confirm the flow and success criteria
+
+If browser MCP is missing, fall back to a manual checklist rather than
+pretending a real-browser run happened.

package/skills/browser-qa/references/qa-contract.md

@@ -0,0 +1,20 @@
+# Browser QA Contract — What the QA Agent Must Do
+
+`flow-qa-engineer` should:
+
+1. open the target URL
+2. drive the flow in a real browser
+3. collect console, network, screenshot, and optional Lighthouse evidence
+4. compare observed behavior to expected behavior
+
+## Required Artifacts
+
+- `.flow/specs/<active>/qa-report.md`
+- `.flow/specs/<active>/qa-screenshots/`
+
+The report should include:
+
+- bugs by severity
+- performance metrics
+- accessibility findings
+- console errors

package/skills/cancel/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cancel
-description: Stop the active CurDX-Flow execution loop safely. Optional --delete-spec --yes removes the spec directory.
+description: Cancel the active execution loop or delete a spec with explicit confirmation.
 when_to_use: Use when the user wants to stop the current execution loop, abort a stuck run, or delete the active spec intentionally.
 argument-hint: "[spec-name] [--delete-spec --yes]"
 disable-model-invocation: true
@@ -9,74 +9,33 @@ allowed-tools: [Read, Bash]
 
 # CurdX-Flow Cancel
 
-Safely stop an active execution loop. Default behavior is non-destructive: preserve spec files, tasks, progress, and artifacts.
+`cancel` is a recovery control, not an execution path. Keep this entrypoint
+focused on target selection, destructive-mode gating, and the final recovery
+message. Detailed cancel rules live in:
 
-## Target Resolution
-
-1. If `$ARGUMENTS` includes a spec name, use `.flow/specs/<name>`.
-2. Otherwise read `.flow/.active-spec`.
-3. If no target exists, print `No active spec to cancel` and stop.
-
-## Default: Cancel Execution Loop Only
-
-Default mode removes stop-hook/subagent execution state while preserving all human-readable artifacts:
-
-1. Read `.flow/specs/<target>/.state.json`.
-2. Use `Edit` or `Write` to 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.` and stop.
-
-Do not rewrite `.state.json` with a Bash heredoc or ad-hoc Python writer; use checkpoint-tracked `Edit`/`Write` operations.
-
-Append to `.progress.md`:
+- `references/target-resolution.md`
+- `references/state-recovery.md`
+- `references/destructive-mode.md`
+- `references/reporting.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
-```
+## Target Resolution
 
-## Destructive Mode
+Use `references/target-resolution.md` to resolve the target spec.
 
-Only delete the spec directory when both flags are present:
+## Default Behavior
 
-```bash
-/curdx-flow:cancel <spec-name> --delete-spec --yes
-```
+Default mode is non-destructive. Use `references/state-recovery.md` to:
 
-If `--delete-spec` is present without `--yes`, do not delete. Print the exact command required.
+- roll execution state back safely
+- preserve spec artifacts and reports
+- append a recovery note to `.progress.md`
+- recommend the best resume command
 
-Destructive mode:
+## Destructive Behavior
 
-1. Print target path and files that will be removed.
-2. Delete `.flow/specs/<target>`.
-3. If it was active, remove `.flow/.active-spec`.
-4. Do not delete `.flow/PROJECT.md`, `.flow/CONTEXT.md`, `.flow/STATE.md`, or other specs.
+Delete a spec only when both `--delete-spec` and `--yes` are present. The
+deletion rules live in `references/destructive-mode.md`.
 
 ## Output
 
-Default mode:
-
-```markdown
-✓ Cancelled execution loop: <spec-name>
-  State: execute → cancelled, phase → tasks
-  Preserved: spec artifacts and progress
-  Resume: /curdx-flow:implement --strategy=subagent
-```
-
-Destructive mode:
-
-```markdown
-✓ Deleted spec: <spec-name>
-  Removed: .flow/specs/<spec-name>
-  Active spec cleared: yes|no
-```
-
-## Safety Rules
-
-- Never delete a spec unless `--delete-spec --yes` is present.
-- Never delete project-level `.flow` files.
-- If state JSON is corrupt, rename it to `.state.json.corrupt.<timestamp>` instead of deleting it.
-- Prefer `/curdx-flow:status` after cancel to confirm recovery state.
+Use `references/reporting.md` for the default and destructive-mode summaries.

package/skills/cancel/references/destructive-mode.md

@@ -0,0 +1,17 @@
+# Cancel Destructive Mode — Explicit and Narrow
+
+Delete the spec directory only when both flags are present:
+
+```text
+/curdx-flow:cancel <spec-name> --delete-spec --yes
+```
+
+## Destructive Flow
+
+1. print the target path and removal scope
+2. delete `.flow/specs/<target>`
+3. if it was active, clear `.flow/.active-spec`
+4. leave all project-level `.flow` files untouched
+
+If `--delete-spec` appears without `--yes`, stop and print the exact command
+required.

package/skills/cancel/references/reporting.md

@@ -0,0 +1,18 @@
+# Cancel Reporting — Recovery vs Deletion Summary
+
+Default mode:
+
+```text
+✓ Cancelled execution loop: <spec-name>
+  State: execute → cancelled, phase → tasks
+  Preserved: spec artifacts and progress
+  Resume: /curdx-flow:implement --strategy=subagent
+```
+
+Destructive mode:
+
+```text
+✓ Deleted spec: <spec-name>
+  Removed: .flow/specs/<spec-name>
+  Active spec cleared: yes|no
+```

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.