@curdx/flow 2.2.4 → 2.3.0

package/skills/start/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: start
-description: Smart entry point — create a new spec, resume an existing one, or switch between specs. Replaces v1's /start + /switch.
+description: Create, resume, list, or switch the active feature spec.
 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
@@ -9,9 +9,18 @@ allowed-tools: [Read, Write, Bash, AskUserQuestion, Agent]
 
 # Start or Resume a Feature Spec
 
-Entry point for every feature. Works in four modes depending on flags and existing state.
+Entry point for every feature. Keep this skill focused on argument parsing,
+branch selection, state seeding, and next-step routing. Detailed branch behavior
+and workflow handoff rules live in:
 
-## Invocation patterns
+- `references/preflight.md`
+- `references/branch-routing.md`
+- `references/state-seeding.md`
+- `references/mode-semantics.md`
+- `references/workflow-handoff.md`
+- `references/reporting.md`
+
+## Invocation Patterns
 
 | Pattern | Behavior |
 |---------|----------|
@@ -24,140 +33,48 @@ Entry point for every feature. Works in four modes depending on flags and existi
 
 ## Preflight
 
-```bash
-# Require a .flow project
-[ ! -d ".flow" ] && {
-  echo "✗ Not a CurdX-Flow project. Run /curdx-flow:init first.";
-  exit 1;
-}
-```
+Use `references/preflight.md` for the project-level guard.
 
-## Flag parsing
-
-**Do not shell-split `$ARGUMENTS`.** It is a user-supplied string that may
-contain quoted substrings with spaces, `$`-signs, or embedded quotes.
-`xargs`, naive `awk`, and `sed`-based quote stripping all mis-parse at
-least one of those cases (e.g. `my-feature "Fix user's login bug"` breaks
-`xargs: unmatched quote`). Parse the string as a model task instead:
-
-1. **Flags** (order-independent, each is self-delimited):
-   - `--resume` / `--list` — boolean presence
-   - `--mode=<fast|standard|enterprise>` — value after `=`
-   Detect each with a single regex over the full `$ARGUMENTS` string and
-   remove the matched span from your working copy. Flags not in the list
-   above are errors — surface them to the user.
-
-2. **Positional args** (after flags removed):
-   - First whitespace-separated token → `SPEC_NAME` (kebab-case `[a-z0-9-]+`).
-   - Remainder of the string, trimmed and with one layer of outer `"..."`
-     or `'...'` quotes stripped → `GOAL`. Preserve inner quotes as-is.
-
-3. If `SPEC_NAME` does not match `^[a-z0-9][a-z0-9-]*$` (per
-   `schemas/spec-state.schema.json`), stop and ask the user to pick a
-   valid kebab-case name.
-
-Mode must be `fast`, `standard`, or `enterprise`. Invalid → default to
-`standard` with a warning.
-
-Example inputs and their parse:
-
-| `$ARGUMENTS`                                    | SPEC_NAME    | GOAL                          | flags         |
-|-------------------------------------------------|--------------|-------------------------------|---------------|
-| `my-feature "Add JWT auth"`                     | `my-feature` | `Add JWT auth`                | —             |
-| `my-feature --mode=fast "Add JWT auth"`         | `my-feature` | `Add JWT auth`                | mode=fast     |
-| `my-feature "Fix user's login bug"`             | `my-feature` | `Fix user's login bug`        | —             |
-| `--list`                                        | —            | —                             | list=true     |
-| `--resume`                                      | —            | —                             | resume=true   |
-
-## Branch logic
-
-### Branch A: `--list`
-Enumerate every directory under `.flow/specs/`, read each `.state.json` for `phase` and `updated` (per `schemas/spec-state.schema.json`), print a numbered list, then `AskUserQuestion` to pick one. Picking sets `.flow/.active-spec` and exits.
-
-### Branch B: `--resume` (no name)
-Read `.flow/.active-spec`. If it points to a valid spec dir, report its current phase and next suggested command (`/curdx-flow:spec` if incomplete, `/curdx-flow:implement` if tasks ready). If `.active-spec` is empty or stale, fall back to Branch A.
-
-### Branch C: `SPEC_NAME` provided, spec exists
-Switch `.flow/.active-spec` to `SPEC_NAME`. Confirm with the user if they intended to switch (not overwrite). Report current phase.
-
-### Branch D: `SPEC_NAME` provided, spec does NOT exist
-Create a new spec:
-
-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",
-  "goal": "$GOAL",
-  "mode": "$FLAG_MODE",
-  "phase": "research",
-  "phase_status": {},
-  "strategy": "auto",
-  "execute_state": {},
-  "created": "YYYY-MM-DD",
-  "updated": "YYYY-MM-DDTHH:MM:SSZ"
-}
-```
+## Flag Parsing
 
-If `GOAL` is empty, `AskUserQuestion` to gather it before writing `.state.json`.
+Do not shell-split `$ARGUMENTS`. Parse flags and positional arguments using the
+rules in `references/branch-routing.md`.
 
-Then seed a minimal `.progress.md`:
+Hard constraints:
 
-Use the `Write` tool for `.flow/specs/$SPEC_NAME/.progress.md`:
+- Flags allowed: `--resume`, `--list`, `--mode=<fast|standard|enterprise>`
+- First positional token -> `SPEC_NAME`
+- Remaining trimmed content -> `GOAL`
+- `SPEC_NAME` must be kebab-case per `schemas/spec-state.schema.json`
+- Invalid mode -> warn and fall back to `standard`
 
-```markdown
-# Progress Log — $SPEC_NAME
+## Branch Selection
 
