@curdx/flow 1.1.11 → 2.0.0-beta.10

package/gates/devex-gate.md

@@ -13,7 +13,7 @@ depends_on: []
 
 ## Trigger Timing
 
-- When `/curdx-flow:plan-dx` runs (design phase)
+- When `/curdx-flow:spec --review=dx` runs (design phase)
 - When `/curdx-flow:review --devex` runs (code phase)
 - Enabled by default in open-source / multi-person collaboration scenarios
 
@@ -195,12 +195,12 @@ Reading these test names = reading API behavior documentation.
 
 ### Agent Automatic
 
-When `flow-ux-designer` / `flow-reviewer` applies this gate, use sequential-thinking ≥ 4 rounds to scan the 8 dimensions.
+When `flow-ux-designer` / `flow-reviewer` applies this gate, use sequential-thinking proportional to the complexity of the codebase being scanned.
 
 ### Human Review
 
 Attach a DevEx checklist at PR time:
-- [ ] Clear naming (reviewed at least 3 times)
+- [ ] Clear naming (re-read until obvious to a new maintainer)
 - [ ] Critical comments exist
 - [ ] Consistent structure
 - [ ] Actionable error messages
@@ -210,7 +210,7 @@ Attach a DevEx checklist at PR time:
 
 ## Scoring
 
-Each dimension 0-10 points:
+Score each **applicable** dimension 0-10 (N/A dimensions are excluded from the total):
 
 ```
 10 = best practice
@@ -220,8 +220,7 @@ Each dimension 0-10 points:
 0  = serious issue
 ```
 
-Total 40+ / 80 = pass (warning, non-blocking).
-Total < 40 = blocked, improvement required.
+Emit the per-dimension scores with evidence. The gate itself does not block on a numeric threshold; it surfaces the weaknesses for the user (or the reviewing agent) to decide whether any of them rise to a blocker. A single 0/10 on a material dimension is a blocker regardless of the total.
 
 ---
 

package/gates/edge-case-gate.md

@@ -18,7 +18,7 @@ depends_on: []
 - After the requirements phase ends (to supplement edge conditions)
 - After the design phase (to check error-path completeness)
 - After tests are written (to check whether only the happy path is covered)
-- Explicitly requested by /curdx-flow:audit
+- Explicitly requested by /curdx-flow:verify --strict
 
 ---
 
@@ -104,7 +104,7 @@ Q4. If no test, what test should be added to cover it?
 Input: object under review (function / component / API) + requirements + tests
   ↓
 For each category (1-7):
-  1. Use sequential-thinking to list at least 3 possible edge scenarios
+  1. Use sequential-thinking to list every plausible edge scenario for this category — stop when you've covered the real risk surface, don't pad to a quota, don't fabricate scenarios that won't occur in production
   2. Check whether each scenario has corresponding coverage in tests
   3. Add uncovered ones to the "gap list"
   ↓

package/gates/security-gate.md

@@ -13,7 +13,7 @@ depends_on: []
 
 ## Trigger Timing
 
-- When `/curdx-flow:security` runs
+- When the `security-audit` skill runs
 - Before `/curdx-flow:ship` (auto-triggered, Phase 6+)
 - When committing specs involving auth / payments / PII
 
@@ -130,8 +130,8 @@ Production environment only accepts HTTPS. HTTP requests → 301 to HTTPS.
 # Run all scans
 bash scripts/security-scan.sh  # provided by project (if available)
 
