flock-agents

flock-agents - 自主处理待办事项

夜间无人值守，完成整批待办工单。提供你希望实现其构建工单的规格说明 （或父级问题）；它会从已配置的问题跟踪系统中获取关联工单，读取规格说明 和已完成工单以了解上下文，按依赖关系排列未完成工单，然后为每个工单运行一个 Agent—— 每个 Agent 都会在自己的 git worktree 中使用 /implement 技能，并根据工单难度 选择匹配的模型（见下方模型矩阵），同时采用高推理强度——早上为你留下所选的交付成果： 一组经过审查的分支、一个集成分支，或一个可供审查的 PR。

当你有一批格式完善、规模适合单次会话的构建工单，并希望它们在你离线时完成， 就使用此工具。这些是 /to-tickets 根据规格说明生成的 tracer-bullet 工单， 而不是 wayfinder 的决策工单。因此，对于源自 wayfinder 的工作，请将 flock 指向 /to-spec 根据地图生成的规格说明，而不是地图本身：地图的子项是 HITL 决策， 任何仍需决策的工单都应先通过讨论或原型设计会话处理，而不是在这里处理。

输入

如果用户尚未提供，请先询问以下内容：

• SOURCE — 你要实现其构建工单的规格说明或父级问题，以问题编号或 URL 表示。在使用本地 Markdown 跟踪系统时，SOURCE 则是 .scratch/<feature>/issues/ 待办文件夹。

启动时还要确认以下三项——如果用户已在调用中说明，则直接使用；否则一开始就 一次性询问（绝不要在运行中途询问，那时没人醒着）：

• MODEL POLICY — 自动（采用下方矩阵），或由用户按工单或层级指定。 默认值：自动。
• DELIVERABLE — 已完成工作的交付方式：(a) 按工单分别创建一组分支（默认）， (b) 按依赖顺序串行 cherry-pick，构建一个集成分支——这是最适合早上一次性审查的格式， 或 (c) 推送分支 + 一个 PR，将提交映射到工单。
• EXTERNAL WRITES — 明确授权哪些对外操作： 关闭已完成工单？评论 SOURCE？推送？创建 PR？默认值： 无（跟踪系统只读）。将这些答案写入每个 Agent 提示词。

如何将 SOURCE 转换为工单集合取决于跟踪系统：阅读 docs/agents/issue-tracker.md，了解此仓库如何列出某规格说明的子问题／关联 问题、读取其正文，以及公开阻塞关系。若缺少该文件，请运行 /setup-matt-pocock-skills。

步骤

1. 收集上下文。 阅读 SOURCE 规格说明／父级问题，以及与其关联的 已完成（已关闭）工单。了解既有模式和惯例，并记下已经完成的内容——这样 Agent 才能与现有工作保持一致，也不会重复处理已关闭工单。

2. 列出工作。 从跟踪系统中获取与 SOURCE 关联的未完成工单——其子项／子问题 或引用它的问题，并按 docs/agents/issue-tracker.md 中的说明筛选带有 ready-for-agent 标签的工单；如果使用本地跟踪系统，则获取待办文件夹中的未完成工单文件。 跳过已关闭、已合并或仍标记为需要决策的工单。逐一记录其验收标准和可能涉及的文件。 设置质量门槛：缺少可测试验收标准，或仍包含待定设计决策的工单，都尚未达到 Agent 处理条件；应将其留给早间报告，而不是让 Agent 在夜间自行猜测。

3. 按阶段排序。 根据依赖关系将工单分组——优先使用跟踪系统原生的阻塞关系 （只有阻塞工单关闭后，才能处理该工单），并结合文件重叠情况。同一阶段不得并行处理 共享文件或依赖其他工单输出的工单。相互独立的工单并行运行；有依赖关系的工单放在后续阶段。

4. 预先验证一个工作树。 在全新的工作树中，所有被 Git 忽略的内容都会缺失——node_modules、生成的文件、环境配置、符号链接链。启动任何任务之前：创建一个工作树，为其配置环境，并确认工单依赖的检查在其中确实能通过（至少要通过类型检查）。将结果保留为一个可重复执行的设置脚本，供每个并行任务复用。跳过这一步，是导致夜间运行失败的头号原因：每个 Agent 都会卡在同一套损坏的工具链上——更糟的是，还可能去“修复”由此产生的虚假错误。

