workflow

工作流

⚠️ 请先调用此技能；参考资料必须通过它读取，不得单独读取。

四个阶段加一个收尾：头脑风暴 → 规划 → 执行 → 评审 → 收尾。每个阶段都是一个席位 （有输出约定的工作），由当前最能胜任的模型担任。作者和评审者有意选用不同供应商——独立性正是关键。ROUTING.md 将席位映射到供应商、模型和工作量。

调用：workflow <command> [slug]；如果卡片的命令行包含 CLI 自带的技能前缀，也要一并使用。

**检出：**读取一次运行前，请遵循 references/worktrees.md。 它会将每个阶段和状态对应到该次运行的检出；执行阶段会创建隔离环境，收尾阶段会合并改动。

一次运行 — .workflow/<slug>/

一次运行对应一个文件夹，在 git 中跟踪并永久保留；其中的文件就是状态机。

工件	编写者	内容
brainstorm.md	头脑风暴	简报：问题、行为（B#）、决策、测试切入点、范围外事项——该次运行的权威状态记录
plan.md	规划，然后执行	发现 + 任务单（T#），每项都有验收条目和验证命令；执行状态
patch_plan.md	评审	当前修复周期的修复任务单
review.md	评审	覆盖情况、当前周期的发现和结论，以及包含先前周期的 ## Resolved 表格
learnings.md、wrap.md	任意阶段 / 收尾	带标签的经验；收尾检查点，以及该次运行不超过约 40 行的摘要

目录布局。 顶层只存放上述工件；其他所有内容都按类型放入子文件夹，在首次需要时创建：receipts/（验证输出、差异、交接记录： t3-verification.md）· screens/（UI 前后对比：t3-topic-page-before.jpg）· notes/ （调查、审计、运行手册、草稿）· scripts/（一次性代码，与其他代码一样进行评审）· data/（小型冻结 *.json/*.csv；大量数据保留在仓库之外）· prototypes/ （一次性草图）· understand/（仅由 understand 技能写入）。

每个工件的标头都包含 Status: — drafting（从该阶段继续）· complete · parked · done。brainstorm.md 状态为 parked 或 done 的运行不属于进行中的运行。

进行中运行的状态	下一步
仅有 brainstorm.md	规划
plan.md 中有一项任务为 awaiting-human，且没有其他已就绪任务	执行该任务中指定的人工操作，然后执行
plan.md 中有未标记为 done 的任务	执行
所有任务均已完成；没有 review.md，或自其 Base 以来代码有改动	评审
patch_plan.md 中有未标记为 done 的任务	执行（运行修复任务单）
review.md 没有未解决的发现，且自其 Base 以来代码未改动	收尾

**Slug：**命令会指定一个 slug，或者当前恰好只有一次进行中的运行；否则请列出进行中的运行，按字母编号并询问。每个解析后的检出中，进行中的运行通过以下命令查找：grep -l 'Status: *\(drafting\|complete\)' .workflow/*/brainstorm.md。 workflow status 会为每个未完成的运行打印一行——slug · 阶段 · 阻塞项或无 · 下一条命令 （awaiting-human 任务及其指定操作即为阻塞项）。如果命令与运行状态不符，应说明并询问。

接地——分层读取

• 始终读取： 本次运行的实时产物（brainstorm.md、plan.md、patch_plan.md、review.md 的当前周期及其 ## Resolved 表格）；ROUTING.md（卡片的各行）；AGENTS.md；MEMORY.md 索引——仅当某个 memory/<slug>.md 页面中的 “Applies when” 条件匹配时才打开；git log --oneline -15；git status。
• 按需读取——PRODUCT.md、DESIGN.md： 当产品或 UI 属于工作范围时，先读标题，再只读工作涉及的章节，并记录为：Docs read: PRODUCT.md §Vocabulary · DESIGN.md §Tables。它们是防止偏离的护栏：对于新的产品方向、realign、偏离设计的提案，以及任何可能与它们冲突的工单，都要通读全文。
• 按需读取——TODO.md、ROADMAP.md： 仅在 brainstorm、wrap 和 todo 阶段读取。
• 默认绝不读取： *_ARCHIVE.md、最新条目以外的 WORKLOG.md 内容、其他运行的文件夹、.workflow/archive/：对它们使用 grep，且仅阅读匹配的行。对于已 done 的运行，只读其 wrap.md。

