@curdx/flow 2.2.0 → 2.2.4

package/skills/init/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: init
 description: Initialize the CurdX-Flow project structure (create the .flow/ directory and core files)
+when_to_use: Use when the current repository is not yet a CurdX-Flow project and needs the initial .flow scaffold.
 argument-hint: "[--force]"
 disable-model-invocation: true
 allowed-tools: [Read, Write, Bash, AskUserQuestion]
@@ -106,7 +107,7 @@ Next steps (in order):
   3. npx @curdx/flow doctor      — verify health
   4. /curdx-flow:start <name> "<goal>"  — begin your first feature spec
   
-  Start development (after Phase 1 ships):
+  Start development:
   5. /curdx-flow:start <name> "<goal>"  — kick off the first spec
 ```
 

package/skills/review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: review
-description: Two-stage code review — Stage 1 spec compliance, Stage 2 code quality. Optional flags add adversarial review, edge-case hunting, or developer-experience audit.
+description: "Run two-stage review: spec compliance first, code quality second. Optional flags add adversarial, edge-case, and DevEx passes."
+when_to_use: Use when implementation exists and the user wants review findings, spec-compliance checks, adversarial review, edge-case hunting, or a DevEx audit.
 argument-hint: "[--stage=<1|2|both>] [--adversarial] [--edge-case] [--devex]"
 disable-model-invocation: true
 allowed-tools: [Read, Bash, Agent, Grep, Glob]
@@ -12,6 +13,8 @@ Distinct from `/curdx-flow:verify`:
 - **verify** checks that the spec's stated goals actually work (goal-backward).
 - **review** checks that the code is good (spec compliance + craftsmanship).
 
+When this command is used to review follow-up work after prior review comments, apply `@${CLAUDE_PLUGIN_ROOT}/knowledge/review-feedback-intake.md` first: classify each feedback item before changing code, verify it against the current code/spec, and record accepted fixes or technical pushback in `.progress.md`.
+
 ## Flags
 
 | Flag | Default | Purpose |

package/skills/security-audit/SKILL.md

@@ -2,7 +2,21 @@
 name: security-audit
 description: Use when the user needs security review of code, specs, credentials, sensitive data, or dependency risk.
 when_to_use: 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]
+argument-hint: "[scope] [--depth=<owasp|stride|full>]"
+context: fork
+agent: flow-security-auditor
+paths:
+  - "**/*.{js,jsx,ts,tsx,py,rb,go,java,kt,php,cs,rs,swift,sql,sh}"
+  - "**/*.{json,yml,yaml,toml,tf,hcl,conf,ini}"
+  - "**/.env*"
+  - "**/Dockerfile*"
+  - ".github/workflows/**"
+  - ".gitlab-ci.yml"
+  - "docker-compose*.yml"
+  - "k8s/**"
+  - "helm/**"
+  - "infra/**"
+  - "terraform/**"
 ---
 
 # Security Audit
@@ -23,9 +37,9 @@ Confirm:
 - **Depth** (OWASP-only / OWASP + STRIDE / + dependency CVE scan)
 - **Risk tolerance** (block on any SR / only block on SR with POC / advisory only)
 
-### Step 2: Dispatch `flow-security-auditor`
+### Step 2: Run via `flow-security-auditor`
 
-Delegate to the `flow-security-auditor` agent. It will:
+This skill executes in a forked context through `flow-security-auditor`. It will:
 1. Scan for hardcoded secrets, weak crypto, unsanitized inputs
 2. Apply OWASP Top 10 (A01 Broken Access Control → A10 SSRF)
 3. Apply STRIDE threat modeling (Spoofing, Tampering, Repudiation, Information disclosure, DoS, Elevation)

package/skills/spec/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: spec
-description: Generate or refresh a feature specification. By default runs research → requirements → design → tasks in sequence. Flags let you target a single phase, stop early, regenerate, or tack on a multi-dimensional planning review.
+description: Generate or refresh the active spec across research, requirements, design, and tasks. Flags target phases, regeneration, and planning review.
+when_to_use: Use when the user wants to generate, resume, regenerate, or review a feature spec across research, requirements, design, and task planning.
 argument-hint: "[--phase=<X[,Y,...]>] [--until=<X>] [--review[=<dim[,dim]>]] [--regenerate] [--resume]"
 disable-model-invocation: true
 allowed-tools: [Read, Write, Bash, Agent, AskUserQuestion]

package/skills/start/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: start
 description: Smart entry point — create a new spec, resume an existing one, or switch between specs. Replaces v1's /start + /switch.
+when_to_use: Use when the user wants to create a spec, switch active work, resume a prior spec, list specs, or set the workflow mode for a feature.
 argument-hint: "[<spec-name>] [\"<one-line goal>\"] [--resume] [--list] [--mode=<fast|standard|enterprise>]"
 disable-model-invocation: true
 allowed-tools: [Read, Write, Bash, AskUserQuestion, Agent]
@@ -82,16 +83,17 @@ Switch `.flow/.active-spec` to `SPEC_NAME`. Confirm with the user if they intend
 ### Branch D: `SPEC_NAME` provided, spec does NOT exist
 Create a new spec:
 
-```bash
-mkdir -p ".flow/specs/$SPEC_NAME"
-# NOTE: field names MUST match schemas/spec-state.schema.json:
-#   - spec_name (not "spec")
-#   - created (date, not "created_at")
-#   - updated (date-time, not "updated_at")
-#   - phase must be one of the enum values; the initial phase is "research"
-#     (there is no "created" phase — that was schema drift pre-beta.9)
-#   - version is required
-cat > ".flow/specs/$SPEC_NAME/.state.json" <<JSON
+Use the `Write` tool for `.flow/specs/$SPEC_NAME/.state.json` and `.flow/.active-spec` so Claude Code checkpoints can rewind the new spec. The state file must match `schemas/spec-state.schema.json`:
+
+- `spec_name`, not `spec`
+- `created` as date, not `created_at`
+- `updated` as date-time, not `updated_at`
+- `phase` starts as `research`; there is no `created` phase
+- `version` is required
+
+Initial state JSON shape:
+
+```json
 {
   "version": "1.0",
   "spec_name": "$SPEC_NAME",
@@ -101,31 +103,29 @@ cat > ".flow/specs/$SPEC_NAME/.state.json" <<JSON
   "phase_status": {},
   "strategy": "auto",
   "execute_state": {},
-  "created": "$(date -u +%Y-%m-%d)",
-  "updated": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  "created": "YYYY-MM-DD",
+  "updated": "YYYY-MM-DDTHH:MM:SSZ"
 }
-JSON
-echo "$SPEC_NAME" > .flow/.active-spec
 ```
 
 If `GOAL` is empty, `AskUserQuestion` to gather it before writing `.state.json`.
 
 Then seed a minimal `.progress.md`:
 