-# Or use flow-security-auditor agent
-/curdx-flow:security
+# Or use flow-security-auditor agent via the `security-audit` skill
+# (or say "audit for security issues")
 ```
 
 ### Dependency CVE

package/hooks/hooks.json

@@ -20,17 +20,6 @@
         ]
       }
     ],
-    "PostToolUseFailure": [
-      {
-        "matcher": "Bash|Edit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/fail-tracker.sh"
-          }
-        ]
-      }
-    ],
     "Stop": [
       {
         "hooks": [

package/hooks/scripts/quick-mode-guard.sh

@@ -40,17 +40,20 @@ ACTIVE=$(cat .flow/.active-spec 2>/dev/null)
 STATE_FILE=".flow/specs/$ACTIVE/.state.json"
 [ ! -f "$STATE_FILE" ] && exit 0
 
-# Read quickMode + mode
-QUICK_MODE=$(python3 -c "
-import json
+# Read quickMode + mode. Pass STATE_FILE via env (NOT shell interpolation
+# into the python source) so an active-spec name containing quotes/$ cannot
+# inject python code.
+export STATE_FILE
+QUICK_MODE=$(python3 -c '
+import json, os
 try:
-    s = json.load(open('$STATE_FILE'))
-    qm = s.get('quickMode', False)
-    mode = s.get('mode', '')
-    print('true' if (qm or mode == 'autonomous') else 'false')
+    s = json.load(open(os.environ["STATE_FILE"]))
+    qm = s.get("quickMode", False)
+    mode = s.get("mode", "")
+    print("true" if (qm or mode == "autonomous") else "false")
 except Exception:
-    print('false')
-" 2>/dev/null)
+    print("false")
+' 2>/dev/null)
 
 if [ "$QUICK_MODE" = "true" ]; then
   # Block and inject guidance

package/hooks/scripts/session-start.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # CurDX-Flow SessionStart Hook
 # Duties:
-#   1. Daily dependency check — nudge user to /flow-install-deps if recommended plugins missing
+#   1. Daily dependency check — nudge user to `npx @curdx/flow install --all` if recommended plugins missing
 #   2. Load active spec progress into session context
 #
 # Design notes:
@@ -36,7 +36,7 @@ if [ "$LAST_CHECK" != "$TODAY" ]; then
 
   if [ "${#MISSING[@]}" -gt 0 ]; then
     JOINED="$(IFS=,; echo "${MISSING[*]}")"
-    ADDITIONAL_CONTEXT+="## CurDX-Flow Recommended Plugins Check\n\nThe following recommended plugins were not detected: **${JOINED}**\n\nRun \`/curdx-flow:install-deps\` for interactive one-shot install. Run \`/curdx-flow:doctor\` for the full health report.\n\n"
+    ADDITIONAL_CONTEXT+="## CurDX-Flow Recommended Plugins Check\n\nThe following recommended plugins were not detected: **${JOINED}**\n\nRun \`npx @curdx/flow install --all\` for interactive one-shot install. Run \`npx @curdx/flow doctor\` for the full health report.\n\n"
   fi
 
   echo "$TODAY" > "$MARKER" 2>/dev/null || true

package/hooks/scripts/stop-watcher.sh

@@ -56,6 +56,12 @@ if ! command -v python3 >/dev/null 2>&1; then
   allow_stop
 fi
 
+# Export STATE_FILE BEFORE invoking python3 — the heredoc-based parser reads
+# os.environ["STATE_FILE"]. Previously the export was placed after the
+# heredoc, so python3 always got None, json.load(None) silently failed, and
+# the stop-hook strategy never activated.
+export STATE_FILE
+
 read STRATEGY PHASE TASK_INDEX TOTAL_TASKS FAILED ROUNDS <<EOF
 $(python3 <<'PY'
 import json, os, sys
@@ -75,7 +81,6 @@ print(strategy, phase, ti, tt, failed, rounds)
 PY
 )
 EOF
-export STATE_FILE
 
 # Only activate for stop-hook strategy + execute phase
 [ "$STRATEGY" != "stop-hook" ] && allow_stop
@@ -95,12 +100,17 @@ if [ -n "$TRANSCRIPT_PATH" ] && [ -f "$TRANSCRIPT_PATH" ]; then
   TRANSCRIPT_TAIL=$(tail -c 51200 "$TRANSCRIPT_PATH" 2>/dev/null || echo "")
 fi
 
+# Python state-file updates: use quoted heredocs (<<'PY') + os.environ so
+# the spec-name-derived STATE_FILE path is NEVER interpolated into the
+# python source text. Previously a spec name containing single quotes or
+# $-signs could break the script or inject arbitrary code.
+
 # Check for explicit completion signals
 if echo "$TRANSCRIPT_TAIL" | grep -q "ALL_TASKS_COMPLETE"; then
   # Cleanup: mark phase completed
-  python3 <<PY 2>/dev/null
-import json
-p = "$STATE_FILE"
+  python3 <<'PY' 2>/dev/null
+import json, os
+p = os.environ["STATE_FILE"]
 s = json.load(open(p))
 s.setdefault("phase_status", {})["execute"] = "completed"
 s["phase"] = "verify"  # move to verify phase
@@ -112,16 +122,16 @@ fi
 # Check for fail signal (accumulate; actual stop decision below)
 if echo "$TRANSCRIPT_TAIL" | grep -q "TASK_FAILED"; then
   # Increment failed_attempts
-  python3 <<PY 2>/dev/null
-import json
-p = "$STATE_FILE"
+  python3 <<'PY' 2>/dev/null
+import json, os
+p = os.environ["STATE_FILE"]
 s = json.load(open(p))
 s.setdefault("execute_state", {})
 s["execute_state"]["failed_attempts"] = s["execute_state"].get("failed_attempts", 0) + 1
 json.dump(s, open(p, "w"), indent=2, ensure_ascii=False)
 PY
-  # Re-read
-  FAILED=$(python3 -c "import json; print(json.load(open('$STATE_FILE'))['execute_state']['failed_attempts'])" 2>/dev/null || echo 0)
+  # Re-read — again via os.environ, no shell interpolation into python.
+  FAILED=$(python3 -c 'import json, os; print(json.load(open(os.environ["STATE_FILE"]))["execute_state"]["failed_attempts"])' 2>/dev/null || echo 0)
 fi
 
 # ---------- 6. Safety brakes ----------
@@ -138,9 +148,9 @@ fi
 # Check if all tasks done
 if [ "$TASK_INDEX" -ge "$TOTAL_TASKS" ] && [ "$TOTAL_TASKS" -gt 0 ]; then
   # Mark complete
-  python3 <<PY 2>/dev/null
-import json
-p = "$STATE_FILE"
+  python3 <<'PY' 2>/dev/null
+import json, os
+p = os.environ["STATE_FILE"]
 s = json.load(open(p))
 s.setdefault("phase_status", {})["execute"] = "completed"
 s["phase"] = "verify"
@@ -151,9 +161,9 @@ fi
 
 # ---------- 7. Block and continue ----------
 # Increment round counter
-python3 <<PY 2>/dev/null
-import json
-p = "$STATE_FILE"
+python3 <<'PY' 2>/dev/null
+import json, os
+p = os.environ["STATE_FILE"]
 s = json.load(open(p))
 s.setdefault("execute_state", {})
 s["execute_state"]["global_iteration"] = s["execute_state"].get("global_iteration", 0) + 1

package/knowledge/epic-decomposition.md

@@ -238,13 +238,13 @@ Week 5-6: Spec 4 (refund) + Spec 5 (query)
 ## Epic Lifecycle
 
 ```
