@curdx/flow 2.0.0-beta.8 → 2.0.0

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:

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/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@curdx/flow",
-  "version": "2.0.0-beta.8",
+  "version": "2.0.0",
   "description": "CLI installer for CurDX-Flow — AI engineering workflow meta-framework for Claude Code",
   "type": "module",
   "bin": {
-    "flow": "bin/curdx-flow.js",
     "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 +22,7 @@
     "agent-preamble/",
     "templates/",
     "schemas/",
+    "skills/",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -43,5 +44,9 @@
     "installer",
     "ai-engineering",
     "curdx-flow"
-  ]
+  ],
+  "dependencies": {
+    "@clack/prompts": "^0.8.2",
+    "picocolors": "^1.1.1"
+  }
 }

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

package/skills/epic/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: epic
+description: Invoke when user wants to break a large feature into multiple smaller specs with a dependency graph. Triggers on "epic", "big feature", "too big", "decompose", "break down", "break into", "split into", "multi-spec", "multiple features", "sub-features", "vertical slice", "parent feature", "large scope", "won't fit in one sprint", "needs splitting".
+allowed-tools: [Read, Write, Grep, Glob, Bash]
+---
+
+# Epic Decomposition
+
+You are invoked when the user wants to break a large feature into multiple vertical-slice specs.
+
+## Preconditions
+
+1. A `.flow/` project must exist (run `/curdx-flow:init` first if missing).
+2. The user has stated a feature scope that is too large for a single spec.
+
+## Workflow
+
+### Step 1: Clarify the epic scope
+
+Ask the user (or infer from context) for:
+- **Epic name** (short identifier, kebab-case)
+- **One-sentence goal** of the whole epic
+- **Hard boundary**: what is explicitly out of scope for this epic
+
+### Step 2: Dispatch `flow-triage-analyst`
+
+Delegate to the `flow-triage-analyst` agent with the epic name + goal + boundary. The agent returns:
+- A vertical-slice decomposition (not horizontal by layer)
+- Dependency graph between slices
+- Shared interfaces that must be frozen before parallel work begins
+- Suggested slice ordering (MVP → iteration → polish)
+
+### Step 3: Write epic manifest
+
+Create `.flow/_epics/<epic-name>/epic.md` with:
+
+```markdown
+# Epic: <name>
+
+## Goal
+<one sentence>
+
+## Slices (vertical)
+| ID | Slice | Depends on | Shared interface |
+|----|-------|-----------|------------------|
+| S1 | ...   | —          | —                |
+| S2 | ...   | S1         | `types/auth.ts`  |
+| S3 | ...   | S1         | —                |
+
+## Frozen Interfaces
+(contracts that must not change once slices start)
+
+## Out of Scope
+- ...
+```
+
+### Step 4: Scaffold sub-spec skeletons
+
+For each slice, create `.flow/specs/<epic-name>-<slice-id>/` with a minimal `.state.json` linking back to the epic manifest.
+
+### Step 5: Report to user
+
+Summarize: "Epic `<name>` decomposed into N vertical slices. Start any slice with `/curdx-flow:start <epic-name>-<slice-id>`. Suggested order: S1 → S2 → S3."
+
+## References
+
+- Vertical-slice methodology: `@${CLAUDE_PLUGIN_ROOT}/knowledge/epic-decomposition.md`
+- Spec skeleton: `@${CLAUDE_PLUGIN_ROOT}/templates/`

package/skills/security-audit/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: security-audit
+description: Invoke when the user wants a security review — OWASP Top 10, STRIDE threat modeling, credential handling, injection, secrets, sensitive data handling. Triggers on "security", "auth", "authentication", "credential", "password", "secret", "API key", "token", "OWASP", "STRIDE", "CVE", "vulnerability", "injection", "XSS", "CSRF", "SSRF", "SQL injection", "hardcoded secret", "sensitive data", "leak", "will my API key leak", "is this safe".
+allowed-tools: [Read, Grep, Glob, Bash, WebSearch]
+---
+
+# Security Audit
+
+You are invoked when the user wants a systematic security review of the current spec or codebase.
+
+## Preconditions
+
+1. The code or spec under review is reachable from the current working directory.
+2. The user has identified the scope (current spec, specific module, or whole repo).
+
+## Workflow
+
+### Step 1: Clarify audit scope
+
+Confirm:
+- **Scope** (current spec / specific paths / whole repo)
+- **Depth** (OWASP-only / OWASP + STRIDE / + dependency CVE scan)
+- **Risk tolerance** (block on any SR / only block on SR with POC / advisory only)
+
+### Step 2: Dispatch `flow-security-auditor`
+
+Delegate to the `flow-security-auditor` agent. It will:
+1. Scan for hardcoded secrets, weak crypto, unsanitized inputs
+2. Apply OWASP Top 10 (A01 Broken Access Control → A10 SSRF)
+3. Apply STRIDE threat modeling (Spoofing, Tampering, Repudiation, Information disclosure, DoS, Elevation)
+4. Run dependency CVE scan (`npm audit` / equivalent)
+5. Produce a findings report with severity labels (SR = Blocking Red line, SW = Warning, SM = Mandatory-to-address)
+
+### Step 3: Write security report
+
+Output `.flow/specs/<active>/security-audit.md` containing:
+- **SR (blocking)** — must fix before ship
+- **SW (warning)** — should fix, won't block
+- **SM (mandatory)** — baseline items that must be present
+- **CVE hits** — direct / transitive dependencies with known vulns
+- **Recommended fixes** — concrete patches, not generic advice
+
+### Step 4: Enforce gate
+
+Apply the `security-gate` (`@${CLAUDE_PLUGIN_ROOT}/gates/security-gate.md`) — if any SR findings exist, block completion until remediated or explicitly waived with a D-NN decision in STATE.md.
+
+## References
+
+- `flow-security-auditor` agent: `@${CLAUDE_PLUGIN_ROOT}/agents/flow-security-auditor.md`
+- security-gate: `@${CLAUDE_PLUGIN_ROOT}/gates/security-gate.md`

