@curdx/flow 1.1.10 → 2.0.0-beta.1

package/commands/spec.md

@@ -1,135 +1,153 @@
 ---
 name: spec
-description: One-shot sequential run of research → requirements → design → tasks across all four stages
-argument-hint: "[spec-name] [--skip-research | --skip-requirements]"
+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.
+argument-hint: "[--phase=<X[,Y,...]>] [--until=<X>] [--review[=<dim[,dim]>]] [--regenerate] [--resume]"
 allowed-tools: [Read, Write, Bash, Task, AskUserQuestion]
 ---
 
-# One-Shot Full Spec Generation
+# Generate or Refresh the Active Spec
 
-Runs the 4 spec stages sequentially, prompting the user between stages to decide whether to continue. Suitable for generating a full spec in one go.
+This command writes the four spec documents (`research.md`, `requirements.md`, `design.md`, `tasks.md`) inside `.flow/specs/<active-spec>/`. It replaces the v1 commands `/research`, `/requirements`, `/design`, `/tasks`, `/plan-ceo`, `/plan-eng`, `/plan-design`, `/plan-dx`, and `/autoplan` — all expressed here as flags.
 
-## Step 1: Preflight + confirmation
+## Flags
 
-```bash
-[ ! -d ".flow" ] && { echo "❌ Not a CurDX-Flow project"; exit 1; }
+| Flag | Default | Purpose |
+|------|---------|---------|
+| `--phase=<X[,Y]>` | (inferred from `.state.json`) | Run only the listed phase(s). `X ∈ {research, requirements, design, tasks}`. Accepts comma-separated list. |
+| `--until=<X>` | (none) | Run from the current phase forward, stopping after `X`. Mutually exclusive with `--phase`. |
+| `--review[=<dim[,dim]>]` | (not run) | After phases complete, run a planning review. `dim ∈ {ceo, eng, design, dx, all}`. Bare `--review` = `--review=all`. |
+| `--regenerate` | (resume) | Wipe existing phase output for the targeted phases and rebuild from scratch. |
+| `--resume` | (default) | Continue from `.state.json.phase`. This is the default when no flag is given. |
 
-SPEC_NAME="$(echo "$ARGUMENTS" | awk '{print $1}')"
-[ -z "$SPEC_NAME" ] && SPEC_NAME=$(cat .flow/.active-spec 2>/dev/null)
+## Preflight
 
+```bash
+# 1. A .flow project must exist
+[ ! -d ".flow" ] && {
+  echo "✗ Not a CurDX-Flow project. Run /curdx-flow:init first.";
+  exit 1;
+}
+
+# 2. An active spec must be set
+SPEC_NAME=$(cat .flow/.active-spec 2>/dev/null)
 if [ -z "$SPEC_NAME" ]; then
-    echo "❌ No active spec. Run /curdx-flow:start <name> \"<goal>\" first"
-    exit 1
+  echo "✗ No active spec. Run /curdx-flow:start <name> \"<goal>\" first.";
+  exit 1;
 fi
+SPEC_DIR=".flow/specs/$SPEC_NAME"
+STATE_FILE="$SPEC_DIR/.state.json"
+[ ! -f "$STATE_FILE" ] && { echo "✗ Missing $STATE_FILE"; exit 1; }
 ```
 
-## Step 2: Parse skip options
-
-```bash
-SKIP_RESEARCH=0
-SKIP_REQUIREMENTS=0
-case "$ARGUMENTS" in
-    *--skip-research*)     SKIP_RESEARCH=1 ;;
-esac
-case "$ARGUMENTS" in
-    *--skip-requirements*) SKIP_REQUIREMENTS=1 ;;
-esac
-```
-
-## Step 3: Execute the 4 stages in sequence
-
-### Phase 1: Research
+## Flag parsing
 
 ```bash
