@chenguangyao/devflow-kit 0.1.43

package/skills/df-orchestrator/references/workflow-state-machine.md

@@ -0,0 +1,208 @@
+# df-orchestrator / workflow-state-machine
+
+workflow step / phase 之间怎么走、哪些转移合法、哪些必须回退。orchestrator 据此判定 sub-skill 之间的交接是否合法。
+
+---
+
+## 规范 workflow 模型
+
+新 change 优先由 `devflow new` / `devflow ingest` 自动生成 `state.workflow` draft,再通过 `devflow flow picker --json` → 可选 `devflow flow apply-selection --selection='<json>' --json` → `devflow flow card --json` → `devflow flow confirm` 冻结 `state.workflow.steps`。`devflow flow check --json` 仍保留给脚本做预检。如果自动 draft 失败,再退回 `devflow flow recommend` → `devflow flow draft` 的手动补救路径。orchestrator 决定下一步时:
+
+1. 若 `state.workflow.status = confirmed`,按 `state.workflow.steps` 中未完成 / 未禁用的 step 推进。
+2. 若 `state.workflow.status = draft`,先展示 `devflow flow picker --json` 让用户看到线形选项卡；如果用户调整勾选,执行 `devflow flow apply-selection --selection='<json>' --json`；然后展示 `devflow flow explain` 和 `devflow flow card --json`,只有确认面 `ok=true` 时才展示 `devflow flow confirm` 下一步卡片,不得直接进入 requirement/design/apply。
+3. 若旧 change 没有 `state.workflow`,才使用下面的固定 phase 列表作为兼容路径。
+4. `review`、`verify`、`deliver` 是 protected gates,workflow 不得删除或降级。
+
+`level` 不再决定流程链路,只决定 verify 证据强度。workflow recipe 才决定本次需求实际编排哪些 skill。详细说明见 `docs/workflow-orchestration.md`。
+
+## 兼容 phase 列表
+
+```
+intake → brainstorm → [complexity-grading] → requirement → design → (test-design) → plan → apply → review → verify → deliver → archive
+```
+
+12 个 phase。`[complexity-grading]` 在 intake/brainstorm 完成后**自动触发**，不需要用户主动调用。`test-design` 在 L0/L1 可跳过，`intake` 和 `brainstorm` 互斥(二选一)。在无 workflow 的旧 change 上，其余按兼容顺序推进。
+
+> **极简模式(L0)** 是独立路径,跳过前 5 个 phase(intake/brainstorm/requirement/design/test-design),从 plan(最简化)直接进入 apply,不做 archive。详见下文。
+
+## 状态机图(合法转移)
+
+```
+         start
+           │
+   ┌───────┴──────┬──────────────────────────────┐
+   ↓              ↓                              ↓
+intake        brainstorm               ★极简模式(L0)★
+   │              │                         [--micro]
+   └──────┬───────┘                              │
+          ↓                                      │
+  ★complexity-grading★  ←────────────────────────┘
+  (自动触发，输出判定卡)          (L0 需二次确认)
+          │
+   ┌──────┴──────────────────────┐
+   ↓ level=L1/L2/L3              ↓ level=L0
+requirement                    plan(极简)
+          ↓
+          ↓                                    apply ←──┐
+       design                                    ↓       │
+          │                                   review ───┘
+      ┌───┴──── (L2/L3 fork) ───┐               ↓
+      ↓                          ↓            verify
+    plan ←─────── test-design     │   (仅 unit-test + 测试文档)
+      ↓                           │              ↓
+     apply ←──────┐               │           deliver
+      ↓            │ (review 判    │   (自动发测试邮件 --notify=test-report)
+    review ───────┘ back_to_apply) │      (不进 archive)
+      ↓
+    verify ←──────┐
+      ↓            │ (verify 发现 required report section fail)
+      │            └── apply
+      ↓
+    deliver
+      ↓
+    archive (终态)
+```
+
+---
+
+## 合法正向转移(只写非显然的)
+
+| From | To | 条件 |
+| --- | --- | --- |
+| `intake` | `complexity-grading` | `ingest` 成功落 `refs/source.md` 且 state 已建（**自动触发**，不需要用户命令） |
+| `brainstorm` | `complexity-grading` | `proposal.md` 满足 brainstorm 的 Done Criteria（**自动触发**） |
+| `complexity-grading` | `requirement` | `state.level` 写入且用户已确认 |
+| `complexity-grading` | `plan` (L0) | `state.level = L0` 且用户二次确认极简模式 |
+| `requirement` | `design` | `requirement.md` 至少 1 条有可验收 AC + Round 1 Q 完成;L1 可跳 Round 2 |
+| `design` | `plan` (L1) | `design.md` 最低有"改动点汇总" |
+| `design` | `test-design` (L2/L3) | `design.md` 满足硬闸门 |
+| `test-design` | `plan` | `tests.md` 每条 F-ID 至少有 1 个 TC |
+| `plan` | `apply` | `plan.md` 非空 + 每个 task 含 5 要素(Files/Behavior/Test/Implementation/Commit) |
+| `apply` | `review` | 所有 plan task `--done`,单元测试至少跑过一次(存在 `reports/test-report.md#unit`) |
+| `review` | `verify` | round ≤ 3 且 `finalOutcome ∈ {pass, force-pass}`,`code-review-report.md` 落盘 |
+| `verify` | `deliver` | 本级别的 required reports 全 pass/partial(非 fail),`devflow doctor --scope cred` clean |
+| `deliver` | `archive` | mode=pr:PR merged;mode=merge:本地已合并到 main;mode=keep/discard:不进 archive |
+
+### 极简模式(L0)合法转移
+
+`state.mode = "micro"` 时,下面规则覆盖上表:
+
+| From | To | 条件 |
+| --- | --- | --- |
+| `start` | `plan` (L0) | `devflow new <slug> --micro` 建 state,`plan.md` 写 1-3 行改动意图即可 |
+| `plan` (L0) | `apply` | `plan.md` 非空（无 5 要素要求） |
+| `apply` | `review` | 代码已改,`reports/test-report.md#unit` 存在 |
+| `review` | `verify` | 同标准路径（至少 1 轮,`finalOutcome ∈ {pass, force-pass}`） |
+| `verify` | `deliver` | `reports/test-report.md#unit` pass,`devflow doctor --scope cred` clean |
+| `deliver` | _(结束)_ | **不进 archive**；`deliver --notify=test-report` 触发测试邮件后完成 |
+
+> **L0 特有约束**：如果 apply 阶段发现改动超出"单文件 / 无 DDL / 无契约变更"，orchestrator **必须提示升级到 L1**（`devflow status set-level L1`），补做 requirement + design，再进 plan 正式版。
+
+---
+
+## 合法回退(向后跳)
+
+回退意味着"发现当前 phase 的前置 phase 产物有问题,要回去修",state 里会留 audit entry。
+
+| From (当前 phase) | 可回退到 | 触发条件 | 会被清除的产物 |
+| --- | --- | --- | --- |
+| `requirement` | `brainstorm` | Round 1 发现 proposal.md 的 scope 写错 | 无(requirement.md 可迭代) |
+| `design` | `requirement` | 发现某些功能点在 requirement 未定义 | 无 |
+| `plan` | `design` | 任务切到一半发现 design 的改动点漏了一层 | 无 |
+| `apply` | `plan` | 编码过程中发现 task 定义不对 | 正在进行的 task `--revert` |
+| `apply` | `design` | 发现方案本身错了 | 触发 tech-spec --revise,design.v1 备份,apply 状态重建 |
+| `review` | `apply` | round 的 MUST > 0 | 无(review.md append 新 round) |
+| `review` | `design` | 同一 MUST 跨 2 轮未解 / `fixMode: SPEC` ≥ 1 | 参见 `code-review/references/escalation-playbook.md` Path B |
+| `verify` | `apply` | 测试报告 fail | 无 |
+| `verify` | `design` | 发现 design 的 non-functional 漏了(如性能) | 同上 Path B |
+
+**回退时必做的事**:
+
+1. 在 `state.json.audit[]` 写一条 `{type: "phase_rollback", from, to, reason, operator, at}`。
+2. 在目标 phase 的产物末尾追加一段 "第 N 次返工" 记录(不是删重写)。
+3. 不自动清除下游产物,允许沿用;但 `state.currentPhase` 回到目标 phase,后续 phase 的 status 重置为 `pending`。
+
+---
+
+## 非法转移(orchestrator 必拒绝)
+
+| 企图的转移 | 拒绝理由 | 给用户的话术 |
+| --- | --- | --- |
+| `intake` 或 `brainstorm` → `design` | 跳过 requirement-analysis | "先跑 requirement-analysis,它会确认 Scope 和 AC,design 没 AC 做不动" |
+| `requirement` → `plan` | 跳过 design | "没 design 的 plan 是假 plan,任务粒度没依据" |
+| `design` → `apply` | 跳过 plan | "apply 的单位是 plan 里的 task;先 plan 拆" |
+| `apply` → `verify` | 跳过 review | "review 是质量闸,至少 1 轮;强行 skip 会在 deliver 处被 gate" |
+| `review` → `deliver` | 跳过 verify | "verify 要产出 reports 给 PR;review 不等于 verify" |
+| `deliver` → `archive`(PR 未 merge) | 过早 archive | "archive 只在 PR merge 后做,否则 specs 会合入未部署的能力" |
+| L0 极简模式 → `archive` | L0 没有可 archive 的规格文档 | "极简模式不进 archive；有经验要沉淀，请用 `devflow knowledge deposit`" |
+| L0 改动超 1 个文件 → 继续 L0 | L0 对改动规模有硬约束 | "检测到改动超出极简模式范围，建议升级到 L1：`devflow status set-level L1`" |
+
+---
+
+## 跳过(Skip)规则
+
+Skip ≠ 回退;skip 是"这个 phase 对本次任务不需要做,允许直接跨过"。
+
+| 可 skip 的 phase | 条件 | 怎么做 |
+| --- | --- | --- |
+| `intake` | 走了 brainstorm 路径,或极简模式 | 自然跳过,无需命令 |
+| `brainstorm` | 走了 ingest 路径,或极简模式 | 自然跳过 |
+| `requirement` | 极简模式(L0) | state.mode=micro 时自动跳过 |
+| `design` | 极简模式(L0) | state.mode=micro 时自动跳过 |
+| `test-design` | L0 / L1 任务 | state.level ∈ {L0,L1} 时直接跳 |
+| `archive` | 极简模式(L0) | state.mode=micro 时跳过,可手动 `devflow knowledge deposit` 补充沉淀 |
+| `code-review` | **不允许 skip**（`--force-pass` 是走完流程后放行，不是 skip） | — |
+| `verify` | **不允许 skip**（即使 L0 也要至少 unit-test） | — |
+| `deliver` | `mode=keep` 表示"暂停,不交付",不进 archive | 手动触发 resume |
+
+---
+
+## state.json 的 phase 状态字段
+
+每个 phase 在 `state.json.phases.<phase>` 下有 4 个字段:
+
+```json
+{
+  "status": "pending | in_progress | completed | blocked | skipped",
+  "startedAt": "<ISO>",
+  "completedAt": "<ISO>",
+  "auditLogPath": "devflow/changes/<slug>/audit/<phase>.log"
+}
+```
+
+**转移合法性判定**:orchestrator 在调用 sub-skill 前,先检查目标 phase 的所有前置 phase `status ∈ {completed, skipped}`,否则拒绝并回退。
+
+---
+
+## 多轮 / iteration 的记账
+
+有些 phase 支持多轮(iteration):
+
+| phase | 支持多轮 | 记账字段 |
+| --- | --- | --- |
+| `requirement` | 是(Round 1 / Round 2) | `phases.requirement.rounds[]` |
+| `design` | 是(v1 / v2 / ...,每次 `--revise`) | `phases.design.versions[]` |
+| `apply` | 是(每次 back_to_apply 来一轮) | `phases.apply.iterations[]` |
+| `review` | 是(3 轮硬上限,可 `--continue-rounds` 越限) | `phases.review.rounds[]`(见 code-review skill) |
+| `verify` | 是(report fail → apply 回修 → 重跑 verify) | `phases.verify.attempts[]` |
+
+其他 phase 不支持多轮,一次过。
+
+---
+
+## 与 sub-skill 的接口
+
+sub-skill 完成时必须输出 `---STATUS---` 块(完成状态协议)。orchestrator 用下面规则决定接下来做什么:
+
+```
+status = DONE                    → 进入下一 phase(按状态图)
+status = DONE_WITH_CONCERNS      → 进入下一 phase,但把 concerns 加入 state.followup[]
+status = BLOCKED                 → 按 escalation-matrix 决定回退或终止
+status = NEEDS_INPUT             → 把 sub-skill 的问题转给用户,不做转移
+```
+
+---
+
+## 本文与 SKILL.md 的关系
+
+SKILL.md 只给了正向 phase 顺序 + 硬闸门简表。所有转移合法性、回退路径、多轮记账 细节在这里。orchestrator 在每次决定"要不要让 sub-skill 进入下一 phase"时,**必须**回到这里查表。

