@curdx/flow 2.2.3 → 2.2.5

package/skills/init/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: init
-description: Initialize the CurdX-Flow project structure (create the .flow/ directory and core files)
+description: Initialize the .flow scaffold for the current repository.
 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
@@ -9,110 +9,41 @@ allowed-tools: [Read, Write, Bash, AskUserQuestion]
 
 # Initialize CurdX-Flow Project
 
-Create the `.flow/` directory structure in the current directory so CurdX-Flow can operate in this project.
+Bootstrap `.flow/` for the current repository. Keep the entrypoint focused on
+safe preflight checks, scaffold contracts, and next-step routing. Detailed init
+rules live in:
 
-## Execution Steps
+- `references/preflight.md`
+- `references/scaffold-contract.md`
+- `references/gitignore-and-health.md`
+- `references/next-steps.md`
 
-### Step 1: Check Environment
+## Arguments
 
-```bash
-# Confirm a reasonable project root
-pwd
-ls -la
-```
+`$ARGUMENTS` may include `--force`.
 
-- 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 inspect `.flow/` directly, or run `/curdx-flow:start --list` to see existing specs
+Use `references/preflight.md` for:
 
-### Step 2: Create Directory Skeleton
+- dangerous-root rejection
+- existing `.flow/` handling
+- `--force` repair semantics
 
-```bash
-mkdir -p .flow/specs
-mkdir -p .flow/_epics
-mkdir -p .flow/checkpoints
-mkdir -p .flow/threads
-mkdir -p .flow/seeds
-```
+`--force` is for scaffold repair, not blind overwrites.
 
-### Step 3: Generate Core Files from Templates
+## Scaffold Contract
 
-Read the files under `${CLAUDE_PLUGIN_ROOT}/templates/`, replace placeholders, and write to `.flow/`:
+Use `references/scaffold-contract.md` for the required directory skeleton,
+template rendering, and placeholder substitution contract.
 
-| Source template | Target file | Description |
-|-----------------|-------------|-------------|
-| `templates/PROJECT.md.tmpl` | `.flow/PROJECT.md` | Project vision (user fills in later) |
-| `templates/CONTEXT.md.tmpl` | `.flow/CONTEXT.md` | User preferences |
-| `templates/STATE.md.tmpl` | `.flow/STATE.md` | Cross-session state (empty) |
-| `templates/ROADMAP.md.tmpl` | `.flow/ROADMAP.md` | Roadmap |
-| `templates/config.json.tmpl` | `.flow/config.json` | Configuration (default standard mode) |
+## Gitignore and Health
 
-Placeholders:
-- `{{PROJECT_NAME}}` — inferred from the current directory name (user may be asked)
-- `{{CREATED_DATE}}` — `$(date +%Y-%m-%d)`
-- `{{USER_NAME}}` — from git config
+Use `references/gitignore-and-health.md` for:
 
-### Step 4: Update `.gitignore`
+- runtime ignore entries
+- committed-vs-runtime file boundaries
+- doctor / dependency health guidance
 
-Append (if not already present):
+## Output and Handoff
 
-```
-# CurdX-Flow runtime files
-.flow/checkpoints/
-.flow/threads/
-.flow/seeds/
-.flow/.active-spec
-.flow/specs/*/.state.json
-.flow/specs/*/.progress.md
-.flow/_epics/*/.epic-state.json
-```
-
-**Note**: the primary state files (PROJECT.md / CONTEXT.md / STATE.md / ROADMAP.md / config.json)
-**should be committed to version control** so team members share the same view.
-
-### Step 5: Health Check
-
-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
-
-Output:
-
-```
-✓ CurdX-Flow project initialized
-  .flow/
-  ├── PROJECT.md       ← fill in your project vision
-  ├── CONTEXT.md       ← fill in your preferences
-  ├── STATE.md
-  ├── ROADMAP.md
-  └── config.json (mode: standard)
-
-Next steps (in order):
-  1. Edit .flow/PROJECT.md to add the project goal
-  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:
-  5. /curdx-flow:start <name> "<goal>"  — kick off the first spec
-```
-
-## Error Handling
-
-- Directory creation failure → report the specific error (permissions/disk/path issue)
-- Missing template file → check whether `${CLAUDE_PLUGIN_ROOT}/templates/` is complete
-- User interrupts with Ctrl+C → leave no partial state, prompt that re-running is safe
+The user-facing success output and route to `/curdx-flow:start` live in
+`references/next-steps.md`.

package/skills/init/references/gitignore-and-health.md

