@curdx/flow 2.3.10 → 3.0.0

package/hooks/scripts/session-title.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$SCRIPT_DIR/common.sh"
+
+INPUT="$(cat 2>/dev/null || echo "{}")"
+DATA_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.claude/plugins/data/curdx-flow}"
+FLOW_ROOT="$(resolve_flow_root 2>/dev/null || true)"
+
+[ -n "$FLOW_ROOT" ] || exit 0
+
+ACTIVE="$(cat "$FLOW_ROOT/.flow/.active-spec" 2>/dev/null || true)"
+[ -n "$ACTIVE" ] || exit 0
+
+if ! has_python3; then
+  emit_userprompt_submit_title "curdx-flow/${ACTIVE}"
+  exit 0
+fi
+
+export CURDX_FLOW_SESSION_TITLE_INPUT="$INPUT"
+export CURDX_FLOW_SESSION_TITLE_ACTIVE="$ACTIVE"
+export CURDX_FLOW_ROOT="$FLOW_ROOT"
+
+TITLE_INFO="$(python3 <<'PY' 2>/dev/null
+import json
+import os
+from pathlib import Path
+
+active = os.environ["CURDX_FLOW_SESSION_TITLE_ACTIVE"]
+data = json.loads(os.environ.get("CURDX_FLOW_SESSION_TITLE_INPUT", "{}"))
+session_id = data.get("session_id", "")
+
+phase = ""
+task_index = 0
+total_tasks = 0
+
+state_path = Path(os.environ["CURDX_FLOW_ROOT"]) / ".flow" / "specs" / active / ".state.json"
+if state_path.exists():
+    try:
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+        phase = state.get("phase") or ""
+        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)
+    except Exception:
+        phase = ""
+        task_index = 0
+        total_tasks = 0
+
+label = phase
+if phase == "execute" and total_tasks > 0:
+    label = f"{phase} {task_index}/{total_tasks}"
+
+title = f"curdx-flow/{active}"
+if label:
+    title = f"{title} [{label}]"
+
+print(session_id)
+print(title)
+PY
+)"
+
+SESSION_ID="$(printf '%s\n' "$TITLE_INFO" | sed -n '1p')"
+TITLE="$(printf '%s\n' "$TITLE_INFO" | sed -n '2p')"
+[ -n "$TITLE" ] || exit 0
+
+if [ -n "$SESSION_ID" ]; then
+  MARKER_DIR="$DATA_DIR/session-titles"
+  MARKER_FILE="$MARKER_DIR/$SESSION_ID"
+  LAST_TITLE=""
+
+  if [ -f "$MARKER_FILE" ]; then
+    LAST_TITLE="$(cat "$MARKER_FILE" 2>/dev/null || true)"
+  fi
+
+  if [ "$LAST_TITLE" = "$TITLE" ]; then
+    exit 0
+  fi
+
+  mkdir -p "$MARKER_DIR" 2>/dev/null || true
+  printf '%s\n' "$TITLE" > "$MARKER_FILE" 2>/dev/null || true
+fi
+
+emit_userprompt_submit_title "$TITLE"
+exit 0

package/hooks/scripts/stop-watcher.sh

@@ -38,12 +38,13 @@ block_continue() {
 }
 
 # ---------- 1. Must be a flow project ----------
-[ ! -d ".flow" ] && allow_stop
+FLOW_ROOT="$(resolve_flow_root 2>/dev/null || true)"
+[ -n "$FLOW_ROOT" ] || allow_stop
 
 # ---------- 2. Must have active spec ----------
-ACTIVE=$(cat .flow/.active-spec 2>/dev/null)
+ACTIVE=$(cat "$FLOW_ROOT/.flow/.active-spec" 2>/dev/null)
 [ -z "$ACTIVE" ] && allow_stop
-SPEC_DIR=".flow/specs/$ACTIVE"
+SPEC_DIR="$FLOW_ROOT/.flow/specs/$ACTIVE"
 [ ! -d "$SPEC_DIR" ] && allow_stop
 
 STATE_FILE="$SPEC_DIR/.state.json"

package/hooks/scripts/subagent-artifact-guard.sh