-```bash
-cat > ".flow/specs/$SPEC_NAME/.progress.md" <<MD
+Use the `Write` tool for `.flow/specs/$SPEC_NAME/.progress.md`:
+
+```markdown
 # Progress Log — $SPEC_NAME
 
 **Goal**: $GOAL
 **Mode**: $FLAG_MODE
-**Created**: $(date -u +%Y-%m-%d)
+**Created**: YYYY-MM-DD
 
 ## Decisions
 (populated during /curdx-flow:spec)
 
 ## Learnings
 (populated during /curdx-flow:implement)
-MD
 ```
 
 ### Branch E: no args, no flags

package/skills/status/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: status
+description: Show CurdX-Flow project/spec status, active spec, phase, task progress, artifacts, and recovery hints.
+when_to_use: Use when the user asks what is active, which phase a spec is in, what artifacts exist, or how to recover from interrupted execution.
+argument-hint: "[--all]"
+disable-model-invocation: true
+allowed-tools: [Read, Bash, Glob]
+---
+
+# CurdX-Flow Status
+
+Show a compact, read-only status summary for the current project.
+
+## Preconditions
+
+```bash
+[ ! -d ".flow" ] && { echo "✗ Not a CurdX-Flow project. Run /curdx-flow:init first."; exit 1; }
+```
+
+## Gather
+
+1. Read `.flow/.active-spec` if present.
+2. List `.flow/specs/*/` directories.
+3. For each spec, check artifacts:
+   - `research.md`
+   - `requirements.md`
+   - `design.md`
+   - `tasks.md`
+   - `verification-report.md`
+   - `review-report.md`
+4. If `.state.json` exists, read:
+   - `phase`
+   - `strategy`
+   - `phase_status`
+   - `execute_state.task_index`
+   - `execute_state.total_tasks`
+   - `execute_state.failed_attempts`
+   - `execute_state.global_iteration`
+5. If `tasks.md` exists, count:
+   - completed tasks: lines matching `- [x] **`
+   - open tasks: lines matching `- [ ] **`
+
+## Output Format
+
+```markdown
+# CurDX-Flow Status
+
+Project: <cwd>
+Active spec: <name | none>
+
+## Specs
+
+### <spec-name> [ACTIVE]
+Phase: <phase | unknown>
+Strategy: <strategy | auto>
+Tasks: <done>/<total from tasks.md> checked, state cursor <task_index>/<total_tasks>
+Failures: <failed_attempts>, rounds: <global_iteration>
+Artifacts: [x] research [x] requirements [x] design [x] tasks [ ] verify [ ] review
+Health: OK | NEEDS_ATTENTION
+Recovery: <one concrete next command>
+```
+
+## Health Rules
+
+- `OK`: state and tasks agree, no failed attempts, no missing current-phase artifact.
+- `NEEDS_ATTENTION`: any of these:
+  - `.state.json` says execute complete but `tasks.md` has open tasks.
+  - failed attempts > 0.
+  - active spec points to a missing directory.
+  - current phase's expected artifact is missing or too small.
+
+## Recovery Hints
+
+- No `.flow/`: `/curdx-flow:init`
+- No active spec: `/curdx-flow:start <name> "<goal>"`
+- In spec phase with missing artifact: `/curdx-flow:spec --resume`
+- Execute in progress: `/curdx-flow:implement --task=next`
+- Stop-hook appears stuck: `/curdx-flow:cancel` then `/curdx-flow:implement --strategy=subagent`
+- Verify missing after execute complete: `/curdx-flow:verify`
+- Review missing after verify pass: `/curdx-flow:review`
+
+## Strictness
+
+- Read-only. Do not modify files.
+- Do not claim a spec is complete from `.state.json` alone; compare `tasks.md` checkboxes.

package/skills/ui-sketch/SKILL.md

@@ -2,7 +2,15 @@
 name: ui-sketch
 description: Use when the user needs UI design drafts, layout variants, mockups, prototypes, or styling direction.
 when_to_use: Triggers on "design UI", "UI design", "component layout", "variants", "wireframe", "mockup", "prototype", "sketch", "draft layout", "visual design", "styling", "CSS", "theming", "dark mode", "responsive design", "color scheme", "build me a UI", "show several variants", "try different colors".
-allowed-tools: [Read, Write, Bash, WebSearch]
+argument-hint: "\"<screen or component brief>\""
+context: fork
+agent: flow-ux-designer
+paths:
+  - "**/*.{html,css,scss,sass,less,js,jsx,ts,tsx,vue,svelte,astro}"
+  - "app/**"
+  - "pages/**"
+  - "components/**"
+  - "public/**"
 ---
 
 # UI Sketch