@@ -0,0 +1,26 @@
+# Init Gitignore and Health — Runtime Hygiene
+
+Append these runtime-only entries to `.gitignore` if they are missing:
+
+```gitignore
+# CurdX-Flow runtime files
+.flow/checkpoints/
+.flow/threads/
+.flow/seeds/
+.flow/.active-spec
+.flow/specs/*/.state.json
+.flow/specs/*/.progress.md
+.flow/_epics/*/.epic-state.json
+```
+
+The canonical shared files should stay committed:
+
+- `.flow/PROJECT.md`
+- `.flow/CONTEXT.md`
+- `.flow/STATE.md`
+- `.flow/ROADMAP.md`
+- `.flow/config.json`
+
+Do not spawn a separate CLI subprocess from inside the skill just to show the
+doctor output. If the user wants the full environment report, route them to
+run `npx @curdx/flow doctor` in a terminal.

package/skills/init/references/next-steps.md

@@ -0,0 +1,22 @@
+# Init Handoff — What to Tell the User Next
+
+Success output should confirm the scaffold exists and route the user into the
+main workflow:
+
+```text
+✓ CurdX-Flow project initialized
+  .flow/
+  ├── PROJECT.md
+  ├── CONTEXT.md
+  ├── STATE.md
+  ├── ROADMAP.md
+  └── config.json
+
+Next:
+  1. Fill in .flow/PROJECT.md with the project goal
+  2. Run npx @curdx/flow doctor if environment health needs verification
+  3. Start the first spec with /curdx-flow:start <name> "<goal>"
+```
+
+If `--force` repaired a partial scaffold, say that the existing project context
+was preserved and only missing runtime pieces were backfilled.

package/skills/init/references/preflight.md

@@ -0,0 +1,15 @@
+# Init Preflight — Safe Bootstrap Rules
+
+Before writing `.flow/`:
+
+- confirm the current directory is the intended repository root
+- reject dangerous locations such as `/`, the home directory, or other obvious
+  non-project folders
+- if `.flow/` already exists and `--force` is absent, stop and route the user
+  to inspect it or run `/curdx-flow:start --list`
+
+`--force` means "repair or complete the scaffold" rather than "overwrite user
+content". Existing committed files such as `.flow/PROJECT.md`,
+`.flow/CONTEXT.md`, `.flow/STATE.md`, `.flow/ROADMAP.md`, and
+`.flow/config.json` should be preserved unless the user explicitly asks to
+replace them.

package/skills/init/references/scaffold-contract.md

@@ -0,0 +1,27 @@
+# Init Scaffold Contract — What Must Be Created
+
+Create the runtime skeleton:
+
+- `.flow/specs/`
+- `.flow/_epics/`
+- `.flow/checkpoints/`
+- `.flow/threads/`
+- `.flow/seeds/`
+
+Render the canonical scaffold files from `${CLAUDE_PLUGIN_ROOT}/templates/`:
+
+- `templates/PROJECT.md.tmpl` -> `.flow/PROJECT.md`
+- `templates/CONTEXT.md.tmpl` -> `.flow/CONTEXT.md`
+- `templates/STATE.md.tmpl` -> `.flow/STATE.md`
+- `templates/ROADMAP.md.tmpl` -> `.flow/ROADMAP.md`
+- `templates/config.json.tmpl` -> `.flow/config.json`
+
+Populate placeholders with:
+
+- `{{PROJECT_NAME}}` from the current directory name unless the user gave a
+  better project label
+- `{{CREATED_DATE}}` from the current date
+- `{{USER_NAME}}` from git config when available
+
+Create missing scaffold files. Do not overwrite user-edited canonical files
+unless the user explicitly asks for a reset.

package/skills/review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review
-description: "Run two-stage review: spec compliance first, code quality second. Optional flags add adversarial, edge-case, and DevEx passes."
+description: Run two-stage review with optional 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
@@ -10,174 +10,66 @@ allowed-tools: [Read, Bash, Agent, Grep, Glob]
 # Two-Stage Code Review
 
 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`.
+- `verify` checks whether the spec's user-visible goals work
+- `review` checks whether the implementation is correct, aligned, and maintainable
+
+Keep this entrypoint focused on review routing, pass selection, and final
+report handoff.
+
+When this skill is used for follow-up work after prior review comments, apply
+`@${CLAUDE_PLUGIN_ROOT}/knowledge/review-feedback-intake.md` first so accepted
+fixes and technical pushback are recorded in `.progress.md`.
+
+Detailed review protocols live in:
+
+- `references/preflight.md`
+- `references/stage-execution.md`
+- `references/optional-passes.md`
+- `references/report-contract.md`
+- `references/reporting.md`
 
 ## Flags
 
 | 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. |
-| `--devex` | off | Apply the DevEx audit: naming, comments, structure, error handling, setup, types, tests, and developer loop. Gate: `@${CLAUDE_PLUGIN_ROOT}/gates/devex-gate.md`. |
+| `--adversarial` | off (`enterprise` -> on) | Add an adversarial review pass across applicable categories. |
+| `--edge-case` | off (`enterprise` -> on) | Add edge-case hunting across applicable categories. Produces a test-gap checklist. |
+| `--devex` | off (`enterprise` -> on) | Add the DevEx audit for naming, comments, structure, error handling, setup, types, tests, and developer loop. |
 
 ## Preflight
 
-```bash
-[ ! -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; }
+Use `references/preflight.md` for:
 
