orchestrating

协调

作为协调者，你无需亲自构建，就能推动工作完成：阅读计划，把每项工作交给受委派者，提交返回的成果，并及时告知用户进展。让自己的上下文专注于协调，这样便能容纳整个工作，而每位受委派者都能从一个任务单开始，拥有全新的上下文。

参数

• <session-host>：Agent 会话运行的位置，例如 herdr、Claude Code Desktop、Codex Desktop。
• <notification-method>：通知用户的方式，例如桌面通知命令，或运行框架自带的工具。

工作生命周期

一个工作项（例如一项功能、一个新应用、一次重构或重新架构）从构想到合并拉取请求的流程如下。思考阶段会使用 /grilling、/prototype、/to-spec、/to-tickets 和 /handover。构建阶段会使用协调技能，其受委派者会使用 /implement、/tdd 和 /code-review。日常维护工作（例如数据编辑和小修复）则在当前检出目录中直接完成，无需使用这些技能。

一个工作项会在同一工作树、同一分支中经历五个阶段：

START      decide the worktree once; everything after follows it
THINKING   decide what to build; leave a spec, tickets, and a handoff
HANDOVER   the session commits everything and starts a fresh orchestrator
BUILD      orchestrate the tickets through delegates; open the pull request
SETTLE     the user approves; the agent merges, follows up, and cleans up

<session-host> 决定工作项要采用两种路径中的哪一种。如果 <session-host> 是 herdr，就走主机路径：/handover-to-herdr 会自动处理各阶段之间的所有步骤。否则就走通用路径，适用于任何环境：本会话继续执行，或者由用户粘贴每个启动提示词。

                START                          HANDOVER                        BUILD
Host path       init-effort                    handover                        orchestrate-with-handoff
                worktree tool;                 → handover-to-herdr:            → orchestrate-effort
                  → handover-to-herdr:           new "Orchestrator" tab,
                  "Thinking" tab,                agent started, prompted
                  agent started, prompted

Plain path      init-effort                    handover                        orchestrate-with-handoff
                worktree tool,                 runs the prompt here,           → orchestrate-effort
                or git worktree;               or prints it; the user
                thinks here, or prints         pastes it into a new
                the starting prompt            session

开始

/init-effort 为工作项命名，并创建其分支和工作树。工作树会在任何思考开始前确定，因此规范、任务单和交接文档都会写在工作项的分支上，而不是默认分支上。后续构建也会在同一工作树中进行。

对于全新项目，该技能会先创建代码库，然后像启动其他工作项一样启动项目的第一个工作项。它会把构想写入工作树中的交接文档，并据此启动思考会话。

思考

grilling     sharpen the idea, one round of questions at a time
  prototype  when a question needs a runnable answer; the user reviews it
to-spec      the thread becomes a spec
to-tickets   tracer-bullet tickets, each naming what blocks it
handover     hand over to an orchestrator

启动提示词会点名这些技能，Agent 会自行加载每项技能：用户无需输入斜杠命令。在一个连续不中断的上下文窗口中运行，让规范和任务单建立在同一套推理之上。folder-standard.md 说明了规范和任务单的存放位置。

交接

发起交接的会话会通过 /handover 妥善完成自己的工作。交接可以在任何会话的任意阶段进行，不必等到思考结束：默认分支上的桌面应用会话可以把工作项交给 <session-host> 中的协调者，同时保留自己的检出目录。该流程会让会话做好准备，用一行提示词在交接文档上启动新会话，并确认新会话已启动。完成交接的会话随后会停止运行，并保持打开状态以供查阅。

构建

/orchestrate-with-handoff 会接手交接文档并运行 /orchestrate-effort，后者会并行将各任务单分派给子 Agent。每个子 Agent 都会在自己的工作树中使用 /implement 完成对应任务单，将每项任务作为独立提交进行集成，并在完成一次分支审查后使用 /to-pr 创建拉取请求。如果项目选择启用 QA，用户可以试用的任务会保持开放，并附上试用步骤交给用户；只有当规范注明“QA: blocking”时，合并才会等待 QA 完成。

收尾

用户只需审查并批准拉取请求。之后 Agent 会合并拉取请求，并使用 /settle-effort 完成工作项的收尾，无论是交付成果的协调者，还是收到拉取请求已合并或需要合并的通知的任何会话。工作区和 Agent 会话会保持打开，供用户关闭。

