@curdx/flow 1.1.11 → 2.0.0-beta.10

package/commands/init.md

@@ -22,7 +22,7 @@ ls -la
 - If the current directory is a dangerous location such as the home directory or a system directory, stop and ask the user to switch
 - If `.flow/` already exists:
   - With `--force` → continue but warn about overwriting
-  - Without `--force` → stop and prompt the user to run `/curdx-flow:status` to inspect the existing state
+  - Without `--force` → stop and prompt the user to inspect `.flow/` directly, or run `/curdx-flow:start --list` to see existing specs
 
 ### Step 2: Create Directory Skeleton
 
@@ -71,9 +71,20 @@ Append (if not already present):
 
 ### Step 5: Health Check
 
-Run `/curdx-flow:doctor` (or inline its checks) to verify:
-- 3 MCPs started (context7 / sequential-thinking / chrome-devtools)
-- Recommended plugins status (pua / claude-mem / frontend-design)
+Do NOT shell out to a new terminal for this step — you are already inside
+Claude Code. Verify inline via the information the plugin already has:
+
+- Read `~/.claude/plugins/data/curdx-flow/.deps-checked` (optional — the
+  SessionStart hook already refreshes this once per day).
+- If the user asks for the full report, suggest they run
+  `npx @curdx/flow doctor` in a separate terminal — don't try to spawn
+  it from inside the Claude Code session (output won't render cleanly
+  and the user has to alt-tab to see it).
+
+Items the CLI doctor covers (for user reference):
+- 2 bundled MCPs (context7 / sequential-thinking) — visible in `claude mcp list`
+- 4 recommended plugins (pua / claude-mem / frontend-design / chrome-devtools-mcp)
+- Runtime PATH guards for `bun` / `uv` (relevant only when claude-mem is installed)
 
 ### Step 6: Prompt Next Steps
 
@@ -90,9 +101,9 @@ Output:
 
 Next steps (in order):
   1. Edit .flow/PROJECT.md to add the project goal
-  2. /curdx-flow:install-deps   — install recommended plugins (if not installed)
-  3. /curdx-flow:doctor         — verify health
-  4. /curdx-flow:status         — view project status
+  2. (already handled) — recommended plugins installed via `npx @curdx/flow install --all`
+  3. npx @curdx/flow doctor      — verify health
+  4. /curdx-flow:start <name> "<goal>"  — begin your first feature spec
   
   Start development (after Phase 1 ships):
   5. /curdx-flow:start <name> "<goal>"  — kick off the first spec

package/commands/review.md

@@ -1,168 +1,152 @@
 ---
 name: review
-description: Two-Stage Review — Stage 1 spec compliance + Stage 2 code quality. Applies enabled Gates. Dispatches flow-reviewer.
-argument-hint: "[spec-name] [--adversarial | --edge-case | --both]"
+description: Two-stage code review — Stage 1 spec compliance, Stage 2 code quality. Optional flags add adversarial review or edge-case hunting.
+argument-hint: "[--stage=<1|2|both>] [--adversarial] [--edge-case]"
 allowed-tools: [Read, Bash, Task, Grep, Glob]
 ---
 
-# Flow Review — Two-Stage Code Review
+# Two-Stage Code Review
 
-@${CLAUDE_PLUGIN_ROOT}/knowledge/two-stage-review.md
+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).
 
-Dispatches the `flow-reviewer` agent to perform a Two-Stage Review: Stage 1 compliance + Stage 2 quality.
-Optionally layer on deep reviews from `flow-adversary` and `flow-edge-hunter`.
+## Flags
 
-## When to use
+| Flag | Default | Purpose |
+|------|---------|---------|
+| `--stage=<1\|2\|both>` | `both` | Stage 1 = spec compliance only. Stage 2 = code quality only. `both` = sequential. |
+| `--adversarial` | off | Add an adversarial review pass across applicable categories (zero findings requires proof-of-checking, not fabrication). |
+| `--edge-case` | off | Add edge-case hunting across applicable categories. Produces a test-gap checklist. |
 
