orchestrate-herdr

编排 herdr

将工作拆分给每个单元（跟踪器子议题或 harness 提示词）对应的一个由 herdr 管理的工作标签页；如果任务涉及代码，则推动每项任务达到有测试佐证的完成状态。你是编排者：绝不亲自实现，也绝不关闭自己的标签页。

输入

运行模式——存在 SPEC_REF 时为 spec；否则按 references/harness.md 使用 harness。绝不猜测输入。

• SPEC_REF（spec 模式）——其未关闭的子议题将成为工作项的父议题：Linear PRWL-100 / ABC-123，或 GitHub 议题 URL 或编号。可从技能参数（SPEC_REF=...、裸引用；也接受旧版 SPEC_URL=/PRD_URL=）或受理信息中获取。
• WORKERS（harness 模式）——{label, prompt} 列表；按 harness 参考文档定义。
• AGENT——工作器运行时。其 CLI_NAME 启动令牌用于 PATH 检查和标签页名称；AGENT_KIND 用于 herdr --kind。两者均来自 references/intake.md，绝不能取命令的第一个令牌。
• CODING_CLI——CLI_NAME 加上用户已确定的偏好或受理选项中的权限模式标志。绝不将提示词作为启动参数（见规则）。
• ISOLATION——worktree、branch 或 shared；它决定工作器能否并行运行。
• TRACKER / TRACKER_TAG——工作区的事实跟踪器（G / L）。按 references/tracker-map.md 中的 Resolve 规则确定；该文档包含下方粗体章节名所引用的各跟踪器命令。

Factory 阶段。 在由用户启动的 herdr /factory run 中，遵循 references/factory-stage.md，而不是 Intake。

规则

• 不作任何归属标注。 从提示词、提交、跟踪器评论和报告中省略共同作者、AI 和工具归属标注。

• 绝不亲自实现。 编排者只负责读取、创建标签页、提交提示词、监控和报告，不做其他事情。

• 仅使用由 herdr 管理的标签页， 并在现有 herdr 工作区／会话中创建。不得拆分窗格、使用内部子 Agent、嵌套编码会话，也绝不能在一个 CODING_CLI 内启动另一个 CODING_CLI。

• 隔离方式由用户选择，由 herdr 执行。 保持编排者的工作目录不变。仅在选择 worktree 模式时通过 herdr worktree create 创建工作树，绝不手动操作 Git。启动前，按 Intake 验证项目自有路径；不支持的路径会阻止相应工作器启动。branch 和 shared 标签页从编排者文件夹启动，该文件夹必须是分配的仓库检出目录。

• 仅使用已保存的 ID。 每次提交、读取、监控和跟进调用都必须使用创建时保存的标签页 ID 和 Agent 名称，绝不能使用活动标签页、最新标签页、视觉顺序或猜测值。

• 将提示词粘贴并提交到已就绪的 CLI 中——绝不能将其作为启动参数／标志传入，也绝不能留作草稿或不提交；绝不能将提示词粘贴到已失效标签页的 shell 中，否则提示词文本会作为命令执行。

• 从标签页读取完成证明。 如果任务的差异涉及源代码或测试，则必须提供测试命令和引用的通过输出，无论工作器如何描述；非代码任务则必须提供提示词中指定的证明；如果提示词未指定，则提供可观察到的结果。Spec 任务还必须提供覆盖每项验收标准的 AC map:。缺少证明即视为未完成；仅有摘要只是声称完成。

• 只建议，绝不自动串联。 最终报告后，对于 AC map 中仍有条目需交由其处理的每个 PR，建议运行 /agentic-qa；对工作器的差异建议运行 /code-review；或对已发布内容建议运行 /release-notes。只提出建议，然后停止。

工作流

每次阶段转换时，都输出 Stage / Found / Next / Needs user——每个字段占一行。阶段转换包括：创建标签页、提交提示词、任一工作器状态变更、最终报告。

1. 预检

创建任何内容之前，快速失败并指出缺少的内容：

1. 已设置 HERDR_ENV=1——你位于 herdr 中。未设置 → 停止。
2. 除非上下文中已加载 herdr companion，否则按 references/herdr-commands.md 中的 Companion 加载；它随二进制文件一同提供，因此这是加载步骤，而非门槛。该文件包含下方粗体章节名所引用的 herdr 命令。
3. **模式：**存在 SPEC_REF → spec；没有 SPEC_REF → harness。当运行会使用跟踪器 API（spec 模式，或带有 issues 的 harness workers）时，按 Resolve 解析 TRACKER / TRACKER_TAG，并运行相应跟踪器的访问检查。
4. **仅限 Harness：**定义步骤后 WORKERS 为空 → 停止。

2. 构建 worker 集合

Spec — 按 Discover 列出未关闭的子 issue。创建标签页之前说明数量，并与 spec 交叉核对——worker 数量不足会漏掉工作切片。每个未关闭的子 issue 都要处理；ready-for-agent 不会作为筛选条件。每个 issue 的标识符为 <n>。未关闭的 issue 数量为零 → 在 Intake 前停止。被另一个未关闭子 issue 阻塞的子 issue不属于并行工作；按 Discover 列出相关 issue 对，并在 Intake 的问题 3 中询问。

Harness — 按 references/harness.md 定义 WORKERS。创建标签页前说明数量。