-1. /curdx-flow:triage "Epic goal"
+1. Invoke the `epic` skill with "Epic goal" (auto-invoked; or say "break this big feature down")
      ↓ flow-triage-analyst decomposes
 2. Generates .flow/_epics/<name>/epic.md + sub-spec skeletons
 3. User reviews epic.md
      ↓
 4. For each sub-spec:
-   /curdx-flow:switch <sub-spec-name>
+   /curdx-flow:start <sub-spec-name>
    /curdx-flow:spec
    /curdx-flow:implement
    /curdx-flow:review

package/knowledge/execution-strategies.md

@@ -223,13 +223,14 @@ return "linear"
 
 ## Failure Handling (common to all strategies)
 
-`flow-executor` agent's 5-round retry mechanism:
+`flow-executor` agent's retry ladder — each step escalates only when the prior is honestly exhausted, not on a fixed count:
 
 ```
-Rounds 1-2: agent retries autonomously (edit code, rerun Verify)
-Round 3: sequential-thinking root-cause analysis ≥ 5 rounds
-Round 4: read related source + trace data flow
-Round 5: report TASK_FAILED
+Step A: autonomous retry (edit + rerun Verify) — only for shallow failures
+Step B: sequential-thinking root-cause analysis proportional to the hypothesis space
+Step C: read related source + trace data flow
+Step D: if ≥3 retries fail with no new hypothesis, stop and challenge the architecture (see preamble L3)
+Step E: report TASK_FAILED
 ```
 
 ### Extra protections for Stop-Hook strategy