-if [ "$SKIP_RESEARCH" = "1" ]; then
-    echo "⊘ Skipping research"
-elif [ -f ".flow/specs/$SPEC_NAME/research.md" ]; then
-    echo "ℹ research.md already exists; asking the user..."
-    # AskUserQuestion: re-run research? (skip / rerun / abort)
-else
-    echo "▶ Running research stage..."
-    # Via SlashCommand or directly dispatch the agent
-    # Recommended: directly invoke the /curdx-flow:research logic (inline or via the SlashCommand tool)
+# $ARGUMENTS is the raw argument string
+FLAG_PHASE=$(echo "$ARGUMENTS" | grep -oP -- '--phase=\K[^\s]+' || true)
+FLAG_UNTIL=$(echo "$ARGUMENTS" | grep -oP -- '--until=\K[^\s]+' || true)
+FLAG_REVIEW=$(echo "$ARGUMENTS" | grep -oP -- '--review(?:=[^\s]+)?' || true)
+FLAG_REGENERATE=$(echo "$ARGUMENTS" | grep -q -- '--regenerate' && echo "1" || echo "0")
+
+# Rule: --phase and --until are mutually exclusive
+if [ -n "$FLAG_PHASE" ] && [ -n "$FLAG_UNTIL" ]; then
+  echo "✗ --phase and --until cannot be combined. Pick one.";
+  exit 1;
 fi
 ```
 
-**Implementation 1** (recommended): Dispatch the agent directly, skipping SlashCommand:
+## Phase resolution
 
-Call the Task tool with the same content as the Task call in `/curdx-flow:research` (reading flow-researcher.md).
+The ordered pipeline is `research → requirements → design → tasks`. Resolve which phases to run:
 
-**Implementation 2**: If Claude Code supports the SlashCommand tool chain:
-```
-SlashCommand: /curdx-flow:research $SPEC_NAME
-```
+- No flags → start at `state.json.phase`, run forward to `tasks`.
+- `--phase=design` → run only `design`.
+- `--phase=design,tasks` → run `design` then `tasks`.
+- `--until=design` → start at `state.json.phase`, stop after `design`.
+- `--regenerate` (no other phase flag) → same as default but clear existing output for each phase before running.
+- `--regenerate --phase=X` → clear `X`'s output, re-run only `X`.
 
-### Intermediate confirmation after each stage
+Read and update `.state.json.phase` after each phase succeeds.
 
-```
-✓ research stage complete
+## Phase execution
 
-Key findings:
-  - ...
-  - ...
+For each phase in the resolved list, dispatch a sub-agent via the `Task` tool:
 
-⚠ The following open questions were found; recommend answering first:
-  Q1: ...
+### research → `flow-researcher`
+Inputs: spec goal + one-line description from `.state.json`.
+Output: `research.md` covering problem space, prior art (library candidates via `context7`), constraints, technical recommendation.
 