package/skills/frontend-quality/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: devflow-frontend-quality
+description: |
+  devflow-kit 前端质量专项 skill。当 diff 涉及 React / Vue / Next / Vite / CSS / 页面组件 / 表单 / 弹窗 / 路由 / 前端状态时触发。
+  接入 code-review 与 verify,要求补齐 UI 一致性、响应式、可访问性、性能和 Playwright/截图证据,避免前端改动只跑单测就提测。
+when_to_use: |
+  任何前端用户界面、浏览器交互、前后端联调页面、移动端适配或可访问性风险出现时。L2/L3 前端改动必须使用;L1 小 UI 改动按风险使用。
+---
+
+# frontend-quality
+
+前端质量专项 skill。它不替代 `devflow-code-review` / `devflow-verify`,而是在前端 diff 出现时给这两个阶段增加专项检查。
+
+## 触发条件
+
+- 修改 `*.tsx`、`*.jsx`、`*.vue`、`*.css`、`*.scss`、`*.less`、`routes/`、`pages/`、`components/`。
+- 新增或修改表单、弹窗、列表、分页、筛选、上传、支付/签约/登录等关键页面。
+- `design.md` 有前端消费者、轮询页、redirect/query、returnUrl、callback 或浏览器验证要求。
+- code-review 发现 UI、性能、可访问性、状态管理、联调路径风险。
+
+## 接入点
+
+| phase | 必做动作 |
+| --- | --- |
+| requirement-analysis | 标记受影响页面、入口、设备、浏览器、前端消费者 |
+| tech-spec | 在契约消费者影响矩阵里写清页面状态来源、query/route 兼容、刷新/直达策略 |
+| plan | 每个 UI task 要有截图/交互验证字段 |
+| code-review | 使用 `references/checklist.md` 做 UI/性能/可访问性 review |
+| verify | 产出 `test-report.md#joint` 或 `#e2e`;有浏览器路径时附截图/录屏/Playwright 结果 |
+
+## 执行流程
+
+1. 先确认前端改动范围:页面、组件、路由、状态、接口契约。
+2. 读取 `design.md` 的契约消费者影响矩阵,确认前端数据来源没有被后端假设覆盖。
+3. code-review 时按 `references/checklist.md` 逐项检查。
+4. verify 时优先跑已有前端测试命令,例如:
+
+```bash
+devflow test joint --cmd="npm run test:e2e" --backend-url=<url> --frontend-url=<url>
+devflow test e2e --cmd="npx playwright test"
+```
+
+5. 如果没有自动化测试,必须人工补充浏览器操作步骤、关键截图和失败风险,写进 `reports/test-report.md#joint` 或 `#self-test`。
+
+## 输出要求
+
+- `review.md` 中必须有 frontend-quality 结论:pass / concerns / blocked。
+- `reports/test-report.md#joint` 或 `#e2e` 应记录:
+  - 前端地址、后端地址、账号/权限说明。
+  - 操作路径:打开页面 -> 输入/点击 -> 结果验证。
+  - 截图/录屏相对路径或说明。
+  - 移动端/窄屏是否验证。
+- 若跳过浏览器验证,必须在 `verify.md` 写明原因和风险接受人。
+
+## 反模式
+
+- 只看 API 成功,不打开页面。
+- 只验证桌面宽屏,不看移动端或窄屏。
+- 只凭肉眼说"页面正常",没有截图、步骤或自动化结果。
+- UI 文案、按钮、表格列被接口字段改动影响,但没有消费者矩阵。
+

