orchestrate-effort

编排工作项

作为编排者，根据其规格和工单构建一个工作项，并遵循 /orchestrating。在当前检出目录中工作：工作项的工作树和分支在启动时已选定。将设计视为已定稿：如果规格、交接说明或工单中存在未明确的问题，请在该设计范围内自行决定，而不要重新设计。默认并行处理工单，并尽可能在真实应用中验证。

参数

• <worktree-tool>：用于创建和释放工作树的工具，例如 treehouse 或普通的 git worktree。
• <session-host>：运行 Agent 会话的环境，例如 herdr、Claude Code Desktop、Codex Desktop。

步骤

1. 阅读工作项。 参数指向工作项文件夹，或指向规格和工单。完整阅读规格、交接说明和每个工单，了解每个工单的阻塞项、验收标准，以及任何只能由用户提供的输入。

   • 没有参数时： 请用户提供一个。
   • 没有工单时： 告知用户并停止：工单由 /to-tickets 生成，在用户运行或要求运行的会话中进行。

2. 从干净的工作树开始。 将所有未提交的更改单独提交，并推送，以免委派者遇到自己不能修改、必须绕开的文件。

3. 使用 /show-me 展示计划，以树状结构列出：先列阻塞项，再列哪些工单并行运行、哪些需要用户提供输入，以及每个工单的审查深度。无需等待回复即可继续：该计划用于告知用户，不会向用户提问。

   • 仅将需要使用共享资源的步骤串行化，例如已安装的应用、单个真实 UI、端口或数据库；不要将整个工单串行化。文件重叠不是串行化的理由：集成时解决冲突的成本很低。
   • 为大型或高风险工单单独安排一次 /code-review。小型、低风险工单无需单独审查，因为交付时会对整个分支进行一次审查。

4. 使用 /implement 将每个无阻塞项的工单委派给子 Agent，在各自的 git 工作树中执行。每个子 Agent 创建一个提交，且不推送。任务说明应包含：

   • 工单、规格和交接说明的路径；
   • 工单的审查深度；
   • 留给你的共享资源；
   • 你要求返回的报告：提交、修改的文件、每项验收标准的证据、未遗留临时验证代码的证明、任何仍在运行的内容，以及任何未解决的问题。

   不要写入仓库已记录的操作方法和约定，包括提交规则，因为委派者会在那里阅读。让委派者在真实应用中通过实际截图和点击进行验证，而不是使用屏幕外渲染：屏幕外渲染耗时，还会错过真实屏幕检查能发现的缺陷。 在每份检查 UI 的简报中（包括最终审查和任何演练），都写明如何验证，并在你自己对真实应用进行检查时遵循：

   • **工具：**使用 Agent 自行运行的无头浏览器进行验证，例如项目自带的 Playwright 测试，或通过 npx playwright 检查真实开发服务器，并将屏幕截图保存为文件。在其中进行的真实点击算作对真实应用的检查。
   • **用户的 Chrome：**只有当用户在当前任务中提出要求时，才通过 Claude in Chrome 扩展使用它，因为这会接管用户正在使用的浏览器。测试框架会提供该扩展，因此简报中如果没有指定工具，最终就会使用它。
   • **用户的屏幕和剪贴板：**留给用户操作，并在页面内读取页面写入剪贴板的内容。这样就排除了使用 open 打开 Finder 窗口或文件、通过 System Events 脚本控制应用（这需要用户不会授予的辅助功能权限），以及使用 pbcopy 或 pbpaste。
   • **真实应用是共享资源时：**让受托者在其工作树中尽可能进行验证，并在集成时由你自己对整个批次进行一次真实应用检查。

5. 集成每批报告。

   • **耗时：**记录每位受托者花费的时间。耗时远超其他人的工单应列入拉取请求说明，让用户了解哪次运行耗费了时间。
   • **提交：**使用 --no-commit 将每位受托者的提交 cherry-pick 到工作分支，勾选报告中有证据支持的每项标准，并将其作为该工单自己的提交提交。
   • **检查：**针对整个批次运行一次测试、安装和真实应用检查，然后推送。
   • **释放：**推送后，仅通过 <worktree-tool> 的全新身份、占用状态和租约检查，释放已集成受托者的工作树；当 <worktree-tool> 为 treehouse 时，使用 /treehouse。保留被占用或状态不确定的工作树，并说明原因；保持所有 <session-host> 拓扑处于打开状态。重试失败或状态不确定的释放操作前，先检查状态。
   • **删除分支：**将集成证明绑定到受托者分支的最新提交，并在释放和删除分支之前立即重新检查；如果最新提交发生变化，则证明新的提交已落地，否则保留目标。只有在成功释放工作树后，才能删除受托者的分支。推送到工作分支的工单提交就是其工作已落地的证明：git 无法显示受托者的分支已合并，因为 cherry-pick 后连同已勾选的标准，其补丁都与受托者的提交不再匹配。
   • **报告：**用一句话告知用户有哪些内容已落地。
   • **使用本地跟踪器时：**将已勾选的复选框和状态放入工单自己的提交，并在其中注明代码状态：已完成；或工单交给用户时，注明等待用户 QA。
   • **使用托管跟踪器时：**提交推送后，以同样方式勾选问题的检查清单；所有项目都勾选后，关闭问题。交给用户进行 QA 的工单保持打开。
   • **某项标准仅在结账目录之外得到证明时，**例如在分支副本、其他环境中或安装后：不要勾选该项，并用一行说明证明的位置和确认依据。确认之前，工单保持打开。
   • **权限检查拒绝移除操作时：**将该工作树或分支留给 /settle-effort。

6. **仅在项目说明明确选择启用并说明构建版本如何交付给用户时，才将可供使用的工单交给用户进行 QA。**处理第一张工单前，先阅读 user-qa.md。合并不会等待 QA。

   • **当规范注明“QA：阻塞”时：**拉取请求需等到用户关闭每张 QA 工单后才能继续；在拉取请求中说明这一点。 重复步骤 4 到 6，直到每张工单都已提交并推送，且其标准已勾选或注明，或者由用户决定延期。

7. 交付。 将最终审核委派给子 Agent：针对整个分支相对于其基准分支运行完整检查和 /code-review。以同样的方式委派修复发现的问题，然后提交这些修复。使用 /to-pr 创建拉取请求，并在其描述中列出截至目前的决策，以及委派者报告的意外情况和跳过的检查。除了差异内容，描述是用户唯一会阅读的报告，因此你学到的任何内容若未写入其中，都会留在本次会话中。保持工作树干净：提交并推送 git status 仍显示的所有工作，或者有意将某个文件排除在外。

8. 报告拉取请求、每张工单对应的提交、任何延期事项、等待用户 QA 的工单，以及合并是否要等 QA 完成，并报告 git status 的结果：干净，或列出每个被排除的文件及原因。除 QA 外，用户唯一要做的就是审核并批准拉取请求。将收到指示后你要执行的事项列为自己的步骤：合并拉取请求，执行该工作的合并后跟进事项，例如安装或更新，尝试只能在合并后进行的事项并报告结果，然后使用 /settle-effort 收尾。

参考资料

• user-qa.md：将工单交由用户进行 QA，以及其“可以开始尝试”评论中应包含的内容。