@curdx/flow 2.1.0 → 2.2.0

package/cli/lib/semver.js

@@ -0,0 +1,95 @@
+function normalizeVersionToken(token) {
+  return /^\d+$/.test(token) ? Number(token) : token;
+}
+
+function parseVersion(version) {
+  const normalized = String(version || "").trim().replace(/^v/i, "");
+  const [coreRaw = "0", prereleaseRaw] = normalized.split("-", 2);
+  const core = coreRaw.split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const prerelease = prereleaseRaw
+    ? prereleaseRaw.split(/[.-]/).filter(Boolean).map(normalizeVersionToken)
+    : [];
+
+  return { core, prerelease };
+}
+
+function compareIdentifier(left, right) {
+  if (left === right) {
+    return 0;
+  }
+
+  const leftIsNumber = typeof left === "number";
+  const rightIsNumber = typeof right === "number";
+
+  if (leftIsNumber && rightIsNumber) {
+    return left > right ? 1 : -1;
+  }
+
+  if (leftIsNumber) {
+    return -1;
+  }
+
+  if (rightIsNumber) {
+    return 1;
+  }
+
+  return left > right ? 1 : -1;
+}
+
+export function compareVersions(leftVersion, rightVersion) {
+  const left = parseVersion(leftVersion);
+  const right = parseVersion(rightVersion);
+  const coreLength = Math.max(left.core.length, right.core.length);
+
+  for (let index = 0; index < coreLength; index += 1) {
+    const leftPart = left.core[index] ?? 0;
+    const rightPart = right.core[index] ?? 0;
+    if (leftPart !== rightPart) {
+      return leftPart > rightPart ? 1 : -1;
+    }
+  }
+
+  const leftHasPrerelease = left.prerelease.length > 0;
+  const rightHasPrerelease = right.prerelease.length > 0;
+
+  if (!leftHasPrerelease && !rightHasPrerelease) {
+    return 0;
+  }
+
+  if (!leftHasPrerelease) {
+    return 1;
+  }
+
+  if (!rightHasPrerelease) {
+    return -1;
+  }
+
+  const prereleaseLength = Math.max(left.prerelease.length, right.prerelease.length);
+  for (let index = 0; index < prereleaseLength; index += 1) {
+    const leftPart = left.prerelease[index];
+    const rightPart = right.prerelease[index];
+
+    if (leftPart === undefined) {
+      return -1;
+    }
+
+    if (rightPart === undefined) {
+      return 1;
+    }
+
+    const comparison = compareIdentifier(leftPart, rightPart);
+    if (comparison !== 0) {
+      return comparison;
+    }
+  }
+
+  return 0;
+}
+
+export function isVersionNewer(latestVersion, currentVersion) {
+  return compareVersions(latestVersion, currentVersion) > 0;
+}
+
+export function isVersionAtLeast(version, minimumVersion) {
+  return compareVersions(version, minimumVersion) >= 0;
+}

package/cli/utils.js

@@ -29,6 +29,7 @@ export {
   listPluginMarketplaces,
   listPlugins,
   parseMcpList,
+  parsePluginListJson,
   readUserMcpConfig,
 } from "./lib/claude.js";
 export { ensureClaudeMemRuntimes, ensureRuntimeInPath } from "./lib/runtime.js";

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # CurDX-Flow PreToolUse Hook for AskUserQuestion
-# Blocks AskUserQuestion when the active spec has quickMode=true or mode=autonomous.
-# This prevents the autonomous loop from stalling waiting for user input.
+# Blocks AskUserQuestion when the active spec has quickMode=true.
+# This prevents quick execution loops from stalling waiting for user input.
 #
 # The hook reads Claude's PreToolUse input JSON from stdin. We only act when
 # the tool being invoked is AskUserQuestion.
@@ -34,7 +34,7 @@ if [ "$TOOL_NAME" != "AskUserQuestion" ]; then
   exit 0
 fi
 