-**Goal**: $GOAL
-**Mode**: $FLAG_MODE
-**Created**: YYYY-MM-DD
+Use `references/branch-routing.md` for the full branch contract:
 
-## Decisions
-(populated during /curdx-flow:spec)
+- Branch A: `--list`
+- Branch B: `--resume`
+- Branch C: existing `SPEC_NAME`
+- Branch D: new `SPEC_NAME`
+- Branch E: no args / no flags
 
-## Learnings
-(populated during /curdx-flow:implement)
-```
+If a new spec must be created, seed `.state.json`, `.flow/.active-spec`, and
+`.progress.md` using `references/state-seeding.md`.
 
-### Branch E: no args, no flags
-```
-AskUserQuestion:
-  "No spec name given. What would you like to do?"
-  Options:
-    - Create a new spec (prompts for name + goal)
-    - Resume the last active spec
-    - List all specs
-```
-
-Route to the matching branch.
+## Mode Semantics
 
-## Mode semantics
+Use `references/mode-semantics.md` for the workflow defaults implied by
+`mode`.
 
-The `mode` field in `.state.json` drives behavior in later commands:
+## Post-Create and Resume Handoff
 
-| Mode | `/curdx-flow:spec` default | `/curdx-flow:implement` default | Gates applied |
-|------|---------------------------|--------------------------------|---------------|
-| `fast` | skipped (use `/curdx-flow:fast` instead) | linear strategy | karpathy + verification |
-| `standard` | full 4 phases | auto strategy | + tdd + coverage-audit |
-| `enterprise` | full 4 phases + `--review=all` | auto strategy + stricter gates | + adversarial + edge-case + security |
+The next-command routing rules are centralized in
+`references/workflow-handoff.md`.
 
-## Post-create reporting
-
-```
-✓ Spec ready: <name>
-  Goal:  <goal>
-  Mode:  <mode>
-  Path:  .flow/specs/<name>/
+User-visible create/switch/resume summaries live in `references/reporting.md`.
+For a newly created spec, the immediate handoff remains:
 
+```text
 Next: /curdx-flow:spec
 ```
 

package/skills/start/references/branch-routing.md

