@curdx/flow 2.2.4 → 2.3.0

package/skills/ui-sketch/references/variant-contract.md

@@ -0,0 +1,15 @@
+# UI Sketch Variant Contract — What Must Be Produced
+
+`flow-ux-designer` should:
+
+1. invoke the frontend-design workflow
+2. generate distinct variants
+3. write rationale for each variant
+4. optionally use `flow-ui-researcher` for precedent gathering
+
+## Required Artifacts
+
+- `.flow/specs/<active>/ui-sketch/`
+- `.flow/specs/<active>/ui-sketch/index.html`
+
+Each variant should include rationale and accessibility notes.

package/skills/verify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: verify
-description: Prove the active spec is truly implemented by tracing every FR, AC, and AD to code and tests. Optional --strict adds multi-source coverage audit.
+description: Verify the active spec against code, tests, and browser evidence.
 when_to_use: Use when implementation is done and the user wants proof that FRs, ACs, and ADs are actually satisfied rather than merely claimed complete.
 argument-hint: "[--strict]"
 disable-model-invocation: true
@@ -10,102 +10,47 @@ agent: flow-verifier
 
 # Goal-Backward Verification
 
-Verify the active `.flow/` spec using goal-backward analysis. This is the
-differentiator step — catches Claude's most common failure: claiming "done"
-while the code is a stub, a fake completion, or an untested AC.
+Verify the active `.flow/` spec using goal-backward analysis. Keep this
+entrypoint focused on preflight, evidence scope, strict-mode expansion, and the
+final handoff. Detailed evidence rules live in:
 
-**Arguments**: `$ARGUMENTS` (optionally `--strict` for multi-source coverage audit).
+- `references/preflight.md`
+- `references/evidence-workflow.md`
+- `references/strict-mode.md`
+- `references/output-contract.md`
+- `references/report-handoff.md`
 
-## Preflight
-
-- `.flow/` must exist and `.flow/.active-spec` must be non-empty.
-- `.flow/specs/<active>/requirements.md`, `design.md`, `tasks.md` must all exist.
-
-If any precondition fails, emit a clear error and stop.
-
-## What to verify
-
-Read the active spec's `requirements.md` (for FR-NN and AC-N.N),
-`design.md` (for AD-NN), `tasks.md` (for T-N.M with per-task Verify
-commands), and `.flow/STATE.md` (for D-NN decisions).
-
-For EACH assertion in the spec, walk goal-backward:
-
-1. Classify the assertion as **UI-facing** (uses words like "user sees",
-   "click", "render", or names a UI element) vs. **code-only** (schema,
-   API response, performance, error envelope, etc.).
-2. For **code-only**: grep the codebase for matching symbols, find the
-   implementing file + line, find a test that exercises it, run the test
-   (`npm test` or the declared `Verify` command), capture pass/fail.
-3. For **UI-facing**: browser verification via `mcp__chrome_devtools__*`
-   is required. `jsdom` / `happy-dom` unit tests are insufficient. If the
-   browser MCP isn't available, mark the AC **unverified — browser MCP
-   missing** and include a CRITICAL section in the report; do NOT
-   silently pass based on code reading alone.
-
-Also scan for **stub / fake-completion** patterns on FR-covered paths:
+## Arguments
 
-- `throw new Error("not implemented")`, `// TODO:` on critical paths
-- `return null` / `return {}` where real output is expected
-- tests with only `it.skip(...)` or no assertions
-- code returning mocked fixtures instead of calling real collaborators
+`$ARGUMENTS` optionally includes `--strict`.
 
-Apply `@${CLAUDE_PLUGIN_ROOT}/gates/test-quality-gate.md` to every test used as evidence. Mock-heavy tests are acceptable only when they mock boundaries while asserting real behavior, or when separate integration/e2e coverage exists. Mock-only tests, skipped tests, assertion-free tests, and tests without cleanup for stateful mocks cannot be the sole evidence for an FR/AC.
-
-Run the per-task `Verify` commands from `tasks.md` and record pass/fail.
-
-For fix/debug specs, also verify reality evidence:
-
-- `.progress.md` must contain `Reality Check (BEFORE)` with a reproduction command and observed failure.
-- `.progress.md` must contain `Reality Check (AFTER)` with the same command rerun and an explicit comparison.
-- `Verified: Issue resolved` is valid only if AFTER proves the original observed failure disappeared.
-- If the spec has fix/debug language but no `VF` task or BEFORE/AFTER evidence, mark the verdict `PARTIAL` even if all tests pass.
-
-## --strict mode
-
-When `$ARGUMENTS` contains `--strict`, also apply the multi-source coverage
-audit at `@${CLAUDE_PLUGIN_ROOT}/gates/coverage-audit-gate.md`. Cross-check:
-
-- Every FR ↔ AC ↔ AD ↔ task ↔ test ↔ commit must reference each other.
-- Research conclusions: was the recommended library / approach actually used?
-- Every D-NN in `.flow/STATE.md` that references this spec is honored.
-
-## Deliverables
+## Preflight
 