@@ -14,6 +14,7 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 . "$SCRIPT_DIR/common.sh"
 
 INPUT="$(cat 2>/dev/null || echo "{}")"
+FLOW_ROOT="$(resolve_flow_root 2>/dev/null || true)"
 
 if ! has_python3; then
   # Without JSON parsing, fail open rather than blocking subagents blindly.
@@ -43,18 +44,6 @@ looks_like_success() {
   printf '%s' "$msg" | grep -Eq '(^✓| generated$| generated\n|Wrote |Review complete|Requirements done|Research complete|UI Sketch generation complete|Report:|Next:|TASK_COMPLETE|ALL_TASKS_COMPLETE)'
 }
 
-active_spec_path() {
-  local file_name="$1"
-
-  [ ! -d ".flow" ] && return 1
-
-  local active
-  active="$(cat .flow/.active-spec 2>/dev/null)"
-  [ -z "$active" ] && return 1
-
-  printf '.flow/specs/%s/%s\n' "$active" "$file_name"
-}
-
 completed_task_id() {
   local msg="${1:-}"
   printf '%s' "$msg" | sed -nE 's/.*TASK_COMPLETE:[[:space:]]*([0-9]+(\.([0-9]+|VF|X(\+[0-9]+)?))*).*/\1/p' | head -1
@@ -64,24 +53,10 @@ artifact_target=""
 minimum_size=200
 
 case "$AGENT_TYPE" in
-  flow-researcher)
-    artifact_target="$(active_spec_path research.md)" || exit 0
-    minimum_size=400
-    ;;
-  flow-product-designer)
-    artifact_target="$(active_spec_path requirements.md)" || exit 0
-    minimum_size=400
-    ;;
-  flow-architect)
-    artifact_target="$(active_spec_path design.md)" || exit 0
-    minimum_size=400
-    ;;
-  flow-planner)
-    artifact_target="$(active_spec_path tasks.md)" || exit 0
-    minimum_size=400
-    ;;
   flow-executor)
-    artifact_target="$(active_spec_path tasks.md)" || exit 0
+    curdx_resolve_artifact_contract "$AGENT_TYPE" "$LAST_MESSAGE" "$FLOW_ROOT" || exit 0
+    artifact_target="$CURDX_ARTIFACT_TARGET"
+    minimum_size="$CURDX_ARTIFACT_MIN_SIZE"
     if printf '%s' "$LAST_MESSAGE" | grep -q 'ALL_TASKS_COMPLETE'; then
       exit 0
     fi
@@ -93,52 +68,10 @@ case "$AGENT_TYPE" in
     emit_subagentstop_block "[CurDX-Flow subagent-artifact-guard] flow-executor emitted TASK_COMPLETE: ${task_id}, but ${artifact_target} does not mark that task as [x]. Update tasks.md and the spec progress/state before stopping."
     exit 0
     ;;
-  flow-debugger)
-    artifact_target="$(active_spec_path debug-report.md)" || exit 0
-    minimum_size=250
-    ;;
-  flow-triage-analyst)
-    artifact_target="$(active_spec_path triage-report.md)" || exit 0
-    minimum_size=250
-    ;;
-  flow-ux-designer)
-    artifact_target="$(active_spec_path ui-sketch.md)" || exit 0
-    minimum_size=250
-    ;;
-  flow-reviewer)
-    artifact_target="$(active_spec_path review-report.md)" || exit 0
-    minimum_size=300
-    ;;
-  flow-verifier)
-    artifact_target="$(active_spec_path verification-report.md)" || exit 0
-    minimum_size=300
-    ;;
-  flow-security-auditor)
-    artifact_target="$(active_spec_path security-audit.md)" || exit 0
-    minimum_size=250
-    ;;
-  flow-qa-engineer)
-    artifact_target="$(active_spec_path qa-report.md)" || exit 0
-    minimum_size=250
-    ;;
-  flow-edge-hunter)
-    artifact_target="$(active_spec_path edge-cases.md)" || exit 0
-    minimum_size=250
-    ;;
-  flow-adversary)
-    artifact_target="$(active_spec_path adversarial-review.md)" || exit 0
-    minimum_size=250
-    ;;
-  flow-ui-researcher)
-    artifact_target="$(active_spec_path ui-research.md)" || exit 0
-    minimum_size=250
-    ;;
-  flow-brownfield-analyst)
-    artifact_target=".flow/codebase-index.md"
-    minimum_size=250
-    ;;
   *)
