@curdx/flow 2.3.11 → 3.0.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Claude Code Discipline Layer — spec-driven workflow + goal-backward verification + Karpathy 4 principles enforced via gates. Stops Claude from faking \"done\" on non-trivial features.",
-    "version": "2.3.11"
+    "version": "3.0.0"
   },
   "allowCrossMarketplaceDependenciesOn": [
     "context7-marketplace"
@@ -16,7 +16,7 @@
       "name": "curdx-flow",
       "source": "./",
       "description": "Claude Code Discipline Layer — spec-driven workflow + goal-backward verification + Karpathy 4 principles enforced via gates. Stops Claude from faking \"done\" on non-trivial features.",
-      "version": "2.3.11",
+      "version": "3.0.0",
       "author": {
         "name": "wdx",
         "email": "bydongxin@gmail.com"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "curdx-flow",
-  "version": "2.3.11",
+  "version": "3.0.0",
   "description": "Claude Code Discipline Layer — spec-driven workflow + goal-backward verification + Karpathy 4 principles enforced via gates. Stops Claude from faking \"done\" on non-trivial features.",
   "author": {
     "name": "wdx",
@@ -18,25 +18,7 @@
     "claude-code"
   ],
   "skills": "./skills/",
-  "agents": [
-    "./agents/flow-adversary.md",
-    "./agents/flow-architect.md",
-    "./agents/flow-brownfield-analyst.md",
-    "./agents/flow-debugger.md",
-    "./agents/flow-edge-hunter.md",
-    "./agents/flow-executor.md",
-    "./agents/flow-orchestrator.md",
-    "./agents/flow-planner.md",
-    "./agents/flow-product-designer.md",
-    "./agents/flow-qa-engineer.md",
-    "./agents/flow-researcher.md",
-    "./agents/flow-reviewer.md",
-    "./agents/flow-security-auditor.md",
-    "./agents/flow-triage-analyst.md",
-    "./agents/flow-ui-researcher.md",
-    "./agents/flow-ux-designer.md",
-    "./agents/flow-verifier.md"
-  ],
+  "agents": "./agents/",
   "outputStyles": "./output-styles/",
   "monitors": "./monitors/monitors.json",
   "userConfig": {

package/CHANGELOG.md

@@ -1,10 +1,63 @@
 # Changelog
 
+## 3.0.0
+
+The modernization release. No breaking changes for end users — internal
+manifest reshape, schema realignment, and platform-feature uptake.
+
+- aligned `schemas/agent-frontmatter.schema.json` with the canonical field
+  list documented at <https://code.claude.com/docs/en/sub-agents.md>; reversed
+  the P1 contract validator's misjudgement that flagged `effort`,
+  `maxTurns`, `background`, and `color` as non-canonical, and replaced it
+  with a strict-mode threshold check on combined `description + when_to_use`
+  length (1536-char skill listing cap)
+- collapsed `plugin.json#agents` from a 17-entry explicit array to the
+  directory pointer `"./agents/"`, matching `skills` and `outputStyles` and
+  eliminating per-agent manifest drift
+- explicitly forbade plugin-ignored fields (`hooks`, `mcpServers`,
+  `permissionMode`) at schema validation time so misconfigurations surface
+  before install instead of being silently dropped at runtime
+- shipped a plugin root `bin/` directory: `bin/curdx-flow-state` emits a
+  one-line snapshot of the active spec and is added to the Bash tool's
+  `PATH` whenever the plugin is enabled (Claude Code v2.1.91+); agents,
+  skills, and hooks can call it as a bare command instead of duplicating
+  Python/Bash snippets
+- added `subagentStatusLine.refreshInterval: 5` so the worktree-aware
+  status line refreshes automatically (Claude Code Week 15 statusline
+  feature)
+- shipped two new output styles, `CurdX Spec Mode` (verbose, artifact-first)
+  and `CurdX Fast Mode` (low-ceremony surgical work), alongside the
+  default evidence-first style
+- expanded the test suite from 10 to 110+ assertions across five new files:
+  every skill frontmatter parses with name/description/length contract,
+  every hook script invoked from `hooks.json` is executable + bash-parsable,
+  every output style has frontmatter + non-trivial body, the
+  `RECOMMENDED_PLUGINS` registry stays in lockstep with `session-start.sh`,
+  and every plugin `bin/` executable parses + runs without crashing
+- restored the README and CHANGELOG that were dropped during the
+  P1 slate-clearing (commits 0dee423 / 8b14aba) and updated them to v3.0.0
+
+## 2.3.11
+
+- internal-only patches; no user-facing behavior change
+
+## 2.3.10
+
+- auto-heal legacy Context7 state on upgrade; doctor reports "all healthy" once
+  the legacy user-level Context7 MCP entry has been reconciled
+
+## 2.3.9
+
+- aligned Claude runtime hooks with the official auto-discovery contract
+  (`hooks.json` is loaded automatically; manifest `hooks` field is reserved
+  for non-standard locations only) and resolved the `context7-plugin
+  unknown version` install failure that blocked upgrades
+
 ## 2.3.8
 
 - taught `doctor` to detect dirty CurDX-Flow source checkouts, so plugin developers immediately see when Claude cannot possibly be running their latest local edits yet
 - surfaced bundled source repo metadata (`branch`, `shortSha`, `exactTag`, `dirty`) alongside bundled plugin body version in diagnostics and JSON output
-- documented the reinstall workflow for “same version, but local source changed” plugin-development scenarios
+- documented the reinstall workflow for "same version, but local source changed" plugin-development scenarios
 
 ## 2.3.7
 
@@ -26,7 +79,7 @@
 
 ## 2.3.1
 
-- expanded `doctor` to report CurDX-Flow’s bundled main-thread agent, monitor surface, and plugin option defaults
+- expanded `doctor` to report CurDX-Flow's bundled main-thread agent, monitor surface, and plugin option defaults
 - documented where Claude Code stores CurDX-Flow non-sensitive `userConfig` values in `pluginConfigs`
 - added troubleshooting guidance for stop-hook blocking and plugin monitor behavior
 

package/README.md

@@ -9,8 +9,15 @@
 
 CurdX-Flow is a skill-first Claude Code plugin. The public surface stays small:
 11 slash commands, 5 auto-invoked skills, 17 internal agents, and a thin set of
-entry docs. The heavy workflow detail lives in `skills/*/references/` and
-`knowledge/`.
+runtime contracts. The heavy workflow detail lives in `skills/*/references/`,
+`knowledge/`, and the `agent-preamble/`.
+
+v3.0.0 is the modernization release: the plugin manifest, agent/skill schemas,
+and contract validator are aligned with the latest Claude Code plugin spec
+([sub-agents.md](https://code.claude.com/docs/en/sub-agents.md),
+[plugins-reference.md](https://code.claude.com/docs/en/plugins-reference.md)),
+and the plugin now ships a `bin/` directory whose executables are added to the
+Bash tool's `PATH` while CurdX-Flow is enabled (Claude Code v2.1.91+).
 
 ## Install
 
@@ -21,10 +28,10 @@ npx @curdx/flow install --all
 Requires modern Claude Code and Node 18+. The install flow registers the plugin,
 required reasoning/doc tools, and recommended companion plugins. Run
 `npx @curdx/flow doctor` after install if anything looks off. For CI or wrapper
-automation, use `npx @curdx/flow doctor --json`, which now includes file-based
-managed settings in its inspected precedence model.
+automation, use `npx @curdx/flow doctor --json`, which reports file-based
+managed settings at their correct precedence layer.
 
-After restart, CurDX-Flow routes the main thread through `flow-orchestrator`
+After restart, CurdX-Flow routes the main thread through `flow-orchestrator`
 by default and starts the bundled `.flow` progress monitor in interactive
 Claude Code sessions.
 
@@ -70,26 +77,69 @@ This produces a durable audit trail instead of a chat-only claim of completion.
 ## What ships
 
 - 11 slash commands and 5 auto-invoked skills
-- 17 internal agents
-- a default main-thread `flow-orchestrator` agent
-- a `.flow` state monitor that streams spec progress changes back into Claude
-- 8 composable gates
-- 4 execution strategies for `/curdx-flow:implement`
+- 17 internal agents wired through `flow-orchestrator`
+- 3 output styles: default, `CurdX Spec Mode`, `CurdX Fast Mode`
+- a `flow-state` background monitor that streams spec progress changes back into Claude
+- 9 composable gates and 14 knowledge docs referenced by every agent
+- 4 execution strategies for `/curdx-flow:implement` (linear, subagent, stop-hook, wave)
+- a plugin `bin/` directory: `curdx-flow-state` is PATH-mounted while the plugin is enabled, so agents and hooks can call it as a bare command
 - thin public docs, thick supporting references
 
-## Docs
+## Plugin layout
+
+```
+.claude-plugin/
+  plugin.json          plugin manifest (agents/skills/outputStyles point at directories, not file lists)
+  marketplace.json
+agents/                17 specialist subagents
+skills/                16 skills (commands + auto-invoked)
+hooks/
+  hooks.json           SessionStart, UserPromptSubmit, Stop, SubagentStop, …
+  scripts/             shell handlers (sourced helpers in common.sh, invoked scripts +x)
+gates/                 9 composable review gates
+knowledge/             14 long-form references @-included by agents
+monitors/
+  monitors.json        background watchers (flow-state)
+output-styles/         default + spec-mode + fast-mode
+agent-preamble/        shared preamble all agents @-include
+schemas/               JSON Schemas for plugin manifest, agent / skill frontmatter, hooks
+templates/             scaffold templates the CLI installer copies into .flow/
+bin/                   plugin executables on PATH (curdx-flow-state, plus the npm CLI bin)
+cli/                   npm-published CLI installer (install / upgrade / doctor / uninstall)
+test/                  node:test suite + plugin contract validator regression baseline
+scripts/               release.sh + validate-plugin-contracts.mjs + npm-dist-tag
+```
+
+## Compatibility notes
+
+- **Skill shell execution** — CurdX-Flow skills rely on Bash tool calls. If your
+  Claude Code settings have `disableSkillShellExecution: true`, the spec
+  workflow will not run; remove that setting or scope it away from CurdX-Flow.
+- **Plugin agent fields** — agent frontmatter follows the canonical fields
+  documented at
+  [sub-agents.md](https://code.claude.com/docs/en/sub-agents.md). The fields
+  `hooks`, `mcpServers`, and `permissionMode` are silently ignored by the
+  Claude Code plugin runtime; CurdX-Flow's schema rejects them at validation
+  time so misconfigurations surface before install.
+- **Plugin executables on PATH** — the plugin root `bin/` directory lands on
+  the Bash tool's `PATH` while CurdX-Flow is enabled (Claude Code v2.1.91+).
+
+## Development
+
+```bash
+npm test                              # 110+ tests
+npm run validate:contracts            # lenient validator
+npm run validate:contracts:strict     # strict validator (skill description-length cap is fatal)
+claude plugin validate .              # ground-truth gate
+```
 
-- [docs/getting-started.md](./docs/getting-started.md) for the first end-to-end walkthrough
-- [docs/command-reference.md](./docs/command-reference.md) for flags, strategy semantics, and specialty skill contracts
-- [docs/workflows.md](./docs/workflows.md) for greenfield, brownfield, epic, fast, and enterprise flows
-- [docs/headless-ci.md](./docs/headless-ci.md) for `claude --bare -p`, `system/init`, `system/plugin_install`, and CI patterns
-- [docs/troubleshoot.md](./docs/troubleshoot.md) for operator fixes
-- [docs/architecture.md](./docs/architecture.md) for the skill-first layout
-- [docs/agent-reference.md](./docs/agent-reference.md) for the 17 internal agents and their artifacts
+`scripts/release.sh major|minor|patch` bumps `package.json`, `plugin.json`,
+`marketplace.json`, and the lockfile in lockstep, commits, tags, and pushes.
+The tag push triggers `.github/workflows/npm-publish.yml`.
 
 ## Notes
 
 - `enterprise` mode turns on adversarial, edge-case, security, and DevEx gates.
-- `subagent` is serial; `wave` is the parallel strategy.
+- `subagent` is serial; `wave` is the parallel execution strategy.
 - Headless usage should favor `claude --bare -p` and explicit `--plugin-dir`,
   `--settings`, and `--mcp-config` wiring.

package/agents/flow-adversary.md

@@ -4,6 +4,7 @@ description: Use proactively when reviewing a spec or diff from an attacker or s
 model: opus
 effort: high
 maxTurns: 30
+background: true
 color: red
 tools: [Read, Grep, Glob, Bash]
 ---

package/agents/flow-architect.md

@@ -5,6 +5,7 @@ memory: project
 model: opus
 effort: high
 maxTurns: 40
+background: true
 color: cyan
 tools: [Read, Write, Grep, Glob, Bash, WebSearch]
 ---

package/agents/flow-brownfield-analyst.md

@@ -5,6 +5,7 @@ memory: project
 model: sonnet
 effort: high
 maxTurns: 30
+background: true
 color: blue
 tools: [Read, Write, Grep, Glob, Bash]
 ---

package/agents/flow-edge-hunter.md

@@ -4,6 +4,7 @@ description: Use proactively when a feature, spec, or diff needs a non-happy-pat
 model: sonnet
 effort: high
 maxTurns: 30
+background: true
 color: purple
 tools: [Read, Grep, Glob, Bash]
 ---

package/agents/flow-planner.md

@@ -5,6 +5,7 @@ memory: project
 model: sonnet
 effort: high
 maxTurns: 30
+background: true
 color: cyan
 tools: [Read, Write, Grep, Glob, Bash]
 ---

package/agents/flow-researcher.md

@@ -5,6 +5,7 @@ memory: project
 model: sonnet
 effort: high
 maxTurns: 40
+background: true
 color: blue
 tools: [Read, Write, WebSearch, WebFetch, Grep, Glob, Bash]
 ---

package/agents/flow-reviewer.md

@@ -5,6 +5,7 @@ memory: project
 model: sonnet
 effort: high
 maxTurns: 40
+background: true
 color: purple
 tools: [Read, Grep, Glob, Bash]
 ---

package/agents/flow-ui-researcher.md

@@ -5,6 +5,7 @@ memory: project
 model: sonnet
 effort: medium
 maxTurns: 25
+background: true
 color: blue
 tools: [Read, Write, WebSearch, WebFetch, Grep, Glob, Bash]
 ---

package/agents/flow-verifier.md

@@ -5,6 +5,7 @@ memory: project
 model: sonnet
 effort: high
 maxTurns: 30
+background: true
 color: yellow
 tools: [Read, Grep, Glob, Bash, Monitor]
 ---

package/bin/curdx-flow-state

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+# curdx-flow-state — emit a one-line snapshot of the active CurDX-Flow spec.
+#
+# When the curdx-flow plugin is enabled, Claude Code adds the plugin's bin/
+# directory to the Bash tool's PATH (Claude Code v2.1.91+). Agents, skills,
+# and hooks can then call `curdx-flow-state` as a bare command instead of
+# duplicating Python/Bash snippets that walk .flow state.
+#
+# Output format (single line, stable contract):
+#   spec=<name> phase=<phase> strategy=<strategy> tasks=<idx>/<total> unchecked=<n> [failed_attempts=<n>] [loop=<n>]
+#
+# Exit codes:
+#   0  state available (line printed)
+#   2  no .flow/ root found
+#   3  no active spec
+#
+# Usage from a Bash tool call (or any shell):
+#   curdx-flow-state              # current cwd
+#   curdx-flow-state /path/to/repo
+
+set -u
+
+ROOT="${CLAUDE_PLUGIN_ROOT:-}"
+if [ -z "$ROOT" ]; then
+  # Resolve relative to this script's location (works for npm install + plugin install).
+  ROOT="$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)"
+fi
+
+# shellcheck source=hooks/scripts/common.sh
+. "$ROOT/hooks/scripts/common.sh"
+
+target="${1:-${PWD:-}}"
+flow_root="$(resolve_flow_root "$target" 2>/dev/null || true)"
+[ -n "$flow_root" ] || exit 2
+
+active="$(cat "$flow_root/.flow/.active-spec" 2>/dev/null || true)"
+[ -n "$active" ] || exit 3
+
+spec_dir="$flow_root/.flow/specs/$active"
+state_file="$spec_dir/.state.json"
+tasks_file="$spec_dir/tasks.md"
+
+if has_python3; then
+  export CURDX_STATE_ACTIVE="$active"
+  export CURDX_STATE_FILE="$state_file"
+  export CURDX_TASKS_FILE="$tasks_file"
+  python3 <<'PY'
+import json
+import os
+import re
+
+active = os.environ["CURDX_STATE_ACTIVE"]
+state_file = os.environ["CURDX_STATE_FILE"]
+tasks_file = os.environ["CURDX_TASKS_FILE"]
+
+phase = "unknown"
+strategy = "unknown"
+task_index = 0
+total_tasks = 0
+failed_attempts = 0
+global_iteration = 0
+
+if os.path.exists(state_file):
+    try:
+        state = json.load(open(state_file, "r", encoding="utf-8"))
+        phase = state.get("phase") or phase
+        strategy = state.get("strategy") or strategy
+        execute_state = state.get("execute_state") or {}
+        task_index = int(execute_state.get("task_index") or 0)
+        total_tasks = int(execute_state.get("total_tasks") or 0)
+        failed_attempts = int(execute_state.get("failed_attempts") or 0)
+        global_iteration = int(execute_state.get("global_iteration") or 0)
+    except Exception:
+        phase = "invalid-state"
+
+unchecked = -1
+if os.path.exists(tasks_file):
+    try:
+        text = open(tasks_file, "r", encoding="utf-8").read()
+        unchecked = len(re.findall(r"^- \[ \] \*\*[0-9]+(\.[0-9]+|\.VF|\.X(\+[0-9]+)?)*\*\*", text, re.M))
+    except Exception:
+        unchecked = -1
+
+parts = [
+    f"spec={active}",
+    f"phase={phase}",
+    f"strategy={strategy}",
+]
+if total_tasks > 0:
+    parts.append(f"tasks={task_index}/{total_tasks}")
+parts.append(f"unchecked={unchecked}")
+if failed_attempts > 0:
+    parts.append(f"failed_attempts={failed_attempts}")
+if global_iteration > 0:
+    parts.append(f"loop={global_iteration}")
+
+print(" ".join(parts))
+PY
+  exit 0
+fi
+
+# Fallback when python3 is unavailable: emit minimum useful info.
+printf 'spec=%s\n' "$active"
+exit 0

package/hooks/hooks.json

@@ -21,6 +21,37 @@
         ]
       }
     ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/session-title.sh",
+            "statusMessage": "Refreshing CurDX-Flow session title"
+          }
+        ]
+      }
+    ],
+    "CwdChanged": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/flow-context-watch.sh"
+          }
+        ]
+      }
+    ],
+    "FileChanged": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/flow-context-watch.sh"
+          }
+        ]
+      }
+    ],
     "Stop": [
       {
         "hooks": [
@@ -43,6 +74,47 @@
         ]
       }
     ],
+    "TaskCreated": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/task-lifecycle-guard.sh"
+          }
+        ]
+      }
+    ],
+    "TaskCompleted": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/task-lifecycle-guard.sh"
+          }
+        ]
+      }
+    ],
+    "TeammateIdle": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/teammate-idle-guard.sh"
+          }
+        ]
+      }
+    ],
+    "ConfigChange": [
+      {
+        "matcher": "project_settings|local_settings",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/config-change-guard.sh"
+          }
+        ]
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "AskUserQuestion",