@@ -24,9 +32,9 @@ Confirm with the user:
 - **Must-haves** (brand colors / existing design system / responsive breakpoints)
 - **Variant count** (default: 3 variants with distinct design directions)
 
-### Step 2: Dispatch `flow-ux-designer`
+### Step 2: Run via `flow-ux-designer`
 
-Delegate to the `flow-ux-designer` agent with the brief. It will:
+This skill executes in a forked context through `flow-ux-designer`. It will:
 1. Invoke the `frontend-design` skill with the brief
 2. Generate N variant HTML/JSX files under `.flow/specs/<active>/sketches/`
 3. For each variant, produce a rationale: typography, color, layout decisions

package/skills/verify/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: verify
-description: Goal-backward verification — trace from every FR / AC / AD in the active spec to the code and tests, detect stubs and fake completions. The differentiator command. Optionally adds multi-source coverage audit with --strict.
+description: Prove the active spec is truly implemented by tracing every FR, AC, and AD to code and tests. Optional --strict adds multi-source coverage audit.
+when_to_use: Use when implementation is done and the user wants proof that FRs, ACs, and ADs are actually satisfied rather than merely claimed complete.
 argument-hint: "[--strict]"
 disable-model-invocation: true
 context: fork
@@ -49,8 +50,17 @@ Also scan for **stub / fake-completion** patterns on FR-covered paths:
 - tests with only `it.skip(...)` or no assertions
 - code returning mocked fixtures instead of calling real collaborators
 