5. 决定如何选择模型——根据 MODEL POLICY 输入（启动过程中再询问会阻碍即发即忘式启动）：

   • 自动选择（推荐）——由你这个编排者根据下方矩阵，为每张工单选择模型层级，并结合其验收标准和可能的影响范围（在第 2 步中记录）进行判断。
   • 用户指定——由用户指定模型：所有工单使用同一个模型，或按层级／工单分别指定模型。对实现 Agent 严格遵照用户指定，并跳过矩阵。

   矩阵（自动选择路径）。 按能力层级匹配，而非指定具体模型名称——这样无论使用什么运行时（Claude Code、OpenAI Codex 等）都适用；将每个层级映射到运行时所提供的最合适模型。最难的工单使用可用的最强、能力最全面的模型；随着工作变得更机械化，再切换到速度更快、成本更低的层级。如果拿不准该选两个层级中的哪一个，就选更强的那个；夜间运行失败的代价高于 token 差异。

   工单类型	模型层级	判断信号
   最难：UI/UX 工作、跨领域或架构性变更、含糊不清的规格、大量文件受影响	可用的最强、能力最全面的模型	“重新设计”、“跨范围重构”、视觉／布局验收标准，涉及共享框架或 5 个以上文件
   常规实现工单（默认）	均衡的中端模型	一个功能或修复、验收标准明确、涉及少量文件、有成熟模式可供参考
   简单任务：格式调整、重命名、配置／文档微调、机械式的单文件变更	快速／低成本模型	无需设计决策，仅凭工单文本就能预测差异

   验证 Agent 会根据验收标准检查差异——发现细微遗漏值得使用最强的判断能力，因此无论实现时使用什么模型，都应使用可用的最强、能力最全面的模型来运行验证 Agent，除非用户的规格另有要求。

6. 启动整个并行任务群，作为后台动态工作流运行，以便它能持续过夜，并在中断后恢复。首先检查之前中断的运行是否留下了未完成内容（现存的并行任务工作树／分支、尚未验证提交的工单）：接手并处理这些工作——变基、根据验收标准审查、评审、修复——而不是重新来过。为每张工单启动一个 Agent：

   • 在其独立的 Git 工作树中运行（隔离分支——互不冲突）；
   • 使用第 5 步选择的模型，并将推理力度设为 high；
   • 遵循下方的专属 Agent 指令。 按顺序运行各个阶段；同一阶段内的 Agent 并行运行。让每个分支准备步骤都可重复执行：被终止的 Agent 可能会留下有未提交更改的工作树和创建到一半的分支，而简单地在重跑时执行 checkout -b 只会失败——应暂存遗留更改，复用现有分支，并且只在安全时重置。

7. 验证每项结果。 Agent 提交后，由独立的验证 Agent 根据该工单的验收标准判断差异——采取对抗式审查，以证据为准而非轻信陈述：验证 Agent 会自行重新运行检查，而不是相信实现者的报告；确认新测试确实能锁定所需行为（如果不做这项变更，测试套件仍能通过，那这些测试就是空洞的）；并检查提交是否规范。若验证失败，将工单退回给对应 Agent 一次，并附上失败说明；如果仍然失败，就停止并标记问题。绝不让夜间运行陷入无休止的循环。

8. 按照 DELIVERABLE 落地。 分支堆栈模式：保留已验证的分支。集成分支模式：一次只安排一个合并 Agent，严格串行——按依赖顺序将每个已验证工单 cherry-pick 到集成分支；发生冲突的生成产物（声明汇总文件、API 报告、生成的客户端）必须从源代码重新生成，绝不手动合并。然后运行最终的跨工单集成检查（仓库类型检查 + 对每个受影响的包/应用执行完整检查）：每个工单单独通过，不代表合在一起也能通过。PR 模式：检查通过后，推送并创建一个 PR，其描述需将提交 → 工单 → 规范标准对应起来。所有模式下：不得强制推送，不得合并到默认分支。

9. 汇报。 编写一份用户能边喝咖啡边看的运行日志，放在工作树旁边的文件中（记录在本地跟踪器或待办文件夹中）：列出每个工单的状态（已完成 / 失败 / 需要决策）、分支或 PR、提交 SHA、验证证据，以及任何需要人工处理的事项。仅当 EXTERNAL WRITES 授权后，才评论 SOURCE 或关闭已完成的工单。其余事项留待早上审查——不要自动合并。

每个 Agent 的指示

给每个实现 Agent 的指示必须严格采用以下格式：

• 你负责一个工单：<ticket>——从跟踪器中获取并完整阅读。
• 参考（只读）规范和这些已完成工单，了解约定：<pointers>。遵循现有模式；不要重复已完成的工作。
• 仅针对这个工单调用 /implement skill：尽可能在预先约定的边界处使用 TDD，定期进行类型检查并运行单个测试文件，最后进行一次完整测试。
• 然后进行代码审查，并提交到你的工作树分支。
• 如果遇到阻塞因素或需要真正做出决策，请停止并说明原因——不要猜测。

运行前准备（无人值守安全）

• 预先允许列表中的命令必须包含 Agent 需要的 shell 命令（测试运行器、类型检查、git、包管理器和跟踪器 CLI，例如 gh，用于读取工单和发布状态）。无人值守的 Agent 会自动批准文件编辑，但遇到未列入允许列表的命令时会停住，等待人工确认。
• 明确授权外部写入（EXTERNAL WRITES 输入）。权限分类器会根据用户的请求判断意图：如果用户从未请求过无人值守的 gh issue close 或 git push，这些操作会在运行中途被拒绝，而此时没有人醒着可以批准。启动时收集授权，并原样附加到提示词中。
• 必须启用动态工作流（Max/Team/Enterprise 默认启用；Pro 用户需在 /config 的 Dynamic workflows 行中启用）。
• 非交互式运行创建的工作树不会自动清理；合并后需执行 git worktree remove。
• 扇出会增加 Token 用量并消耗速率限制（工作流上限：最多同时运行 16 个 Agent，每次运行最多 1000 个）。请根据计划合理安排批次大小。