package/skills/frontend-quality/references/checklist.md

@@ -0,0 +1,35 @@
+# frontend-quality checklist
+
+## UI 一致性
+
+- 布局无重叠、溢出、截断、横向滚动异常。
+- 按钮、输入框、表格、弹窗使用项目现有组件和样式约定。
+- 空态、加载态、错误态、禁用态完整。
+- 中文文案、金额、日期、枚举展示符合业务语义。
+
+## 响应式
+
+- 至少检查桌面宽屏、普通笔记本宽度、移动端或窄屏。
+- 表格列过多时有合理横滚、折行或列隐藏策略。
+- 弹窗、下拉、toast 不被遮挡。
+
+## 可访问性
+
+- 表单字段有 label 或可理解的 aria-label。
+- 按钮可键盘聚焦和触发。
+- 颜色不作为唯一状态表达。
+- 错误提示靠近对应字段。
+
+## 性能
+
+- 避免在 render 中做大计算或重复创建重对象。
+- 列表、表格、轮询、定时器有清理和分页/节流策略。
+- 图片和资源大小可接受。
+- 不因接口失败造成无限重试或页面卡死。
+
+## 证据
+
+- 有 Playwright/Cypress/Vitest UI 测试时优先跑自动化。
+- 无自动化时,至少提供操作步骤 + 截图路径 + 验证结论。
+- 涉及前后端联调时,写入 `test-report.md#joint`。
+