-    exit 0
+    curdx_resolve_artifact_contract "$AGENT_TYPE" "$LAST_MESSAGE" "$FLOW_ROOT" || exit 0
+    artifact_target="$CURDX_ARTIFACT_TARGET"
+    minimum_size="$CURDX_ARTIFACT_MIN_SIZE"
     ;;
 esac
 

package/hooks/scripts/subagent-statusline.sh

@@ -55,10 +55,16 @@ def active_spec(cwd):
     if not cwd:
         return ""
     try:
-        value = (Path(cwd) / ".flow" / ".active-spec").read_text(encoding="utf-8").strip()
+        current = Path(cwd).resolve()
     except Exception:
         return ""
-    return value[:40]
+    for candidate in [current, *current.parents]:
+        try:
+            value = (candidate / ".flow" / ".active-spec").read_text(encoding="utf-8").strip()
+        except Exception:
+            continue
+        return value[:40]
+    return ""
 
 
 def token_label(value):

package/hooks/scripts/task-lifecycle-guard.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$SCRIPT_DIR/common.sh"
+
+INPUT="$(cat 2>/dev/null || echo "{}")"
+
+if ! has_python3; then
+  exit 0
+fi
+
+export CURDX_TASK_GUARD_INPUT="$INPUT"
+
+read_json_field() {
+  local field="$1"
+  python3 - "$field" <<'PY' 2>/dev/null
+import json
+import os
+import sys
+
+try:
+    data = json.loads(os.environ.get("CURDX_TASK_GUARD_INPUT", "{}"))
+except Exception:
+    data = {}
+
+field = sys.argv[1]
+value = data.get(field, "")
+if isinstance(value, str):
+    value = value.strip()
+elif value is None:
+    value = ""
+print(value)
+PY
+}
+
+HOOK_EVENT_NAME="$(read_json_field hook_event_name)"
+TASK_SUBJECT="$(read_json_field task_subject)"
+TASK_DESCRIPTION="$(read_json_field task_description)"
+
+FLOW_ROOT="$(resolve_flow_root 2>/dev/null || true)"
+[ -n "$FLOW_ROOT" ] || exit 0
+
+ACTIVE_SPEC="$(cat "$FLOW_ROOT/.flow/.active-spec" 2>/dev/null || true)"
+[ -n "$ACTIVE_SPEC" ] || exit 0
+
+TASKS_FILE="$FLOW_ROOT/.flow/specs/$ACTIVE_SPEC/tasks.md"
+[ -f "$TASKS_FILE" ] || exit 0
+
+extract_curdx_task_id() {
+  python3 <<'PY' 2>/dev/null
+import os
+import re
+
+subject = os.environ.get("CURDX_TASK_GUARD_SUBJECT", "").strip()
+patterns = [
+    r'^\[P\]\s+([0-9]+(?:\.([0-9]+|VF|X(\+[0-9]+)?))*)\b',
+    r'^\[VERIFY\]\s+([0-9]+(?:\.([0-9]+|VF|X(\+[0-9]+)?))*)\b',
+    r'^([0-9]+(?:\.([0-9]+|VF|X(\+[0-9]+)?))*)\b',
+]
+for pattern in patterns:
+    match = re.match(pattern, subject)
+    if match:
+        print(match.group(1))
+        break
+PY
+}
+
+export CURDX_TASK_GUARD_SUBJECT="$TASK_SUBJECT"
+CURDX_TASK_ID="$(extract_curdx_task_id)"
+[ -n "$CURDX_TASK_ID" ] || exit 0
+
+task_exists() {
+  local escaped_id
+  escaped_id="$(printf '%s' "$1" | sed 's/[.[\*^$()+?{|]/\\&/g')"
+  grep -Eq "^- \\[[ xX]\\] \\*\\*${escaped_id}\\*\\*" "$TASKS_FILE" 2>/dev/null
+}
+
+task_completed() {
+  local escaped_id
+  escaped_id="$(printf '%s' "$1" | sed 's/[.[\*^$()+?{|]/\\&/g')"
+  grep -Eq "^- \\[[xX]\\] \\*\\*${escaped_id}\\*\\*" "$TASKS_FILE" 2>/dev/null
+}
+
+if ! task_exists "$CURDX_TASK_ID"; then
+  printf '%s\n' "[CurDX-Flow task-lifecycle-guard] Native task '${TASK_SUBJECT}' references CurDX task ${CURDX_TASK_ID}, but ${TASKS_FILE} does not contain that task id. Rebuild native tasks from tasks.md before proceeding." >&2
+  exit 2
+fi
+
+case "$HOOK_EVENT_NAME" in
+  TaskCreated)
+    if [ -z "$TASK_DESCRIPTION" ]; then
+      printf '%s\n' "[CurDX-Flow task-lifecycle-guard] Native task '${TASK_SUBJECT}' is missing a description. Include a compact description derived from 'Done when' and 'Verify' so the task list mirrors tasks.md faithfully." >&2
+      exit 2
+    fi
+    ;;
+  TaskCompleted)
+    if ! task_completed "$CURDX_TASK_ID"; then
+      printf '%s\n' "[CurDX-Flow task-lifecycle-guard] Native task '${TASK_SUBJECT}' cannot be marked completed before ${TASKS_FILE} marks ${CURDX_TASK_ID} as [x]. Update tasks.md and disk-backed state first, then complete the native task." >&2
+      exit 2
+    fi
+    ;;
+esac
+
+exit 0