-Write `.flow/specs/<name>/verification-report.md` with:
+Use `references/preflight.md` for the project-level guard.
 
-- Summary counts (FR / AC / AD coverage, stub count, failing Verify count)
-- Detailed Checklist (one section per FR / AC / AD with Evidence + Verdict)
-- Stub / fake findings with file paths
-- Verdict: `PASS` / `PARTIAL` / `MISSING`
+## Evidence Scope
 
-Exact format schema is in `agents/flow-verifier.md` Step 6 (loaded via the
-`agent: flow-verifier` frontmatter field — its system prompt governs).
+Use `references/evidence-workflow.md` for the full evidence contract.
+UI-facing checks still rely on `mcp__chrome_devtools__*` when browser evidence
+is required.
 
-**Landing check**: your FIRST substantive action after gathering findings
-must be the `Write` tool call with the complete report. Do NOT preview the
-report as assistant text first; that doubles output tokens and risks
-truncating inside the Write call. After Write succeeds, respond with a
-≤ 5-line summary only.
+## Strict Mode
 
-## Apply the gate
+If `$ARGUMENTS` contains `--strict`, also apply the multi-source audit from
+`references/strict-mode.md`.
 
-Per `@${CLAUDE_PLUGIN_ROOT}/gates/verification-gate.md`:
+## Deliverables and Gate
 
-- Any `STUB` or `MISSING` finding on a non-deferred FR blocks completion.
-- Any failing Verify command blocks completion.
-- Missing fix/debug BEFORE/AFTER reality verification blocks a full PASS.
-- Any FR/AC supported only by mock-only/skipped/assertion-free tests blocks a full PASS.
-- Waive only with an explicit D-NN decision logged in `.flow/STATE.md`.
+Use `references/output-contract.md` for the required artifact and compact
+summary. The exact report structure, landing order, and post-write routing are
+governed by `references/report-handoff.md` plus the `flow-verifier` agent
+contract.
+Primary artifact: `.flow/specs/<name>/verification-report.md`.
 
-## Output to user (≤ 5 lines after Write succeeds)
+Apply `@${CLAUDE_PLUGIN_ROOT}/gates/verification-gate.md` before returning a
+PASS verdict.
 
-```
-✓ Verification complete: <spec-name>
-  FR coverage: N/M implemented (S stub, K missing)
-  AC coverage: N/M tested
-  Verdict: PASS | PARTIAL | MISSING
-  Report: .flow/specs/<name>/verification-report.md
-```
+## Output to User
 
-Next: address findings, then re-run `/curdx-flow:verify`, or run `/curdx-flow:review`.
+Use `references/output-contract.md` for the final compact response. Next-step
+routing is defined in `references/report-handoff.md`.

package/skills/verify/references/evidence-workflow.md

@@ -0,0 +1,39 @@
+# Evidence Workflow — Verification Rules
+
+## Read Set
+
+Load:
+
+- `.flow/specs/<name>/requirements.md`
+- `.flow/specs/<name>/design.md`
+- `.flow/specs/<name>/tasks.md`
+- `.flow/specs/<name>/.progress.md`
+- `.flow/specs/<name>/.state.json`
+- `.flow/STATE.md`
+
+## Assertion Model
+
+Verify every relevant:
+
+- `FR`
+- `AC`
+- `AD`
+- implementation-relevant component existence
+
+For fix/debug specs, also verify `VF-original-issue`.
+
+## UI vs Code-Only
+
+- UI-facing ACs require browser verification through `mcp__chrome_devtools__*`
+- Code inspection plus `jsdom` / `happy-dom` tests are insufficient for
+  UI-facing ACs
+- If browser MCP is unavailable, mark UI-facing ACs as
+  `unverified — browser MCP missing`
+
+## Required Checks
+
+- run real tests or verify commands, never hypothetical ones
+- scan for stub and fake-completion patterns on FR-covered paths
+- apply `test-quality-gate` to every evidentiary test
+- downgrade assertions backed only by weak tests
+- require `.progress.md` BEFORE/AFTER reality checks for fix/debug work

package/skills/verify/references/output-contract.md

@@ -0,0 +1,23 @@
+# Verify Output Contract — Artifact and Summary
+
+## Artifact
+
+Write:
+
+```text
+.flow/specs/<name>/verification-report.md
+```
+
+## Summary
+
+After the report lands, respond with:
+
+```text
+✓ Verification complete: <spec-name>
+  FR coverage: N/M implemented (S stub, K missing)
+  AC coverage: N/M tested
+  Verdict: PASS | PARTIAL | MISSING
+  Report: .flow/specs/<name>/verification-report.md
+```
+
+Keep the response compact. The report file holds the detail.