@@ -0,0 +1,51 @@
+# Branch Routing — Start Skill Control Flow
+
+## Argument Parsing Rules
+
+Do not shell-split `$ARGUMENTS`.
+
+1. Detect and remove these flags from the raw string:
+   - `--resume`
+   - `--list`
+   - `--mode=<fast|standard|enterprise>`
+2. After flags are removed:
+   - first whitespace-delimited token -> `SPEC_NAME`
+   - remaining trimmed text -> `GOAL`
+   - strip one outer layer of matching single or double quotes from `GOAL`
+3. Reject unknown flags instead of ignoring them.
+
+## Branches
+
+### Branch A — `--list`
+
+- enumerate `.flow/specs/*`
+- read each `.state.json`
+- show phase + updated timestamp
+- use `AskUserQuestion` to choose
+- set `.flow/.active-spec`
+
+### Branch B — `--resume`
+
+- read `.flow/.active-spec`
+- if stale or missing, fall back to Branch A
+- report current phase and route using `references/workflow-handoff.md`
+
+### Branch C — Existing `SPEC_NAME`
+
+- switch `.flow/.active-spec` to that spec
+- confirm if the user likely intended to switch rather than overwrite
+- report current phase
+
+### Branch D — New `SPEC_NAME`
+
+- gather missing `GOAL` if necessary
+- create state and progress files using `references/state-seeding.md`
+- set `.flow/.active-spec`
+
+### Branch E — No args / no flags
+
+Ask the user to choose:
+
+- create a new spec
+- resume the last active spec
+- list all specs

package/skills/start/references/mode-semantics.md

@@ -0,0 +1,12 @@
+# Start Mode Semantics — What Each Mode Implies
+
+The `mode` field in `.state.json` drives later workflow defaults:
+
+| Mode | `/curdx-flow:spec` default | `/curdx-flow:implement` default | Gates applied |
+|------|---------------------------|--------------------------------|---------------|
+| `fast` | skipped (use `/curdx-flow:fast` instead) | linear strategy | karpathy + verification |
+| `standard` | full 4 phases | auto strategy | + tdd + coverage-audit |
+| `enterprise` | full 4 phases + `--review=all` | auto strategy + stricter gates | + adversarial + edge-case + security + devex |
+
+If an invalid mode is provided during argument parsing, warn and fall back to
+`standard`.

package/skills/start/references/preflight.md

@@ -0,0 +1,13 @@
+# Start Preflight — Project Must Be Initialized
+
+Before parsing arguments or touching spec state:
+
+```bash
+[ ! -d ".flow" ] && {
+  echo "✗ Not a CurdX-Flow project. Run /curdx-flow:init first.";
+  exit 1;
+}
+```
+
+`/curdx-flow:start` is the first mutable workflow entrypoint after init. If the
+project scaffold is missing, stop immediately instead of attempting recovery.

package/skills/start/references/reporting.md

@@ -0,0 +1,20 @@
+# Start Reporting — User-Facing Summaries
+
+For a newly created spec, report:
+
+```text
+✓ Spec ready: <name>
+  Goal:  <goal>
+  Mode:  <mode>
+  Path:  .flow/specs/<name>/
+
+Next: /curdx-flow:spec
+```
+
+For resume and switch flows, keep the message short:
+
+- identify the active spec
+- state the current phase when known
+- route using `references/workflow-handoff.md`
+
+Do not restate the full workflow. Point to the immediate next command only.

package/skills/start/references/state-seeding.md

@@ -0,0 +1,44 @@
+# State Seeding — New Spec Bootstrap
+
+When creating a fresh spec, use `Write` for all files so Claude checkpoints can
+rewind the bootstrap cleanly.
+
+## `.state.json`
+
+Required shape:
+
+```json
+{
+  "version": "1.0",
+  "spec_name": "$SPEC_NAME",
+  "goal": "$GOAL",
+  "mode": "$FLAG_MODE",
+  "phase": "research",
+  "phase_status": {},
+  "strategy": "auto",
+  "execute_state": {},
+  "created": "YYYY-MM-DD",
+  "updated": "YYYY-MM-DDTHH:MM:SSZ"
+}
+```
+
+## `.progress.md`
+
+```markdown
+# Progress Log — $SPEC_NAME
+
+**Goal**: $GOAL
+**Mode**: $FLAG_MODE
+**Created**: YYYY-MM-DD
+
+## Decisions
+(populated during /curdx-flow:spec)
+
+## Learnings
+(populated during /curdx-flow:implement)
+```
+
+## Activation
+
+Write `.flow/.active-spec` last, after the spec directory and both artifacts
+exist.

package/skills/start/references/workflow-handoff.md