-# Check if we're in a flow project with quick mode enabled
+# Check if we're in a flow project with quick mode enabled.
 [ ! -d ".flow" ] && exit 0
 
 ACTIVE=$(cat .flow/.active-spec 2>/dev/null)
@@ -43,7 +43,7 @@ ACTIVE=$(cat .flow/.active-spec 2>/dev/null)
 STATE_FILE=".flow/specs/$ACTIVE/.state.json"
 [ ! -f "$STATE_FILE" ] && exit 0
 
-# Read quickMode + mode. Pass STATE_FILE via env (NOT shell interpolation
+# Read quickMode. 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
@@ -52,15 +52,14 @@ import json, os
 try:
     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")
+    print("true" if qm else "false")
 except Exception:
     print("false")
 ' 2>/dev/null)
 
 if [ "$QUICK_MODE" = "true" ]; then
   # Block and inject guidance
-  MSG="[CurDX-Flow quick-mode-guard] Active spec '$ACTIVE' is in quick mode or autonomous mode — AskUserQuestion is forbidden. Decide autonomously based on user preferences in .flow/CONTEXT.md plus the most reasonable assumption, and record your assumption in .progress.md."
+  MSG="[CurDX-Flow quick-mode-guard] Active spec '$ACTIVE' is in quick mode — AskUserQuestion is forbidden. Decide based on user preferences in .flow/CONTEXT.md plus the most reasonable assumption, and record your assumption in .progress.md."
   emit_pretooluse_deny "$MSG"
   exit 0
 fi

package/knowledge/execution-strategies.md

@@ -65,8 +65,8 @@ The main agent reads tasks.md and **dispatches a fresh flow-executor subagent pe
 
 ```
 main agent
-  ├─ Task() → subagent(task 1) → TASK_COMPLETE
-  ├─ Task() → subagent(task 2) → TASK_COMPLETE
+  ├─ Agent() → subagent(task 1) → TASK_COMPLETE
+  ├─ Agent() → subagent(task 2) → TASK_COMPLETE
   └─ ...
    (each subagent has isolated context)
 ```
@@ -86,7 +86,7 @@ main agent
 ### Disadvantages
 - Dispatch overhead (each subagent reloads context)
 - Cross-task info sharing goes through files (.progress.md)
-- Not parallel (a single Task call is serial)
+- Not parallel (a single Agent call is serial)
 
 ### Enable
 ```bash
@@ -149,7 +149,7 @@ main agent → task N → Stop → stop-watcher.sh
 ### How it works
 - Tasks in tasks.md marked `[P]` are "parallel-safe"
 - The main agent identifies consecutive `[P]` tasks as one wave
-- **In a single message**, it dispatches multiple Task() tool calls simultaneously
+- **In a single message**, it dispatches multiple Agent() tool calls simultaneously
 - All tasks within a wave run in parallel
 - Waves run serially relative to each other
 
@@ -175,7 +175,7 @@ main agent
 ### Disadvantages
 - Parallel conflict risk (e.g., two tasks editing the same file)
 - Requires flow-planner to have tagged `[P]` (Phase 1-generated tasks.md should)
-- Main agent manages many Task calls, high context pressure
+- Main agent manages many Agent calls, high context pressure
 
 ### Enable
 ```bash

package/knowledge/planning-reviews.md

@@ -149,7 +149,7 @@ Essentially runs `flow-architect` again — but this time not to generate the de
 
 A new agent `flow-devex-reviewer`, or reuse `flow-reviewer` by passing in the devex-gate.
 
-Phase 5 implementation: reuse `flow-reviewer` + `@gates/devex-gate.md`.
+Phase 5 implementation: reuse `flow-reviewer` + `@${CLAUDE_PLUGIN_ROOT}/gates/devex-gate.md`.
 
 ---
 
