@curdx/flow 2.0.21 → 2.2.0

package/schemas/gate-frontmatter.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://curdx-flow.dev/schemas/gate-frontmatter.schema.json",
+  "title": "CurdX-Flow Gate Frontmatter",
+  "description": "Supported YAML frontmatter fields for gates/*.md quality gate definitions.",
+  "type": "object",
+  "required": ["gate", "category", "severity", "depends_on"],
+  "additionalProperties": false,
+  "properties": {
+    "gate": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
+    },
+    "category": {
+      "type": "string",
+      "enum": ["always-on", "standard-mode", "enterprise-mode"]
+    },
+    "severity": {
+      "type": "string",
+      "enum": ["blocking", "warning"]
+    },
+    "depends_on": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
+      }
+    }
+  }
+}

package/schemas/hooks.schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://curdx-flow.dev/schemas/hooks.schema.json",
+  "title": "CurdX-Flow Hook Configuration",
+  "description": "Supported event names and handler shape for hooks/hooks.json.",
+  "type": "object",
+  "required": ["hooks"],
+  "additionalProperties": false,
+  "properties": {
+    "hooks": {
+      "type": "object",
+      "propertyNames": {
+        "enum": [
+          "SessionStart",
+          "InstructionsLoaded",
+          "UserPromptSubmit",
+          "UserPromptExpansion",
+          "PreToolUse",
+          "PermissionRequest",
+          "PostToolUse",
+          "PostToolUseFailure",
+          "PostToolBatch",
+          "PermissionDenied",
+          "Notification",
+          "SubagentStart",
+          "SubagentStop",
+          "TaskCreated",
+          "TaskCompleted",
+          "Stop",
+          "StopFailure",
+          "TeammateIdle",
+          "ConfigChange",
+          "CwdChanged",
+          "FileChanged",
+          "WorktreeCreate",
+          "WorktreeRemove",
+          "PreCompact",
+          "PostCompact",
+          "Elicitation",
+          "ElicitationResult",
+          "SessionEnd"
+        ]
+      },
+      "additionalProperties": {
+        "type": "array",
+        "items": { "$ref": "#/definitions/matcherGroup" }
+      }
+    }
+  },
+  "definitions": {
+    "matcherGroup": {
+      "type": "object",
+      "required": ["hooks"],
+      "additionalProperties": false,
+      "properties": {
+        "matcher": { "type": "string" },
+        "hooks": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/hookHandler" }
+        }
+      }
+    },
+    "hookHandler": {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": true,
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["command", "http", "mcp_tool", "prompt", "agent"]
+        },
+        "if": { "type": "string" },
+        "timeout": { "type": "integer", "minimum": 1 },
+        "statusMessage": { "type": "string" },
+        "once": { "type": "boolean" },
+        "command": { "type": "string" },
+        "url": { "type": "string" },
+        "prompt": { "type": "string" },
+        "model": { "type": "string" }
+      }
+    }
+  }
+}

package/schemas/plugin-manifest.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://curdx-flow.dev/schemas/plugin-manifest.schema.json",
+  "title": "CurdX-Flow Claude Code Plugin Manifest",
+  "description": "Project-local schema for .claude-plugin/plugin.json.",
+  "type": "object",
+  "required": ["name", "version", "description"],
+  "additionalProperties": true,
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*$"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?$"
+    },
+    "description": { "type": "string" },
+    "author": { "type": "object" },
+    "homepage": { "type": "string" },
+    "repository": { "type": "string" },
+    "license": { "type": "string" },
+    "keywords": { "type": "array", "items": { "type": "string" } },
+    "skills": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ]
+    },
+    "agents": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ]
+    },
+    "hooks": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "object" }
+      ]
+    },
+    "mcpServers": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "object" }
+      ]
+    },
+    "dependencies": {
+      "type": "array",
+      "items": {
+        "oneOf": [
+          { "type": "string" },
+          {
+            "type": "object",
+            "required": ["name"],
+            "properties": {
+              "name": { "type": "string" },
+              "version": { "type": "string" },
+              "marketplace": { "type": "string" }
+            }
+          }
+        ]
+      }
+    }
+  }
+}