package/hooks/scripts/teammate-idle-guard.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# CurDX-Flow TeammateIdle Hook
+# Keeps artifact-producing CurDX teammates from idling before their disk artifact lands.
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$SCRIPT_DIR/common.sh"
+
+INPUT="$(cat 2>/dev/null || echo "{}")"
+FLOW_ROOT="$(resolve_flow_root 2>/dev/null || true)"
+
+[ -n "$FLOW_ROOT" ] || exit 0
+has_python3 || exit 0
+
+export CURDX_TEAMMATE_IDLE_INPUT="$INPUT"
+
+read_json_field() {
+  local field="$1"
+  python3 - "$field" <<'PY' 2>/dev/null
+import json
+import os
+import sys
+
+try:
+    data = json.loads(os.environ.get("CURDX_TEAMMATE_IDLE_INPUT", "{}"))
+except Exception:
+    data = {}
+
+value = data.get(sys.argv[1], "")
+if isinstance(value, str):
+    value = value.strip()
+elif value is None:
+    value = ""
+print(value)
+PY
+}
+
+TEAM_NAME="$(read_json_field team_name)"
+TEAMMATE_NAME="$(read_json_field teammate_name)"
+
+[ -n "$TEAM_NAME" ] || exit 0
+[ -n "$TEAMMATE_NAME" ] || exit 0
+
+TEAM_CONFIG="${HOME}/.claude/teams/${TEAM_NAME}/config.json"
+[ -f "$TEAM_CONFIG" ] || exit 0
+
+export CURDX_TEAM_CONFIG="$TEAM_CONFIG"
+export CURDX_TEAMMATE_NAME="$TEAMMATE_NAME"
+
+AGENT_TYPE="$(python3 <<'PY' 2>/dev/null
+import json
+import os
+
+try:
+    data = json.load(open(os.environ["CURDX_TEAM_CONFIG"]))
+except Exception:
+    raise SystemExit(0)
+
+name = os.environ["CURDX_TEAMMATE_NAME"]
+for member in data.get("members", []) or []:
+    if isinstance(member, dict) and (member.get("name") or "").strip() == name:
+        print((member.get("agent_type") or "").strip())
+        break
+PY
+)"
+
+[ -n "$AGENT_TYPE" ] || exit 0
+
+curdx_resolve_artifact_contract "$AGENT_TYPE" "" "$FLOW_ROOT" || exit 0
+
+artifact_target="$CURDX_ARTIFACT_TARGET"
+minimum_size="$CURDX_ARTIFACT_MIN_SIZE"
+
+if [ -f "$artifact_target" ]; then
+  size="$(wc -c < "$artifact_target" 2>/dev/null | tr -d ' ')"
+  if [ "${size:-0}" -ge "$minimum_size" ]; then
+    exit 0
+  fi
+fi
+
+printf '%s\n' "[CurDX-Flow teammate-idle-guard] Teammate '${TEAMMATE_NAME}' (${AGENT_TYPE}) is about to go idle, but ${artifact_target} is missing or too small. Write the required CurDX artifact to disk before idling." >&2
+exit 2

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

