orchestrate-effort

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Orchestrate Effort

编排 Effort

Build one effort from its spec and tickets, as its orchestrator, following
/orchestrating
. Work in the current checkout: the effort's worktree and branch were chosen when it started. Treat the design as settled: where the spec, the handoff or a ticket leaves a question open, decide it yourself within that design rather than redesigning. Run tickets in parallel by default, and have them verified in the real app wherever the machine allows it.
根据 spec(规格说明)和 tickets(工单)构建一个 Effort(交付任务),并充当其 orchestrator(编排者),遵循
/orchestrating
。在当前 checkout 中工作:该 Effort 的 worktree 和 branch 已在启动时选定。将设计视为已经确定:如果 spec、handoff(交接说明)或某个 ticket 留下未决问题,应在该设计的边界内自行决定,而不是重新设计。默认并行运行 tickets,并在机器条件允许时,让它们在真实 app 中接受验证。

Flow

流程

  1. Read the effort. The argument points at the effort folder or at the spec and tickets. Read the spec, the handoff and every ticket in full, for each ticket's blockers, its acceptance criteria and any input only the user can give.
    • With no argument: ask for one.
    • With no tickets: tell the user so and stop: the tickets come from
      /to-tickets
      , in a session they run or ask for.
  2. Start from a clean worktree. Commit whatever is uncommitted in its own commit and push, so no delegate finds files it may not touch and has to work around them.
  3. Show the plan with
    /show-me
    , as a tree: blockers first, which tickets run in parallel, which use an input from the user, and each ticket's review depth. Go on without waiting for a reply: the plan informs the user and asks them nothing.
    • Serialise only the step that uses a shared resource, such as an installed app, a single real UI, a port or a database, not the whole ticket. Overlapping files are no reason to serialise: conflicts are cheap to resolve at integration.
    • Give a large or risky ticket its own
      /code-review
      . A small, low-risk ticket gets none, because the one review of the whole branch at delivery covers it.
  4. Delegate each unblocked ticket to a sub-agent with
    /implement
    , in its own git worktree, where it makes one commit and doesn't push. The brief gives:
    • the paths to the ticket, the spec and the handoff;
    • the ticket's review depth;
    • the shared resources it leaves to you;
    • the report you want back: its commit, the files it changed, the evidence for each acceptance criterion, proof that no temporary verification code is left, anything left running, and any open question.
    Leave out the recipes and conventions the repository already documents, its commit rules included, since the delegate reads them there. Have the delegate verify in the real app, with real screenshots and clicks, rather than with off-screen renders: off-screen renders cost time, and have missed a bug that the first real-screen check caught.
    Write how to verify into every brief that checks a UI, the final review's and any walk-through's included, and follow it in your own real-app checks. Verify with a headless browser the agent runs itself, such as the project's own Playwright tests or
    npx playwright
    against the real dev server, saving screenshots to files: real clicks there count as the real app. Use the user's Chrome through the Claude in Chrome extension only when the user asks for it in the current task, because it takes over the browser they are working in; the harness advertises the extension, so a brief that names no tool ends up using it. Keep off the user's screen and clipboard: don't open Finder windows or files with
    open
    , don't script apps through System Events, which needs an Accessibility permission the user won't grant, and don't use
    pbcopy
    or
    pbpaste
    ; read what the page writes to the clipboard inside the page instead.
    • When the real app is a shared resource: have the delegate verify what it can in its worktree, and run the real-app check yourself once per batch at integration.
  5. Integrate each batch of reports. Note how long each delegate took; a ticket that took far longer than the others goes on your list for the pull request's description, so the user sees where a run lost time. Cherry-pick each delegate's commit onto the effort branch with
    --no-commit
    , tick each criterion the report shows evidence for, and commit it as the ticket's own commit. Then run the tests, the install and the real-app check once for the whole batch, and push. After the push, release an integrated delegate's worktree only through the configured worktree tool's fresh identity, occupancy and lease checks; use
    /treehouse
    when that is the tool. Keep occupied or uncertain worktrees and report why, leaving all session-host topology open. Bind the integration proof to the delegate branch tip, and recheck it immediately before release and branch deletion; if the tip changed, prove the new tip landed or preserve the target. Delete the delegate's branch only after its worktree release succeeds: the ticket's commit on the pushed effort branch is the proof its work landed, and git can't show the delegate's branch as merged, because the cherry-pick, with its ticked criteria, no longer matches the delegate's commit by patch. Inspect state before retrying a failed or uncertain release. Tell the user in a line what landed.
    • On a local tracker: the ticked boxes and the status go in the ticket's own commit, with its code: done, or waiting for the user's QA when the ticket goes to them.
    • On a hosted tracker: tick the issue's checklist the same way once the commit is pushed, and close the issue once every box is ticked. A ticket that goes to the user for QA stays open.
    • When a criterion is shown only outside the checkout, such as on a copy of the branch, in another environment or after an install: leave it unticked with a one-line note saying where it was shown and what confirms it. The ticket stays open until it is confirmed.
    • When a permission check refuses a removal: leave that worktree or branch for
      /settle-effort
      .
  6. Hand usable tickets to the user for QA, only in a project whose instructions opt in to it and say how a build reaches the user. Read
    user-qa.md
    before the first one. The merge doesn't wait for QA.
    • When the spec says "QA: blocking": the pull request waits until the user closes each QA ticket; say so in the pull request.
    Repeat steps 4 to 6 until every ticket is committed and pushed, with its criteria ticked or noted, or deferred by the user.
  7. Deliver. Delegate the final review to a sub-agent: the full checks and
    /code-review
    over the whole branch against its base. Delegate the fixes for what it finds the same way, then commit them. Open the pull request with
    /to-pr
    , and put in its description your running list of decisions and the surprises and skipped checks delegates reported. Besides the diff, the description is the only report the user reads, so whatever you learned and leave out of it stays behind in this session. Leave the worktree clean: commit and push any effort work
    git status
    still shows, or leave a file out on purpose.
  8. Report the pull request, each ticket's commit, anything deferred, the tickets waiting for the user's QA and whether the merge waits for them, and the
    git status
    result: clean, or each file left out with its reason. Besides any QA, the user's only step is to review and approve the pull request. List what you will do once told, as your own steps: merge the pull request, run the effort's post-merge follow-ups such as installs or updates, try what can only be tried after the merge and report the result, and settle the effort with
    /settle-effort
    .
  1. 阅读 Effort。 参数指向 Effort 文件夹,或指向 spec 和 tickets。完整阅读 spec、handoff 和每个 ticket,查明各 ticket 的 blockers、acceptance criteria,以及任何只有用户才能提供的 input。
    • **没有参数:**要求用户提供参数。
    • **没有 tickets:**告知用户并停止;tickets 来自
      /to-tickets
      ,应在用户运行或请求该命令的 session 中生成。
  2. 从干净的 worktree 开始。 将所有尚未 commit 的内容放入一个单独的 commit 并 push,避免任何 delegate 发现其不应触碰、因而不得不绕开的文件。
  3. 展示计划。 使用
    /show-me
    以树状形式展示计划:先列出 blockers、哪些 tickets 会并行运行、哪些需要用户的 input,以及每个 ticket 的 review depth。展示后继续执行,无需等待回复:该计划用于告知用户,不会向用户提出任何问题。
    • 仅将使用共享资源的步骤串行化,例如已安装的 app、单一的真实 UI、端口或数据库,而不要串行化整个 ticket。文件重叠不是串行化的理由:集成时解决冲突的成本很低。
    • 为大型或高风险 ticket 单独安排一次
      /code-review
      。小型、低风险 ticket 不需要,因为交付时对整个 branch 的一次 review 已覆盖它。
  4. 委派每个无阻塞的 ticket。 使用
    /implement
    将每个无阻塞的 ticket 委派给一个 sub-agent,让它在自己的 git worktree 中完成工作:生成一个 commit,并且不 push。任务简报应包含:
    • ticket、spec 和 handoff 的路径;
    • ticket 的 review depth;
    • 它留给你处理的共享资源;
    • 希望返回的报告:该 ticket 的 commit、修改过的文件、每项 acceptance criterion 的证据、没有遗留临时验证代码的证明、仍在运行的任何内容,以及任何未决问题。
    任务简报中不要重复仓库已经记录的配方(recipes)、约定(conventions)和 commit 规则;delegate 会在仓库中自行阅读这些内容。让 delegate 在真实 app 中通过真实截图和点击进行验证,而不是使用 off-screen render:off-screen render 会耗费时间,而且曾漏掉首个真实屏幕检查发现的 bug。
    对每个包含 UI 检查的任务简报,都要写明验证方法,最终 review 和任何 walk-through 也包括在内,并在自己的真实 app 检查中遵循它。使用 Agent 自行运行的 headless browser 进行验证,例如项目自己的 Playwright tests,或针对真实 dev server 运行
    npx playwright
    ,并将截图保存为文件:在那里进行的真实点击也算真实 app 验证。只有当用户在当前任务中提出要求时,才通过 Claude in Chrome extension 使用用户的 Chrome,因为它会接管用户正在使用的浏览器;由于 harness 中已提供该 extension,未指定工具的简报最终会使用它。不要占用用户的屏幕和 clipboard:不要用
    open
    打开 Finder 窗口或文件;不要通过 System Events 脚本控制 app,因为这需要用户不会授予的 Accessibility 权限;也不要使用
    pbcopy
    或
    pbpaste
    ;应在页面内部读取页面写入 clipboard 的内容。
    • **当真实 app 是共享资源时:**让 delegate 在自己的 worktree 中验证其能够验证的部分,并在集成时由你针对整批工作执行一次真实 app 检查。
  5. 集成每批报告。 记录每个 delegate 用了多长时间;如果某个 ticket 的耗时远超其他项,就将其加入你为 Pull Request 描述维护的清单,让用户看出这次运行的时间损耗发生在哪里。使用
    --no-commit
    将每个 delegate 的 commit cherry-pick 到 Effort branch,勾选报告中已有证据支持的每项 criterion,并将结果作为该 ticket 自己的 commit 提交。随后针对整批工作运行一次 tests、install 和真实 app 检查,然后 push。Push 后,只有通过已配置 worktree 工具执行最新的 identity、occupancy 和 lease 检查,才能 release 已集成的 delegate worktree;如果所配置的 worktree 工具是
    /treehouse
    ,则使用
    /treehouse
    。保留仍被占用或状态不确定的 worktree,并说明原因,同时不锁定任何 session-host 拓扑。将集成证明绑定到 delegate branch tip,并在 release 和 branch 删除前立即重新检查;如果 tip 已变化,则证明新 tip 已落地,或保留目标。只有在 worktree release 成功后才删除 delegate branch:已 push 的 Effort branch 上的 ticket commit 才是其工作已落地的证明;而 git 无法将 delegate branch 显示为已合并,因为带有已勾选 criteria 的 cherry-pick 不再按 patch 与 delegate 的 commit 匹配。失败或状态不确定的 release 在重试前,先检查状态。用一行告知用户哪些内容已落地。
    • **在 local tracker 上:**勾选项和 status 应随代码一起放入 ticket 自己的 commit:标记为
      done
      ,或者当 ticket 转交给用户时标记为
      waiting for user QA
      。
    • **在 hosted tracker 上:**commit 被 push 后,以同样方式勾选 issue 的 checklist;所有勾选项都勾选后,close issue。转交给用户进行 QA 的 ticket 保持 open。
    • **当某项 criterion 仅在 checkout 之外展示时,**例如在 branch 的副本、其他环境中或 install 之后:保持未勾选,并用一行注明它在哪里展示、由什么内容确认。该 ticket 保持 open,直到得到确认。
    • **当权限检查拒绝移除时:**将该 worktree 或 branch 留给
      /settle-effort
      处理。
  6. **将可交付的 tickets 交给用户进行 QA,**但仅在项目 instructions 选择启用该流程并说明构建成果如何交付给用户时。首次交接前阅读
    user-qa.md
    。合并不会等待 QA。
    • **当 spec 写明
      QA: blocking
      时:**Pull Request 等待用户关闭每个 QA ticket;在 Pull Request 中说明这一点。
    重复步骤 4 至 6,直到每个 ticket 都已 commit 并 push,其 criteria 已勾选或附注,或者由用户明确延期。
  7. 交付。 将最终 review 委派给一个 sub-agent:针对整个 branch 相对其 base 执行完整 checks 和
    /code-review
    。以同样方式委派对 review 所发现问题的修复,然后 commit。使用
    /to-pr
    创建 Pull Request,并在描述中放入你持续维护的决策清单、delegate 报告的意外情况和跳过的 checks。除 diff 外,描述是用户唯一会阅读的报告,因此任何已经了解但没有写入其中的内容都会留在本次 session 中。保持 worktree 干净:对于
    git status
    仍显示的 Effort 工作,将其 commit 并 push;或者明确有意留下某个文件。
  8. 报告。 报告 Pull Request、每个 ticket 的 commit、所有延期事项、等待用户 QA 的 tickets,以及合并是否等待这些 tickets;还要报告
    git status
    的结果:干净,或列出每个有意留下的文件及其原因。除 QA 外,用户唯一需要做的步骤是 review 并批准 Pull Request。列出收到指示后将执行的事项,并将其作为你自己的步骤:合并 Pull Request、运行 Effort 在 merge 后的后续操作(如安装或更新)、尝试只能在 merge 后执行的内容并报告结果,以及使用
    /settle-effort
    收尾该 Effort。

References

参考资料

  • user-qa.md: handing a ticket to the user for QA, and what its "Ready for you to try" comment holds.
  • user-qa.md:将 ticket 交给用户进行 QA,以及其“Ready for you to try”评论所包含的内容。