package/skills/handoff-resume/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: devflow-handoff-resume
+description: |
+  devflow-kit 长任务交接 / 恢复专项 skill。当任务跨天、上下文接近上限、多 agent/多人接力、用户说"接着上次继续"或需要交接状态时触发。
+  读取 state.json、当前 phase、已改文件和报告,生成或消费 handoff.md,让下一个 agent 不重新猜上下文。
+when_to_use: |
+  长任务、上下文压缩、暂停后继续、换 agent、多人协作、用户要求"整理交接"或"继续上次"时使用。
+---
+
+# handoff / resume
+
+交接恢复 skill。目标是把"我做到哪里了"变成可读文件,避免新会话从头扫描和误解旧决策。
+
+## 触发条件
+
+- 用户说"整理一下交接"、"明天继续"、"接着上次"、"换个 agent 继续"。
+- 当前任务已经跨多个 phase 或上下文很长。
+- apply/review/verify 中断。
+- 存在多 worktree / 多 agent 并行实现。
+
+## 生成 handoff
+
+优先写到当前 change:
+
+```text
+handoff.md
+```
+
+必要时也可以在 `state.auditLog` 记录 `handoff.create` 事件。
+
+handoff 必须包含:
+
+- 当前 change、level、phase、mode。
+- 已完成事项。
+- 未完成事项。
+- 当前风险和阻塞。
+- 已运行命令和结果。
+- 修改过的关键文件。
+- 下一步建议命令。
+- 不要重复做的事情。
+
+模板见 `references/handoff-template.md`。
+
+## resume 流程
+
+1. 读取 `state.json` 和最新 `handoff.md`。
+2. 读取 `reports/test-report.md`、`review.md`、`verify.md` 中最近状态。
+3. 用 `git status --short` 看工作区,不要回滚用户改动。
+4. 对照 handoff 的下一步,判断是否仍有效。
+5. 如果 handoff 和 state 冲突,以 CLI state/checkpoint 为准,并说明冲突。
+6. 继续执行前先给用户一个简短状态摘要。
+
+## 反模式
+
+- 只写聊天总结,不落文件。
+- handoff 只写"已完成",没有下一步命令。
+- 新 agent 不读 state/checkpoint,直接按旧聊天继续。
+- 把未验证的猜测写成事实。
+

