@curdx/flow 2.0.21 → 2.1.0

package/cli/install-required-plugins.js

@@ -0,0 +1,44 @@
+/**
+ * Install required Claude Code companion plugins (today: context7-plugin).
+ * Post-install, dispatches Context7 API-key configuration if applicable.
+ */
+
+import { addPluginMarketplace, installPlugin } from "./lib/claude-ops.js";
+import { REQUIRED_PLUGINS } from "./registry.js";
+import { color, log, resultLastLine } from "./utils.js";
+import { installContext7Config } from "./install-context7-config.js";
+
+export async function installRequiredPlugins({ yes, language, config }) {
+  log.blank();
+  log.info("Installing required Claude Code plugins...");
+  for (const plugin of REQUIRED_PLUGINS) {
+    console.log(`  ${color.cyan("▸")} Installing ${color.bold(plugin.name)}...`);
+    const ma = await addPluginMarketplace(plugin);
+    if (ma.code !== 0 && !ma.stderr.includes("already")) {
+      log.warn(`     marketplace add warning: ${ma.stderr.trim().split("\n")[0]}`);
+    }
+
+    const ir = await installPlugin(plugin);
+    if (ir.code === 0) {
+      console.log(`  ${color.green("✓")} ${plugin.name} installed`);
+
+      if (plugin.requiresConfig && plugin.configType === "apiKey" && !yes) {
+        await installContext7Config(plugin, language, config);
+      }
+    } else {
+      console.log(
+        `  ${color.red("✗")} ${plugin.name} install failed: ${resultLastLine(ir)}`
+      );
+      console.log(
+        color.dim(
+          `     Run manually: claude plugin marketplace add --scope ${plugin.scope} ${plugin.marketplaceSource}`
+        )
+      );
+      console.log(
+        color.dim(
+          `     Then: claude plugin install --scope ${plugin.scope} ${plugin.installSpec}`
+        )
+      );
+    }
+  }
+}

package/cli/protocols-body.md

@@ -3,10 +3,11 @@
 All operations MUST strictly follow these system constraints:
 
 ### Language separation
-- **Tool / persistence layer = English**: commit messages, code, comments, file names, function names, PR descriptions, CLI log output, error messages thrown by code, and any artifact persisted to the repository or shown in a developer terminal.
+- **Tool / persistence layer = English**: commit messages, code, comments, file names, function names, PR descriptions, error messages thrown by code, and any artifact persisted to the repository or consumed by agents / skills / hooks at runtime.
 - **Conversational layer = Simplified Chinese**: chat replies, explanations and reasoning shown directly to the human in a conversation interface (e.g. Claude Code chat).
+- **Installer UX (`cli/` only, narrow carve-out)**: interactive menus printed by the npm-published installer under `cli/**` may present localized Chinese options because they serve a human operator at install time. This carve-out does NOT apply to `agents/`, `skills/`, `commands/`, `gates/`, `hooks/`, `knowledge/`, documentation, or any prose consumed by agents at runtime — those stay English.
 
-Rationale: English in the persistence/tool layer aligns with developer-tool industry norms (npm/git/cargo are all English) and keeps the codebase internationally collaborable. Chinese in the conversational layer matches the user's language preference. Mixing the two (e.g. Chinese commit messages, Chinese CLI log output) is a violation.
+Rationale: English in the persistence / tool / agent-input layer aligns with developer-tool industry norms (npm/git/cargo are all English) and keeps AI / agent adaptation reliable. Chinese in the conversational layer matches the user's language preference. The installer carve-out reflects the fact that installer menus are a human-to-human interaction surface, not agent input. Mixing the two (e.g. Chinese commit messages, Chinese strings inside agent prompts) is a violation.
 
 ### Discovery & reasoning
 - **Library / framework / API questions**: query `context7` MCP first. Do not rely on training memory.

package/hooks/scripts/session-start.sh

@@ -32,9 +32,12 @@ if [ "$LAST_CHECK" != "$TODAY" ]; then
   if command -v claude >/dev/null 2>&1; then
     INSTALLED="$(claude plugin list 2>/dev/null || true)"
 