-Choose:
-  [continue]    Continue to requirements (agent will answer open questions with reasonable assumptions)
-  [pause]       Pause — I'll review research.md myself, then manually run /curdx-flow:requirements
-  [abort]       Abort the entire /curdx-flow:spec
-```
+### requirements → `flow-product-designer`
+Inputs: `research.md`.
+Output: `requirements.md` with user stories (US-NN), acceptance criteria (AC-N.N), functional requirements (FR-NN), non-functional requirements (NFR-*).
+
+### design → `flow-architect`
+Inputs: `research.md` + `requirements.md`.
+Output: `design.md` with architecture decisions (AD-NN), component boundaries, data models, error-path design, mermaid diagrams. Must use `sequential-thinking` MCP (≥8 thoughts).
 
-Use AskUserQuestion for the choice.
+### tasks → `flow-planner`
+Inputs: all three prior files + `.flow/PROJECT.md` tech stack.
+Output: `tasks.md` — POC-First 5-phase decomposition with per-task Verify commands, multi-source coverage audit against FR/AC/AD/Research/Decisions.
 
-### Phase 2: Requirements
+After each phase completes successfully, update `.state.json`:
 
-If continue, dispatch flow-product-designer (mirroring the Task call in `/curdx-flow:requirements`).
+```json
+{
+  "phase": "<just-completed-phase>",
+  "phase_status": { "<phase>": "completed" },
+  "updated_at": "<ISO8601 timestamp>"
+}
+```
 
-Confirm again after completion.
+## Optional planning review
 
-### Phase 3: Design
+If `--review` (or `--review=<dims>`) is present:
 
-If continue, dispatch flow-architect (mirroring the Task call in `/curdx-flow:design`).
+1. **Precondition**: `design.md` must exist. If missing, error: "Design missing. Run `/curdx-flow:spec --phase=design` first."
+2. Parse the dims: `all` expands to `ceo,eng,design,dx`.
+3. Dispatch review agents in parallel via `Task` (one per dim):
 
-Confirm again after completion. **This step is especially important** because design freezes the technology choices — recommend that the user review the AD-NN entries before entering tasks.
+| Dim | Agent | Focus |
+|-----|-------|-------|
+| `ceo` | `flow-architect` (review mode) | Strategic: scope fit, ROI, opportunity cost |
+| `eng` | `flow-architect` (review mode) | Engineering: architecture lock-in, risk, technical debt |
+| `design` | `flow-ux-designer` | UX / UI / accessibility / design system |
+| `dx` | `flow-architect` (review mode) | Developer experience: naming, comments, structure, error handling, setup, types, tests, dev loop |
 
-### Phase 4: Tasks
+4. Aggregate findings into `.flow/specs/<active>/spec-review.md` with one section per dim and a consolidated verdict (GO / GO-WITH-CHANGES / HOLD).
 
-If continue, dispatch flow-planner (mirroring the Task call in `/curdx-flow:tasks`).
+## Reporting
 
-## Step 4: Final summary
+Final console output:
 
 ```