@@ -252,7 +253,7 @@ Can you switch strategies mid-execution? Not recommended.
 - Any → Wave: needs `[P]` markers in tasks.md
 
 If you really must switch, do it manually:
-1. `/curdx-flow:doctor` to check status
+1. `npx @curdx/flow doctor` to check status
 2. Manually edit `.flow/specs/<name>/.state.json`'s `strategy` field
 3. Rerun `/curdx-flow:implement`
 
@@ -262,13 +263,13 @@ If you really must switch, do it manually:
 
 ### View progress
 ```bash
-/curdx-flow:status        # global
-/curdx-flow:status <name> # single-spec details
+/curdx-flow:start --list        # global
+# For single-spec details, inspect .flow/specs/<name>/.progress.md
 ```
 
 ### Interrupt
 - `Ctrl+C` interrupts the current session → Stop event triggers, state is saved
-- Next `/curdx-flow:switch <name>` resumes from `task_index`
+- Next `/curdx-flow:start <name>` (or `/curdx-flow:start --resume`) resumes from `task_index`
 
 ### Snapshots
 `/curdx-flow:save <label>` saves a checkpoint (Phase 5+ rollout).

package/knowledge/planning-reviews.md

@@ -26,7 +26,7 @@ design.md
 
 Each review is dispatched independently (different agent / context) to avoid perspective convergence.
 
-Finally `/curdx-flow:autoplan` ties them together: runs all 4 reviews in one pass.
+Finally `/curdx-flow:spec --review=all` ties them together: runs all 4 reviews in one pass.
 
 ---
 
@@ -115,7 +115,7 @@ Essentially runs `flow-architect` again — but this time not to generate the de
 
 ### Dispatch
 
-`flow-ux-designer` (Emma) switches into review mode.
+`flow-ux-designer` switches into review mode.
 
 ---
 
@@ -153,10 +153,10 @@ Phase 5 implementation: reuse `flow-reviewer` + `@gates/devex-gate.md`.
 
 ---
 
-## /curdx-flow:autoplan — Run All 4 at Once
+## /curdx-flow:spec --review=all — Run All 4 at Once
 
 ```bash
-/curdx-flow:autoplan
+/curdx-flow:spec --review=all
 ```
 
 Workflow:
@@ -183,7 +183,7 @@ Output:
 ...
 
 ## Recommendations