为什么使用两个会话

思考会话的上下文会被讨论、走过的弯路和原型输出占满。构建者不需要这些内容：规范、任务单和交接文档已经记录了结论。从全新会话开始，可以让协调者的上下文保持空闲，以便长期处理整个工作；每项任务的受委派者则能从单个任务单出发，拥有更加清爽的上下文。

执行规范

• 委派。 将每个任务单都交给一名受托 Agent，即使任务很小。除非启动编排的技能另有说明，否则受托 Agent 是子 Agent。
• 指明位置，不要复述。 把任务单和规范的路径交给受托 Agent，不要转述其内容，因为这些文档才是事实依据。
• 信任受托 Agent。 受托 Agent 会按照任务简述规定的审查深度，完成构建、测试和自身审查。根据任务单的验收标准检查其报告，只针对报告中显示的缺失或失败之处让它返工。
• 让受托 Agent 自行审查。 要求受托 Agent 在自己的上下文中同步运行审查，因为受托 Agent 启动的子 Agent 会向你汇报，而不是向受托 Agent 汇报。
• 由你统一对接。 受托 Agent 把问题发给你，让用户只需和一个 Agent 沟通。
• 继续推进。 一个任务单在等待用户时，处理另一个不受阻的任务单。
• 不要留下仍在运行的内容。 受托 Agent 汇报后，停止它留下的所有运行项，例如开发服务器、预览、浏览器标签页或后台任务；除非其报告说明了保留的理由。在告知用户运行已完成之前，也用同样方式清理你自己留下的内容。
• 独自提交。 每次提交和推送都单独调用，绝不要与清理操作串联：权限检查只要拒绝其中一部分，就会拒绝整个调用链，结果看起来就像提交被拒绝。将受托 Agent 留下的内容移到 .scratch/，并按照 folder-standard.md 的要求存放每条记录。

与用户沟通

思考阶段收集只有用户掌握的信息，例如凭据、ID、账户、外部设置或只有用户才能执行的调用，并将交接记录下来。不得在聊天或已提交文件中放置秘密信息：用户应将其放在工作读取该信息的位置，例如环境变量、钥匙串或工具自身的登录配置中，并在交接说明中指出存放位置。

• 其余事情自行决定。 如果规范、任务单和交接记录都没有解决某个问题，就由你负责：查明事实、权衡选项、做出选择，并将决定告知受其影响的受托 Agent，避免有人再次询问。持续记录你独自做出的决定及其理由，作为拉取请求的最后一节，供用户审阅。
• 仅在关键阻塞时打断用户， 即剩余所有任务单都在等待只有用户才能提供的决定或输入时。发送阻塞通知，然后按以下格式提出一个问题，并等待：

<The question, in one sentence.>

<The facts it rests on, in a line or two: what it is, which ticket needs it
and why, why you can't get or decide it yourself.>

|                | A: <option> (my pick) | B: <option> |
|----------------|-----------------------|-------------|
| <what differs> | ...                   | ...         |

Reply "A" to go with my pick, or name another.

• 记录答案， 让后续受托 Agent 和接手的编排者能在任务单或交接记录中看到。
• 说明每项决定的事实、选项和你的选择， 可写在聊天或拉取请求中，让用户无需打开文件即可权衡。
• 使用真实数据展示。 使用 /show-me 绘制可视化报告；如果图片有助于权衡选项，也用它展示选项，例如任务树或差异形式的结果。
• 通过标题指明问题、任务单或拉取请求， 绝不要只写编号：#12 Add login，而不是 #12。

通知

用户可能会在长时间运行期间离开，通知能让他们知道何时回来。仅在以下两个时点使用 <notification-method> 发送通知：

• 完成： 拉取请求已交付，所有任务单均已提交并推送，最终审查问题已修复，且描述已撰写完成。
• 阻塞： 没有任何工作可以继续，必须等待用户，而且你即将提出唯一的问题。

常规进度（例如任务单完成或受托 Agent 汇报）留在聊天中。每条通知写成一行，不超过 200 个字符，并以用户需要采取的行动开头：

PR ready for review: Effort workflow, 19 tickets, 2 decisions to check
blocked: "Sign in with the provider" needs your OAuth app client ID

参考资料

• folder-standard.md：说明项目中各类工作记录的存放位置，以及如何移除不再需要的内容。