workflow-specify

工作流 specify

将协议转化为其他 Agent 可以实现的工单，并获得计划批准。不编写应用程序代码或测试。

从同级目录 ../workflow/ 读取共享策略，包括其中的“Always”列表。如果缺失则停止；绝不能用其他已安装副本替代。

开始之前，检查：规则涵盖此范围（workflow/RULES.md）；检查点 Agreement 已就绪、对此修订属于遗留或已豁免，或者已发送一项小而明确的变更说明，以便在此处同时申请两道关卡（workflow/VISUAL-REVIEW.md）；否则转到 workflow-clarify；没有未解决的选项会阻碍计划；应用程序 UI 已采用 ui-design 模式并记录了来源（未记录的模式只会阻碍 UI 工单）；如果本次会话尚未读取 ../ui-design/SKILL.md，则阅读它。当现有样式无法实现已商定的布局时，提出 design.md 规则 4 中的问题；绝不提议新增 CSS。对于协议达成后更改过的文件，刷新其证据。

1. 确定行为归属

将每项行为放入现有的负责代码中。如果接口或边界不明确，阅读 ../codebase-design/SKILL.md；如果术语或归属不明确，阅读 ../domain-modeling/SKILL.md。每个新增的辅助项、包装器、回退方案或设置都必须通过 workflow/AUDIT.md 中的必要性检查。根据实际风险，采用 rule-maker 的 ENGINEERING.md 中的指导。

2. 拆分纵向工单

工单交付一个贯穿所需各层、可独立测试和评审的用户旅程切片。没有自身行为的工单属于标明用途的前置项，并须说明其支持的内容。

通过 record.py，按 workflow/TASK-FOLDER.md 的格式（概览表、标注的工单）编写 TODO。Supports、Depends on 和 Rules 放在 References 下；其余内容放在 Technical details 下：

• Supports：R-ID 和 A-ID。
• Scope：可能变更的文件或区域，以及不得变更的内容。
• Depends on：必须先通过验证的工单。
• What should work：他人可以观察到的效果，包括失败情形。
• Test seam：测试使用的公共接口、测试能捕获的问题、无法覆盖的内容，以及如何弥补这一缺口。
• TDD：填写 yes；若填写 no，说明原因（文档、配置、没有可测试的边界）。
• How to verify：准确的检查项及其输出文件夹（workflow/ARTIFACTS.md）；只能由人员执行的步骤（设备、账户、视觉签核）标注为 Human check: what, when（或 needs human），并一并提出。
• Docs and cleanup：需要更新的文档、需要替换和删除的代码。
• Rules：必须遵循的项目规则（工单路径上每个 AGENTS.md 或 CLAUDE.md 中的规则）。规则禁止的相邻代码模式不能作为先例：通过第二道关卡提出询问。

完成条件：依赖图无环；每项需求和验收项都有对应工单，且每项工单都能追溯到其中一项；并行工单不共享文件。

3. 列出更大范围的检查

列出每组相互依赖的工单所需的检查，以及针对协议的整体验收检查：其他调用方、兼容性、失败旅程。说明无法检查的内容及原因。即使没有测试运行器，无头 Edge 或 Chrome 探测页面仍可通过点击进行检查（--dump-dom）。列明每项检查所需条件（服务端、端口、设备、账户），并通过第二道关卡申请，避免交付时默默遗漏必要检查。

4. 挑战计划（适用于大型或高风险计划）

在新上下文中运行 plan-review 并解决其发现的问题。行为相关的问题返回 workflow-clarify。任何会改变用户所见或已商定需求（位置、措辞、行）的答复，都会改变协议：为这些事项编写新的协议修订，并在申请第二道关卡的同一条消息中一并提出；绝不能只将其记为决策。

5. 第二道关卡

先逐行对照每张工单与约定（行为、时机、数据、失败情况、假设）；任何差异都是约定变更（第 4 步）。按照 workflow/VISUAL-REVIEW.md 中的“准备报告”要求，制作 HTML 计划并请求批准实施；只有在对照未发现任何差异时，才能说“实现我们约定的行为”。**停止。**收到答复前，只能编写任务记录和报告。

完成条件：针对本次修订的报告已存在，且报告路径已写入审批问题（包括单行变更），或者已记录用户明确表示“不要报告”。设置 task_report.screen_change；用户在屏幕上可见的变更（visible）还需要报告中的屏幕示意图（ui-design 第 3 步）：在安全的情况下，页面打开时截取当前屏幕（本地页面：../codebase-map/scripts/screenshot_report.py），并绘制提议方案的草图；只有草图的预览属于 not-needed。

将答复记录在检查点的 Approval 行和 DECISIONS 中：已批准（修订、报告、工单、排除项）、更正（行为或范围 → workflow-clarify；工单、边界、呈现方式 → 在此处理），或有范围限定的豁免。

修订

后续变更时，只重写受影响的工单和检查，并展示与上一已批准修订的差异。其他已批准的工单继续执行。在已批准工单内修正路径或顺序无需修订。

下一步

• 已批准或获得豁免，且已请求实施：workflow-execute。
• 仅请求计划：无论是否获批，都在计划完成后停止。
• 受阻：记录哪些工单受到什么阻碍，以及仍可批准的内容。

绝不暂存、提交、创建分支、打开跟踪器问题或发布。