与用户沟通（每个阶段）

产物是记录；聊天是回执（用户会在手机上阅读）。用户阅读的所有内容都遵循 plain 技能的规则：每个阶段写作前调用一次。Id、命令、路径和固定行格式保持原样。结束卡片上方最多约 12 行：

• 结果——说明阶段完成的工作，最多 3 行简洁文字。

• 需要决定——按编号列出，每项只涉及一个决定；每个问题都采用以下格式，每个选项占一行，绝不写成一整段：

  **1. <title>** <the question, ≤2 plain sentences>
  - ➡️ **a) <option>** — recommended: <why it wins, in the reader's terms>
  - b) <option> — <what it costs or risks, why it is the weaker pick>
  - c) <option> — <same>
  

  ➡️ 行必须放在首位并加粗，让用户不用继续阅读就能看到推荐项。每个选项都要说明理由：推荐项说明胜出的原因，其他选项说明落选的原因；“也可以”不算理由。若两个选项确实不分上下，要明确说明，并指出什么因素会决定选择。每行控制在一到两行；问题之间空一行，这样用户回复“除 2b 外都按默认选项”即可。

• 负面结果用一行说明（"PRODUCT.md — 无变更"）。

澄清关卡（除 brainstorm 以外的每个阶段）：第一次编辑前，若误解会造成高昂代价——例如范围含糊、命令与状态不匹配、涉及架构／契约／删除工作，或存在未明说的假设——先提一轮不超过 3 个问题，然后等待回复。

预算——思考不设限，文件有上限：brainstorm.md 最多约 80 行、8 项行为；plan.md 最多约 120 行、8 个工单、20 行验收标准；review.md 最多约 100 行；已完成的 wrap.md 最多约 40 行。超出预算时：提出拆分为两次运行并询问；如用户拒绝，记录为 Split declined by human: <when>。删减文字说明，绝不删减验收标准或检查项。

席位

头脑风暴搭档（烧烤环节；也包括 todo、收尾）· 默认执行者（逻辑工单、P1–P3 修复）· 重型执行者（架构/SQL/契约工单、P0 修复、最棘手的多文件工作）· 机械处理通道（有明确预期文本结果的工单）· 操作员（实时或不可逆写入、授权、托管控制台：由人工执行，或经批准后由 Agent 执行）· 严格审查者（持怀疑态度的人——计划、审查、补丁计划、realign；除 realign 外只读）。

不变量：

• 跨厂商审查。 严格审查者必须与代码编写者来自不同厂商；同厂商审查属于降级审查，并须在 review.md 中说明。一个步骤只能在一个会话中运行。
• 优先保证可用性。 在会话开始时打开模型选择器，按顺序遍历 ROUTING.md 中的回退链，并说明任何切换。
• 根据记录而非记忆说出当前运行的模型（references/phase-3-execute.md）。
• 只有在人能带来额外价值时才由人工执行（参见 ROUTING.md 中的映射）：代码由测试和跨厂商审查验证，而不是通过阅读差异来检查；面向用户的变更须由人工在提交前试用。决定席位的是通道，而非严重程度，修复工单也不例外。
• 子 Agent 只负责只读式广泛调查，其发现须经核实；写入操作在主会话中执行。

每个阶段都要从运行文件夹和 Git 重新开始，重新建立依据；模型切换发生在交接时，方法是重置（而非压缩上下文）。CLI 中 重置、上下文计量器 和 模型选择器 的确切命令见 README.md。

收尾卡片 — workflow next

每个阶段都以此卡片作为该轮的最后输出。需要等待聊天回复的轮次（UI 检查、澄清问题、计划中的工单列表环节）以 Decisions 列表结束，不附卡片。根据 ROUTING.md 中的行填写模型项（Trial 条目取代主模型，并标记为 (trial)），这样人工无需打开文件来选择模型。

---

▶ 下一步： ·

• 原因： <一句话；补丁周期则填写周期和发现 ID>
• 重置： yes | no
• 模型： · ·
• 回退： ·
• 读取： 下一阶段首先打开的文件

运行：

workflow <phase> <slug>

---

每个字段单独占一行，并使用项目符号列表，绝不要写成连在一起的一行：Markdown 会合并普通行，因此没有项目符号的行会并入段落。**运行：**标签前和代码围栏前都要空一行；无论卡片多短，命令始终放在独立的 text 围栏代码块中，以便显示复制按钮。