+Apply `@${CLAUDE_PLUGIN_ROOT}/gates/test-quality-gate.md` to every test used as evidence. Mock-heavy tests are acceptable only when they mock boundaries while asserting real behavior, or when separate integration/e2e coverage exists. Mock-only tests, skipped tests, assertion-free tests, and tests without cleanup for stateful mocks cannot be the sole evidence for an FR/AC.
+
 Run the per-task `Verify` commands from `tasks.md` and record pass/fail.
 
+For fix/debug specs, also verify reality evidence:
+
+- `.progress.md` must contain `Reality Check (BEFORE)` with a reproduction command and observed failure.
+- `.progress.md` must contain `Reality Check (AFTER)` with the same command rerun and an explicit comparison.
+- `Verified: Issue resolved` is valid only if AFTER proves the original observed failure disappeared.
+- If the spec has fix/debug language but no `VF` task or BEFORE/AFTER evidence, mark the verdict `PARTIAL` even if all tests pass.
+
 ## --strict mode
 
 When `$ARGUMENTS` contains `--strict`, also apply the multi-source coverage
@@ -84,6 +94,8 @@ Per `@${CLAUDE_PLUGIN_ROOT}/gates/verification-gate.md`:
 
 - Any `STUB` or `MISSING` finding on a non-deferred FR blocks completion.
 - Any failing Verify command blocks completion.
+- Missing fix/debug BEFORE/AFTER reality verification blocks a full PASS.
+- Any FR/AC supported only by mock-only/skipped/assertion-free tests blocks a full PASS.
 - Waive only with an explicit D-NN decision logged in `.flow/STATE.md`.
 
 ## Output to user (≤ 5 lines after Write succeeds)

package/templates/config.json.tmpl

@@ -9,7 +9,10 @@
     "_strategy_options": "auto | subagent | stop-hook | wave | linear",
     "max_parallel": 5,
     "subagent_threshold": 8,