package/skills/ui-sketch/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: ui-sketch
+description: Invoke when the user wants UI design drafts — components, layouts, variants, mockups, CSS/theme/styling decisions. Triggers on "design UI", "UI design", "component layout", "variants", "wireframe", "mockup", "prototype", "sketch", "draft layout", "visual design", "styling", "CSS", "theming", "dark mode", "responsive design", "color scheme", "build me a UI", "show several variants", "try different colors".
+allowed-tools: [Read, Write, Bash, WebSearch]
+---
+
+# UI Sketch
+
+You are invoked when the user wants fresh UI design drafts — typically 2–4 variants for comparison, or a single iterative refinement.
+
+## Preconditions
+
+1. The `frontend-design` skill (Anthropic official) should be installed. Without it, fall back to Tailwind + shadcn/ui defaults.
+2. The user provides a description of the UI goal (component, page, or flow).
+
+## Workflow
+
+### Step 1: Clarify design brief
+
+Confirm with the user:
+- **What is being designed** (component / page / full screen)
+- **Context** (consumer product / enterprise tool / marketing site / internal dashboard)
+- **Must-haves** (brand colors / existing design system / responsive breakpoints)
+- **Variant count** (default: 3 variants with distinct design directions)
+
+### Step 2: Dispatch `flow-ux-designer`
+
+Delegate to the `flow-ux-designer` agent with the brief. It will:
+1. Invoke the `frontend-design` skill with the brief
+2. Generate N variant HTML/JSX files under `.flow/specs/<active>/sketches/`
+3. For each variant, produce a rationale: typography, color, layout decisions
+4. Open the variants for user preview if a dev server is running
+
+### Step 3: Present variants
+
+Show the user:
+- **Variant preview URLs** or file paths
+- **Design rationale** per variant (what's different, why)
+- **Accessibility notes** (contrast ratios, focus states)
+
+### Step 4: Iterate or finalize
+
+- If user picks a variant: move the chosen file into the spec's `design.md` asset section.
+- If user wants a hybrid: dispatch `flow-ux-designer` again with "merge variant A layout + variant B color scheme".
+
+## References
+
+- `flow-ux-designer` agent: `@${CLAUDE_PLUGIN_ROOT}/agents/flow-ux-designer.md`
+- `flow-ui-researcher` agent (for competitive reference scraping): `@${CLAUDE_PLUGIN_ROOT}/agents/flow-ui-researcher.md`

package/hooks/scripts/fail-tracker.sh

@@ -1,31 +0,0 @@
-#!/usr/bin/env bash
-# CurDX-Flow PostToolUseFailure Hook
-# Tracks consecutive tool failures to enable pua integration (Phase 4+).
-# For now, just maintains a counter in plugin data directory.
-#
-# Future: when pua is installed and fail_count >= threshold, auto-invoke /pua:pua.
-
-set -u
-
-DATA_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.claude/plugins/data/curdx-flow}"
-COUNTER="$DATA_DIR/fail-count"
-
-mkdir -p "$DATA_DIR" 2>/dev/null || true
-
-# Read current count
-CURRENT=0
-[ -f "$COUNTER" ] && CURRENT="$(cat "$COUNTER" 2>/dev/null || echo 0)"
-
-# Increment
-NEXT=$((CURRENT + 1))
-echo "$NEXT" > "$COUNTER" 2>/dev/null || true
-
-# Placeholder for future pua escalation (Phase 4+):
-# if [ "$NEXT" -ge 2 ] && command -v claude >/dev/null 2>&1; then
-#   if claude plugin list 2>/dev/null | grep -q 'pua'; then
-#     # Inject escalation suggestion via hook output
-#     ...
-#   fi
-# fi
-
-exit 0