-# 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)
-FLAG_DEVEX=$(echo "$ARGUMENTS" | grep -q -- '--devex' && echo 1 || echo 0)
-```
-
-## Stage 1 — Spec compliance
+- `.flow/` and active-spec checks
+- required artifact checks
+- mode-aware `--stage`, `--adversarial`, `--edge-case`, and `--devex`
+  normalization
 
-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
-
-Output: Stage-1 section of the report with any compliance gaps.
-
-## Stage 2 — Code quality
-
-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
-
-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?
-
-**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`.
-
-## 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
-
-Output: test-gap checklist with suggested test cases.
-
-## Optional: DevEx audit
-
-If `--devex`:
-Pass the DevEx gate at `@${CLAUDE_PLUGIN_ROOT}/gates/devex-gate.md` as
-additional context to `flow-reviewer`. The gate adds these dimensions to
-Stage 2:
-
-1. **Naming** — identifier clarity, consistency across modules.
-2. **Comments** — only non-obvious WHY; no redundant WHAT.
-3. **Structure** — file and function sizes, colocation of related code.
-4. **Error handling** — at system boundaries only; no defensive guards inside trusted paths.
-5. **Setup** — `npm install && npm test` green on a fresh clone.
-6. **Types** — strictness, no unexplained `any` / `unknown`.
-7. **Tests** — failure messages, fixture clarity, no flake.
-8. **Dev loop** — time from code-change to feedback.
-
-`flow-reviewer` is NOT edited for `--devex` — the gate file is injected
-into the reviewer dispatch prompt as reference context, so the agent
-stays generic. Output: a "DevEx" section in the review report with
-per-dimension verdicts.
-
-## Report
-
-**Landing check**: sub-agent responses can be truncated. After dispatching review agents, verify the report actually landed on disk:
-
-```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
-```
-
-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)
-...
-
-## DevEx (if run)
-- Naming:         <verdict>
-- Structure:      <verdict>
-- Error handling: <verdict>
-- Setup:          <verdict>
-- Types:          <verdict>
-- Tests:          <verdict>
-- Dev loop:       <verdict>
-
-## Verdict
-- [ ] APPROVED
-- [X] CHANGES REQUIRED — <n> blockers
-- [ ] REJECTED
-```
+## Stage Execution
 
-## Reporting
+Stage responsibilities, reviewer prompts, and pass/fail expectations live in
+`references/stage-execution.md`.
+
+- Stage 1 -> `flow-reviewer` in spec-compliance mode
+- Stage 2 -> `flow-reviewer` in code-quality mode
 
-```
-✓ Review complete
-  Stage 1 findings: <n>
-  Stage 2 findings: <n>
-  Adversarial findings: <n>   (if --adversarial)
-  Edge-case gaps: <n>         (if --edge-case)
-  DevEx findings: <n>         (if --devex)
-  Verdict: CHANGES REQUIRED
+Optional adversarial, edge-case, and DevEx extensions live in
+`references/optional-passes.md`.
 
-Report: .flow/specs/<name>/review-report.md
+## Report Contract
+
+Landing checks, report shape, and final status output live in
+`references/report-contract.md`.
+
+The report lands at:
+
+- `.flow/specs/$SPEC_NAME/review-report.md`
+
+## Reporting
 