package/schemas/skill-frontmatter.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://curdx-flow.dev/schemas/skill-frontmatter.schema.json",
+  "title": "CurdX-Flow Skill Frontmatter",
+  "description": "Supported YAML frontmatter fields for skills/<name>/SKILL.md.",
+  "type": "object",
+  "required": ["name", "description"],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Concise trigger summary. Keep detailed trigger phrases in when_to_use."
+    },
+    "when_to_use": {
+      "type": "string",
+      "description": "Additional trigger phrases appended to description in the skill listing."
+    },
+    "argument-hint": {
+      "type": "string"
+    },
+    "arguments": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ]
+    },
+    "disable-model-invocation": {
+      "type": "boolean"
+    },
+    "user-invocable": {
+      "type": "boolean"
+    },
+    "allowed-tools": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ]
+    },
+    "model": {
+      "type": "string"
+    },
+    "effort": {
+      "type": "string",
+      "enum": ["low", "medium", "high", "xhigh", "max"]
+    },
+    "context": {
+      "type": "string",
+      "enum": ["fork"]
+    },
+    "agent": {
+      "type": "string"
+    },
+    "hooks": {
+      "type": "object"
+    },
+    "paths": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ]
+    },
+    "shell": {
+      "type": "string",
+      "enum": ["bash", "powershell"]
+    }
+  }
+}

package/schemas/spec-state.schema.json

@@ -17,11 +17,11 @@
     },
     "goal": {
       "type": "string",
-      "description": "One-sentence goal from /flow-start"
+      "description": "One-sentence goal from /curdx-flow:start"
     },
     "mode": {
       "type": "string",
-      "enum": ["sketch", "fast", "standard", "enterprise", "autonomous"],
+      "enum": ["fast", "standard", "enterprise"],
       "default": "standard"
     },
     "strategy": {
@@ -29,6 +29,11 @@
       "enum": ["auto", "subagent", "stop-hook", "wave", "linear"],
       "default": "auto"
     },
+    "quickMode": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, execution hooks block AskUserQuestion and agents must record assumptions instead of asking."
+    },
     "phase": {
       "type": "string",
       "enum": [

package/skills/brownfield-index/SKILL.md

@@ -1,6 +1,7 @@
 ---
 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".
+description: Use when the user needs structural understanding of an unfamiliar, inherited, legacy, or brownfield codebase.
+when_to_use: 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]
 ---
 

package/skills/browser-qa/SKILL.md

@@ -1,6 +1,7 @@
 ---
 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".
+description: Use when the user needs real-browser QA for a UI or frontend flow.
+when_to_use: 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]
 ---
 
@@ -10,7 +11,7 @@ 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.
+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
@@ -25,8 +26,8 @@ Confirm with the user:
 ### 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`
+1. Open the target URL via `mcp__chrome_devtools__new_page`
+2. Drive the flow with `mcp__chrome_devtools__click` / `fill` / `navigate_page`
 3. Capture `list_console_messages`, `list_network_requests`, `take_screenshot`, optionally `lighthouse_audit`
 4. Compare against expected behavior
 

package/skills/debug/SKILL.md

@@ -0,0 +1,105 @@
+---
+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>\""
+disable-model-invocation: true
+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/skills/epic/SKILL.md

@@ -1,6 +1,7 @@
 ---
 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".
+description: Use when the user needs to decompose a large feature into smaller vertical-slice specs with dependencies.
+when_to_use: 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]
 ---
 

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

@@ -2,7 +2,8 @@
 name: fast
 description: Ultra-fast execution — skip all spec phases and implement directly per the description. Suited for one-shot small tasks.
 argument-hint: "\"<task description>\""
-allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Task]
+disable-model-invocation: true
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
 ---
 
 # Flow Fast — Ultra-Fast Execution

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

@@ -2,6 +2,7 @@
 name: help
 description: Show CurdX-Flow command list, workflow overview, or troubleshooting guide. With a command name, show that command's detail.
 argument-hint: "[<command-name> | workflow | troubleshoot]"
+disable-model-invocation: true
 allowed-tools: [Read, Bash]
 ---
 
@@ -48,15 +49,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