编码 Agent 写完实现，勾选任务，然后继续下一项。SDK 仍然暴露旧行为，文档描述的默认值已经变了。另一个会话看到勾选状态，以为功能已经交付。每一步单独看都说得通，但在交接过程中，“完成”的含义丢失了。
我们的仓库工作流通过三个技能明确这些交接：/pm-brainstorm 提出工作建议，/pm 维护 Markdown 看板，/loop-worker 按里程碑执行指定队列。这个设计的价值在于三者之间的契约：谁能把想法变成执行承诺，哪些证据允许任务关闭，以及下一个会话能从磁盘上恢复什么信息。
1. 为提案、承诺和执行分别定义契约
即使三个技能都由同一个编码 Agent 执行，它们的职责也不同。这里的技能，是 Agent 读取并遵循的一组仓库指令。这些边界属于流程约定，并不构成操作系统层面的访问控制。
| 技能 | 读取什么 | 产出什么 | 边界 |
|---|---|---|---|
/pm-brainstorm | 项目约束、当前看板、已完成工作 | 包含范围、依赖和结果的文本提案 | 不写看板文件 |
/pm | 提案和权威看板规范 | 收件箱笔记、里程碑、任务和同步后的状态 | 负责看板修改 |
/loop-worker | 一个指定工作流及其任务契约 | 实现、验证、遵循 PM 规范的状态更新和交付结果 | 在选定队列内执行 |
头脑风暴首先读取 PM 规范、仓库规则和反目标文件，也就是明确哪些事情不该做的约束清单。它还会检查当前路线图和已完成的里程碑。最后这一步很关键：Agent 提出的工作可能合理，却早已交付。历史记录有助于区分缺失的能力，以及已经存在但需要修复实现或文档的能力。
提案列出具体任务、粗略估时、依赖关系、完成定义，以及为什么现在要做。结尾提供按优先级编号的摘要，以及把选中工作写入看板的准确 PM 命令。这样，一次讨论可以形成可审阅的交接材料，而不会立即扩大执行队列。
PM 技能维护唯一权威的层级结构、模板、大小规则和收尾任务规范。头脑风暴技能在运行时读取这些规则。这避免了同时维护两份“里程碑是什么”的描述，再寄希望于它们始终一致。
这里可以借用 Anthropic 对预定义工作流和自主选择工具调用的 Agent 的区分。我们的系统固定外层流程，同时为任务内部的工程判断保留空间。这是借助 Building Effective Agents 的术语，对我们工作流做出的架构解读。
反目标文件让产品判断得以持久保存。在我们的规范中，推测性的工作需要对应具体问题，公共 API 变更需要明确的用户需求，里程碑必须具有可观察的结果。Agent 重启后，可以恢复这些约束，无需重建产生这些决策的完整对话。
2. 让看板便于阅读，也足够精确以支持恢复
看板位于 .pm/ 下，采用四层结构：
| 层级 | 路径示例 | 用途 |
|---|---|---|
| 工作流 | .pm/w1/ | 通用工作队列 |
| 收件箱笔记 | .pm/w1/005.md | 一个想法，或大约一小时以内的工作 |
| 里程碑 | .pm/w1/m2/ | 需要多个任务完成的可交付结果 |
| 任务 | .pm/w1/m2/t001.md | 范围明确的实现或验证步骤 |
工作流记录调度容量和历史。上周处理 SDK 的队列，这周可以处理文档。任务放在哪里，应考虑容量、依赖和潜在的文件冲突；以前的任务分配不意味着永久所有权。
大小规则让管理成本与工作规模相称。里程碑通常应超过一小时，并包含多个任务。更小的工作保留为独立的收件箱笔记，附上一句简短的 Why:。这些估时是规划时的经验判断，并非对 Agent 速度的实测保证。
这种区分避免让一个拼写修复背上复杂的里程碑结构，也为尚不足以进入实现阶段的早期想法提供了存放位置。有一个后果需要注意：这里的工作循环只选择里程碑。因此，清空它的队列，并不代表自动执行了所有独立的收件箱笔记。
里程碑必须说明来源、与项目目标的联系、预期结果，以及为什么应该放在当前顺序中。这些字段回答不同的问题。“提高可靠性”表达的是愿望；“安装后的客户端在现有命令下正确报告取消状态”则给出了审阅者可以观察的结果。
每个任务进一步提供目标、上下文、步骤、涉及文件、验收标准和明确的范围排除项。Frontmatter 记录逻辑 ID、执行者、状态、估时和依赖。ID 必须对应它所属的工作流和里程碑；归档时，这个逻辑身份保留在 done/ 目录下。
这些上下文足以让有用的工作重新启动。新会话可以读取里程碑和未完成任务，检查指定代码，判断下一个依赖已满足的任务。它仍需要探索仓库，但“原本打算做什么”这个决定不会丢失。
Anthropic 的长时间运行 Agent 框架报告描述了类似的恢复问题：Agent 一次尝试做太多，或者过早宣布完成。其框架采用增量工作、持久化进度文件和验证机制。报告还提到，他们更偏好用 JSON 保存功能清单，因为 Agent 较少对它做出不恰当的修改。Markdown 方便我们审阅和编辑，但这种便利不会自动保证正确性。
3. 把真正完成工作所需的步骤放进里程碑
考虑一个假设需求：让一个现有超时设置在 CLI 和 TypeScript SDK 中具有一致行为。用户可见的问题是，同一个值通过不同入口传入，会产生不同结果。
一个有用的里程碑可以把完成定义为：两个入口具有一致的超时语义，取消行为正确，帮助信息与文档已更新，行为检查通过。实现任务可以先复现差异，再修复共享行为，然后更新各个集成。依赖关系可以防止后续任务假定一个尚未建立的接口已经存在。
PM 技能创建里程碑时，会追加固定的收尾任务：
- 跨入口一致性检查。 当功能开发或修复涉及公共 CLI 或 SDK 接口时，检查相关命令、参数、允许值、默认值、容器行为和文档。
- 简化。 检查修改后的代码是否可以复用、是否存在不必要的复杂度，以及效率问题，同时保持行为不变。
- 测试覆盖。 验证有意义的行为和失败模式，而不是单纯提高覆盖率数字。
- 收尾。 确认完成定义成立，同步状态，并归档已完成的工作。
如果里程碑不涉及公共接口变更，可以省略一致性检查任务，并记录原因。这样，检查清单与实际变更保持关联。纯内部重构不应衍生出无关的公共 API 检查工作。
收尾任务计入总任务数，也纳入依赖结构。执行中发现的新实现工作会插入它们之前，同时更新其依赖。否则，Agent 可能先完成检查清单，随后发现另一个改动，却没有对新增改动执行同样的检查就交付。
在超时示例中，共享辅助函数的单元测试，无法独自证明 CLI 与 SDK 行为一致。适配层可能使用不同单位，或提供不同默认值。验收应覆盖相关边界上的可观察行为：等价输入、预期的完成或取消，以及对外一致的表现。
通用的评估原则是，除了 Agent 的报告，还要检查最终状态。Anthropic 的 Agent 评估指南区分执行轨迹与实际结果，并讨论了通过多种证据进行评分。里程碑的验收标准，就是针对具体项目落实这一原则的小型机制。
收尾让结果在磁盘上可见。完成的任务文件移入里程碑内部的 done/ 文件夹。当所有工作完成，且完成定义确实满足时，整个里程碑移入工作流的 done/ 目录，对应复选框也被勾选。归档随后成为未来头脑风暴的输入，帮助避免重复提案。
4. 运行具有明确停止条件的顺序循环
/loop-worker w1 表示执行一个指定队列中待完成的里程碑。这个技能要求明确提供工作流参数，不能猜测；启动前检查分支前提和已有改动。这些检查明确了执行上下文，也有助于防止无关工作混入里程碑提交。
循环选择编号最小、尚未勾选且仍有活动目录的里程碑。它会交叉检查 README、任务文件和文件系统状态，然后读取里程碑及全部未完成任务，按依赖顺序执行，运行相关检查，并遵循 PM 规范维护状态。
收尾之后，它调用交付工作流。只有收到包含已推送提交的成功交付结果，才能选择下一个里程碑。每个里程碑都有独立的交付单元，让历史记录和回滚更容易理解。
这个循环顺序执行。它不是每隔几分钟唤醒一次的定时器，也不会默认扫描所有队列寻找感兴趣的工作。执行者可以按照规则委派独立子任务，但上层 Agent 仍然负责集成和正确性。
三种情况会停止执行：选定队列没有待完成里程碑；真正的阻塞使工作无法继续；或者中断要求保存检查点。如果里程碑需要用户决定或缺失的访问权限，执行者会说明具体缺少什么输入。它不会为了让完成数量更好看而悄悄跳过当前工作。
理解结果时，必须考虑范围。“w1 中没有待完成里程碑”没有说明独立收件箱笔记或其他队列的状态。同样，这里的交付契约止于成功推送，不会等待远程 CI 或部署。有用的最终报告应列出已交付里程碑、对应提交、相关本地验证和剩余工作，避免暗示更强的完成保证。
5. 把状态一致性和交付恢复当作工程问题
这个设计容易阅读，但包含重复状态。完成状态同时存在于任务 frontmatter、里程碑 README 和工作流复选框中，文件位置又提供了一个信号。更新这些文件是多步骤操作，可能被中断。
当前规则要求同步状态，并要求执行者标记不一致，在选择任务发生偏差时根据任务文件进行判断。这是恢复约定，不是原子事务。勾选框不能证明测试通过，目录移动也不能证明提交已经到达远程仓库。
收尾与交付之间存在一个尤其重要的中断窗口。推送失败时，里程碑可能已经归档。重启后，如果选择器只寻找待完成里程碑，就可能认为队列已空，尽管最后一个里程碑还没有推送。
对于采用这种模式的团队，我会增加一项恢复检查：选择新工作之前，对照 Git 状态和最后记录的交付结果，核对近期关闭的里程碑。这是对当前工作流的改进建议，并非现有看板文件已经确立的能力。持久保存已推送提交的记录，会让这种区别更容易检查。
第二个局限是并发。让 PM 技能负责看板修改，意味着规范有唯一负责人，但两个会话仍可能同时调用它。两者可能选择同一个下一个任务编号。独立工作流可以减少部分冲突，共享文件的修改仍需协调。当这类冲突实际出现时，串行修改入口或显式锁就有价值。
操作指令本身也需要一致性检查。在这里审阅的版本中，路线图反目标禁止对 main 执行 rebase，而交付技能要求通过 rebase 拉取更新。在自动执行走到这一步之前，必须解决这个冲突。统一看板规范可以避免一类漂移，却不能自动协调所有相邻技能。
我会用几个具体指标评估这个系统：完成后的里程碑有多常被重新打开，文件之间有多常出现状态不一致，重启后重复了多少工作，以及本地收尾后有多常缺少已确认的推送。单靠仓库指令，无法证明某个生产力提升倍数。
从一个队列和一个有意义的里程碑开始。写清楚可观察的结果，附上真正完成工作所需的任务，并验证新会话能否恢复下一步动作，以及已完成工作的证据。三个技能组成的系统，其持久价值在于：提案、承诺、验证和交付，每一步都会留下供下一个执行者检查的东西。