-- After `/curdx-flow:verify` passes
-- Before PR
-- When the user explicitly requests a deep review (add --adversarial / --edge-case / --both)
-
-## Step 1: Parse arguments
+## Preflight
 
 ```bash
-ARGS="$ARGUMENTS"
-ADV=0; EDGE=0
-case "$ARGS" in
-    *--both*)        ADV=1; EDGE=1 ;;
-    *--adversarial*) ADV=1 ;;
-    *--edge-case*)   EDGE=1 ;;
-esac
-
-SPEC_NAME=$(echo "$ARGS" | sed 's/--[a-z-]*//g' | xargs)
-[ -z "$SPEC_NAME" ] && SPEC_NAME=$(cat .flow/.active-spec 2>/dev/null)
-[ -z "$SPEC_NAME" ] && { echo "❌ No active spec"; exit 1; }
+[ ! -d ".flow" ] && { echo "✗ Not a CurDX-Flow project."; exit 1; }
+
+SPEC_NAME=$(cat .flow/.active-spec 2>/dev/null)
+[ -z "$SPEC_NAME" ] && { echo "✗ No active spec."; exit 1; }
+
+# Review needs a design.md + implementation to compare against
+for f in design.md; do
+  [ ! -f ".flow/specs/$SPEC_NAME/$f" ] && {
+    echo "✗ Missing $f. Run /curdx-flow:spec first.";
+    exit 1;
+  }
+done
+
+FLAG_STAGE=$(echo "$ARGUMENTS" | grep -oP -- '--stage=\K[^\s]+' || echo "both")
+FLAG_ADV=$(echo "$ARGUMENTS" | grep -q -- '--adversarial' && echo 1 || echo 0)
+FLAG_EDGE=$(echo "$ARGUMENTS" | grep -q -- '--edge-case' && echo 1 || echo 0)
 ```
 
-## Step 2: Preflight checks
+## Stage 1 — Spec compliance
 
-```bash
-DIR=".flow/specs/$SPEC_NAME"
+Dispatch `flow-reviewer` in Stage 1 mode. It checks:
+- Implementation actually addresses every US / AC / FR / NFR in `requirements.md`
+- Code structure reflects AD-NN decisions from `design.md`
+- Task checklist in `tasks.md` is genuinely complete (all tasks marked `[x]` have real code)
+- Conventional-commit log (`git log`) matches the tasks declared completed
 
-# If /curdx-flow:verify hasn't been run, prompt to run it first
-if [ ! -f "$DIR/verification-report.md" ]; then
-    echo "⚠ /curdx-flow:verify not run. Recommend running goal-reverse verification first."
-    echo "Continue? (y/N)"
-    # AskUserQuestion
-fi
-```
+Output: Stage-1 section of the report with any compliance gaps.
 
-## Step 3: Dispatch flow-reviewer (core)
+## Stage 2 — Code quality
 