@@ -32,6 +32,11 @@ When a behavior is unclear, prefer the official docs and `claude plugin validate
 - `PreToolUse` also supports `hookSpecificOutput.permissionDecision = "defer"` for deferred tool handling in `-p` / SDK-style flows; do not assume deny/allow are the only valid permission outcomes.
 - `PermissionDenied` can return `{ "retry": true }` to let Claude try a different approach after an auto-mode classifier denial.
 - Hooks must fail open when runtime prerequisites are missing (`python3`, malformed stdin JSON, absent `.flow/` state). The exception is an explicit, success-looking subagent completion with a missing required artifact.
+- Hook and monitor scripts must not assume the current working directory is the repo root. Official `CwdChanged` exists, and users often work from nested package/app directories, so CurDX-Flow runtime scripts should prefer `CLAUDE_PROJECT_DIR` and otherwise walk upward until they find the project `.flow/` root.
+- CurDX-Flow may use `CwdChanged` + `FileChanged` to maintain dynamic watch paths for `.flow/.active-spec`, the active spec `.state.json`, and `tasks.md`. Treat that watch layer as reactive context plumbing, not as a replacement for the monitor or disk-backed truth.
+- `TaskCreated` / `TaskCompleted` can be used as native-task-sync guardrails, but only for CurDX-shaped task subjects. Never let those hooks break unrelated user task-list workflows that happen outside an active CurDX spec.
+- `ConfigChange` can block project/local settings updates from taking effect in the running session. CurDX-Flow may use that to reject mid-execute changes that would disable hooks or reroute the main thread away from `flow-orchestrator`.
+- `TeammateIdle` has less context than `SubagentStop`, so CurDX-Flow should resolve `teammate_name -> agent_type` through `~/.claude/teams/<team-name>/config.json` before enforcing artifact gates for team-mode workers.
 
 ## Subagent Artifact Discipline
 
@@ -52,10 +57,22 @@ Guarded artifact targets:
 | `flow-edge-hunter` | `.flow/specs/<active>/edge-cases.md` |
 | `flow-adversary` | `.flow/specs/<active>/adversarial-review.md` |
 | `flow-ui-researcher` | `.flow/specs/<active>/ui-research.md` |
+| `flow-ux-designer` | `.flow/specs/<active>/ui-sketch/index.html` |
+| `flow-triage-analyst` | `.flow/_epics/<epic-name>/epic.md` |
 | `flow-brownfield-analyst` | `.flow/codebase-index.md` |
 
 `flow-executor` is marker-driven rather than report-driven: it must update task state and end with `TASK_COMPLETE: <task_id>` or `TASK_FAILED: <task_id>`.
 
+## Background Subagent Policy
+
+- Official background subagents keep the main conversation free while the worker runs, but any `AskUserQuestion` call inside that worker auto-denies instead of surfacing an interactive clarification prompt.
+- CurDX-Flow should therefore reserve `background: true` for agents that are:
+  - artifact-producing or evidence-gathering
+  - long-running enough to justify concurrency
+  - not dependent on `AskUserQuestion` for normal operation
+- Do not set `background: true` by default on `flow-executor`, `flow-debugger`, `flow-qa-engineer`, `flow-product-designer`, `flow-security-auditor`, `flow-triage-analyst`, or `flow-ux-designer` without a tighter clarification/permission contract.
+- If those same agent definitions are reused as teammates, `TeammateIdle` quality gates should reuse the same disk-artifact contract as subagent completion whenever the agent is artifact-bearing.
+
 ## Agent Teams Compatibility
 
 - Official `agent-teams` behavior differs from regular subagent invocation in one critical way: when a subagent definition runs as a teammate, its `skills` and `mcpServers` frontmatter fields are not applied.
@@ -69,6 +86,9 @@ Guarded artifact targets:
 - Use forked context and a named agent only when the skill's work benefits from isolation or a specialized role.
 - Avoid preloading broad tool access. Prefer the smallest useful tool set per skill/agent.
 - Do not make bundled skills or agents implicitly depend on runtime-gated tools such as `SendMessage`, `TeamCreate`, `TeamDelete`, or `ToolSearch` unless CurDX-Flow also ships the matching feature-flag/setup contract.
+- Interactive Claude sessions expose the Task tool family (`TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate`) while headless / SDK flows use `TodoWrite`. Any CurDX native task-list sync must therefore be optional UX, not a correctness dependency.
+- Official interactive-mode docs also support `CLAUDE_CODE_TASK_LIST_ID` for sharing a native task list across sessions. CurDX-Flow may use that later as an optimization, but current execution must still recover correctly when the native task list changes or disappears.
+- If CurDX uses task lifecycle hooks, `TaskCreated` should reject orphan CurDX-native tasks that do not map to `tasks.md`, and `TaskCompleted` should reject UI completion that happens before `tasks.md` is updated.
 
 ## Plugin Settings
 
@@ -85,6 +105,7 @@ Guarded artifact targets:
 
 - 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.
+- The monitor must keep working even when Claude's cwd moves below the repo root; `.flow` discovery should be project-root aware rather than cwd-fragile.
 - 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.

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

@@ -2,6 +2,9 @@
 
 set -u
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$SCRIPT_DIR/../../hooks/scripts/common.sh"
+
 interval="${CLAUDE_PLUGIN_OPTION_MONITOR_INTERVAL_SECONDS:-8}"
 case "$interval" in
   ''|*[!0-9]*)
@@ -13,15 +16,15 @@ if [ "$interval" -lt 3 ] 2>/dev/null; then
 fi
 
 build_snapshot() {
-  if [ ! -d ".flow" ]; then
-    return 0
-  fi
+  local flow_root=""
+  flow_root="$(resolve_flow_root 2>/dev/null || true)"
+  [ -n "$flow_root" ] || return 0
 
   local active=""
-  active="$(cat .flow/.active-spec 2>/dev/null || true)"
+  active="$(cat "$flow_root/.flow/.active-spec" 2>/dev/null || true)"
   [ -z "$active" ] && return 0
 
-  local spec_dir=".flow/specs/$active"
+  local spec_dir="$flow_root/.flow/specs/$active"
   [ ! -d "$spec_dir" ] && return 0
 
   local state_file="$spec_dir/.state.json"

package/output-styles/curdx-fast-mode.md

@@ -0,0 +1,42 @@
+---
+name: CurdX Fast Mode
+description: Low-ceremony style for /curdx-flow:fast and small surgical work. Skip preamble, ship the change, validate, stop.
+keep-coding-instructions: true
+---
+
+# CurdX Fast Mode
+
+You are still Claude Code. Keep the default coding workflow, safety rules,
+tool usage behavior, and verification discipline. This style strips ceremony
+for small, well-bounded tasks.
+
+## When this style fits
+
+Use during `/curdx-flow:fast` runs or any task that is obviously small,
+surgical, low-ambiguity, and not worth a full spec workflow.
+
+## Response priorities
+
+1. State the change in one sentence before the first edit.
+2. Make the smallest correct edit — do not refactor surrounding code, do
+   not introduce abstractions, do not "improve" unrelated lines.
+3. Run the smallest verification that proves the change works (one test,
+   one command, one curl). State it explicitly.
+4. End with a one-line status: `Validated` (with evidence), `Unvalidated`
+   (with reason), or `Blocked` (with the blocker).
+5. If you find scope creep — a second bug, a desired refactor, an unclear
+   interface — stop and surface it instead of expanding silently.
+
+## Hard rules
+
+- No spec scaffolding, no phase narration, no "let me think step by step".
+- No defensive validation, no fallback paths, no try/except for impossible
+  cases.
+- No new files unless the change inherently requires one.
+- No follow-on TODOs in the diff. Surface them in the reply, not the code.
+
+## Format
+
+- Plain prose with one diff or one command per paragraph.
+- Bullets only when listing more than two parallel items.
+- No section headers under three lines of content.

package/output-styles/curdx-spec-mode.md

@@ -0,0 +1,46 @@
+---
+name: CurdX Spec Mode
+description: Spec-driven verbose style for multi-phase work. Lead with the active phase, cite artifact paths, and never claim done without an evidence block.
+keep-coding-instructions: true
+---
+
+# CurdX Spec Mode
+
+You are still Claude Code. Keep the default coding workflow, safety rules,
+tool usage behavior, and verification discipline. This style adds spec-driven
+discipline on top of the defaults.
+
+## When this style fits
+
+Use this style during multi-phase CurDX-Flow work — research / requirements /
+design / tasks / execute / verify — when the user wants a clear paper trail
+across phases.
+
+## Response priorities
+
+1. State the active spec and phase explicitly. If no spec is active, say so.
+2. Lead with the artifact you produced or modified, including its full path
+   under `.flow/specs/<active>/`.
+3. Quote the smallest concrete decision that drove the change (one or two
+   lines). Do not repeat the full artifact body.
+4. End every reply with one of: `Validated`, `Unvalidated`, `Blocked`. State
+   what evidence backs the label.
+5. When proposing a next step, name the exact CurDX-Flow surface that should
+   run it (`/curdx-flow:spec --phase=design`, `flow-verifier`, etc.).
+
+## Hard rules
+
+- Never claim a phase is complete without referencing the produced artifact
+  on disk and the gate it passed.
+- Never produce a long architecture essay in chat — that belongs in the
+  spec artifact. The reply should point to the file and call out the
+  decision taken.
+- Never advance phase state from chat narrative. The phase counter in
+  `.state.json` is the source of truth; only the corresponding skill or
+  agent is allowed to advance it.
+
+## Format
+
+- Short headers only when they aid scanning.
+- Bullets for status, prose only for the decision rationale.
+- Match the user's language.

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@curdx/flow",
-  "version": "2.3.10",
+  "version": "3.0.0",
   "description": "Skill-first discipline layer and CLI installer for Claude Code",
   "type": "module",
   "bin": {
     "curdx-flow": "bin/curdx-flow.js"
   },
   "scripts": {
+    "test": "node --test test/*.test.mjs",
     "validate:contracts": "node scripts/validate-plugin-contracts.mjs",
-    "test": "node --test test/*.test.js",
-    "prepublishOnly": "npm run validate:contracts && node --test test/*.test.js && node bin/curdx-flow.js --version"
+    "validate:contracts:strict": "node scripts/validate-plugin-contracts.mjs --strict",
+    "lint": "echo 'lint placeholder; wired in P5'",
+    "prepublishOnly": "npm run validate:contracts && npm test"
   },
   "files": [
     "bin/",

package/schemas/agent-frontmatter.schema.json

@@ -2,7 +2,7 @@
   "$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.",
+  "description": "Supported YAML frontmatter fields for agents/*.md plugin subagent definitions. Tracks the canonical field list documented at https://code.claude.com/docs/en/sub-agents.md#supported-frontmatter-fields. The fields `hooks`, `mcpServers`, and `permissionMode` are canonical for non-plugin agents but are silently ignored when an agent is loaded from a plugin (Claude Code security boundary), so this schema intentionally omits them — `additionalProperties: false` rejects them and surfaces the mistake at validation time instead of at runtime.",
   "type": "object",
   "required": ["name", "description"],
   "additionalProperties": false,
@@ -55,6 +55,9 @@
       "type": "string",
       "enum": ["worktree"]
     },
+    "initialPrompt": {
+      "type": "string"
+    },
     "color": {
       "type": "string",
       "enum": ["red", "blue", "green", "yellow", "purple", "orange", "pink", "cyan"]

package/schemas/spec-state.schema.json

@@ -98,6 +98,24 @@
               "last_error": { "type": "string" }
             }
           }
+        },
+        "native_task_map": {
+          "type": "object",
+          "description": "Best-effort mapping from CurDX task ids (for example 1.2 or 4.VF) to Claude native task ids for interactive task-list sync.",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "native_sync_enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "When false, execution skips Claude native task-list sync and relies only on tasks.md plus state.json."
+        },
+        "native_sync_failure_count": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 0,
+          "description": "Consecutive best-effort native task sync failures during the current execute run."
         }
       }
     },