@@ -0,0 +1,26 @@
+# Workflow Handoff — What Comes Next
+
+`/curdx-flow:start` is the entrypoint, but it should route users to the right
+next command based on current phase.
+
+## New Spec
+
+After a fresh spec is created:
+
+```text
+Next: /curdx-flow:spec
+```
+
+## Resume / Switch Routing
+
+When resuming an existing spec:
+
+- `phase` before `tasks` completion -> suggest `/curdx-flow:spec`
+- `tasks` completed but execution not complete -> suggest `/curdx-flow:implement`
+- `execute` completed but verification missing or failed -> suggest `/curdx-flow:verify`
+- `verify` completed but review missing or failed -> suggest `/curdx-flow:review`
+- both verification and review completed -> report evidence-backed handoff is
+  ready for human PR/release work
+
+Do not invent non-existent ship commands. The workflow ends at human handoff
+with persisted evidence.

package/skills/status/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: status
-description: Show CurdX-Flow project/spec status, active spec, phase, task progress, artifacts, and recovery hints.
+description: Show active spec health, 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
@@ -9,77 +9,33 @@ allowed-tools: [Read, Bash, Glob]
 
 # CurdX-Flow Status
 
-Show a compact, read-only status summary for the current project.
+Show a compact, read-only status summary for the current project. Keep this
+entrypoint focused on read-only inventory, health classification, and recovery
+hints. Detailed health and recovery rules live in:
+
+- `references/preflight.md`
+- `references/gather-contract.md`
+- `references/health-rules.md`
+- `references/recovery-hints.md`
+- `references/output-contract.md`
 
 ## Preconditions
 
-```bash
-[ ! -d ".flow" ] && { echo "✗ Not a CurdX-Flow project. Run /curdx-flow:init first."; exit 1; }
-```
+Use `references/preflight.md` for the project-level guard.
 
 ## 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 `- [ ] **`
+Use `references/gather-contract.md` for the full read-only inventory contract.
 
 ## 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
+Use `references/output-contract.md` for the compact markdown report shape.
 