@@ -160,7 +160,7 @@ Phase 5 implementation: reuse `flow-reviewer` + `@gates/devex-gate.md`.
 ```
 
 Workflow:
-1. In parallel (single-message multi-Task), dispatch 4 reviews
+1. In parallel (single-message multi-Agent), dispatch 4 reviews
 2. Wait for all to return
 3. Merge findings, sort by priority
 4. Present to the user for decision

package/knowledge/wave-execution.md

@@ -1,6 +1,6 @@
 # Wave Execution — DAG Parallel Execution Strategy
 
-> One of Phase 2's 4 execution strategies. Identify parallel-safe task groups via `[P]` markers, dispatch multiple Task tool calls **in a single message**, run in parallel within a wave and serially across waves.
+> One of Phase 2's 4 execution strategies. Identify parallel-safe task groups via `[P]` markers, dispatch multiple Agent tool calls **in a single message**, run in parallel within a wave and serially across waves.
 >
 > Agents reference this via `@${CLAUDE_PLUGIN_ROOT}/knowledge/wave-execution.md`.
 
@@ -23,10 +23,10 @@ tasks.md:
   1.7 [P] add README to user
 
 Analysis:
-  Wave 1: { 1.1, 1.2, 1.3 }     — parallel (3 Tasks)
+  Wave 1: { 1.1, 1.2, 1.3 }     — parallel (3 Agent calls)
   Wave 2: { 1.4 }                — serial (VERIFY breaks)
   Wave 3: { 1.5 }                — serial (no [P])
-  Wave 4: { 1.6, 1.7 }           — parallel (2 Tasks)
+  Wave 4: { 1.6, 1.7 }           — parallel (2 Agent calls)
 ```
 
 ---
@@ -95,11 +95,11 @@ Rules:
 
 ---
 
-## How Parallel Task Dispatch Actually Works
+## How Parallel Agent Dispatch Actually Works
 
-### Key: multiple Task tool calls in a single message
+### Key: multiple Agent tool calls in a single message
 
-Claude Code's Task tool runs in parallel **when multiple calls appear in the same message**.
+Claude Code's Agent tool runs in parallel **when multiple calls appear in the same message**.
 Across **separate messages** → runs sequentially.
 
 ### Correct form (Wave strategy)
@@ -107,9 +107,9 @@ Across **separate messages** → runs sequentially.
 ```
 # In a single main-agent response:
 
-Task(description="Task 1.1", prompt="...execute 1.1...")
-Task(description="Task 1.2", prompt="...execute 1.2...")
-Task(description="Task 1.3", prompt="...execute 1.3...")
+Agent(description="Task 1.1", prompt="...execute 1.1...")
+Agent(description="Task 1.2", prompt="...execute 1.2...")
+Agent(description="Task 1.3", prompt="...execute 1.3...")
 
 # Wait for all to return before continuing to the next wave
 ```
@@ -118,13 +118,13 @@ Task(description="Task 1.3", prompt="...execute 1.3...")
 
 ```
 # One response:
-Task(description="Task 1.1", ...)
+Agent(description="Task 1.1", ...)
 # wait for return
 # Next response:
-Task(description="Task 1.2", ...)
+Agent(description="Task 1.2", ...)
 # wait for return
 # Next response:
-Task(description="Task 1.3", ...)
+Agent(description="Task 1.3", ...)
 ```
 
 This is not parallel — it's serial subagent. The Wave strategy loses its meaning.
@@ -142,9 +142,9 @@ for wave_index, wave in enumerate(waves):
         echo "  • $task.id $task.title"
 
     # === Step 2: dispatch (key: within a single message) ===