-1. Return to /curdx-flow:design to fix blockers
+1. Return to /curdx-flow:spec --phase=design to fix blockers
 2. Record warnings in STATE.md, address in tasks phase
 ```
 
@@ -191,7 +191,7 @@ Output:
 
 ## When to Skip Planning Reviews
 
-- **MVP / prototype**: time-pressured, run /curdx-flow:tasks first, review after launch
+- **MVP / prototype**: time-pressured, run /curdx-flow:spec --phase=tasks first, review after launch
 - **Tiny changes**: a single file < 50 lines doesn't warrant a 4-dimension review
 - **Similar work done before**: reuse prior review conclusions
 

package/knowledge/spec-driven-development.md

@@ -57,7 +57,7 @@ What's wasted isn't code — it's context tokens and decision fatigue from churn
 **Key behaviors** (flow-researcher agent):
 1. Read `.flow/PROJECT.md` and `.flow/CONTEXT.md` to understand project background
 2. Call `mcp__claude_mem__search` to retrieve relevant historical experience
-3. Use sequential-thinking for 5-8 rounds of problem understanding
+3. Use sequential-thinking proportional to the unknowns (1 thought for a trivial prototype, many for a novel domain)
 4. Scan the codebase for reusable modules
 5. Use `mcp__context7__*` to look up latest docs for relevant libraries
 6. When necessary, WebSearch for the latest technical trends
@@ -99,11 +99,12 @@ What's wasted isn't code — it's context tokens and decision fatigue from churn
 
 **Key behaviors** (flow-architect agent):
 1. Read `research.md` + `requirements.md`
-2. **Must use sequential-thinking for at least 8 rounds**:
-   - Rounds 1-2: constraints
-   - Rounds 3-5: comparison of options A/B
-   - Rounds 6-7: selection + trade-offs
-   - Round 8: rebut yourself
+2. **Use sequential-thinking proportional to the tradeoff surface** — the phases below are orientation, not a quota:
+   - Constraints (from NFR / tech stack)
+   - Option comparison (only when alternatives genuinely compete)
+   - Selection + accepted tradeoff
+   - Self-rebuttal
+   A well-known stack pick may finish in 1 thought; a distributed-system design may run many. Do not pad.
 3. Assign an `AD-NN` ID to each architectural decision
 4. Draw a data flow diagram (mermaid)
 5. Define component interfaces + error paths
@@ -125,7 +126,7 @@ What's wasted isn't code — it's context tokens and decision fatigue from churn
 3. Each task has 5 fields: `Do` / `Files` / `Done-when` / `Verify` / `Commit`
 4. **Multi-source coverage audit**: for each FR / AC / AD / decision, confirm there is a covering task (no omissions)
 5. Mark `[P]` (parallel-safe) and `[VERIFY]` (checkpoint)
-6. Simple decomposition doesn't need sequential-thinking, but reflect on coverage every 5 tasks
+6. Simple decomposition doesn't need sequential-thinking; run a coverage audit at the end (every FR/AC/AD has a task)
 
 **Deliverable**: `tasks.md`
 
@@ -147,7 +148,7 @@ Regardless of the path taken, the 4 files must satisfy:
 ## Spec vs Epic Difference
 
 - **Spec**: a single independently-deliverable feature. Typically 1-2 weeks of effort.
-- **Epic**: a collection of specs. `/curdx-flow:triage` breaks down a large goal into multiple specs.
+- **Epic**: a collection of specs. The `epic` skill (auto-invoked, or say "break this big feature down") breaks down a large goal into multiple specs.
 
 `.flow/specs/<name>/` is a single-spec directory.
 `.flow/_epics/<name>/` is an Epic directory (contains the dependency graph and sub-spec list).
@@ -159,8 +160,8 @@ Regardless of the path taken, the 4 files must satisfy:
 SDD is not dogma. The following scenarios may skip phases:
 
 - **One-off scripts** (`/curdx-flow:fast` mode) — skip all specs
-- **UI prototype exploration** (`/curdx-flow:sketch` mode) — only research + design sketches
-- **Emergency hotfix** (`/curdx-flow:spike` mode) — validating the assumption is enough
+- **UI prototype exploration** (the `ui-sketch` skill) — only research + design sketches
+- **Emergency hotfix** (`/curdx-flow:fast "spike: validate <hypothesis>"` mode) — validating the assumption is enough
 
 But **production code changes** should follow the full flow. Rationale:
 - Code may be only 20 lines, but impact may reach all users

package/knowledge/two-stage-review.md

@@ -113,17 +113,18 @@ Stage 2 applies all enabled Gates (from `.flow/config.json`):
 
 #### 2.5 (enterprise) Adversarial review (adversarial-review-gate)
 
-- ≥ 3 categories of issues found?
+- Every applicable category examined (N/A documented for the rest)?
+- Findings proportional to real issues (zero is OK with a proof-of-checking report)?
 - Each finding has evidence + recommendation?
 
 #### 2.6 (enterprise) Edge cases (edge-case-gate)
 
-- Did all 7 major categories pass?
+- Each applicable edge-case category addressed (N/A noted for the rest)?
 - Gap list has priorities?
 
 ### Stage 2 verdict
 
-- **EXCELLENT**: all enabled Gates pass, adversarial findings < 3 (high-quality code)
+- **EXCELLENT**: all enabled Gates pass, adversarial review clean or only low-severity findings
 - **GOOD**: all enabled Gates pass, but some warnings
 - **NEEDS_IMPROVEMENT**: Gate violations (blocking)
 
@@ -206,7 +207,7 @@ Some reviewers list 50 minor improvements — the user can't process.
 ## Relationship to Other Phases
 
 ```
