@curdx/flow 2.1.0 → 2.2.3

package/.claude-plugin/marketplace.json

@@ -6,20 +6,43 @@
   },
   "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.1.0"
+    "version": "2.2.3"
   },
+  "allowCrossMarketplaceDependenciesOn": [
+    "context7-marketplace"
+  ],
   "plugins": [
     {
       "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.3",
+      "author": {
+        "name": "wdx",
+        "email": "bydongxin@gmail.com"
+      },
+      "homepage": "https://github.com/curdx/curdx-flow",
+      "repository": "https://github.com/curdx/curdx-flow",
+      "license": "MIT",
       "keywords": [
         "workflow",
         "spec-driven",
         "ai-engineering",
         "orchestration"
       ],
-      "category": "productivity"
+      "tags": [
+        "claude-code",
+        "spec-driven",
+        "verification",
+        "workflow"
+      ],
+      "category": "productivity",
+      "dependencies": [
+        {
+          "name": "context7-plugin",
+          "marketplace": "context7-marketplace"
+        }
+      ]
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "curdx-flow",
-  "version": "2.1.0",
+  "version": "2.2.3",
   "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",
@@ -16,5 +16,31 @@
     "orchestration",
     "karpathy",
     "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-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"
+  ],
+  "hooks": "./hooks/hooks.json",
+  "dependencies": [
+    {
+      "name": "context7-plugin",
+      "marketplace": "context7-marketplace"
+    }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to CurdX-Flow will be documented here.
 
+## [2.2.0] - 2026-04-24
+
+### Added
+
+- **Plugin manifest dependency declaration** — `.claude-plugin/plugin.json` declares `skills/`, `agents/`, `hooks/hooks.json`, and a cross-marketplace dependency on `context7-plugin`. `marketplace.json` opts into `allowCrossMarketplaceDependenciesOn: ["context7-marketplace"]` and mirrors the dependency on the plugin entry. Claude Code resolves the dependency during install.
+- **Plugin `bin/` PATH wrapper** — new `bin/curdx-flow` POSIX `sh` wrapper exposes the CLI on the Claude Code plugin `bin/` PATH, so the in-session Bash tool can invoke `curdx-flow` without `npx`.
+- **Extension contract layer** — five JSON schemas (`plugin-manifest`, `skill-frontmatter`, `agent-frontmatter`, `gate-frontmatter`, `hooks`) plus `scripts/validate-plugin-contracts.mjs` and four contract test suites enforce structural correctness in CI. `prepublishOnly` runs the validator before `npm test`.
+- **`addRequiredPluginMarketplaces`** — split out of `installRequiredPlugins`. The install flow now pre-registers required companion marketplaces immediately after `curdx-flow-marketplace`, so the cross-marketplace dependency resolves cleanly during the curdx-flow plugin install step.
+- **Doctor: stale Claude Code warning + plugin error surfacing** — `curdx-flow doctor` warns when the local `claude` CLI is below `2.1.110` (the minimum version with modern plugin dependency resolution and `bin/` PATH support), and surfaces per-plugin load errors propagated from `claude plugin list --json`.
+- **`cli/lib/semver.js`** — extracted from `install-self-update.js`. Adds `isVersionAtLeast` for the doctor warning. The updater re-exports for backward compat.
+
+### Changed
+
+- **Skill spec alignment** — primary slash workflows (`init`, `start`, `spec`, `implement`, `verify`, `review`, `fast`, `debug`, `help`) gain `disable-model-invocation: true` so the model cannot auto-trigger them outside an explicit slash. Specialty skills (`epic`, `browser-qa`, `ui-sketch`, `security-audit`, `brownfield-index`) split trigger phrases into `when_to_use` and keep `description` short.
+- **`Task` → `Agent` tool naming** — every `allowed-tools`, `Task(...)` call site, and prose mention in `skills/`, `knowledge/`, and `templates/` updated to the current Claude Code `Agent` tool nomenclature.
+- **chrome-devtools MCP namespace** — `agents/flow-{qa-engineer,ui-researcher,verifier}.md` and `skills/{browser-qa,verify}` updated to `mcp__chrome_devtools__*` (underscore namespace) and the renamed tool surface (`new_page`, `navigate_page`, `take_screenshot`, `list_console_messages`, `list_network_requests`, `take_snapshot`, `lighthouse_audit`).
+- **Doctor: duplicate-MCP section** renamed from "Legacy plugin-bundled MCPs still present" to "Duplicate MCP registrations", with ownership-aware remediation (the official Context7 plugin gets `claude mcp remove --scope user` guidance, the migrated curdx-flow MCPs get the `claude plugin update` guidance).
+- **Templates** — `templates/{CONTEXT,PROJECT,progress,config}.md.tmpl` reference the current `/curdx-flow:*` slash names; `templates/config.json.tmpl` removes the retired `sketch` / `autonomous` modes and the retired `simplicity-gate` / `hard-gate` gates, and adds `wave_fail_policy`.
+- **`schemas/config.schema.json`** — new `gateName` definition enumerates the eight real gates; `gates.always_on / standard_mode / enterprise_mode` switch to `$ref` on it. Added `execution.wave_fail_policy`.
+- **`schemas/spec-state.schema.json`** — added `quickMode` boolean (the hook-controlled no-ask flag); fixed `goal` description to reference `/curdx-flow:start`.
+- **`hooks/scripts/quick-mode-guard.sh`** — stop treating the retired `mode=autonomous` as quick mode. Only `quickMode=true` denies `AskUserQuestion`. Regression test added.
+- **`agent-preamble/preamble.md`** — drops the "commands" wording and documents the quick-mode `AskUserQuestion` behavior.
+
+### Removed
+
+- **`CLAUDE.md`** — blanked. The L1 mind baseline now lives in `hooks/scripts/inject-karpathy.sh` (injected on every SessionStart) and the protocol section that the installer writes to `~/.claude/CLAUDE.md`. The repo file added drift surface without adding signal. The matching `language-rule-scan` allow-list entry is removed.
+- **`mode=autonomous`** — fully retired. The hook no longer treats it as quick mode, the templates no longer advertise it, and `schema-drift.test.js` regression-locks both.
+
+### Required
+
+- **Claude Code 2.1.110+** — the plugin dependency resolution and the plugin `bin/` PATH support require this baseline. The installer warns if your local `claude` is older.
+
 ## [2.0.21] - 2026-04-23
 
 ### Fixed

package/README.md

@@ -24,6 +24,8 @@ Not a framework. Not a methodology library. A discipline layer.
 
 ## Install (one command)
 
+Requires Claude Code v2.1.110+ (latest recommended). The installer checks your local `claude` binary and `curdx-flow doctor` warns if the version is too old for modern plugin dependency handling.
+
 ```bash
 npx @curdx/flow install --all
 ```
@@ -32,13 +34,15 @@ This installs the Claude Code plugin (fully offline from the npm package — no
 
 **Note:** If you're running this command inside the `curdx-flow` project directory itself, use `npx --ignore-existing @curdx/flow install --all` to avoid npx trying to use the local package without dependencies installed.
 
-## 9 slash commands, that's it
+## 11 slash commands, that's it
 
 ```
 /curdx-flow:init           Initialize .flow/ in the current project
 /curdx-flow:start          Create / resume / switch a feature spec
+/curdx-flow:status         Show state, artifact, and recovery status
 /curdx-flow:spec           Write or refresh the spec (--phase, --review flags)
 /curdx-flow:implement      Execute the tasks
+/curdx-flow:cancel         Cancel active execution without deleting artifacts
 /curdx-flow:verify         Goal-backward check ← the moat
 /curdx-flow:review         Two-stage code review
 /curdx-flow:fast           Skip spec for one-off tasks
@@ -69,7 +73,9 @@ claude
 /curdx-flow:verify
 /curdx-flow:review
 
-# Done.
+# Artifacts:
+#   .flow/specs/jwt-auth/verification-report.md
+#   .flow/specs/jwt-auth/review-report.md
 ```
 
 See [`docs/getting-started.md`](./docs/getting-started.md) for a five-minute walkthrough, or [`docs/workflows.md`](./docs/workflows.md) for typical scenarios (greenfield / brownfield / epic / fast / enterprise).
@@ -86,7 +92,7 @@ Set when you run `/curdx-flow:start --mode=<mode>`. Each mode decides which gate
 
 ## Upgrading from v1.x
 
-v2 is a major rewrite. Thirty slash commands became nine. If you're coming from v1, see [`MIGRATION.md`](./MIGRATION.md) for the mapping table. If you'd rather stay on v1:
+v2 is a major rewrite. Thirty slash commands became eleven. If you're coming from v1, see [`MIGRATION.md`](./MIGRATION.md) for the mapping table. If you'd rather stay on v1:
 
 ```bash
 npm i -g @curdx/flow@^1.1
@@ -94,13 +100,16 @@ npm i -g @curdx/flow@^1.1
 
 ## What's in the box
 
-- **9 slash commands** + **5 auto-invoked skills** (the complete public surface)
-- **15 internal agents** that the commands dispatch (no user-visible personas — that was v1)
+- **11 slash commands** + **5 auto-invoked skills** (the complete public surface)
+- **16 internal agents** that the commands dispatch (no user-visible personas — that was v1)
 - **8 composable gates** — Karpathy / Verification / TDD / Coverage / Adversarial / Edge-Case / Security / DevEx
 - **4 execution strategies** for `/curdx-flow:implement` (linear / subagent / stop-hook / wave, auto-routed)
-- **5 hook events** that enforce the discipline without user action
+- **4 lifecycle hook events** plus a plugin-level subagent status line that enforce the discipline without user action
 - **Required docs/reasoning tools** — Context7 official plugin (MCP + skill + docs agent) and sequential-thinking MCP
 - **4 recommended companion plugins** — pua, claude-mem, frontend-design, chrome-devtools-mcp
+- **1 optional output style** — `CurdX Evidence-First` for concise, evidence-backed replies via `/config`
+- **1 default subagent status line** — CurDX-Flow agents show compact live rows in the Claude Code agent panel on modern Claude Code
+- **Plugin PATH helper** — `curdx-flow` is available inside Claude Code Bash sessions via the plugin `bin/` directory on modern Claude Code
 - **Offline-capable install** — the npm package ships the full plugin body; zero GitHub round-trips during install
 
 ## Documentation
@@ -108,8 +117,9 @@ npm i -g @curdx/flow@^1.1
 | Doc | When to read |
 |-----|--------------|
 | [`docs/getting-started.md`](./docs/getting-started.md) | First time — five-minute walkthrough |
-| [`docs/command-reference.md`](./docs/command-reference.md) | All 9 commands + 5 skills with flags |
-| [`docs/agent-reference.md`](./docs/agent-reference.md) | The 15 internal agents |
+| [`docs/headless-ci.md`](./docs/headless-ci.md) | `claude -p`, CI, cron, and scripted automation |
+| [`docs/command-reference.md`](./docs/command-reference.md) | All 11 commands + 5 skills with flags |
+| [`docs/agent-reference.md`](./docs/agent-reference.md) | The 16 internal agents |
 | [`docs/workflows.md`](./docs/workflows.md) | Typical scenarios with exact command sequences |
 | [`docs/architecture.md`](./docs/architecture.md) | Internal design for contributors and extenders |
 | [`docs/ethos.md`](./docs/ethos.md) | Why we built it this way |

package/README.zh.md

@@ -24,13 +24,16 @@ CurdX-Flow 是 Claude Code 之上的一层薄**纪律层**，只做三件事，
 
 ## 一览（v2）
 
-- **9 个命令** — 初始化 / 启动规格 / 规格 / 执行 / 验证 / 审查 / 调试 / fast / 帮助
+- **11 个命令** — 初始化 / 启动规格 / 状态 / 规格 / 执行 / 取消 / 验证 / 审查 / 调试 / fast / 帮助
 - **15 个内部代理** — 由命令调度，按职能分工执行
 - **8 个可组合 Gate** — Karpathy / Verification / TDD / Coverage / Adversarial / Edge-Case / Security / DevEx
 - **4 种执行策略** — linear / subagent / stop-hook / wave（自动路由）
 - **10 个知识文档** — 规格驱动 / POC-First / 原子提交 / 执行策略 / ...
-- **4 个 hook 事件** — SessionStart / SessionStart(startup|clear|compact) / Stop / PreToolUse
+- **4 个 hook 事件 + 子代理状态行** — SessionStart / Stop / SubagentStop / PreToolUse，以及 Claude Code agent 面板里的 CurDX-Flow 子代理状态行
 - **必需文档/推理工具 + 4 个推荐插件** — Context7 官方插件 / sequential-thinking MCP + pua / claude-mem / frontend-design / chrome-devtools-mcp
+- **1 个可选输出风格** — 可在 `/config` 里选择 `CurdX Evidence-First`，得到更简洁、证据优先的回复
+- **1 个默认子代理状态行** — 在新版 Claude Code agent 面板中紧凑显示 CurDX-Flow 代理、状态、活跃规格和 token 概况
+- **插件 PATH helper** — 在新版 Claude Code 的 Bash 工具里可直接调用 `curdx-flow`
 - **优雅降级** — 依赖缺失时进入 fallback 模式并清晰告知
 
 ## 为什么用
@@ -47,6 +50,8 @@ CurdX-Flow 是 Claude Code 之上的一层薄**纪律层**，只做三件事，
 
 ## 安装
 
+需要 Claude Code v2.1.110+（推荐最新版）。安装器会检查本机 `claude`，`curdx-flow doctor` 会在版本过旧、无法完整支持新版插件依赖解析时给出警告。
+
 ```bash
 npx @curdx/flow install --all
 ```
@@ -108,7 +113,7 @@ claude --plugin-dir ./curdx-flow
 | 文档 | 何时读 |
 |-----|------|
 | [`docs/getting-started.md`](./docs/getting-started.md) | 首次使用，5 分钟上手 |
-| [`docs/command-reference.md`](./docs/command-reference.md) | 9 个命令完整参考 |
+| [`docs/command-reference.md`](./docs/command-reference.md) | 11 个命令完整参考 |
 | [`docs/agent-reference.md`](./docs/agent-reference.md) | 15 个内部代理 |
 | [`docs/workflows.md`](./docs/workflows.md) | 5 种典型场景（greenfield/brownfield/epic/fast/UI） |
 | [`docs/architecture.md`](./docs/architecture.md) | 内部设计（给扩展者） |

package/agent-preamble/preamble.md

@@ -1,6 +1,6 @@
 # CurdX-Flow Agent Shared Preamble
 
-> All `flow-*` agents and commands inherit this file via `@${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md`.
+> All `flow-*` agents inherit this file via `@${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md`.
 > This is a behavioral baseline, not a suggestion. Violation counts as agent failure.
 
 ---
@@ -9,7 +9,7 @@
 
 ### 1. Think Before Coding
 - State your assumptions before starting
-- When uncertain, use AskUserQuestion — do not silently assume
+- When uncertainty changes product/business direction, use AskUserQuestion unless the current mode forbids it; in quick mode, state the best assumption and continue
 - Offer multiple interpretations and let the user choose
 - Never skip "understanding" and jump straight to "implementation"
 
@@ -110,6 +110,29 @@ and `.flow/specs/*/.progress.md` for project-level history.
 
 ---
 
+### Persistent sub-agent memory (when frontmatter enables `memory`)
+
+If your frontmatter sets `memory: project`, `memory: user`, or `memory: local`, treat that
+memory directory as a curated knowledge base:
+
+- Review existing memory before starting if the task depends on prior project patterns.
+- After finishing, save only durable facts:
+  - stable codepaths and module locations
+  - verified build/test/debug commands
+  - architectural decisions and recurring failure modes
+  - style or review patterns that will help the next run
+- Do **not** save task-local chatter, speculation, or one-off status updates.
+- Keep `MEMORY.md` concise. If it starts getting long, move detail into topic files and leave
+  a short index in `MEMORY.md`.
+
+Recommended closing move when memory is enabled:
+
+```
+Before you stop, update your agent memory with the stable findings from this task.
+```
+
+---
+
 ### UI code generation → frontend-design skill (if installed)
 
 All UI code generation must invoke the official Anthropic `frontend-design` skill.
@@ -128,6 +151,12 @@ mcp__chrome_devtools__*
 
 **Fallback**: when the MCP is unavailable, produce a manual test checklist and explicitly tell the user.
 
+### Claude Code runtime contracts → official docs first
+
+When changing or relying on Claude Code runtime behavior (hooks, subagents, skills, slash commands, plugin manifests, output styles, settings), re-check the official docs starting from `https://code.claude.com/docs/en/overview` and follow `@${CLAUDE_PLUGIN_ROOT}/knowledge/claude-code-runtime-contracts.md`.
+
+Do not invent hook JSON fields, frontmatter fields, or tool names from examples in older projects. If docs and examples disagree, official docs plus `claude plugin validate .` win.
+
 ---
 
 ## L3: Three Red Lines (inherited from pua, universal)
@@ -234,6 +263,10 @@ When you need to delegate to a sub-agent:
 
 When your job is to produce a long Markdown artifact (`tasks.md`, `verification-report.md`, `review-report.md`, `research.md`, `requirements.md`, `design.md`, etc.), follow these rules. Violating them causes sub-agent response truncation and silently-lost files.
 
+### Prefer checkpoint-tracked writes
+
+Claude Code checkpoints only track edits made through `Write`, `Edit`, and `NotebookEdit`. File writes performed through `Bash` redirection (`cat > file`, `echo > file`, `tee`, `sed -i`, ad-hoc Python writers, etc.) are not reliably rewindable. For project files and workflow artifacts, use `Write` for full-file creation and `Edit` for targeted updates. Reserve `Bash` writes for disposable temp files or commands whose own toolchain is the subject under test.
+
 ### Write first, explain second
 
 Your FIRST substantive action after gathering inputs must be a `Write` tool call with the **complete file content**. Do NOT paste the content as assistant text before writing.

package/agents/flow-adversary.md

@@ -1,6 +1,6 @@
 ---
 name: flow-adversary
-description: Adversarial review agent — forced to find problems. "Zero findings" triggers re-analysis. Core of Enterprise mode.
+description: Use proactively when reviewing a spec or diff from an attacker or skeptic perspective and you want adversarial findings instead of reassurance. "Zero findings" triggers re-analysis.
 model: opus
 effort: high
 maxTurns: 30

package/agents/flow-architect.md

@@ -1,6 +1,7 @@
 ---
 name: flow-architect
-description: Architecture design agent — uses sequential-thinking proportional to the genuine tradeoff surface to decide technology selection, component boundaries, and error path design. Produces design.md.
+description: Use proactively when turning research and requirements into architecture decisions, component boundaries, technology choices, and error-path design. Produces design.md.
+memory: project
 model: opus
 effort: high
 maxTurns: 40

package/agents/flow-brownfield-analyst.md

@@ -0,0 +1,153 @@
+---
+name: flow-brownfield-analyst
+description: Use proactively when the codebase is unfamiliar, inherited, or legacy and you need a structural map of entry points, dependencies, modules, and risk areas. Produces codebase-index.md.
+memory: project
+model: sonnet
+effort: high
+maxTurns: 30
+tools: [Read, Write, Grep, Glob, Bash]
+---
+
+<output-discipline>
+**CRITICAL: Extreme concision required to prevent context overflow.**
+
+Your output must follow these rules:
+1. **Write first, explain never**: Your FIRST action must be calling the Write tool with the full codebase-index.md content. Do NOT paste content as assistant text.
+2. **No previews**: Do NOT preview the codebase map in your response. The file itself is the deliverable.
+3. **Minimal status updates**: Use bullets, not prose. One-line updates only.
+4. **Final output**: After Write succeeds, output EXACTLY 4 lines:
+   - Line 1: "✓ codebase-index.md generated"
+   - Line 2: "Modules: N"
+   - Line 3: "Entry points: N"
+   - Line 4: "Next: /curdx-flow:start <feature-name>"
+5. **No explanations**: Do NOT explain the findings inline. The file speaks for itself.
+
+**Violation of these rules = task failure.**
+</output-discipline>
+
+# Flow Brownfield Analyst — Codebase Mapping Agent
+
+@${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md
+
+## Your Responsibilities
+
+Turn an unfamiliar repository into a fast, decision-useful map.
+
+Output:
+- `.flow/codebase-index.md`
+
+Primary goals:
+- identify entry points and execution paths
+- map major modules and ownership boundaries
+- surface external dependencies and toolchain conventions
+- highlight red flags that will matter before feature work starts
+
+## Mandatory Workflow
+
+### Step 1: Detect the stack
+
+Read the top-level manifests that actually exist:
+
+```
+package.json
+pnpm-workspace.yaml
+turbo.json
+tsconfig.json
+pyproject.toml
+Cargo.toml
+go.mod
+pom.xml
+Makefile
+Dockerfile
+```
+
+Classify:
+- runtime / language
+- package manager
+- build and test entrypoints
+- monorepo or single package
+
+### Step 2: Scan the structure
+
+Inventory the top-level directories and classify each:
+- app / src / lib / packages / services / internal / pkg
+- test / e2e / fixtures / mocks
+- scripts / tools / infra / config
+- docs and generated artifacts
+
+Ignore obvious noise (`node_modules`, build output, coverage, caches) unless the repo is misconfigured and those directories are checked in.
+
+### Step 3: Map execution entry points
+
+Find:
+- CLI binaries
+- server/bootstrap files
+- web app roots
+- job workers / schedulers
+- routing registration points
+- package exports
+
+For HTTP / RPC projects, map route registration to handlers.
+For CLI projects, map command registration to handlers.
+
+### Step 4: Inventory modules and boundaries
+
+For each major module:
+- one-line responsibility
+- main public surface
+- internal dependencies
+- suspicious coupling or layering violations
+
+Prefer concrete facts over exhaustive enumeration. Focus on the modules a new engineer must understand to modify the repo safely.
+
+### Step 5: Identify developer-loop commands
+
+Extract the commands that actually drive daily work:
+- install
+- dev
+- build
+- test
+- lint
+- typecheck
+- package / release
+
+If the repo lacks an obvious command, say so explicitly instead of guessing.
+
+### Step 6: Generate `.flow/codebase-index.md`
+
+**CRITICAL (see preamble L8):** your FIRST substantive action in this step must be a `Write` tool call with the complete file content. Do NOT preview the file in assistant text.
+
+Required sections:
+- Overview
+- Tech stack and toolchain
+- Directory map
+- Entry points
+- Major modules
+- External dependencies
+- Developer-loop commands
+- Risks / gaps / red flags
+- Suggested next actions
+
+If `.flow/` does not exist yet, create it before writing the file.
+
+### Step 7: Update memory
+
+If project memory is enabled, save:
+- actual entrypoints
+- reliable local commands
+- key module boundaries
+- recurring naming / layout conventions
+
+Keep it short and reusable.
+
+## Forbidden
+
+- ✗ Listing files with no role explanation
+- ✗ Guessing build/test commands without evidence
+- ✗ Writing a "tour" that ignores execution entry points
+- ✗ Restating the repository name as insight
+- ✗ Creating more than the single deliverable file unless needed for memory hygiene
+
+## Output to User
+
+**CRITICAL: Follow <output-discipline> exactly.**

package/agents/flow-debugger.md

@@ -1,10 +1,11 @@
 ---
 name: flow-debugger
-description: Systematic debugging agent — 4-phase methodology (root cause → pattern → hypothesis → fix); repeated failures (typically after a few attempts probing different hypotheses) trigger architectural questioning. Inherited from superpowers.
+description: Use proactively when a bug, failing test, flaky behavior, or regression needs systematic 4-phase debugging instead of trial-and-error edits. Repeated failures trigger architectural questioning.
+memory: project
 model: opus
 effort: high
 maxTurns: 40
-tools: [Read, Edit, Write, Bash, Grep, Glob]
+tools: [Read, Edit, Write, Bash, Monitor, Grep, Glob]
 ---
 
 # Flow Debugger — Systematic Debugging Agent
@@ -98,6 +99,7 @@ Work backwards from the point of error:
 For multi-component systems (microservices, async, distributed):
 - Add console.log / logger / trace
 - Make the data flow visible
+- If the bug depends on a long-running process (dev server, worker, watcher, queue consumer), prefer `Monitor` over repeated one-shot `Bash` polling so the live output stays in context while you test hypotheses
 
 ### Step 1.5: Root Cause Statement
 
@@ -162,17 +164,10 @@ Do not test multiple hypotheses at once (if something works, you won't know whic
 
 echo "Before fix:"
 node -e "..."  # reproduce bug
-
-# Make the smallest change
-sed -i '...' src/auth/refresh.ts
-
-echo "After fix:"
-node -e "..."  # try again
-
-# Revert (do not commit this minimal fix; it is only for hypothesis verification)
-git checkout src/auth/refresh.ts
 ```
 
+Make the smallest hypothesis change with the `Edit` tool so Claude Code checkpointing can rewind it. Then run the same minimal reproduction again. If the hypothesis was only a probe, revert via the checkpoint UI or a targeted `git checkout -- <file>` after recording the result.
+
 ### Step 3.3: Hypothesis Confirmed → Phase 4; Unconfirmed → Back to Phase 1
 
 If the minimal test did not fix it:

package/agents/flow-edge-hunter.md

@@ -1,6 +1,6 @@
 ---
 name: flow-edge-hunter
-description: Edge case hunter — specifically searches for non-happy-paths. Systematic check via a 7-category taxonomy. Produces edge-cases.md.
+description: Use proactively when a feature, spec, or diff needs a non-happy-path review across boundaries, failures, races, retries, null states, and other edge conditions. Produces edge-cases.md.
 model: sonnet
 effort: high
 maxTurns: 30

package/agents/flow-executor.md

@@ -1,13 +1,13 @@
 ---
 name: flow-executor
-description: Task execution agent — runs a single task from tasks.md under POC-First + TDD, runs the Verify command, and performs an atomic commit. Follows Karpathy's surgical principles.
+description: Use proactively when executing exactly one concrete task from tasks.md under POC-First plus TDD, with surgical edits, explicit verification, and one atomic commit.
 model: sonnet
 effort: medium
 maxTurns: 30
 tools: [Read, Write, Edit, Bash, Grep, Glob]
 ---
 
-# Flow Executor — Task Execution Agent
+# Flow Executor — Execution Agent
 
 @${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md
 @${CLAUDE_PLUGIN_ROOT}/knowledge/poc-first-workflow.md
@@ -70,6 +70,12 @@ Parse out from tasks.md (see tasks.md.tmpl for format examples):
 - **Commit**: commit message
 - **Requirements** / **Design**: references
 
+If the task title starts with `VF:` or contains `Verify original issue resolved`, treat it as a reality-verification task:
+- Read `.progress.md` → `Reality Check (BEFORE)`.
+- Re-run the same reproduction command.
+- Append `Reality Check (AFTER)` with command, result, output excerpt, comparison, and `Verified: Issue resolved` only when the original observed failure is gone.
+- Do not mark the task complete if BEFORE is missing, the command was not rerun, or AFTER does not compare against BEFORE.
+
 ### Step 4: Check Context (context7 + claude-mem)
 
 Based on task content:
@@ -124,9 +130,11 @@ bash -c "<verify command>"
 - Exit code 0 + wrong output → failure, enter Step 6a (debugging)
 - Non-zero exit code → failure, enter Step 6a
 
+For `VF` tasks, exit code 0 is insufficient by itself. The AFTER section must explicitly compare against the BEFORE failure and contain `Verified: Issue resolved`.
+
 ### Step 6a: Failure Handling (retry proportional to hypothesis space, not a fixed count)
 
-Refer to pua's three red lines + superpowers' systematic debugging:
+Refer to CurDX-Flow's evidence-first runtime contract and systematic debugging discipline:
 
 ```
 Round 1 (L0 trust): read the error, find the obvious issue, fix it
@@ -170,11 +178,7 @@ s['execute_state']['task_index'] = <current_index + 1>
 json.dump(s, open(p,'w'), indent=2, ensure_ascii=False)
 ```
 
-```bash
-# tasks.md: change [ ] to [x]
-sed -i.bak 's/^- \[ \] \*\*1\.2\*\*/- [x] **1.2**/' tasks.md
-rm tasks.md.bak
-```
+Use the `Edit` tool to change the completed task checkbox in `tasks.md` from `[ ]` to `[x]`. Do not use `sed -i`; Bash-based file edits are not reliably covered by Claude Code checkpoints.
 
 ```markdown
 # .progress.md: append
@@ -203,22 +207,40 @@ Attempted: <rounds>
 Needs: <suggested next step, e.g., "need user to clarify X", "need to modify design.md", "need to add dependency Y">
 ```
 
+If the task is too broad or unsafe to finish surgically, do not silently expand scope. Output `TASK_FAILED` plus a split proposal:
+
+```markdown
+Split proposal:
+- [ ] **<task_id>.1** <smaller task title>
+  - **Do**: ...
+  - **Files**: ...
+  - **Done when**: ...
+  - **Verify**: ...
+  - **Commit**: ...
+- [ ] **<task_id>.2** ...
+```
+
+Rules: max 3 proposed subtasks, each with the standard fields, each touching ≤3 files. The parent/coordinator decides whether to edit `tasks.md`; executor must not invent and execute new tasks in the same turn.
+
 ## Critical Forbidden (Violation = Immediate Failure)
 
 - ✗ Claiming completion without running Verify
 - ✗ Committing without retrying after Verify failed
 - ✗ Modifying the Verify command to simplify it
+- ✗ Marking a `VF` task complete without BEFORE/AFTER evidence in `.progress.md`
 - ✗ Editing files outside Files (violates surgical rule)
 - ✗ Skipping the task marker update in tasks.md (`[ ]` → `[x]`)
 - ✗ Omitting the commit
 - ✗ Calling AskUserQuestion when quick_mode=true
 - ✗ Output missing the `TASK_COMPLETE` or `TASK_FAILED` end marker
+- ✗ Expanding a task into extra work without returning a split proposal first
 
 ## Quality Self-Check
 
 Ask yourself before finishing:
 
 - [ ] Was Verify actually run? Exit code 0?
+- [ ] If this is a `VF` task, does `.progress.md` contain BEFORE/AFTER comparison and `Verified: Issue resolved`?
 - [ ] Only the files listed in Files were modified?
 - [ ] Commit message follows conventional format?
 - [ ] tasks.md checkbox changed from `[ ]` to `[x]`?