package/skills/verify/references/preflight.md

@@ -0,0 +1,11 @@
+# Verify Preflight — Active Spec and Artifact Guard
+
+Before verifying:
+
+- `.flow/` must exist
+- `.flow/.active-spec` must be non-empty
+- `.flow/specs/<active>/requirements.md` must exist
+- `.flow/specs/<active>/design.md` must exist
+- `.flow/specs/<active>/tasks.md` must exist
+
+If any precondition fails, emit a clear error and stop immediately.

package/skills/verify/references/report-handoff.md

@@ -0,0 +1,35 @@
+# Report Handoff — Deliverable and Next Step
+
+## Deliverable
+
+Write:
+
+```text
+.flow/specs/<name>/verification-report.md
+```
+
+The first substantive action after gathering findings must be the `Write` call
+for the complete report. Do not preview the report first.
+
+## Gate Outcome
+
+- `PASS` -> verification evidence is complete; next logical step is
+  `/curdx-flow:review`
+- `PARTIAL` or `MISSING` -> address findings, then rerun `/curdx-flow:verify`
+
+## Output Summary
+
+After `Write` succeeds, respond with no more than 5 lines:
+
+```text
+✓ Verification complete: <spec-name>
+  FR coverage: N/M implemented (S stub, K missing)
+  AC coverage: N/M tested
+  Verdict: PASS | PARTIAL | MISSING
+  Report: .flow/specs/<name>/verification-report.md
+```
+
+Next:
+
+- `/curdx-flow:review` after a clean verification pass
+- `/curdx-flow:verify` again after fixes

package/skills/verify/references/strict-mode.md

@@ -0,0 +1,12 @@
+# Strict Mode — Multi-Source Audit
+
+When `--strict` is present, also apply
+`@${CLAUDE_PLUGIN_ROOT}/gates/coverage-audit-gate.md`.
+
+Cross-check:
+
+- every `FR` <-> `AC` <-> `AD` <-> task <-> test <-> commit chain
+- research recommendations versus the actual implementation
+- every relevant `D-NN` in `.flow/STATE.md`
+
+`--strict` expands evidence requirements; it does not relax any baseline gate.

package/README.zh.md