-/curdx-flow:tasks  →  tasks.md contains task list
+/curdx-flow:spec --phase=tasks  →  tasks.md contains task list
      ↓
 /curdx-flow:implement  →  code + tests + commits
      ↓
@@ -218,7 +219,7 @@ Some reviewers list 50 minor improvements — the user can't process.
      ↓                     ↓
      ↓              review-report.md
      ↓
-(optional) /curdx-flow:audit  →  adversarial review + edge cases
+(optional) /curdx-flow:verify --strict  →  adversarial review + edge cases
                     ↓
                     adversarial-review.md
                     edge-cases.md

package/knowledge/wave-execution.md

@@ -254,7 +254,7 @@ Decision:
   - 1.1 and 1.3 commits retained
   - Main agent decides:
     A: continue to Wave 2 (skip 1.2, possible cascading failure)
-    B: dispatch David (flow-debugger) to fix 1.2, then continue
+    B: dispatch flow-debugger to fix 1.2, then continue
     C: stop and report, let the user intervene
 
   Default: A, but failed_attempts += 1; after threshold switch to C
@@ -268,7 +268,7 @@ Wave 1 all TASK_FAILED
 Decision:
   - Usually indicates an upstream environment problem (missing deps, tsc config wrong)
   - Stop immediately
-  - Suggest user run /curdx-flow:doctor to diagnose
+  - Suggest user run `npx @curdx/flow doctor` to diagnose
 ```
 
 ### Inter-wave dependency broken
@@ -307,7 +307,7 @@ Decision:
 
 ### In-progress view
 
-`/curdx-flow:status` shows:
+Inspecting `.flow/specs/<name>/.progress.md` (or running `/curdx-flow:start --list`) shows:
 ```
 Spec: auth-system
 Strategy: wave