-═══════════════════════════════════════════════
-✓ Full spec generated: $SPEC_NAME
-
-Output files:
-  .flow/specs/$SPEC_NAME/research.md       (N lines)
-  .flow/specs/$SPEC_NAME/requirements.md   (M lines)
-  .flow/specs/$SPEC_NAME/design.md         (K lines)
-  .flow/specs/$SPEC_NAME/tasks.md          (L lines)
-
-Stats:
-  Research:     2-3 technical options, context7 queried X libraries
-  Requirements: P US, Q FR, R AC
-  Design:       S AD, T components
-  Tasks:        U tasks (fine / coarse)
-
-Next steps:
-  - Review all 4 files
-  - To modify, run /curdx-flow:research / /curdx-flow:requirements / ... individually
-  - After Phase 2 ships: /curdx-flow:implement
+✓ Spec <name> refreshed
+  Phases run:   research, requirements, design, tasks
+  Review dims:  ceo, eng, design, dx   (if --review was used)
+  Files:
+    .flow/specs/<name>/research.md
+    .flow/specs/<name>/requirements.md
+    .flow/specs/<name>/design.md
+    .flow/specs/<name>/tasks.md
+    .flow/specs/<name>/spec-review.md   (if --review was used)
+
+Next: /curdx-flow:implement
 ```
 
-## Auto mode (/curdx-flow:spec --yolo)
-
-If the user passes `--yolo`, all intermediate confirmations default to `continue`, running through in one pass.
+## Common invocations
 
-**Warning**: yolo mode may run to completion but not necessarily match the user's intent. Recommend using it only on sketch / fast projects.
+```
+/curdx-flow:spec                              # full spec from current state
+/curdx-flow:spec --phase=design               # re-run only design (e.g., after requirements changed)
+/curdx-flow:spec --phase=design,tasks         # re-run design and tasks
+/curdx-flow:spec --until=design               # run up through design, stop (human review checkpoint)
+/curdx-flow:spec --review                     # full spec + all 4 planning dimensions
+/curdx-flow:spec --review=eng,dx              # full spec + engineering + DX review only
+/curdx-flow:spec --regenerate                 # clear all four phases and rebuild
+/curdx-flow:spec --regenerate --phase=tasks   # only rebuild tasks (keep research/requirements/design)
+```
 
-## Error recovery
+## References
 
-- A stage fails → stop without advancing; after manual fixes the user can re-run /curdx-flow:<phase>
-- User chooses abort → preserve generated files, but do not advance phase_status
-- sequential-thinking / context7 requirements at every stage match the per-command definitions
+- Agents: `@${CLAUDE_PLUGIN_ROOT}/agents/flow-researcher.md`, `flow-product-designer.md`, `flow-architect.md`, `flow-planner.md`, `flow-ux-designer.md`
+- Knowledge: `@${CLAUDE_PLUGIN_ROOT}/knowledge/spec-driven-development.md`, `poc-first-workflow.md`
+- Preamble: `@${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md`

package/commands/start.md

@@ -1,189 +1,136 @@
 ---
 name: start
-description: intelligent entry point — create a new spec or resume an existing one, entering the corresponding phase
-argument-hint: "<spec-name> \"<goal>\""
-allowed-tools: [Read, Write, Bash, AskUserQuestion]
+description: Smart entry point — create a new spec, resume an existing one, or switch between specs. Replaces v1's /start + /switch.
+argument-hint: "[<spec-name>] [\"<one-line goal>\"] [--resume] [--list] [--mode=<fast|standard|enterprise>]"
+allowed-tools: [Read, Write, Bash, AskUserQuestion, Task]
 ---
 
-# Start a Spec
+# Start or Resume a Feature Spec
 
-CurDX-Flow's main entry point. Based on context, automatically:
-- New spec → create directory + templates + enter research phase
-- Existing spec → resume from the last phase
+Entry point for every feature. Works in four modes depending on flags and existing state.
 
-## Step 1: Preflight Check
+## Invocation patterns
 
-```bash
-# Must be initialized
-if [ ! -d ".flow" ]; then
-    echo "❌ Current directory is not a CurDX-Flow project. Run /curdx-flow:init first"
-    exit 1
-fi
-```
+| Pattern | Behavior |
+|---------|----------|
+| `/curdx-flow:start my-feature "Add JWT auth to REST API"` | Create a fresh spec named `my-feature`, set it active, seed draft requirements. |
+| `/curdx-flow:start my-feature` (name exists) | Switch active spec to `my-feature` (same as v1 `/switch`). |
+| `/curdx-flow:start --resume` | Resume the last active spec from `.flow/.active-spec`. |
+| `/curdx-flow:start --list` | List all specs with their phase and last-updated time, prompt to pick. |
+| `/curdx-flow:start` (no args) | Interactive: ask the user whether to create new, resume recent, or list all. |
+| Add `--mode=<fast\|standard\|enterprise>` | Set the execution mode for this spec (stored in `.state.json`). |
 
-## Step 2: Parse Arguments
+## Preflight
 
 ```bash
-ARGS="$ARGUMENTS"
-
-# Extract spec-name and goal
-# Format: flow-start my-feature "Add JWT auth to API"
-#         or: flow-start my-feature  (resume existing spec)
-SPEC_NAME=$(echo "$ARGS" | awk '{print $1}')
-GOAL=$(echo "$ARGS" | sed -E "s/^[a-z0-9-]+\s*//" | sed 's/^["\x27]//;s/["\x27]$//')
-
-if [ -z "$SPEC_NAME" ]; then
-    echo "Usage: /curdx-flow:start <spec-name> \"<goal>\""
-    echo "Example: /curdx-flow:start auth-system \"Add JWT authentication to REST API\""
-    exit 1
-fi
-
-# Validate that spec-name is kebab-case
-if ! echo "$SPEC_NAME" | grep -Eq '^[a-z][a-z0-9-]*$'; then
-    echo "❌ spec-name must be kebab-case (start with lowercase letter, only letters, digits, hyphens)"
-    exit 1
-fi
+# Require a .flow project
+[ ! -d ".flow" ] && {
+  echo "✗ Not a CurDX-Flow project. Run /curdx-flow:init first.";
+  exit 1;
+}
 ```
 
-## Step 3: Determine New vs Resume
+## Flag parsing
 
 ```bash
-SPEC_DIR=".flow/specs/$SPEC_NAME"
-
-if [ -d "$SPEC_DIR" ]; then
-    # Resume mode
-    MODE="resume"
-    echo "🔄 Resuming spec: $SPEC_NAME"
-else
-    # New mode
-    MODE="new"
-    echo "🆕 New spec: $SPEC_NAME"
-    
-    if [ -z "$GOAL" ]; then
-        # If no goal given, ask the user
-        echo "Please provide a one-sentence goal, then continue."
-        exit 0
-    fi
-fi
+FLAG_RESUME=$(echo "$ARGUMENTS" | grep -q -- '--resume' && echo 1 || echo 0)
+FLAG_LIST=$(echo "$ARGUMENTS" | grep -q -- '--list' && echo 1 || echo 0)
+FLAG_MODE=$(echo "$ARGUMENTS" | grep -oP -- '--mode=\K[^\s]+' || echo "standard")
+
+# Strip flags from ARGUMENTS to leave the positional args
+POS=$(echo "$ARGUMENTS" | sed -E 's/--[a-z-]+(=[^ ]+)?//g' | xargs)
+SPEC_NAME=$(echo "$POS" | awk '{print $1}')
+GOAL=$(echo "$POS" | awk '{$1=""; print $0}' | sed 's/^"//; s/"$//' | xargs)
 ```
 
-## Step 4a: New Path
+Mode must be `fast`, `standard`, or `enterprise`. Invalid → default to `standard` with a warning.
 
-If `MODE=new`:
+## Branch logic
 
-```bash
-# Create directory
-mkdir -p "$SPEC_DIR"
+### Branch A: `--list`
+Enumerate every directory under `.flow/specs/`, read each `.state.json` for `phase` and `updated_at`, 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.
 
-# Generate .state.json
-TODAY=$(date +%Y-%m-%d)
-CONFIG_MODE=$(python3 -c "import json; print(json.load(open('.flow/config.json')).get('mode','standard'))" 2>/dev/null || echo "standard")
+### 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.
 
-cat > "$SPEC_DIR/.state.json" <<EOF
+### Branch D: `SPEC_NAME` provided, spec does NOT exist
+Create a new spec:
+
+```bash
+mkdir -p ".flow/specs/$SPEC_NAME"
+cat > ".flow/specs/$SPEC_NAME/.state.json" <<JSON
 {
-  "version": "1.0",
-  "spec_name": "$SPEC_NAME",
+  "spec": "$SPEC_NAME",
   "goal": "$GOAL",
-  "mode": "$CONFIG_MODE",
+  "mode": "$FLAG_MODE",
+  "phase": "created",
+  "phase_status": {},
   "strategy": "auto",
-  "phase": "research",
-  "phase_status": {
-    "research": "not_started",
-    "requirements": "not_started",
-    "design": "not_started",
-    "tasks": "not_started"
-  },
-  "decisions": [],
-  "created": "$TODAY",
-  "updated": "$TODAY"
+  "execute_state": {},
+  "created_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "updated_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 }
-EOF
-
-# Generate progress.md (from template)
-python3 <<PYEOF
-from pathlib import Path
-tmpl = Path("${CLAUDE_PLUGIN_ROOT}/templates/progress.md.tmpl").read_text()
-content = tmpl.replace("{{SPEC_NAME}}", "$SPEC_NAME").replace("{{CREATED_DATE}}", "$TODAY")
-Path("$SPEC_DIR/.progress.md").write_text(content)
-PYEOF
-
-# Set as active spec
-echo "$SPEC_NAME" > ".flow/.active-spec"
-
-echo "✓ Spec directory created: $SPEC_DIR"
-echo "  Goal: $GOAL"
-echo ""
-echo "Next step (automatically entering research):"
-echo "  /curdx-flow:research"
+JSON
+echo "$SPEC_NAME" > .flow/.active-spec
 ```
 
-## Step 4b: Resume Path
+If `GOAL` is empty, `AskUserQuestion` to gather it before writing `.state.json`.
 
-If `MODE=resume`:
+Then seed a minimal `.progress.md`:
 
 ```bash
-# Read current phase
-STATE_FILE="$SPEC_DIR/.state.json"
-if [ ! -f "$STATE_FILE" ]; then
-    echo "✗ Spec directory exists but .state.json is missing. State may be corrupted."
-    # Ask user
-    # AskUserQuestion: "Rebuild state file?" (yes/no)
-    exit 0
-fi
-
-# Set as active
-echo "$SPEC_NAME" > ".flow/.active-spec"
-
-# Show current progress
-python3 <<PYEOF
-import json
-s = json.load(open("$STATE_FILE"))
-print(f"✓ Spec activated: $SPEC_NAME")
-print(f"  Goal:        {s.get('goal','(undefined)')}")
-print(f"  Current phase: {s['phase']}")
-print(f"  Progress:")
-
-ph_emoji = {"completed": "✓", "in_progress": "●", "not_started": "○", "failed": "✗", "skipped": "—"}
-for phase, status in s.get('phase_status',{}).items():
-    emoji = ph_emoji.get(status, "?")
-    print(f"    {emoji} {phase:<15} {status}")
-
-print()
-
-# Recommend next step
-phase_order = ["research", "requirements", "design", "tasks", "execute", "verify", "ship"]
-for p in phase_order:
-    st = s.get('phase_status',{}).get(p, 'not_started')
-    if st in ("not_started", "in_progress"):
-        print(f"Next step: /curdx-flow:{p}")
-        break
-else:
-    print("All phases complete! Use /curdx-flow:status to see details.")
-PYEOF
+cat > ".flow/specs/$SPEC_NAME/.progress.md" <<MD
+# Progress Log — $SPEC_NAME
+
+**Goal**: $GOAL
+**Mode**: $FLAG_MODE
+**Created**: $(date -u +%Y-%m-%d)
+
+## Decisions
+(populated during /curdx-flow:spec)
+
+## Learnings
+(populated during /curdx-flow:implement)
+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.
 
-## Step 5: Summary Prompt
+## Mode semantics
+
+The `mode` field in `.state.json` drives behavior in later commands:
+
+| 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 |
+
+## Post-create reporting
 
 ```
-═══════════════════════════════════════════════
-✓ Spec ready: $SPEC_NAME
-
-Workflow:
-  1. /curdx-flow:research       ← research (deep exploration)
-  2. /curdx-flow:requirements   ← requirements (user stories + acceptance criteria)
-  3. /curdx-flow:design         ← design (architectural decisions, freeze choices)
-  4. /curdx-flow:tasks          ← task decomposition (auto-verifiable tasks)
-  
-  One-shot version: /curdx-flow:spec    ← run research/req/design/tasks in sequence
-
-Fast modes:
-  /curdx-flow:fast              ← skip spec and implement directly
-  /curdx-flow:sketch            ← UI prototype exploration
-═══════════════════════════════════════════════
+✓ Spec ready: <name>
+  Goal:  <goal>
+  Mode:  <mode>
+  Path:  .flow/specs/<name>/
+
+Next: /curdx-flow:spec
 ```
 
-## Error Recovery
+## References
 
-- `.flow/` does not exist → prompt `/curdx-flow:init`
-- spec-name invalid → provide kebab-case example
-- Spec directory corrupted → ask user whether to delete-and-rebuild or repair
+- State schema: `@${CLAUDE_PLUGIN_ROOT}/schemas/spec-state.schema.json`
+- Mode semantics: `@${CLAUDE_PLUGIN_ROOT}/knowledge/execution-strategies.md`