package/skills/handoff-resume/references/handoff-template.md

@@ -0,0 +1,54 @@
+# Handoff 模板
+
+````markdown
+---
+slug: <slug>
+phase: <phase>
+level: L0 | L1 | L2 | L3
+updatedAt: <ISO>
+---
+
+# Handoff - <title>
+
+## 当前状态
+
+- phase:
+- checkpoint:
+- mode:
+- branch/worktree:
+
+## 已完成
+
+- ...
+
+## 未完成
+
+- ...
+
+## 关键决策
+
+- ...
+
+## 风险 / 阻塞
+
+- ...
+
+## 已运行验证
+
+| 命令 | 结果 | 说明 |
+| --- | --- | --- |
+
+## 关键文件
+
+- ...
+
+## 下一步
+
+```bash
+devflow status --slug=<slug>
+```
+
+## 不要重复做
+
+- ...
+````

package/skills/plan/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: devflow-plan
+description: |
+  devflow-kit plan 阶段把 `design.md`(改动点)和可用的测试用例/验收项切成 30-60 分钟粒度的 TDD task,写进
+  `plan.md`。每个 task 都是"写失败测试 → 最小实现 → 提交"的一个完整闭环。触发时机:
+  `devflow plan` 或 `/df:plan`。apply 阶段只照 plan.md 执行,不允许在 apply 中偷改 scope。
+when_to_use: |
+  tech-spec 完成之后;若本 change 显式生成了 `tests.md`,则以 tests.md 为测试契约。apply 之前的必经 phase。
+---
+
+# plan
+
+plan 是**计划经济**,apply 是**执行经济**:把大象拆成能一口吃掉的小块,让 apply 阶段不用再做决策。
+
+## 前置检查
+
+| 输入 | 必需 | 缺失时 |
+| --- | --- | --- |
+| `design.md`(§4 改动点汇总、§5 契约、§7 关键流程) | 是 | 回退 tech-spec |
+| `tests.md` | 可选；L3 或 `--with-tests` 时使用 | 缺失时把测试点内嵌到每个 task 的 Test 字段 |
+| `state.level` | 是 | 决定 task 最小粒度 |
+
+## 产物
+
+`devflow/changes/<slug>/plan.md`,含:
+
+| # | Section |
+| --- | --- |
+| 1 | 任务依赖图(DAG 或箭头链) |
+| 2 | 任务清单(T-01..) |
+| 3 | 每个任务详表 |
+| 4 | 变更日志(task 改动 / 增删时在此留痕) |
+
+## Task 的 5 要素(硬闸)
+
+每个 task 必须含且只含 5 个字段。缺任一字段 → 回退重写:
+
+```
+T-01
+  文件:          coupon-service/src/.../BatchGrantController.java (新建)
+  行为:          新增 POST /api/v2/coupon/batch-grant 入口,校验 userIds 长度 1-1000
+  测试:          TC-002 (空) + TC-003 (1001 人) 通过；无 tests.md 时写内联验收描述
+  实现:          1. 新建 Controller 类 2. 加 @PostMapping 3. 加参数校验 4. 返回占位 501
+  提交:          feat(coupon): T-01 add batch-grant controller skeleton
+```
+
+- **Files**:具体路径(不接受 "whatever needed");(new) / (modified) 标记
+- **Behavior**:**可直接测的一句话**。不接受 "make it work"
+- **Test**:优先引用 `tests.md` 的 TC 编号；没有 tests.md 时写 inline 用例 / AC 描述
+- **Implementation**:2-4 条项目级 bullet,不写代码行;描述**做哪些步骤**
+- **Commit**:Conventional Commits 格式,含 task ID
+
+完整模板、任务排序原则、5 要素的正反例见 [`references/task-template.md`](references/task-template.md)。
+
+## 拆分规则(Bite-size)
+
+- 每个 task 目标 **30-60 分钟**(或小 PR 粒度)
+- 一个 task 改 ≤ 3 个文件(特殊例外标注)
+- 一个 task 改 ≤ 150 行(diff loose 计数,含 test)
+- 一个 task 有 **可独立验收**的产物(跑测试通过、或可手测)
+
+超出任一条 → **拆**。
+
+拆分的具体手法(按 vertical slice / by layer / by F-ID / by behavior)、分别适用什么场景,见 [`references/task-breakdown.md`](references/task-breakdown.md)。
+
+## 任务排序(Sequencing)
+
+硬规则:
+
+1. **契约变更 task 在 前**(DTO / proto 改动 task 先,消费者 task 后)
+2. **DDL 变更 task 在 前**(表结构先落,业务代码后用)
+3. **每个 task 留下仓库在 "tests pass" 状态**(不允许"先提交编不过的代码")
+4. **feature flag 添加 task 在最后**(保留 off 状态直到全部就绪)
+
+排序方法论与例子(含并行化判断)见 [`references/task-sequencing.md`](references/task-sequencing.md)。
+
+## Ready 判据
+
+一个 task 可以进 apply 必须达到 "Ready":
+
+- [ ] 5 要素齐
+- [ ] 引用的 TC 在 tests.md 里真实存在；若无 tests.md，Test 字段有可执行的内联验收描述
+- [ ] 前置 task 已完成(或明确标 `blocks: T-0X`)
+- [ ] 可以独立 commit 并 leave repo green
+
+未达 Ready → 拆 / 补 / 重写。
+
+## 并行化
+
+独立 task(无共同文件、无依赖链)可以并行(通过 `devflow apply --task=N` 自动创建 worktree)。并行判断:
+
+- 共享文件 → 不并行(或合并为一个 task)
+- 前后依赖 → 不并行
+- 独立模块 → 并行 ✓
+
+"哪些 task 可以并行"的判断流程 + DAG 画法见 `references/task-sequencing.md` §2。
+
+## 硬闸(Done Criteria)
+
+- [ ] 每个 F-ID 至少有 1 个 task 负责
+- [ ] 每个 TC/内联验收点至少被一个 task 引用(覆盖率 100%)
+- [ ] 所有 task 的 5 要素齐
+- [ ] §1 依赖图画了
+- [ ] 首个 task(T-01) 是 Ready
+
+未达标 → 继续写;达标 → DONE → **展示计划审查卡，等待用户确认**。不得自动执行 `devflow apply`。
+
+## 计划审查卡（apply 前人工闸）
+
+plan 生成完成后，必须向用户展示一张**计划审查卡**，让用户审查 scope、任务拆分和执行顺序。用户确认前不得进入 apply。
+
+> **注意**：计划审查卡不是补技术细节的入口。若 plan 生成时还需要用户回答"字段从哪里取 / 渠道怎么判 / 缓存怎么查 / helper 复用哪个"这类实现问题，说明 tech-spec 没有完成，必须回到 `devflow-tech-spec` 收敛设计，不能把这些问题放到 plan_review 里让用户补。
+
+必须展示：
+
+- `plan.md` 路径和任务总数。
+- 每个 task 的 ID、Files、Behavior、Test 摘要。
+- DAG / 依赖顺序：哪些 task 先做，哪些可并行。
+- 首个 ready task：默认建议从哪个 task 开始。
+- 风险提示：大 task、共享文件、未覆盖 TC、可能需要拆分的点。
+
+确认协议：
+
+```markdown
+## 计划审查卡
+
+请审查 plan.md：
+- 回车 / "确认" / "OK"：确认计划，写入 `state.planReviewConfirmedAt`，再进入 apply
+- "改 T-02 ..."：回到 plan 修改对应 task
+- "拆 T-03" / "合并 T-04/T-05"：回到 plan 重写任务
+- "先做 T-02"：调整执行顺序并重新展示审查卡
+```
+
+`state.planReviewConfirmedAt` 是 apply 的硬前置。旧 change 若已有 `plan.md` 但没有这个字段，必须补展示计划审查卡，不能因为用户说"继续"就直接编码。
+
+## 反模式
+
+- **task 大粒度 ("实现批量发放功能" 一个 task 干完)**:3 小时以上的 task 无法回退、难以并行、掩盖风险
+- **task 没引用 TC**:apply 时没法 TDD,变成"写完再说"
+- **先实现后写测试**:本 skill 的基本假设就是 TDD;"先实现再补测" 会让 review / verify 阶段翻车
+- **commit message 里不带 task ID**:后续追溯困难;review 时无法对应 task
+- **task 改文件超出 Files 列表**:要么更新 Files,要么拆新 task;不要默默改
+- **依赖图乱成一团 / 没画依赖图**:每次 apply 前都要确认"接下来可以干哪些"
+- **"flag 开关"最先加而不是最后加**:导致半成品上线(flag 开了但实现没好)
+- **契约 task 放在消费者 task 后面**:消费者没法写,只能 mock,后面又要改
+
+## 完成状态协议
+
+```
+---STATUS---
+result: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_INPUT
+outputs:
+  - devflow/changes/<slug>/plan.md
+taskCount: N
+estimatedTotalMinutes: M          # 粗估
+parallelizable: [T-02, T-03]      # 可并行的 task ID 列表
+firstReadyTask: T-01
+nextAction: 等用户确认计划审查卡（确认后才允许 devflow apply --task=1）
+---END_STATUS---
+```
+
+## 参考
+
+- [`references/task-template.md`](references/task-template.md) — task 详表模板、5 要素正反例、完整 plan.md 示例
+- [`references/task-breakdown.md`](references/task-breakdown.md) — 拆分手法(vertical slice / by layer / by F-ID / by behavior)
+- [`references/task-sequencing.md`](references/task-sequencing.md) — 依赖排序 + DAG 画法 + 并行化判断