3. Intake

在 Discover 之后、且绝不能提前，提出一组批量问题——四个问题中有两个需要 issue 列表。在问题中注明受影响的 issue 和 repo。离线回退方案和完整矩阵见：references/intake.md。

1. 使用哪个编码 Agent。 按 Intake 名单，以产品名称提供全部六种运行时；括号中的标记为 AGENT_KIND。绝不能只用二进制文件名标注选项。提供 PATH 上存在启动标记的所有运行时，并说明哪些运行时不可用。
2. 使用哪种权限模式。 沿用用户已确定的权限模式；否则按 Intake 提供已验证的交互式预设或裸启动标记。所选模式将成为 CODING_CLI。
3. 如何隔离工作。 使用 worktree、branch 或 shared；当两个未关闭的子 issue 共用同一个 repo 时，建议使用 worktree。
4. 上次运行此 spec 遗留的标签页和 Agent——监控它们，还是新建并行标签页。

4. 创建 worker 标签页

按 Context 保存调用方的工作区、标签页和文件夹。每个 worker 创建一个标签页：spec → [CLI_NAME] - <TRACKER_TAG> #<n>；harness → [CLI_NAME] - <label>。ISOLATION 决定选择 Creating worktrees 还是 Create tab。按 checkout binding 保存每个 worker 的上下文、标签页/窗格 ID、Agent 名称和已验证的检出记录。未解析的 repo 或错误的原生位置会阻止启动。

5. 启动 worker

在各标签页中并行执行耗时步骤：

• 按 Start agent 启动每个 worker，将 AGENT_KIND 作为 --kind，并将 CODING_CLI 的标志放在 -- 之后。每次调用都会阻塞，直到 Agent 就绪，因此应并发调用。例外情况是共享检出目录上的 branch 隔离：这些 worker 必须逐个派发。绝不轮询或休眠等待就绪。agent_not_ready 表示 Agent 启动后直接进入了审批界面——将此情况列在 Needs user 下，绝不要重新启动；任何其他错误都属于 Monitor 下的死 CLI 情况。
• 按 Submit 提交该 issue 对应的 worker 提示词。

只有在保存了标签页 ID 和 Agent 名称、提示词已被接受且首条响应可见后，worker 才算启动。

**Spec：**填写 references/worker-prompt.md，每个 worker 对应一个 issue。**Harness：**在该 worker 的提示词后附加其页脚和检出绑定。传递适用的指令和已保存的检出记录；worker 必须在修改前验证身份和基线。适用时使用本地通道；绝不使用云端。

未使用 /tdd-loop 的编码 worker 仍须提供测试证据；在启动更新中说明这一点。

6. 监控

按照 Watch 等待生命周期状态——它会在工作器结束时立即响应，无需扫描。按照 Read 读取已结束的标签页。压缩或重启后，在任何调用前按照 Context 恢复上下文。

• 状态： blocked → 出现审批或提问界面；将其列在“需要用户处理”下，绝不重新启动或作答。idle / done → 读取标签页获取报告。working → 保持不动。
• 停滞： unknown 绝不能证明任务已完成。启动、提交或等待出错后，先检查状态和输出，再重试；超时可能发生在提交成功之后。Agent 消失 → 确认其进程已退出后，仅重新执行一次 Launch workers。仍在运行的长时间测试应继续运行；仅凭沉默不能判断为受阻。只有观察到失败或缺少人工决策时，才能报告阻塞事项。
• 标签： 跟踪器已分配的工作器遇到人工阻塞时 → 标记为 ready-for-human，并按照 Block 添加决策评论。绝不编辑议题标题（不添加 BLOCKER:、AFK: 或 HITL: 标记）。
• 完成： 按照 Read 读取每个标签页；代码任务引用通过测试的输出，非代码任务引用已分配的证据。
• 状态看板： 每次因状态变化而唤醒时，输出一行计数——N running · M completed · K blocked/needs-user——并指出状态发生变化的标签页。

7. 报告

报告模式、Agent、隔离方式、工作区／会话 ID、文件夹、标签页映射和分配任务、每项任务的最终状态、任务证据，以及 AC map / Decisions / Open items（规格模式下包含 AC map）。在 worktree/branch 模式下，列出多个分支修改的文件（git diff --name-only <base>...<branch>），作为合并风险。

完成标准

• 最终标签页映射涵盖集合中的每个工作器（包括发现的子议题或测试框架 WORKERS），包含启动失败和已退出的工作器；保存的 ID 和最终状态与回读内容一致
• 每个标签页经回读后均显示已提交的提示词和工作器的响应——没有暂存或尚未发送的内容
• 每个已启动工作器的检出内容和指令均与其提示词一致；写入任务报告基线和首次写入者身份
• 在 worktree 或 branch 模式下，每个工作器的提交都进入对应议题的分支，不进入其他分支
• 每个工作器均已完成并提供代码测试或已分配的非代码证据（规格任务还须提供 AC map），或处于受阻或出错状态
• 每个受阻且已分配跟踪器议题的工作器，都显示 ready-for-human，并在 Verify 回读中包含明确指出决策内容的评论，标题保持不变
• 记录以最终报告和 /agentic-qa / /code-review / /release-notes 建议结尾——后面没有其他内容