@@ -321,7 +321,7 @@ Progress: Wave 2/5 (60%)
 ### Ctrl+C interruption
 
 - Running Task calls in the current wave keep going (Claude Code's Task is an independent process)
-- Next `/curdx-flow:switch` shows some tasks already committed
+- Next `/curdx-flow:start --resume` shows some tasks already committed
 - Resume from the failing task
 
 ---
@@ -367,7 +367,7 @@ Phase 6+ will consider automatic fallback.
 ### 1. `[P]` markers incorrect
 
 If the planner missed a dependency, `[P]` may be wrong. Solutions:
-- Before execution, confirm tasks coverage via `/curdx-flow:audit`
+- Before execution, confirm tasks coverage via `/curdx-flow:verify --strict`
 - Conflict detection as a safety net (validate Files before dispatch)
 
 ### 2. A wave too large

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@curdx/flow",
-  "version": "1.1.11",
+  "version": "2.0.0-beta.10",
   "description": "CLI installer for CurDX-Flow — AI engineering workflow meta-framework for Claude Code",
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
     "curdx-flow": "bin/curdx-flow.js"
   },
   "scripts": {
-    "prepublishOnly": "node bin/curdx-flow.js --version"
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "node --test test/*.test.js && node bin/curdx-flow.js --version"
   },
   "files": [
     "bin/",
@@ -22,6 +23,7 @@
     "agent-preamble/",
     "templates/",
     "schemas/",
+    "skills/",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"

package/skills/brownfield-index/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: brownfield-index
+description: Invoke when the user is new to an unfamiliar / legacy / brownfield codebase and wants a structural understanding — module map, component inventory, API surface, data flow. Triggers on "legacy code", "brownfield", "unfamiliar", "new to this code", "new to this project", "just joined", "inherited codebase", "explore codebase", "understand structure", "index code", "map modules", "tour", "onboard", "what is this project".
+allowed-tools: [Read, Grep, Glob, Bash]
+---
+
+# Brownfield Index
+
+You are invoked when the user needs a structural map of an existing codebase they are not yet familiar with.
+
+## Preconditions
+
+1. The repository root is the current working directory (or a path the user specifies).
+2. The project is not a new `/curdx-flow:init`-ed greenfield project (if it is, direct the user to `/curdx-flow:start` instead).
+
+## Workflow
+
+### Step 1: Detect project type
+
+Read `package.json` / `Cargo.toml` / `pyproject.toml` / `go.mod` / `pom.xml` to classify the ecosystem and build tool. This determines which directory conventions to apply.
+
+### Step 2: Scan directory structure
+
+Produce a top-level inventory:
+- **Entry points** (main / index / bin scripts)
+- **Module directories** (src/, lib/, internal/, pkg/ …)
+- **Test directories**
+- **Config files**
+- **Tooling** (CI, lint, format configs)
+
+### Step 3: Component inventory
+
+For each module directory, list:
+- Files and their apparent role (inferred from names + top-of-file comments)
+- Public exports / exported symbols
+- Third-party dependencies imported
+
+### Step 4: API surface
+
+If HTTP / RPC endpoints exist, index them: route → handler → middleware. For CLI tools, index commands → handlers.
+
+### Step 5: Write index document
+
+Output `.flow/codebase-index.md` containing:
+- **Overview** (project purpose, build tool, runtime)
+- **Directory tree** (with per-directory one-liner descriptions)
+- **Entry points** (where execution starts)
+- **Key abstractions** (core types, interfaces, classes that everything else hangs off)
+- **External dependencies** (grouped: prod runtime / dev tooling / transitive)
+- **Known gaps / red flags** (missing tests, TODOs, suspicious patterns)
+
+### Step 6: Hand off
+
+Point the user at the next useful action:
+- "Looking to add a feature here? Run `/curdx-flow:start <name>` to begin a spec."
+- "Debugging something specific? Run `/curdx-flow:debug '<symptom>'`."
+
+## Notes
+
+This skill uses Read + Grep + Glob + Bash with no specialized agent — general tools are enough for structural discovery. The index is meant to be quick (5–10 minutes), not exhaustive.
+
+For deep research into a specific library or framework, use `context7` MCP directly.

package/skills/browser-qa/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: browser-qa
+description: Invoke when the user wants to test a UI/frontend in a real browser — accessibility, performance, console errors, network traffic, visual regression. Triggers on "browser test", "test in browser", "UI test", "e2e test", "frontend test", "accessibility", "a11y", "WCAG", "lighthouse", "performance audit", "console error", "network request", "cross-browser", "responsive", "mobile test", "visual regression", "screenshot".
+allowed-tools: [Read, Write, Bash, Grep, Glob, WebFetch]
+---
+
+# Browser QA
+
+You are invoked when the user wants real-browser QA of a UI flow.
+
+## Preconditions
+
+1. `chrome-devtools` MCP is available (`mcp__chrome-devtools__*`). If missing, fall back to a manual checklist.
+2. A URL (dev server or deployed) is available. Prompt for it if not provided.
+
+## Workflow
+
+### Step 1: Clarify scope
+
+Confirm with the user:
+- **URL under test** (local `http://localhost:3000` or remote)
+- **Flow to test** (e.g., "sign up → dashboard → logout")
+- **What success looks like** (accessibility / performance / zero console errors / visual match)
+
+### Step 2: Dispatch `flow-qa-engineer`
+
+Delegate to the `flow-qa-engineer` agent. It will:
+1. Open the target URL via `mcp__chrome-devtools__new_page`
+2. Drive the flow with `mcp__chrome-devtools__click` / `fill` / `navigate`
+3. Capture `list_console_messages`, `list_network_requests`, `take_screenshot`, optionally `lighthouse_audit`
+4. Compare against expected behavior
+
+### Step 3: Report findings
+
+Produce `.flow/specs/<active>/qa-report.md` with:
+- **Bugs** (reproducible, severity P1/P2/P3)
+- **Performance** (LCP / INP / CLS from Lighthouse)
+- **Accessibility** (axe violations with WCAG references)
+- **Console errors** (full stack traces)
+- **Screenshots** (attached)
+
+### Step 4: Hand off
+
+If bugs found: suggest `/curdx-flow:debug "<bug title>"` for systematic root-cause analysis.
+If accessibility violations: suggest fixes inline with WCAG refs.
+
+## References
+
+- `flow-qa-engineer` agent: `@${CLAUDE_PLUGIN_ROOT}/agents/flow-qa-engineer.md`
+- chrome-devtools MCP docs: https://github.com/ChromeDevTools/chrome-devtools-mcp