@@ -1,160 +0,0 @@
-# CurdX-Flow
-
-> **让 Claude Code 不再假装"完成"。**
-> 规格驱动工作流 + 目标反向验证 + Karpathy 4 原则。
-
-[![Version](https://img.shields.io/npm/v/@curdx/flow.svg)](https://www.npmjs.com/package/@curdx/flow)
-[![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
-[![Plugin](https://img.shields.io/badge/claude--code-plugin-purple)](https://code.claude.com)
-[![English](https://img.shields.io/badge/doc-English-red)](./README.md)
-
----
-
-## 为什么存在
-
-Claude Code 会漂——声称功能跑通但从未跑过测试、用训练数据里陈旧的库 API、把三个问题的代码量塞进六问。
-
-CurdX-Flow 是 Claude Code 之上的一层薄**纪律层**，只做三件事，拒绝做更多：
-
-1. **一套规格工作流**（研究 → 需求 → 设计 → 任务），用于超出一次性 vibe-code 尺度的特性。
-2. **目标反向验证**——扫描实现是否对齐每一条 FR / AC / AD，揪出桩代码、假完成、未被测试覆盖的验收标准。
-3. **Karpathy 4 原则**（先思考再编码 / 简单优先 / 外科式修改 / 目标驱动）通过常开 hook 和 gate 强制执行。
-
-不是框架。不是方法论库。就是一层纪律。
-
-## 一览（v2）
-
-- **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 / 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 模式并清晰告知
-
-## 为什么用
-
-现有 AI 编程工作流常见问题：
-
-| 问题 | CurdX-Flow 的答案 |
-|-----|-----------------|
-| 上下文腐烂（长会话质量下降） | Subagent 隔离 + stop-hook 循环 + claude-mem |
-| 无工程纪律（AI 跳步、幻觉） | Karpathy L1 + verification-gate + TDD-gate |
-| 最佳实践分散 | 6 个工作流蒸馏到一个元框架 |
-| 验证薄弱（无证据声称"完成"） | 目标反向验证 + 禁用词检测 |
-| 单视角决策 | 多代理协作 + 对抗审查 |
-
-## 安装
-
-需要 Claude Code v2.1.110+（推荐最新版）。安装器会检查本机 `claude`，`curdx-flow doctor` 会在版本过旧、无法完整支持新版插件依赖解析时给出警告。
-
-```bash
-npx @curdx/flow install --all
-```
-
-这会用 `claude plugin ...` 非交互 CLI 安装 CurdX-Flow 插件、Context7 官方插件、必需 MCP，并安装推荐插件。
-
-**注意：** 如果你在 `curdx-flow` 项目目录内运行此命令，请使用 `npx --ignore-existing @curdx/flow install --all` 避免 npx 尝试使用本地未安装依赖的包。
-
-### 本地 dev
-```bash
-git clone https://github.com/curdx/curdx-flow
-claude --plugin-dir ./curdx-flow
-```
-
-安装后在 Claude Code 内运行：
-
-```
-/curdx-flow:init            # 初始化你的项目
-```
-
-详细教程见 [`docs/getting-started.md`](./docs/getting-started.md)（5 分钟上手）。
-
-## 快速开始
-
-```bash
-# 1. 在你的项目
-/curdx-flow:init
-
-# 2. 启动一个功能
-/curdx-flow:start jwt-auth "给 REST API 加 JWT 认证"
-
-# 3. 生成完整规格（研究 → 需求 → 设计 → 任务）
-/curdx-flow:spec
-
-# 4. 执行（自动选最佳策略）
-/curdx-flow:implement
-
-# 5. 验证 + 审查
-/curdx-flow:verify
-/curdx-flow:review
-
-# 完成。git push.
-```
-
-更多场景（棕地 / Epic / Fast / UI 重）见 [`docs/workflows.md`](./docs/workflows.md)。
-
-## 五根支柱
-
-1. **Mind（L1 基线）** — Karpathy 4 原则 + 必用工具规则 + 三条红线
-2. **Spec（规格）** — 研究 → 需求 → 设计 → 任务（可伸缩，4 文件 lite 到 12 文件 enterprise）
-3. **Agents（代理）** — 15 个内部代理，按命令和流程调度
-4. **Flow（流程）** — 4 种执行策略，自动路由
-5. **Memory（记忆）** — claude-mem（隐式）+ `.flow/STATE.md`（显式决策 D-NN）
-
-设计哲学详见 [`docs/ethos.md`](./docs/ethos.md)。
-
-## 文档
-
-| 文档 | 何时读 |
-|-----|------|
-| [`docs/getting-started.md`](./docs/getting-started.md) | 首次使用，5 分钟上手 |
-| [`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) | 内部设计（给扩展者） |
-| [`docs/ethos.md`](./docs/ethos.md) | 设计决策的理由 |
-| [`docs/troubleshoot.md`](./docs/troubleshoot.md) | 故障排查 |
-
-## 当前不做的（故意）
-
-**v1.0 故意跳过**：
-- **Phase 6**（ship / land / canary / retro） — 私有仓库场景 ROI 低。未来社区反馈需要再补。
-- **集成检查代理** — Epic 跨子规格验证。暂时手动。
-- **Checkpoint save/restore** — 当前 `.flow/STATE.md` 覆盖多数需求。
-- **多运行时支持** — 仅 Claude Code。其他工具的插件 API 成熟后再考虑。
-
-完整版本历史见 [`CHANGELOG.md`](./CHANGELOG.md)。
-
-## 致谢
-
-CurdX-Flow 是蒸馏，不是原创。深深致谢：
-
-- [**andrej-karpathy-skills**](https://github.com/forrestchang/andrej-karpathy-skills) — 4 原则
-- [**smart-ralph**](https://github.com/tzachbon/smart-ralph) — 规格引擎 + stop-hook 循环
-- [**superpowers**](https://github.com/obra/superpowers) — Subagent 纪律 + TDD + 两阶段审查
-- [**BMAD-METHOD**](https://github.com/bmad-code-org/BMAD-METHOD) — 协作流程 + 对抗审查
-- [**get-shit-done**](https://github.com/ryangentry/get-shit-done) — 波形执行 + 决策锁定 + 多源审计
-- [**gstack**](https://github.com/garrytan/gstack)（Garry Tan） — 规划审查 + DX 哲学
-- [**pua**](https://github.com/tanweai/pua) — 持续性 + 三条红线
-- [**claude-mem**](https://github.com/thedotmack/claude-mem) — 自动跨会话记忆
-- [**frontend-design skill**](https://claude.ai/skills/frontend-design) — distinctive UI（Anthropic 官方）
-- **Context7**（Upstash）+ **sequential-thinking**（Anthropic）+ **chrome-devtools-mcp**（Chrome 团队）
-
-## 许可
-
-MIT。见 [`LICENSE`](./LICENSE)。
-
-## 贡献
-
-- Issues: https://github.com/curdx/curdx-flow/issues
-- 欢迎 PR，但请先用 `/curdx-flow:spec` 自己走一遍（吃自己的狗粮）
-- 社区准则：友善 + 具体 + 不对着 LLM 发火
-
----
-
-_CurDX = AI 编程时代的 "Current Developer eXperience"。_