-Next: address blockers, then re-run /curdx-flow:review.
-```
+Use `references/reporting.md` for the final summary and rerun handoff.
 
 ## References
 

package/skills/review/references/optional-passes.md

@@ -0,0 +1,48 @@
+# Optional Passes — Adversarial, Edge Cases, DevEx
+
+## Adversarial Review
+
+If `FLAG_ADV=1` after preflight normalization, dispatch `flow-adversary`
+across applicable categories:
+
+1. What's missing?
+2. What's overengineered?
+3. What breaks first in production?
+4. What would a new maintainer misunderstand?
+5. What choice locks out a future option?
+6. What would a skeptical reviewer reject?
+
+Zero findings still requires proof-of-checking.
+
+## Edge-Case Hunting
+
+If `FLAG_EDGE=1` after preflight normalization, dispatch `flow-edge-hunter`
+across:
+
+1. boundary values
+2. concurrency and races
+3. network or partial failure
+4. malformed input
+5. auth and permission failure
+6. resource exhaustion
+7. time, locale, and timezone
+
+Output: a test-gap checklist.
+
+## DevEx Audit
+
+If `FLAG_DEVEX=1` after preflight normalization, inject
+`@${CLAUDE_PLUGIN_ROOT}/gates/devex-gate.md` into `flow-reviewer` so Stage 2
+also evaluates:
+
+1. naming
+2. comments
+3. structure
+4. error handling
+5. setup
+6. types
+7. tests
+8. developer loop
+
+Do not fork a separate custom reviewer for DevEx; keep `flow-reviewer` generic
+and extend it with the gate file.

package/skills/review/references/preflight.md

@@ -0,0 +1,38 @@
+# Review Preflight — Resolve Scope and Flags
+
+Before dispatching any reviewer:
+
+```bash
+[ ! -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; }
+
+SPEC_STATE=".flow/specs/$SPEC_NAME/.state.json"
+SPEC_MODE=$(grep -oP '"mode"\\s*:\\s*"\\K[^"]+' "$SPEC_STATE" 2>/dev/null || echo "standard")
+
+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)
+FLAG_DEVEX=$(echo "$ARGUMENTS" | grep -q -- '--devex' && echo 1 || echo 0)
+
+if [ "$SPEC_MODE" = "enterprise" ]; then
+  FLAG_ADV=1
+  FLAG_EDGE=1
+  FLAG_DEVEX=1
+fi
+```
+
+The entrypoint should resolve flags once, then route all review passes from
+that normalized configuration rather than reparsing later.
+
+`enterprise` mode auto-enables adversarial, edge-case, and DevEx review even
+when the user does not pass those flags explicitly. Manual flags still force
+the same behavior in non-enterprise modes.

package/skills/review/references/report-contract.md

@@ -0,0 +1,49 @@
+# Report Contract — Landing, Shape, Verdict
+
+## Landing Check
+
+Sub-agent responses can truncate before the report is written. After dispatching
+review agents, verify the report actually landed:
+
+```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
+```
+
+## Report Shape
+
+```markdown
+# Review Report — <spec-name>
+
+## Stage 1 — Spec Compliance
+...
+
+## Stage 2 — Code Quality
+...
+
+## Adversarial (if run)
+...
+
+## Edge Cases (if run)
+...
+
+## DevEx (if run)
+...
+
+## Verdict
+- [ ] APPROVED
+- [X] CHANGES REQUIRED — <n> blockers
+- [ ] REJECTED
+```
+
+## Final Output
+
+Summarize:
+
+- Stage 1 finding count
+- Stage 2 finding count
+- optional pass finding counts
+- final verdict
+- report path

package/skills/review/references/reporting.md

@@ -0,0 +1,20 @@
+# Review Reporting — Final Summary and Rerun Handoff
+
+End with a compact review summary:
+
+```text
+✓ Review complete
+  Stage 1 findings: <n>
+  Stage 2 findings: <n>
+  Adversarial findings: <n>   (if adversarial pass ran)
+  Edge-case gaps: <n>         (if edge-case pass ran)
+  DevEx findings: <n>         (if DevEx audit ran)
+  Verdict: CHANGES REQUIRED
+
+Report: .flow/specs/<name>/review-report.md
+
+Next: address blockers, then re-run /curdx-flow:review.
+```
+
+Keep the response outcome-focused. The report file is the artifact; the closing
+message only confirms counts, verdict, path, and next action.

package/skills/review/references/stage-execution.md

@@ -0,0 +1,32 @@
+# Review Stages — Core Two-Pass Protocol
+
+## Stage 1 — Spec Compliance
+
+Dispatch `flow-reviewer` in Stage 1 mode. It verifies:
+
+- every relevant `US`, `AC`, `FR`, and `NFR` in `requirements.md`
+- architecture decisions in `design.md`
+- `tasks.md` completion claims versus actual code
+- conventional commits versus declared task completion
+
+Output: the Stage 1 section of the review report with compliance gaps and
+evidence.
+
+## Stage 2 — Code Quality
+
+Dispatch `flow-reviewer` in Stage 2 mode. It checks:
+
+- naming, comments, and structure
+- error handling completeness
+- test quality and coverage
+- performance and resource concerns
+- security smells
+- Karpathy 4 principles
+
+Output: the Stage 2 section of the review report with prioritized findings.
+
+## Sequencing
+
+- `--stage=1` -> run only Stage 1
+- `--stage=2` -> run only Stage 2
+- `--stage=both` -> Stage 1 first, then Stage 2