**读取：只列出运行文件和凭据；CLI 已加载 AGENTS.md 及相关文件。卡片输出前，根据 references/worktrees.md 从已解析的检出目录提交并推送。 先解决意外出现的 check-run.py 工作树或分支警告，或询问相关情况。 每次交接时，重置均为 yes；只有同席位工作继续时才为 no。仅由人工执行的步骤（操作员工单、升级处理）应写为 - **模型：** human · <唯一操作>，并在读取：**中注明交接对象。已完成的运行以 wrap 的 ✅ 卡片结束（references/wrap.md）。

基本规则

• 对照代码和数据进行验证。 每个阶段所依赖的接口、签名和列都要在真实代码中核对；简报中的说法在核实前都只是待验证的假设。依赖真实数据的成果，在确认其行为前要先执行只读查询。
• 来源标头——每个运行产物都以五行开头：Command:、Created:（简报或计划还要加上 · <model>）、Base:（git sha）、Inputs:（<artifact> @ <its Base> 或 none）、Status:。进入阶段时，输入必须是 Status: complete 且足够新：git diff --stat <Base>..HEAD -- <files it names> 只显示本次运行自身的工单提交。若已过时 → 指明该输入，并转到必须重新运行的阶段。
• 凭据与代码。 凭据包括 *.md、*.txt，以及一次运行的全部 screens/、prototypes/、understand/；其余文件都是代码。“自 X 以来代码有变更” = git diff --stat X..HEAD -- . ':(exclude)*.md' ':(exclude)*.txt' ':(exclude,glob).workflow/*/screens/**' ':(exclude,glob).workflow/*/prototypes/**' ':(exclude,glob).workflow/*/understand/**' 非空——即凭据规则差异。.workflow/ 之外的代码绝不读取其中的内容。
• 人工编辑。 某个脏路径未被任何运行提交触及（git diff --name-only <plan Base>..HEAD 中不包含该路径），说明这是人工修改，例如应用在保存时重写的配置文件。不要提交该文件，并在阶段报告中只提及一次；这不会阻止门禁，也不会导致工作树不干净。
• 简洁性。 以通过检查的最小差异为目标：每增加一行，审查者就多读一行，下一次运行也要多维护一行。编写辅助函数前先在仓库中搜索是否已有现成实现，并在工单报告中说明搜索结果。新的抽象必须有两个正在使用的调用方。
• 每个已验证的工单都要提交。 Wrap 会归档一次运行（Status: done）；文件夹保留。
• 每次推送前都要扫描密钥。 运行 gitleaks git --log-opts="@{u}..HEAD" --redact -v --no-banner （没有上游时：origin/<primary>..HEAD）；--redact 可避免值出现在会话记录中。 凭据通常是问题来源：包含令牌的实时查询或日志。退出码为 0 → 推送。发现问题 → 不要推送；指出文件、行号和规则，并询问：➡️ a 从未推送的提交中移除，并轮换该密钥（真实值已出现在会话中） · b 误报：将其指纹添加到 .gitleaksignore；若该模式会再次出现（ID 字段、公开令牌），则改为在 .gitleaks.toml 中添加允许列表，并扩展默认规则；重新扫描，证明该模式已消失且植入的密钥仍能被捕获。缺少扫描器 → 不要推送；询问：➡️ a 安装它 · b 未扫描就推送，并在卡片上注明。
• 运行产物只有在检查通过后才能提交。 将检查串联起来：python3 <skill>/scripts/check-run.py <slug> && git commit ...。 使用 | tail 这类管道会隐藏 check-run 的退出码；曾有一次审查引用了不存在的文件和 sha，结果被提交出去。只有在报告所依据的读取操作均已返回后，才能编写产物。

命令索引

阅读对应命令的参考文档；status 和 next 只需本文件和 ROUTING.md。

命令	references/ 中的参考文档
brainstorm <slug>、improve <feature> - goal: <goal>、park [slug]	phase-0-brainstorm.md
plan	phase-2-plan.md
execute	phase-3-execute.md（以及 tests.md）
review（含补丁周期）	phase-4-review.md
wrap	wrap.md
learn、log	learning-worklog.md
todo [idea]	todo.md
bootstrap [PRD.md]	bootstrap.md
realign	realign.md

维护此技能的说明见 MAINTAINING.md。