-    # This is the main agent's response body. Call N Task tools at once.
+    # This is the main agent's response body. Call N Agent tools at once.
     results = await asyncio.gather([
-        Task(
+        Agent(
             description=f"execute {task.id}",
             prompt=f"""
               You are the flow-executor agent.
@@ -193,7 +193,7 @@ for wave_index, wave in enumerate(waves):
             return
 
     # === Step 6: inter-wave synchronization point ===
-    # All Tasks complete = wave ends
+    # All Agent calls complete = wave ends
     # Before next wave starts, confirm git state is consistent
 
 # All waves done
@@ -320,7 +320,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)
+- Running Agent calls in the current wave keep going (Claude Code's Agent tool starts independent work)
 - Next `/curdx-flow:start --resume` shows some tasks already committed
 - Resume from the failing task
 
@@ -372,7 +372,7 @@ If the planner missed a dependency, `[P]` may be wrong. Solutions:
 
 ### 2. A wave too large
 
-10+ parallel Tasks may trigger API rate limits or context pressure. Solutions:
+10+ parallel Agent calls may trigger API rate limits or context pressure. Solutions:
 - `max_parallel: 5` splits a big wave into several
 - flow-planner avoids making waves too large when generating
 

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@curdx/flow",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "CLI installer for CurdX-Flow — AI engineering workflow meta-framework for Claude Code",
   "type": "module",
   "bin": {
     "curdx-flow": "bin/curdx-flow.js"
   },
   "scripts": {
+    "validate:contracts": "node scripts/validate-plugin-contracts.mjs",
     "test": "node --test test/*.test.js",
-    "prepublishOnly": "node --test test/*.test.js && node bin/curdx-flow.js --version"
+    "prepublishOnly": "npm run validate:contracts && node --test test/*.test.js && node bin/curdx-flow.js --version"
   },
   "files": [
     "bin/",

package/schemas/agent-frontmatter.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://curdx-flow.dev/schemas/agent-frontmatter.schema.json",
+  "title": "CurdX-Flow Agent Frontmatter",
+  "description": "Supported YAML frontmatter fields for agents/*.md plugin subagent definitions.",
+  "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
+    },
+    "tools": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ]
+    },
+    "disallowedTools": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ]
+    },
+    "model": {
+      "type": "string"
+    },
+    "effort": {
+      "type": "string",
+      "enum": ["low", "medium", "high", "xhigh", "max"]
+    },
+    "maxTurns": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "skills": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ]
+    },
+    "memory": {
+      "type": "string",
+      "enum": ["user", "project", "local"]
+    },
+    "background": {
+      "type": "boolean"
+    },
+    "isolation": {
+      "type": "string",
+      "enum": ["worktree"]
+    },
+    "color": {
+      "type": "string",
+      "enum": ["red", "blue", "green", "yellow", "purple", "orange", "pink", "cyan"]
+    },
+    "initialPrompt": {
+      "type": "string"
+    }
+  }
+}

package/schemas/config.schema.json

@@ -35,6 +35,11 @@
           "minimum": 1,
           "default": 8,
           "description": "Task count above which subagent strategy is preferred"
+        },
+        "wave_fail_policy": {
+          "type": "string",
+          "enum": ["continue-on-single", "stop-on-any"],
+          "default": "continue-on-single"
         }
       }
     },
@@ -44,16 +49,16 @@
       "properties": {
         "always_on": {
           "type": "array",
-          "items": { "type": "string" },
+          "items": { "$ref": "#/definitions/gateName" },
           "default": ["karpathy-gate", "verification-gate"]
         },
         "standard_mode": {
           "type": "array",
-          "items": { "type": "string" }
+          "items": { "$ref": "#/definitions/gateName" }
         },
         "enterprise_mode": {
           "type": "array",
-          "items": { "type": "string" }
+          "items": { "$ref": "#/definitions/gateName" }
         }
       }
     },
@@ -96,5 +101,20 @@
       "type": "string",
       "format": "date"
     }
+  },
+  "definitions": {
+    "gateName": {
+      "type": "string",
+      "enum": [
+        "karpathy-gate",
+        "verification-gate",
+        "tdd-gate",
+        "coverage-audit-gate",
+        "adversarial-review-gate",
+        "edge-case-gate",
+        "security-gate",
+        "devex-gate"
+      ]
+    }
   }
 }

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" }
+            }
+          }
+        ]
+      }
+    }
+  }
+}