-    echo "$INSTALLED" | grep -q 'pua'             || MISSING+=("pua")
-    echo "$INSTALLED" | grep -q 'claude-mem'      || MISSING+=("claude-mem")
-    echo "$INSTALLED" | grep -q 'frontend-design' || MISSING+=("frontend-design")
+    # Names must stay in lockstep with cli/registry.js RECOMMENDED_PLUGINS.
+    # Drift is guarded by test/registry-session-start-parity.test.js.
+    echo "$INSTALLED" | grep -q 'pua'                 || MISSING+=("pua")
+    echo "$INSTALLED" | grep -q 'claude-mem'          || MISSING+=("claude-mem")
+    echo "$INSTALLED" | grep -q 'frontend-design'     || MISSING+=("frontend-design")
+    echo "$INSTALLED" | grep -q 'chrome-devtools-mcp' || MISSING+=("chrome-devtools-mcp")
   fi
 
   if [ "${#MISSING[@]}" -gt 0 ]; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@curdx/flow",
-  "version": "2.0.21",
+  "version": "2.1.0",
   "description": "CLI installer for CurdX-Flow — AI engineering workflow meta-framework for Claude Code",
   "type": "module",
   "bin": {
@@ -16,7 +16,6 @@
     ".claude-plugin/",
     "agents/",
     "gates/",
-    "commands/",
     "hooks/",
     "knowledge/",
     "agent-preamble/",

package/schemas/config.schema.json

@@ -13,7 +13,7 @@
     },
     "mode": {
       "type": "string",
-      "enum": ["sketch", "fast", "standard", "enterprise", "autonomous"],
+      "enum": ["fast", "standard", "enterprise"],
       "description": "Default workflow depth for this project"
     },
     "execution": {

package/schemas/spec-state.schema.json

@@ -21,7 +21,7 @@
     },
     "mode": {
       "type": "string",
-      "enum": ["sketch", "fast", "standard", "enterprise", "autonomous"],
+      "enum": ["fast", "standard", "enterprise"],
       "default": "standard"
     },
     "strategy": {

package/skills/debug/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: debug
+description: Systematic debugging — 4-phase methodology (root cause → pattern → hypothesis → fix); three failures trigger architectural questioning. Routes to flow-debugger.
+argument-hint: "\"<bug description>\""
+context: fork
+agent: flow-debugger
+---
+
+# Systematic Debug
+
+Debug the bug described below using the 4-phase methodology in
+`@${CLAUDE_PLUGIN_ROOT}/knowledge/systematic-debugging.md`. This is NOT
+"retry until green" — each phase has a stop condition.
+
+**Bug description**: `$ARGUMENTS`
+
+If `$ARGUMENTS` is empty, print `Usage: /curdx-flow:debug "<bug description>"` and stop.
+
+## Context to gather before diagnosing
+
+- Recent commits: `git log --oneline -20`
+- Uncommitted changes: `git status --short`, `git diff --stat`
+- Active spec (if any): read `.flow/.active-spec`; if set, read
+  `.flow/specs/<active>/.progress.md` for related history.
+
+## Phase 1 — Root-cause investigation
+
+- Read the error carefully (stack trace + message + location).
+- Build a minimal reproduction.
+- Check recent changes that could have introduced the bug.
+- Trace the data flow from cause to symptom.
+- **Exit condition**: state the root cause in **one sentence**.
+  "maybe it's..." is not allowed.
+
+## Phase 2 — Pattern analysis
+
+- Find a working counter-example in the codebase (same path, different
+  input or neighboring module that behaves correctly).
+- Pinpoint the difference from the failing case.
+- Classify: **isolated case** (one location) vs. **systemic pattern**
+  (multiple siblings). If systemic, Phase 4 must sweep for siblings.
+
+## Phase 3 — Hypothesis and test
+
+- State ONE hypothesis.
+- Write the smallest test that distinguishes confirm vs. disprove.
+- Run the test in-memory (do not commit yet).
+- If disproved, return to Phase 1 with the new signal.
+
+## Phase 4 — Implement the fix
+
+1. Write a failing test; confirm it fails. Commit `test(<scope>): red - ...`.
+2. Fix the root cause (not the symptom). Confirm the failing test now
+   passes. Commit `fix(<scope>): green - ...`.
+3. Run the full regression suite; no regressions allowed.
+4. If Phase 2 classified as systemic, sweep for sibling occurrences and
+   fix them in the same stage. Optional third commit
+   `fix(<scope>): sweep - N similar cases`.
+
+## Three-failure guard (hard stop)
+
+If Phase 4 has tried 3 genuinely different approaches and all failed,
+**stop**. Do not try a 4th. Output the structured failure report:
+
+```
+⚠ Systematic debug halted after 3 attempts
+
+Attempts:
+  1. <approach 1>: <why it failed>
+  2. <approach 2>: <why it failed>
+  3. <approach 3>: <why it failed>
+
+Root-issue hypothesis: architecture | dependency | data | unknown
+Recommended next step: <user action — review architecture, ship a
+                       STATE.md D-NN deferral with @ts-expect-error,
+                       or request pairing>
+```
+
+## Forbidden
+
+- Prayer-driven programming (retry without a new hypothesis each round)
+- "Maybe it's ..." as a Phase 1 conclusion
+- A fix commit without a corresponding failing-test commit
+- Masking the root cause with null checks / try-catch
+- Fixing multiple unrelated things in one commit (one task = one commit)
+
+## Output to user (on success, ≤ 15 lines)
+
+```
+✓ Debug complete
+
+Root cause: <Phase 1 — one sentence>
+Pattern:    <Phase 2 — isolated or systemic>
+
+Fix commits:
+  - <sha>: test(<scope>): red - failing test
+  - <sha>: fix(<scope>): green - root-cause fix
+  - <sha>: fix(<scope>): sweep - N sibling cases    (if systemic)
+
+Verification: failing test now PASS ✓; full suite green ✓
+
+Learnings (candidate for .progress.md):
+  - <lesson>
+```

package/{commands/help.md → skills/help/SKILL.md}

@@ -48,15 +48,24 @@ Show the 9 core slash commands + 5 auto-invoked skills. Keep the table compact,
 
 ## `<command-name>` — command detail
 
-When the argument matches one of the 9 commands, read the corresponding `commands/<name>.md` from the plugin cache and present it cleanly:
+When the argument matches a slash name — one of the 9 primary workflows or one of the 5 auto-invoked skills — read the corresponding body and present it cleanly. The lookup tries the `skills/` layout first and falls back to the legacy `commands/` layout, which keeps help correct throughout the Phase 3 migration window:
 
 ```bash
-PLUGIN=$(ls -dt "$HOME/.claude/plugins/cache/curdx-flow-marketplace/curdx-flow/"*/ 2>/dev/null | head -1)
-CMD="$1"
-cat "$PLUGIN/commands/$CMD.md"
+CMD="$ARGUMENTS"
+[ -z "$CMD" ] && { echo "Usage: /curdx-flow:help <name>"; exit 1; }
+if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/${CMD}/SKILL.md" ]; then
+  cat "${CLAUDE_PLUGIN_ROOT}/skills/${CMD}/SKILL.md"
+elif [ -f "${CLAUDE_PLUGIN_ROOT}/commands/${CMD}.md" ]; then
+  cat "${CLAUDE_PLUGIN_ROOT}/commands/${CMD}.md"
+else
+  echo "Unknown: ${CMD}"
+  echo "Workflows: init start spec implement verify review fast debug help"
+  echo "Skills:    epic browser-qa ui-sketch security-audit brownfield-index"
+  exit 1
+fi
 ```
 
-If the argument isn't a known command, list the 9 candidates and the 5 skill names.
+If the argument isn't a known slash name, the block above prints the 14 candidates.
 
 ## `workflow` — standard workflow
 

package/{commands/implement.md → skills/implement/SKILL.md}

@@ -159,160 +159,19 @@ After the agent completes, read the output marker:
 
 ### Strategy: wave
 
-@${CLAUDE_PLUGIN_ROOT}/knowledge/wave-execution.md
+See `skills/implement/references/wave-execution.md` for the full walkthrough.
+Knowledge-layer canonical algorithm: `@${CLAUDE_PLUGIN_ROOT}/knowledge/wave-execution.md`.
 
-**Core**: consecutive `[P]` tasks form a wave, dispatch multiple Tasks in parallel within a single message, serial across waves.
+**Core**: consecutive `[P]` tasks form a wave; dispatch multiple Tasks in parallel within a single response; serial across waves. The execution loop is:
 
-#### Step 1: DAG Analysis
+1. **DAG analysis** — group remaining `[ ]` tasks by `[P]` / `[SEQUENTIAL]` / `[VERIFY]` tags; conflicting `Files` sets split into a new wave.
+2. **Pre-conflict detection** — within each wave, assert per-task `Files` are disjoint; auto-split if not.
+3. **Dispatch** — list multiple `Task(...)` tool calls in a single main-agent response (splitting across responses = serial degradation; nested `Task` dispatches forbidden). Each Task prompt follows the subagent strategy's uniform format (see `references/wave-execution.md` Step 3).
+4. **Aggregate** — parse each result for `TASK_COMPLETE` / `TASK_FAILED`; run post-hoc conflict detection via git diff to confirm executors only touched declared files.
+5. **Failure handling** — 0 failed → next wave; 1 failed → `config.wave_fail_policy` (`continue-on-single` or `stop-on-any`); ≥2 failed → likely environment issue, stop immediately; cumulative `failed_attempts >= 3` → stop, user intervention.
+6. **Progress feedback** — print a wave summary after each wave (see `references/wave-execution.md` Step 6).
 
-Read remaining `[ ]` tasks from tasks.md and group per the rules:
-
-```
-for task in remaining tasks:
-    if task has [SEQUENTIAL] or [VERIFY]:
-        → own wave (breaks parallelism)
-    elif task has [P]:
-        → check whether Files conflict with current_wave
-          conflict → start a new wave
-          no conflict → add to current_wave
-    else:
-        → own wave (no [P] = serial)
-```
-
-Output wave list:
-```
-Wave 1 [P×3]: 1.1 1.2 1.3
-Wave 2 [VERIFY]: 1.4
-Wave 3: 1.5
-Wave 4 [P×2]: 1.6 1.7
-```
-
-#### Step 2: Pre-Conflict Detection
-
-For each wave, verify that Files across all tasks are **disjoint**:
-
-```python
-for wave in waves:
-    all_files = []
-    for task in wave:
-        if set(task.files) & set(all_files):
-            warn(f"Within wave, {task.id} modifies the same file as a prior task")
-            # split into the next wave
-        all_files.extend(task.files)
-```
-
-If the planner mis-tagged `[P]` (modifies the same file), split the wave automatically at execution time rather than failing outright.
-
-#### Step 3: Dispatch a Single Wave (**key: within a single response**)
-
-```
-# List multiple Task tool calls in one response of the main agent:
-Task(description="Execute 1.1", prompt=<...flow-executor + task_id=1.1...>)
-Task(description="Execute 1.2", prompt=<...flow-executor + task_id=1.2...>)
-Task(description="Execute 1.3", prompt=<...flow-executor + task_id=1.3...>)
-```
-
-Each Task prompt follows a uniform format (similar to subagent strategy):
-
-```
-You are the flow-executor agent. Full definition:
-${CLAUDE_PLUGIN_ROOT}/agents/flow-executor.md
-
-Execute a single task:
-  spec_name: $SPEC_NAME
-  task_id: <specific ID, e.g., 1.2>
-  quick_mode: $QUICK
-
-**You may only modify the following files** (touching anything else is disallowed):
-  <task.files>
-
-Required reading:
-- .flow/specs/$SPEC_NAME/tasks.md
-- .flow/specs/$SPEC_NAME/.state.json  
-- .flow/specs/$SPEC_NAME/design.md (if referencing AD-NN)
-
-Output:
-- TASK_COMPLETE: <task_id>  or
-- TASK_FAILED: <task_id> + reason
-```
-
-**Not allowed**:
-- Splitting multiple Task calls across multiple responses (that is serial degradation)
-- Nesting another Task dispatch inside a Task
-
-#### Step 4: Aggregate Wave Results
-
-Wait for all Tasks to return:
-
-```python
-completed = []; failed = []
-for task, result in zip(wave, results):
-    if "TASK_COMPLETE" in result:
-        completed.append(task)
-    elif "TASK_FAILED" in result:
-        failed.append(task)
-
-# Post-hoc conflict detection (verify executors did not touch out-of-scope files)
-for task in completed:
-    actual_files = git_diff_files_touched_by(task)
-    declared = set(task.files)
-    unexpected = actual_files - declared
-    if unexpected:
-        warn(f"Task {task.id} modified undeclared files: {unexpected}")
-```
-
-#### Step 5: Wave Failure Handling
-
-```
-len(failed) == 0:
-  → continue to the next wave
-
-len(failed) == 1:
-  → failed_attempts += 1
-  → based on config.wave_fail_policy:
-      "continue-on-single": continue to the next wave, report failure at the end
-      "stop-on-any": stop immediately
-
-len(failed) >= 2:
-  → likely environment issue (missing deps/tsc error/permissions)
-  → stop immediately, suggest npx @curdx/flow doctor
-  
-failed_attempts >= 3 (cumulative):
-  → stop, user intervention required
-```
-
-#### Step 6: Progress Feedback
-
-```
-▶ Wave 2/5 complete
-  ✓ 1.1 feat(auth): create module skeleton (abc123)
-  ✓ 1.2 feat(user): create user types (def456)
-  ✓ 1.3 feat(session): init token module (ghi789)
-
-▶ Wave 3/5 starting (VERIFY)...
-```
-
-#### Configuration
-
-`.flow/config.json`:
-```json
-{
-  "execution": {
-    "strategy": "wave",
-    "max_parallel": 5,
-    "wave_fail_policy": "continue-on-single"
-  }
-}
-```
-
-- `max_parallel`: max N parallel within a wave (to avoid API rate limits, default 5)
-- `wave_fail_policy`: single-task failure behavior
-
-#### Pitfalls (see knowledge/wave-execution.md for the detailed version)
-
-- Stray `[P]` → conflict detection as a safety net
-- Wave too large → max_parallel auto-splits
-- Implicit read-write dependencies → planner should avoid this kind of `[P]`
+Configuration under `.flow/config.json.execution`: `strategy: "wave"`, `max_parallel: 5` (wave-parallel ceiling), `wave_fail_policy: "continue-on-single" | "stop-on-any"`.
 
 ### Strategy: stop-hook
 

package/skills/implement/references/wave-execution.md

@@ -0,0 +1,162 @@
+# Wave Execution Strategy — Detailed Walkthrough
+
+Skill-scoped reference for `skills/implement/SKILL.md`. Loaded only when the
+implement skill routes to the `wave` strategy. The knowledge-layer canonical
+algorithm lives in `@${CLAUDE_PLUGIN_ROOT}/knowledge/wave-execution.md`;
+this file is the walkthrough the skill itself embeds for implementers.
+
+**Core**: consecutive `[P]` tasks form a wave, dispatch multiple Tasks in
+parallel within a single message, serial across waves.
+
+## Step 1: DAG Analysis
+
+Read remaining `[ ]` tasks from tasks.md and group per the rules:
+
+```
+for task in remaining tasks:
+    if task has [SEQUENTIAL] or [VERIFY]:
+        → own wave (breaks parallelism)
+    elif task has [P]:
+        → check whether Files conflict with current_wave
+          conflict → start a new wave
+          no conflict → add to current_wave
+    else:
+        → own wave (no [P] = serial)
+```
+
+Output wave list:
+```
+Wave 1 [P×3]: 1.1 1.2 1.3
+Wave 2 [VERIFY]: 1.4
+Wave 3: 1.5
+Wave 4 [P×2]: 1.6 1.7
+```
+
+## Step 2: Pre-Conflict Detection
+
+For each wave, verify that Files across all tasks are **disjoint**:
+
+```python
+for wave in waves:
+    all_files = []
+    for task in wave:
+        if set(task.files) & set(all_files):
+            warn(f"Within wave, {task.id} modifies the same file as a prior task")
+            # split into the next wave
+        all_files.extend(task.files)
+```
+
+If the planner mis-tagged `[P]` (modifies the same file), split the wave automatically at execution time rather than failing outright.
+
+## Step 3: Dispatch a Single Wave (key: within a single response)
+
+```
+# List multiple Task tool calls in one response of the main agent:
+Task(description="Execute 1.1", prompt=<...flow-executor + task_id=1.1...>)
+Task(description="Execute 1.2", prompt=<...flow-executor + task_id=1.2...>)
+Task(description="Execute 1.3", prompt=<...flow-executor + task_id=1.3...>)
+```
+
+Each Task prompt follows a uniform format (similar to subagent strategy):
+
+```
+You are the flow-executor agent. Full definition:
+${CLAUDE_PLUGIN_ROOT}/agents/flow-executor.md
+
+Execute a single task:
+  spec_name: $SPEC_NAME
+  task_id: <specific ID, e.g., 1.2>
+  quick_mode: $QUICK
+
+**You may only modify the following files** (touching anything else is disallowed):
+  <task.files>
+
+Required reading:
+- .flow/specs/$SPEC_NAME/tasks.md
+- .flow/specs/$SPEC_NAME/.state.json
+- .flow/specs/$SPEC_NAME/design.md (if referencing AD-NN)
+
+Output:
+- TASK_COMPLETE: <task_id>  or
+- TASK_FAILED: <task_id> + reason
+```
+
+**Not allowed**:
+- Splitting multiple Task calls across multiple responses (that is serial degradation)
+- Nesting another Task dispatch inside a Task
+
+## Step 4: Aggregate Wave Results
+
+Wait for all Tasks to return:
+
+```python
+completed = []; failed = []
+for task, result in zip(wave, results):
+    if "TASK_COMPLETE" in result:
+        completed.append(task)
+    elif "TASK_FAILED" in result:
+        failed.append(task)
+
+# Post-hoc conflict detection (verify executors did not touch out-of-scope files)
+for task in completed:
+    actual_files = git_diff_files_touched_by(task)
+    declared = set(task.files)
+    unexpected = actual_files - declared
+    if unexpected:
+        warn(f"Task {task.id} modified undeclared files: {unexpected}")
+```
+
+## Step 5: Wave Failure Handling
+
+```
+len(failed) == 0:
+  → continue to the next wave
+
+len(failed) == 1:
+  → failed_attempts += 1
+  → based on config.wave_fail_policy:
+      "continue-on-single": continue to the next wave, report failure at the end
+      "stop-on-any": stop immediately
+
+len(failed) >= 2:
+  → likely environment issue (missing deps/tsc error/permissions)
+  → stop immediately, suggest npx @curdx/flow doctor
+
+failed_attempts >= 3 (cumulative):
+  → stop, user intervention required
+```
+
+## Step 6: Progress Feedback
+
+```
+▶ Wave 2/5 complete
+  ✓ 1.1 feat(auth): create module skeleton (abc123)
+  ✓ 1.2 feat(user): create user types (def456)
+  ✓ 1.3 feat(session): init token module (ghi789)
+
+▶ Wave 3/5 starting (VERIFY)...
+```
+
+## Configuration
+
+`.flow/config.json`:
+```json
+{
+  "execution": {
+    "strategy": "wave",
+    "max_parallel": 5,
+    "wave_fail_policy": "continue-on-single"
+  }
+}
+```
+
+- `max_parallel`: max N parallel within a wave (to avoid API rate limits, default 5)
+- `wave_fail_policy`: single-task failure behavior
+
+## Pitfalls
+
+See `@${CLAUDE_PLUGIN_ROOT}/knowledge/wave-execution.md` for the detailed version.
+
+- Stray `[P]` → conflict detection as a safety net
+- Wave too large → max_parallel auto-splits
+- Implicit read-write dependencies → planner should avoid this kind of `[P]`

package/{commands/review.md → skills/review/SKILL.md}

@@ -1,7 +1,7 @@
 ---
 name: review
-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]"
+description: Two-stage code review — Stage 1 spec compliance, Stage 2 code quality. Optional flags add adversarial review, edge-case hunting, or developer-experience audit.
+argument-hint: "[--stage=<1|2|both>] [--adversarial] [--edge-case] [--devex]"
 allowed-tools: [Read, Bash, Task, Grep, Glob]
 ---
 
@@ -18,6 +18,7 @@ Distinct from `/curdx-flow:verify`:
 | `--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`. |
 
 ## Preflight
 
@@ -38,6 +39,7 @@ 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
@@ -89,6 +91,27 @@ Dispatch `flow-edge-hunter` across the applicable categories (skip N/A with one-
 
 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:
@@ -121,6 +144,15 @@ Consolidated output: `.flow/specs/$SPEC_NAME/review-report.md`:
 ## 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
@@ -135,6 +167,7 @@ Consolidated output: `.flow/specs/$SPEC_NAME/review-report.md`:
   Stage 2 findings: <n>
   Adversarial findings: <n>   (if --adversarial)
   Edge-case gaps: <n>         (if --edge-case)
+  DevEx findings: <n>         (if --devex)
   Verdict: CHANGES REQUIRED
 
 Report: .flow/specs/<name>/review-report.md
@@ -149,4 +182,5 @@ Next: address blockers, then re-run /curdx-flow:review.
 - `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`
+- `devex-gate`: `@${CLAUDE_PLUGIN_ROOT}/gates/devex-gate.md`
 - Knowledge: `@${CLAUDE_PLUGIN_ROOT}/knowledge/two-stage-review.md`