@curdx/flow 2.2.5 → 2.3.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.2.5"
+    "version": "2.3.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.2.5",
+      "version": "2.3.0",
       "author": {
         "name": "wdx",
         "email": "bydongxin@gmail.com"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "curdx-flow",
-  "version": "2.2.5",
+  "version": "2.3.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",
@@ -25,6 +25,7 @@
     "./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",
@@ -37,6 +38,30 @@
     "./agents/flow-verifier.md"
   ],
   "hooks": "./hooks/hooks.json",
+  "outputStyles": "./output-styles/",
+  "monitors": "./monitors/monitors.json",
+  "userConfig": {
+    "autonomous_blocking": {
+      "type": "boolean",
+      "title": "Autonomous stop-hook blocking",
+      "description": "Keep stop-hook execution running until the active spec finishes when work remains.",
+      "default": true
+    },
+    "daily_dependency_check": {
+      "type": "boolean",
+      "title": "Daily dependency reminder",
+      "description": "Show a once-per-day reminder when recommended companion plugins are missing.",
+      "default": true
+    },
+    "monitor_interval_seconds": {
+      "type": "number",
+      "title": "Flow monitor polling interval",
+      "description": "How often the CurDX-Flow plugin monitor polls .flow state and task progress.",
+      "default": 8,
+      "min": 3,
+      "max": 60
+    }
+  },
   "dependencies": [
     {
       "name": "context7-plugin",

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 2.3.0
+
+- added a default `flow-orchestrator` main-thread agent through plugin-level `settings.json`
+- added a plugin `flow-state` monitor plus `userConfig` runtime knobs for stop-hook blocking, dependency reminders, and monitor cadence
+- made the manifest explicit about `outputStyles` and `monitors`, shipped the monitor assets in npm tarballs, and strengthened pack/plugin contract tests
+- updated doctor/runtime guidance and public docs to reflect the new main-agent + monitor architecture
+
 ## 2.2.4
 
 - aligned the public docs surface with the current skill-first plugin layout

package/README.md

@@ -8,7 +8,7 @@
 [![Plugin](https://img.shields.io/badge/claude--code-plugin-blue)](https://code.claude.com)
 
 CurdX-Flow is a skill-first Claude Code plugin. The public surface stays small:
-11 slash commands, 5 auto-invoked skills, 16 internal agents, and a thin set of
+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/`.
 
@@ -64,7 +64,9 @@ This produces a durable audit trail instead of a chat-only claim of completion.
 ## What ships
 
 - 11 slash commands and 5 auto-invoked skills
-- 16 internal agents
+- 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`
 - thin public docs, thick supporting references
@@ -77,7 +79,7 @@ This produces a durable audit trail instead of a chat-only claim of completion.
 - [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 16 internal agents and their artifacts
+- [docs/agent-reference.md](./docs/agent-reference.md) for the 17 internal agents and their artifacts
 
 ## Notes
 

package/agents/flow-orchestrator.md

@@ -0,0 +1,145 @@
+---
+name: flow-orchestrator
+description: "Use proactively when CurDX-Flow should own the main-thread workflow: gather context, choose fast-vs-spec path, coordinate specialist work, and enforce evidence before completion."
+memory: project
+model: sonnet
+effort: high
+maxTurns: 40
+color: cyan
+---
+
+# Flow Orchestrator — Main Thread Coordination Agent
+
+@${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md
+@${CLAUDE_PLUGIN_ROOT}/knowledge/execution-strategies.md
+@${CLAUDE_PLUGIN_ROOT}/knowledge/planning-reviews.md
+@${CLAUDE_PLUGIN_ROOT}/knowledge/claude-code-runtime-contracts.md
+
+## Your Role
+
+You are the default CurDX-Flow main-thread agent. Keep the top-level Claude
+session in a rigorous engineering mode:
+
+- gather context before editing
+- choose the smallest correct workflow
+- delegate specialist work to `flow-*` agents
+- keep artifacts on disk and summaries short
+- refuse completion claims without evidence
+
+You are not the primary artifact writer for research, requirements, design,
+tasks, review, or verification. Those outputs belong to the specialist agents.
+
+## Operating Modes
+
+Choose exactly one operating mode after the first context pass:
+
+1. **Fast path**
+   Use for small, well-bounded work that can be finished safely in one pass.
+   Preferred surfaces:
+   - direct execution in the main thread
+   - `/curdx-flow:fast`
+   - `flow-debugger` for surgical bug work
+
+2. **Spec path**
+   Use for multi-file features, ambiguous requests, risky refactors, new
+   architecture, or anything that needs durable review/verification evidence.
+   Preferred surfaces:
+   - `/curdx-flow:init` if `.flow/` does not exist yet
+   - `/curdx-flow:start` or existing active spec
+   - specialist agents for research, requirements, design, tasks, execution,
+     verification, and review
+
+3. **Advisory path**
+   Use for status checks, explanations, health checks, and runtime diagnostics.
+   Preferred surfaces:
+   - `/curdx-flow:status`
+   - `npx @curdx/flow doctor`
+   - `flow-brownfield-analyst` for unfamiliar codebases
+
+State which path you chose before doing substantial work.
+
+## Delegation Map
+
+- Unfamiliar or inherited repo → `flow-brownfield-analyst`
+- Research or version-sensitive external docs → `flow-researcher`
+- Requirements / user stories / acceptance criteria → `flow-product-designer`
+- Architecture / tradeoffs / component boundaries → `flow-architect`
+- Task decomposition / coverage audit → `flow-planner`
+- Single task execution → `flow-executor`
+- Bug root-cause work → `flow-debugger`
+- Final verification → `flow-verifier`
+- Review / adversarial / edge-case passes → `flow-reviewer`, `flow-adversary`, `flow-edge-hunter`
+- UI QA or UI references → `flow-qa-engineer`, `flow-ui-researcher`, `flow-ux-designer`
+- Security review → `flow-security-auditor`
+- Epic decomposition → `flow-triage-analyst`
+
+Delegate when the subtask will create large context, produce a durable artifact,
+or benefit from a specialized prompt. Keep the main thread focused on orchestration.
+
+## Main-Thread Rules
+
+### 1. Context before edits
+
+Before changing files:
+- inspect the relevant code and runtime surface
+- identify existing patterns to preserve
+- decide whether the task is fast-path or spec-path
+
+Do not jump straight from user request to writes unless the task is obviously
+tiny and local.
+
+### 2. Use the plugin surfaces intentionally
+
+- If the user asks for a workflow action that already exists as a CurDX-Flow
+  command or skill, prefer that surface instead of reinventing a parallel flow.
+- If `.flow/` exists, keep work aligned with the active spec unless the user
+  explicitly asks to bypass it.
+- If `.flow/` does not exist and the task is non-trivial, initialize or ask for
+  confirmation only when the distinction changes the execution model.
+
+### 3. Evidence-first completion
+
+Never say complete merely because code changed.
+
+Completion requires evidence proportional to the task:
+- code read or diff for structural claims
+- tests / build / lint / verify commands for behavioral claims
+- browser evidence for UI claims
+- written artifacts for spec/review/verification phases
+
+### 4. Keep summaries compact
+
+When a specialist agent writes an artifact, your summary should point to the
+artifact path, call out the decision taken, and state the next action. Do not
+restate the full file content in chat.
+
+### 5. Prefer directness over ceremony
+
+CurDX-Flow is disciplined, but not bureaucratic.
+
+- Small clear task: execute directly.
+- Medium ambiguous task: inspect, plan briefly, then execute.
+- Large risky task: switch to the full spec path.
+
+Do not force the user through every phase when the task does not need it.
+
+## Runtime Awareness
+
+When the task depends on Claude Code runtime behavior itself
+(plugins, hooks, agents, monitors, settings, output styles, commands):
+
+- re-check the official Claude Code docs
+- follow `${CLAUDE_PLUGIN_ROOT}/knowledge/claude-code-runtime-contracts.md`
+- prefer `claude plugin validate .` over assumptions
+
+## Output Contract
+
+Your top-level replies should be:
+
+1. short statement of chosen path
+2. what context you gathered or what artifact was produced
+3. what you changed or delegated
+4. concrete evidence and next action
+
+Do not produce long architectural essays in the main thread when a specialist
+artifact is the correct output.

package/cli/install-next-steps.js

@@ -5,7 +5,9 @@ export function printNextSteps() {
   const cliCmd = cliOnPath ? "curdx-flow" : "npx @curdx/flow";
 
   console.log(`\n${color.bold(`${color.green("✓")} Install complete`)}\n`);
-  console.log(`${color.bold("Restart Claude Code")} so the plugin registers all its commands and hooks.\n`);
+  console.log(
+    `${color.bold("Restart Claude Code")} so the plugin registers its commands, hooks, default main-thread agent, and background monitor.\n`
+  );
   console.log(`${color.bold("Next steps")}:\n`);
   console.log(`  ${color.dim("# Verify health")}`);
   console.log(`  ${cliCmd} doctor\n`);

package/cli/lib/doctor-claude-settings.js

@@ -73,6 +73,7 @@ const CURDX_FLOW_AGENT_TYPES = [
   "flow-debugger",
   "flow-edge-hunter",
   "flow-executor",
+  "flow-orchestrator",
   "flow-planner",
   "flow-product-designer",
   "flow-qa-engineer",

package/cli/lib/doctor-report.js

@@ -158,7 +158,7 @@ export function buildDoctorReport({
         "warn",
         `claude CLI            ${claudeVersionValue} below recommended ${MIN_CLAUDE_VERSION}`,
         [
-          "curdx-flow uses modern Claude Code plugin dependency resolution and plugin bin/ PATH support",
+          "curdx-flow uses modern Claude Code plugin dependency resolution, plugin bin/PATH support, plugin-level main-agent routing, and monitor surfaces",
           "run: claude update",
         ]
       );

package/hooks/scripts/common.sh

@@ -4,6 +4,13 @@ has_python3() {
   command -v python3 >/dev/null 2>&1
 }
 
+env_flag_enabled() {
+  case "$(printf '%s' "${1:-}" | tr '[:upper:]' '[:lower:]')" in
+    1|true|yes|on) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
 json_escape() {
   local value="${1:-}"
 

package/hooks/scripts/session-start.sh

@@ -26,7 +26,7 @@ mkdir -p "$DATA_DIR" 2>/dev/null || true
 LAST_CHECK=""
 [ -f "$MARKER" ] && LAST_CHECK="$(cat "$MARKER" 2>/dev/null)"
 
-if [ "$LAST_CHECK" != "$TODAY" ]; then
+if env_flag_enabled "${CLAUDE_PLUGIN_OPTION_DAILY_DEPENDENCY_CHECK:-1}" && [ "$LAST_CHECK" != "$TODAY" ]; then
   MISSING=()
 
   # Skip if `claude` CLI is not on PATH

package/hooks/scripts/stop-watcher.sh

@@ -26,6 +26,10 @@ allow_stop() {
   exit 0
 }
 
+autonomous_blocking_enabled() {
+  env_flag_enabled "${CLAUDE_PLUGIN_OPTION_AUTONOMOUS_BLOCKING:-1}"
+}
+
 # ---------- helper: block and inject continuation ----------
 block_continue() {
   local reason="$1"
@@ -83,6 +87,10 @@ EOF
 [ "$STRATEGY" != "stop-hook" ] && allow_stop
 [ "$PHASE" != "execute" ] && allow_stop
 
+if ! autonomous_blocking_enabled; then
+  allow_stop
+fi
+
 # ---------- 5. Check hook input + completion signal in transcript ----------
 # Claude Code passes transcript path via stdin as JSON: {"transcript_path": "/path/..."}
 # We read stdin to detect ALL_TASKS_COMPLETE or TASK_FAILED

package/knowledge/claude-code-runtime-contracts.md

@@ -72,11 +72,23 @@ Guarded artifact targets:
 ## Plugin Settings
 
 - Claude Code plugin-root `settings.json` currently supports only `agent` and `subagentStatusLine`.
-- CurDX-Flow ships only `subagentStatusLine`, pointing at `${CLAUDE_PLUGIN_ROOT}/hooks/scripts/subagent-statusline.sh`.
+- CurDX-Flow ships both:
+  - `agent: "flow-orchestrator"` to route the main thread through the CurDX-Flow coordinator by default.
+  - `subagentStatusLine`, pointing at `${CLAUDE_PLUGIN_ROOT}/hooks/scripts/subagent-statusline.sh`.
 - The status-line script must fail open on malformed input or missing `python3`; UI decoration must never break agent execution.
 - Plugin-root references must never traverse outside the plugin directory. Installed marketplace plugins run from Claude Code's plugin cache, so parent-directory references are invalid even if they work in a development checkout.
 - If adding plugin settings, update `schemas/plugin-settings.schema.json`, `test/plugin-structure-contract.test.js`, `test/pack-tarball-smoke.test.js`, and `scripts/validate-plugin-contracts.mjs` in the same change.
 
+## Plugin Monitors and User Config
+
+- CurDX-Flow ships a plugin monitor at `${CLAUDE_PLUGIN_ROOT}/monitors/monitors.json` to surface `.flow` state changes back into the active Claude session.
+- Monitors run only when the Claude `Monitor` tool is available, and only in interactive CLI sessions.
+- CurDX-Flow `userConfig` values are exported to plugin subprocesses as `CLAUDE_PLUGIN_OPTION_<KEY>`.
+- Current runtime knobs:
+  - `autonomous_blocking`: lets users disable stop-hook continuation without editing plugin files.
+  - `daily_dependency_check`: silences or enables the once-per-day recommended-plugin reminder.
+  - `monitor_interval_seconds`: controls plugin monitor polling cadence.
+
 ## Plugin Dependency Constraints
 
 - Official dependency version constraints require upstream plugin release tags in the `{plugin-name}--v{version}` format.

package/monitors/monitors.json

@@ -0,0 +1,8 @@
+[
+  {
+    "name": "flow-state",
+    "description": "Watch CurDX-Flow .flow state changes and notify Claude when the active spec, phase, or remaining tasks change.",
+    "command": "${CLAUDE_PLUGIN_ROOT}/monitors/scripts/flow-state-monitor.sh",
+    "when": "always"
+  }
+]

package/monitors/scripts/flow-state-monitor.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+
+set -u
+
+interval="${CLAUDE_PLUGIN_OPTION_MONITOR_INTERVAL_SECONDS:-8}"
+case "$interval" in
+  ''|*[!0-9]*)
+    interval=8
+    ;;
+esac
+if [ "$interval" -lt 3 ] 2>/dev/null; then
+  interval=3
+fi
+
+build_snapshot() {
+  if [ ! -d ".flow" ]; then
+    return 0
+  fi
+
+  local active=""
+  active="$(cat .flow/.active-spec 2>/dev/null || true)"
+  [ -z "$active" ] && return 0
+
+  local spec_dir=".flow/specs/$active"
+  [ ! -d "$spec_dir" ] && return 0
+
+  local state_file="$spec_dir/.state.json"
+  local tasks_file="$spec_dir/tasks.md"
+
+  python3 - "$active" "$state_file" "$tasks_file" <<'PY' 2>/dev/null
+import json
+import os
+import re
+import sys
+
+active, state_file, tasks_file = sys.argv[1:4]
+
+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 = execute_state.get("task_index") or 0
+        total_tasks = execute_state.get("total_tasks") or 0
+        failed_attempts = execute_state.get("failed_attempts") or 0
+        global_iteration = execute_state.get("global_iteration") or 0
+    except Exception:
+        phase = "invalid-state"
+
+unchecked = 0
+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"CurDX-Flow monitor: 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
+}
+
+last_snapshot=""
+
+while true; do
+  snapshot="$(build_snapshot)"
+  if [ -n "$snapshot" ] && [ "$snapshot" != "$last_snapshot" ]; then
+    printf '%s\n' "$snapshot"
+    last_snapshot="$snapshot"
+  fi
+
+  if [ "${CURDX_FLOW_MONITOR_ONCE:-0}" = "1" ]; then
+    exit 0
+  fi
+
+  sleep "$interval"
+done

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@curdx/flow",
-  "version": "2.2.5",
+  "version": "2.3.0",
   "description": "Skill-first discipline layer and CLI installer for Claude Code",
   "type": "module",
   "bin": {
@@ -19,6 +19,7 @@
     "gates/",
     "hooks/",
     "knowledge/",
+    "monitors/",
     "agent-preamble/",
     "output-styles/",
     "templates/",

package/settings.json

@@ -1,4 +1,5 @@
 {
+  "agent": "flow-orchestrator",
   "subagentStatusLine": {
     "type": "command",
     "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/subagent-statusline.sh"