-```
-Task:
-  subagent_type: general-purpose
-  description: "Review $SPEC_NAME"
-  prompt: |
-    You are the flow-reviewer agent. Full definition:
-    ${CLAUDE_PLUGIN_ROOT}/agents/flow-reviewer.md
-    
-    Spec files to read:
-    - .flow/specs/$SPEC_NAME/requirements.md
-    - .flow/specs/$SPEC_NAME/design.md
-    - .flow/specs/$SPEC_NAME/tasks.md
-    - .flow/specs/$SPEC_NAME/.state.json
-    - .flow/specs/$SPEC_NAME/verification-report.md (if exists)
-    
-    Enabled Gates (from .flow/config.json):
-    - karpathy-gate (always)
-    - verification-gate (always)
-    - tdd-gate (standard+)
-    - coverage-audit-gate (standard+)
-    
-    Tasks:
-    Stage 1: Spec compliance review
-      - Judge each FR / AC / AD / error path as ✓/⚠/✗
-      - Check Out of Scope adherence
-    
-    Stage 2: Code quality review
-      - Apply all enabled Gates
-      - Emit per-Gate check results
-    
-    Combined verdict:
-      - APPROVED / APPROVED_WITH_WARNINGS / NEEDS_FIXES / BLOCKED
-    
-    Output:
-    .flow/specs/$SPEC_NAME/review-report.md
-    
-    Return a brief to me: Stage 1/2 verdicts, blocking/warning counts, and the top 3 fix suggestions
-```
+Dispatch `flow-reviewer` in Stage 2 mode. It checks:
+- Naming, comments, structure
+- Error handling completeness
+- Test coverage and test quality
+- Performance / resource usage concerns
+- Security smells (not a full security audit — that's `security-audit` skill)
+- Karpathy 4 principles applied
 
-## Step 4 (optional): Dispatch flow-adversary
+Output: Stage-2 section of the report.
+
+## Optional: adversarial review
 
 If `--adversarial`:
+Dispatch `flow-adversary`. It scans the applicable categories (Architecture / Implementation / Testing / Security / Maintainability / UX — skip N/A with reason) using `sequential-thinking` proportional to the residual uncertainty, probing:
+1. What's missing?
+2. What's overengineered?
+3. What would break first in production?
+4. What's undocumented that a new maintainer would misunderstand?
+5. What decision locks us out of a future option?
+6. What would a skeptical reviewer reject?
 
-```
-Task:
-  subagent_type: general-purpose
-  description: "Adversarial review $SPEC_NAME"
-  prompt: |
-    You are the flow-adversary agent. Full definition:
-    ${CLAUDE_PLUGIN_ROOT}/agents/flow-adversary.md
-    
-    Core rule: zero findings are forbidden — must find ≥ 3 categories of issues
-    
-    Scan:
-    - .flow/specs/$SPEC_NAME/*.md
-    - Related code (git diff)
-    - Recent commits
-    
-    Use sequential-thinking ≥ 12 rounds (2 rounds × 6 dimensions)
-    
-    Output: .flow/specs/$SPEC_NAME/adversarial-review.md
-```
+**Zero findings requires proof-of-checking, not fabrication** — honest "clean" verdicts are fine if the agent lists what it examined. Per `@${CLAUDE_PLUGIN_ROOT}/gates/adversarial-review-gate.md`.
 
-## Step 5 (optional): Dispatch flow-edge-hunter
+## Optional: edge-case hunting
 
 If `--edge-case`:
+Dispatch `flow-edge-hunter` across the applicable categories (skip N/A with one-line reason):
+1. Boundary values (0, MAX, empty, one-over-limit)
+2. Concurrency / race conditions
+3. Network failure / partial failure
+4. Malformed input
+5. Permission / auth failure
+6. Resource exhaustion
+7. Time / locale / timezone
 
-```
-Task:
-  subagent_type: general-purpose
-  description: "Edge-case scan $SPEC_NAME"
-  prompt: |
-    You are the flow-edge-hunter agent. Full definition:
-    ${CLAUDE_PLUGIN_ROOT}/agents/flow-edge-hunter.md
-    
-    Scan the subject's coverage across 7 categories:
-    - Boundary values / nulls / concurrency / error recovery / security / i18n / performance
-    
-    Use sequential-thinking ≥ 3 rounds per category
-    
-    Output: .flow/specs/$SPEC_NAME/edge-cases.md
-```
+Output: test-gap checklist with suggested test cases.
 
-## Step 6: Read reports + aggregate verdict
+## Report
 
-```bash
-MAIN_REPORT="$DIR/review-report.md"
-ADV_REPORT="$DIR/adversarial-review.md"
-EDGE_REPORT="$DIR/edge-cases.md"
+**Landing check**: sub-agent responses can be truncated. After dispatching review agents, verify the report actually landed on disk:
 
-# Parse the verdict from review-report.md
-VERDICT=$(grep -E "^## Verdict:" "$MAIN_REPORT" | head -1 | sed 's/## Verdict: //')
+```bash
+REPORT=".flow/specs/$SPEC_NAME/review-report.md"
+if [ ! -f "$REPORT" ] || [ "$(wc -c < "$REPORT" 2>/dev/null | tr -d ' ')" -lt 300 ]; then
+  echo "⚠ Report missing or truncated. Re-dispatching flow-reviewer with a terse 'Write the report now, no narration' prompt."
+fi
 ```
 
-## Step 7: Output to user
+Consolidated output: `.flow/specs/$SPEC_NAME/review-report.md`:
+
+```markdown
+# Review Report — <spec-name>
+
+## Stage 1 — Spec Compliance
+- ✓ FR-01: implemented in src/auth.ts
+- ✗ FR-04: missing — add handler for token refresh
+- ⚠ AC-2.1: no integration test asserting 403 on expired token
 
+## Stage 2 — Code Quality
+- Blocker: duplicated error-handling pattern in 3 files — extract helper
+- Warning: function foo() in src/a.ts: 90 lines, split
+- Nit: inconsistent naming (getUserId vs fetchUser)
+
+## Adversarial (if run)
+...
+
+## Edge Cases (if run)
+...
+
+## Verdict
+- [ ] APPROVED
+- [X] CHANGES REQUIRED — <n> blockers
+- [ ] REJECTED
 ```
-✓ Review complete: $SPEC_NAME
 
-Main report: .flow/specs/$SPEC_NAME/review-report.md
-  Verdict: $VERDICT
+## Reporting
+
+```
+✓ Review complete
+  Stage 1 findings: <n>
+  Stage 2 findings: <n>
+  Adversarial findings: <n>   (if --adversarial)
+  Edge-case gaps: <n>         (if --edge-case)
+  Verdict: CHANGES REQUIRED
 
-$([ "$ADV" = "1" ] && echo "Adversarial review: $ADV_REPORT")
-$([ "$EDGE" = "1" ] && echo "Edge-case scan: $EDGE_REPORT")
+Report: .flow/specs/<name>/review-report.md
 
-Next steps:
-$([ "$VERDICT" = "APPROVED" ] && echo "  ✓ Proceed to /curdx-flow:ship (Phase 6+)")
-$([ "$VERDICT" = "APPROVED_WITH_WARNINGS" ] && echo "  ⚠ Recommend fixing warnings first, then /curdx-flow:ship")
-$([ "$VERDICT" = "NEEDS_FIXES" ] && echo "  ❌ Fix blockers → /curdx-flow:implement --task=... → /curdx-flow:review re-review")
-$([ "$VERDICT" = "BLOCKED_BY_SPEC" ] && echo "  ❌ Back to /curdx-flow:implement to fill missing FR/AD")
+Next: address blockers, then re-run /curdx-flow:review.
 ```
 
-## Error recovery
+## References
 
-- review-report.md generation fails → check agent turn limit, reduce spec scope
-- Agent returns no findings (violates adversarial zero-tolerance) → agent auto-triggers Round 2
-- Multiple concurrent agents produce conflicting files → run sequentially, not in parallel
+- `flow-reviewer` agent: `@${CLAUDE_PLUGIN_ROOT}/agents/flow-reviewer.md`
+- `flow-adversary` agent: `@${CLAUDE_PLUGIN_ROOT}/agents/flow-adversary.md`
+- `flow-edge-hunter` agent: `@${CLAUDE_PLUGIN_ROOT}/agents/flow-edge-hunter.md`
+- `adversarial-review-gate`: `@${CLAUDE_PLUGIN_ROOT}/gates/adversarial-review-gate.md`
+- `edge-case-gate`: `@${CLAUDE_PLUGIN_ROOT}/gates/edge-case-gate.md`
+- Knowledge: `@${CLAUDE_PLUGIN_ROOT}/knowledge/two-stage-review.md`

package/commands/spec.md

@@ -1,135 +1,177 @@
 ---
 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
+## Flag parsing
 
 ```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
+# $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
 ```
 
-## Step 3: Execute the 4 stages in sequence
+## Phase resolution
 
-### Phase 1: Research
+The ordered pipeline is `research → requirements → design → tasks`. Resolve which phases to run:
 
-```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)
-fi
-```
+- 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`.
 