-- 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`
+Use `references/health-rules.md` to compute `Health`, and
+`references/recovery-hints.md` to compute the single best next action.
 
 ## Strictness
 
 - Read-only. Do not modify files.
-- Do not claim a spec is complete from `.state.json` alone; compare `tasks.md` checkboxes.
+- Do not claim a spec is complete from `.state.json` alone; compare `tasks.md`
+  checkboxes.

package/skills/status/references/gather-contract.md

@@ -0,0 +1,27 @@
+# Status Gather Contract — What to Read
+
+Gather read-only state in this order:
+
+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 `- [ ] **`
+
+Do not mutate files while gathering. `status` is an observer, not a repair
+workflow.

package/skills/status/references/health-rules.md

@@ -0,0 +1,27 @@
+# Status Health Rules — Canonical Evaluation
+
+## `OK`
+
+Use `OK` only when:
+
+- state and tasks agree
+- failed attempts are zero
+- the current phase's expected artifact exists
+
+## `NEEDS_ATTENTION`
+
+Use `NEEDS_ATTENTION` when any of these is true:
+
+- `.state.json` says execute complete but `tasks.md` still has open tasks
+- `failed_attempts > 0`
+- `.flow/.active-spec` points to a missing directory
+- the current phase's expected artifact is missing or obviously truncated
+
+## Artifact Expectations
+
+- `research` -> `research.md`
+- `requirements` -> `requirements.md`
+- `design` -> `design.md`
+- `tasks` / `execute` -> `tasks.md`
+- `verify` -> `verification-report.md`
+- `review` -> `review-report.md`

package/skills/status/references/output-contract.md

@@ -0,0 +1,24 @@
+# Status Output Contract — Compact Read-Only Summary
+
+Render:
+
+```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>
+```
+
+Keep it compact and operational. Show one best recovery command, not a list of
+possible next steps.

package/skills/status/references/preflight.md

@@ -0,0 +1,10 @@
+# Status Preflight — Project Must Exist
+
+Before reading any status signals:
+
+```bash
+[ ! -d ".flow" ] && { echo "✗ Not a CurdX-Flow project. Run /curdx-flow:init first."; exit 1; }
+```
+
+`status` is strictly read-only. If `.flow/` does not exist, stop immediately
+and route to `/curdx-flow:init`.

package/skills/status/references/recovery-hints.md

@@ -0,0 +1,18 @@
+# Status Recovery Hints — Single Best Next Command
+
+Choose one concrete recovery command, not a menu.
+
+## Priority Rules
+
+- No `.flow/` -> `/curdx-flow:init`
+- No active spec -> `/curdx-flow:start <name> "<goal>"`
+- Missing or stale spec artifact before tasks completion -> `/curdx-flow:spec`
+- Tasks complete but execute not done -> `/curdx-flow:implement`
+- Execute complete but verification missing or failed -> `/curdx-flow:verify`
+- Verification complete but review missing or failed -> `/curdx-flow:review`
+- Stop-hook or execution parity drift -> `/curdx-flow:cancel`, then `/curdx-flow:implement --strategy=subagent`
+
+## Constraint
+
+Do not suggest a later-stage command when an earlier missing artifact or failed
+phase blocks it.

package/skills/ui-sketch/SKILL.md

@@ -15,44 +15,25 @@ paths:
 
 # UI Sketch
 
-You are invoked when the user wants fresh UI design drafts — typically 2–4 variants for comparison, or a single iterative refinement.
+This skill is for design exploration, not final implementation. Keep the
+entrypoint focused on design-brief intake, variant output requirements, and the
+iteration handoff. Detailed rules live in:
 
-## Preconditions
+- `references/brief-intake.md`
+- `references/variant-contract.md`
+- `references/iteration-handoff.md`
 
-1. The `frontend-design` skill (Anthropic official) should be installed. Without it, fall back to Tailwind + shadcn/ui defaults.
-2. The user provides a description of the UI goal (component, page, or flow).
+## Design Brief
 
-## Workflow
+Use `references/brief-intake.md` to confirm the brief before dispatching
+`flow-ux-designer`.
 
-### Step 1: Clarify design brief
+## Variant Contract
 
-Confirm with the user:
-- **What is being designed** (component / page / full screen)
-- **Context** (consumer product / enterprise tool / marketing site / internal dashboard)
-- **Must-haves** (brand colors / existing design system / responsive breakpoints)
-- **Variant count** (default: 3 variants with distinct design directions)
+The required outputs for `flow-ux-designer` and optional `flow-ui-researcher`
+live in `references/variant-contract.md`.
 
-### Step 2: Run via `flow-ux-designer`
+## Iteration Handoff
 
-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
-4. Open the variants for user preview if a dev server is running
-
-### Step 3: Present variants
-
-Show the user:
-- **Variant preview URLs** or file paths
-- **Design rationale** per variant (what's different, why)
-- **Accessibility notes** (contrast ratios, focus states)
-
-### Step 4: Iterate or finalize
-
-- If user picks a variant: move the chosen file into the spec's `design.md` asset section.
-- If user wants a hybrid: dispatch `flow-ux-designer` again with "merge variant A layout + variant B color scheme".
-
-## References
-
-- `flow-ux-designer` agent: `@${CLAUDE_PLUGIN_ROOT}/agents/flow-ux-designer.md`
-- `flow-ui-researcher` agent (for competitive reference scraping): `@${CLAUDE_PLUGIN_ROOT}/agents/flow-ui-researcher.md`
+How to pick, merge, or promote a variant lives in
+`references/iteration-handoff.md`.

package/skills/ui-sketch/references/brief-intake.md

@@ -0,0 +1,10 @@
+# UI Sketch Brief Intake — What to Clarify
+
+Before sketching, confirm:
+
+- what is being designed
+- context (consumer, enterprise, marketing, internal tool)
+- must-haves (brand, system, responsive constraints)
+- variant count
+
+If the user already provided all of this, do not over-interview.

package/skills/ui-sketch/references/iteration-handoff.md

@@ -0,0 +1,5 @@
+# UI Sketch Iteration Handoff — Pick, Merge, or Promote
+
+- if the user picks a variant, promote it into the active design discussion
+- if the user wants a hybrid, rerun with an explicit merge instruction
+- treat sketches as exploratory assets, not shipped implementation by default