-    "wave_fail_policy": "continue-on-single"
+    "wave_fail_policy": "continue-on-single",
+    "recovery_mode": "manual",
+    "_recovery_mode_options": "manual | fix-task",
+    "max_fix_tasks_per_original": 2
   },
 
   "gates": {

package/templates/progress.md.tmpl

@@ -16,6 +16,25 @@
 - Current task: N/A (tasks phase not yet entered)
 - Blockers: none
 
+## Reality Check (BEFORE)
+
+<!-- For fix/debug specs only: capture the original failure before changing code. -->
+
+**Goal type**: N/A
+**Reproduction command**: N/A
+**Failure observed**: N/A
+**Output**: N/A
+**Timestamp**: N/A
+
+## Reality Check (AFTER)
+
+<!-- For fix/debug specs only: rerun the same command after the fix and compare. -->
+
+**Command**: N/A
+**Result**: N/A
+**Comparison**: N/A
+**Verified**: N/A
+
 ## Completed Tasks
 
 <!-- List of completed tasks -->

package/templates/tasks.md.tmpl

@@ -9,7 +9,7 @@ depends_on: design.md
 
 # Task Breakdown: {{SPEC_NAME}}
 
-> POC-First is an **orientation, not a mandate**. Use the phases below as an organizing idea and **delete phases that don't apply to this feature**. A bug-fix may be one task. A prototype may skip Phase 2 (refactor) and Phase 5 (PR lifecycle). A library may skip the PR lifecycle entirely. Forcing all five phases for a small feature is the padding pattern this template is designed to prevent.
+> POC-First is an **orientation, not a mandate**. Use the phases below as an organizing idea and **delete phases that don't apply to this feature**. A bug-fix may be one task. A prototype may skip Phase 2 (refactor) and Phase 5 (evidence handoff). A library may skip the handoff phase entirely. Forcing all five phases for a small feature is the padding pattern this template is designed to prevent.
 >
 > Each task includes whatever of `Do`, `Files`, `Done-when`, `Verify`, `Commit` is needed for the executor to finish it in a single sub-agent dispatch. Verify must be an automated command (no "manual test").
 
@@ -21,6 +21,13 @@ depends_on: design.md
 - `[P]` parallel-safe (dispatch in parallel within the same wave)
 - `[VERIFY]` quality checkpoint (flow-verifier agent)
 - `[SEQUENTIAL]` must be serial (breaks the parallel group)
+- `VF` reality verification task for fix/debug specs (BEFORE failure → AFTER pass)
+
+---
+
+## Split Rule
+
+If a task proves too broad or unsafe during execution, the executor must stop with `TASK_FAILED` and propose up to 3 smaller replacement tasks. The coordinator updates this file; executors do not invent and execute new tasks in the same turn.
 
 ---
 
@@ -49,23 +56,39 @@ depends_on: design.md
 ## Phase 3: Testing (TDD red / green / yellow)
 
 > Rule: tests first. Red → Green → Yellow. **Collapse red+green into one task when the test and implementation are trivially paired**; split only when the test genuinely precedes a nontrivial implementation.
+> Test quality: primary FR/AC evidence must exercise real behavior. Mock-only, skipped, or assertion-free tests do not count unless backed by integration/e2e coverage or an explicit D-NN waiver.
 
 - [ ] **3.X** [RED→GREEN→YELLOW] ...
 
 - [ ] **3.X+1** [VERIFY] Coverage check
   - **Verify**: coverage on the changed surface ≥ project standard
 
+- [ ] **3.X+2** [VERIFY] Test quality check
+  - **Do**: apply `test-quality-gate` to tests used as FR/AC evidence
+  - **Done when**: no FR/AC depends solely on mock-only/skipped/assertion-free tests
+  - **Verify**: `<test command>` plus grep scan for skipped tests / mock-only evidence
+
 ## Phase 4: Quality Gates
 
 > Include only the checks this project actually runs. `npx eslint` is dead weight if the project uses biome. `tsc --strict` is dead weight for a JS project.
 
+- [ ] **4.VF** [VERIFY] VF: Verify original issue resolved (fix/debug specs only)
+  - **Do**: 1. Read `Reality Check (BEFORE)` in `.progress.md`; 2. Re-run the same reproduction command; 3. Append `Reality Check (AFTER)` with output and comparison
+  - **Files**: `.flow/specs/{{SPEC_NAME}}/.progress.md`
+  - **Done when**: AFTER proves the original observed failure is gone
+  - **Verify**: `grep -q "Verified: Issue resolved" .flow/specs/{{SPEC_NAME}}/.progress.md`
+  - **Commit**: `chore({{SPEC_NAME}}): verify original issue resolved`
+
 - [ ] **4.X** [VERIFY] Final health check
   - **Do**: flow-verifier performs goal-driven reverse verification
   - **Done when**: every FR/AC has an automated check
 
-## Phase 5: PR Lifecycle (delete for local-only work, scripts, internal tools without a PR flow)
+## Phase 5: Evidence Handoff (delete for local-only work, scripts, internal tools without a PR flow)
 
-- [ ] **5.X** Ship / Land
+- [ ] **5.X** Prepare verification/review handoff
+  - **Do**: collect atomic commits, verification report, review report, and residual risk notes
+  - **Done when**: a human can open or release with clear evidence and no hidden blockers
+  - **Verify**: `test -f .flow/specs/{{SPEC_NAME}}/verification-report.md && test -f .flow/specs/{{SPEC_NAME}}/review-report.md`
 
 ---