-**Implementation 1** (recommended): Dispatch the agent directly, skipping SlashCommand:
+Read and update `.state.json.phase` after each phase succeeds.
 
-Call the Task tool with the same content as the Task call in `/curdx-flow:research` (reading flow-researcher.md).
+## Phase execution
 
-**Implementation 2**: If Claude Code supports the SlashCommand tool chain:
-```
-SlashCommand: /curdx-flow:research $SPEC_NAME
-```
+For each phase in the resolved list, dispatch a sub-agent via the `Task` tool:
 
-### Intermediate confirmation after each stage
+### 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.
 
-```
-✓ research stage complete
+### 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 (when they clarify). Uses `sequential-thinking` MCP proportional to the genuine tradeoff surface.
 
-Key findings:
-  - ...
-  - ...
+### 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.
 
-⚠ The following open questions were found; recommend answering first:
-  Q1: ...
+After each phase completes successfully, update `.state.json`:
 
-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
+```json
+{
+  "phase": "<just-completed-phase>",
+  "phase_status": { "<phase>": "completed" },
+  "updated": "<ISO8601 timestamp>"
+}
 ```
 
-Use AskUserQuestion for the choice.
+### Artifact landing check (mandatory after every phase)
 
-### Phase 2: Requirements
+Sub-agent responses can be truncated by the model's output-length limit, which means the `Write` tool call for the phase's Markdown artifact may never fire. Do NOT trust the agent's return value alone — always verify the file actually landed.
 
-If continue, dispatch flow-product-designer (mirroring the Task call in `/curdx-flow:requirements`).
+For each phase just dispatched, run:
 
-Confirm again after completion.
+```bash
+ARTIFACT=".flow/specs/$SPEC_NAME/<phase>.md"
+if [ ! -f "$ARTIFACT" ]; then
+  echo "⚠ $ARTIFACT did not land. Re-dispatching <phase> agent with an explicit 'write the file' prompt."
+  # Re-dispatch the same agent, but in the prompt, front-load:
+  #   "Your ONLY job is to call the Write tool with the full <phase>.md content now.
+  #    Do not explain. Do not narrate. Write the file and stop."
+  # This pattern produces an artifact even when prior verbosity caused truncation.
+fi
+
+# Minimum-size sanity check — if the file is <500 bytes, the write likely truncated
+if [ -f "$ARTIFACT" ] && [ "$(wc -c < "$ARTIFACT" | tr -d ' ')" -lt 500 ]; then
+  echo "⚠ $ARTIFACT looks truncated (<500 bytes). Re-dispatching to complete it."
+fi
+```
 
-### Phase 3: Design
+Only advance `.state.json.phase` after both the file exists AND passes the size sanity check. If a re-dispatch also fails to produce the artifact, stop and surface the issue to the user instead of silently advancing — that prevents later phases from consuming an empty upstream file.
 
-If continue, dispatch flow-architect (mirroring the Task call in `/curdx-flow:design`).
+## Optional planning review
 
-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.
+If `--review` (or `--review=<dims>`) is present:
 
-### Phase 4: Tasks
+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):
 
-If continue, dispatch flow-planner (mirroring the Task call in `/curdx-flow: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 |
 
-## Step 4: Final summary
+4. Aggregate findings into `.flow/specs/<active>/spec-review.md` with one section per dim and a consolidated verdict (GO / GO-WITH-CHANGES / HOLD).
+
+## Reporting
+
+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`