orchestrate-implementation

编排实现

工作树隔离模式改编自 using-git-worktrees 和 David Ondrej 的 git-worktree。测试接缝模式改编自 Matt Pocock 的 tdd、tests 和 mocking 指南（均采用 MIT 许可证）。精确的固定版本记录在 sources.json 中。

共享写入隔离、最小安全拆分和受限的子任务上下文改编自 Cursor 的 poteto-mode，对应提交为 93b00b89ef425a9c1bac0d0b317dfc49c930ac99（MIT，版权所有 (c) 2026 Cursor）。

所有权与权限

当前会话是父级。它负责范围、决策、任务路由、调查结果的处置、验收、候选版本组装和最终结论。子级负责实现或评审边界明确的任务；其报告是证据，不代表验收或发布权限。仅当当前请求或适用指令授权时才进行委派。所有子级角色均使用 Pi，包括工作者、修复者、侦察者、评审者和顾问。宿主负责管理部署位置和生命周期；Pi 内部的模型提供方并非替代性的 Agent 运行时。

采用最小安全拆分。一个边界明确的问题可由一名写入者负责；并行写入者必须各自负责独立区域，并使用单独的工作树。仅在收集上下文有明确目标时才派遣侦察者。不要仅为填满流程阶段而增加工作流、专家、评审或检查。除非父级明确授权扩展委派，否则子级不得继续委派。

模式

使用指定或配置的模式；否则使用 supervised：

• plan-only：读取输入并概述任务/简报；不修改源代码、不创建工作树，也不启动子级。
• supervised：执行实现、验证和评审，包括组装临时候选版本；在集成到目标分支前暂停。
• autonomous：只要存在安全可执行的工作，就继续推进同一循环；模式名称和候选版本组装均不赋予集成到目标分支或发布的权限。

执行请求授权准备隔离的候选版本，但不授权更改用户的目标分支。用户明确提出的限制优先于此默认规则。集成到目标分支、推送、评论或关闭问题、创建/合并 PR、部署和发布，均需获得适用授权。将获批的集成工作交给 merge-worktree；不要将任何模式视为发布许可。

1. 阅读并授权

加载 planning-contract（契约版本：1）。它是唯一负责产物分类、审批、捕获检查点和执行就绪状态的文件。如果缺少该文件，请求安装并拒绝派发写入任务。阅读提供的计划、问题和链接的已批准行为规范；保留这些内容，不要另行编造规划格式。经批准且范围明确的问题可以满足契约，无需单独的规范或计划。

对于 GitHub，使用明确的仓库获取确切的问题（例如 gh issue view <number> --repo <owner/repo> --json number,url,title,body,updatedAt），将该仓库与当前检出内容核对，并记录来源 URL／修订版本和负责人授权。相关评论仅作背景信息，不会自动改变范围或权限。如果项目在 project/agents/issue-tracker.md（旧路径为 docs/agents/issue-tracker.md）中选择 Epiq，则加载其工作流，并且只使用 epiq_* MCP 工具；不要隐式初始化看板。

如果标准相互冲突或存在尚未解决的重要决策，则停止。缺少行为规范／审批时，转交给 shape-design；缺少任务分解时，转交给 write-implementation-plan。只有当重要的来源／接口／范围变更影响到任务时，才重新检查就绪状态。绝不根据文件位置或助手编写的状态推断执行权限。

2. 选择 Pi 宿主

依次确定：明确指定的角色／泳道选择，然后是所请求／已配置的运行默认值，最后是已验证的当前宿主。在 T3 中使用其支持子 Agent 的 Pi 实例；在 Agent 范围的 Paseo 会话中使用其 Pi 提供方；在 Herdr 中使用新的 Pi 面板；其他情况则使用可用的原生 Pi 子 Agent。仅凭工具是否存在不能判断宿主。记录所选宿主及其能够执行所请求角色的证据；如有歧义，请提问。检测到或选定的宿主如果不具备所需能力，则会阻止该角色执行，但不能因此在未告知的情况下切换宿主或运行时。

派发前，只阅读所选适配器及其已安装运行时指南：

• 原生 Pi 派发：pi-subagents，仅限原生 Pi 子 Agent。
• Herdr 派发：herdr-pane，新建且可见的 Pi 会话。
• Paseo 派发：paseo，Pi 提供方和明确绑定的工作区。
• T3 派发：t3-delegate，Pi 驱动程序；目前为只读，直至支持隔离式变更放置。

分别解析每个角色的模型和思考级别字段：明确指定的运行／泳道设置 → 项目设置 → 全局设置 → 规范默认值。默认值为 worker zai/glm-5.3／high，reviewer openai-codex/gpt-6.1-sol／high。inherit 会移除该字段的覆盖值，并从全局设置或规范默认值解析，而非从父会话解析。即使项目配置对象覆盖了全局对象，也要明确传递完整的有效配置对。按 Pi 筛选配置，再匹配角色。创建 Agent 前，确认确切的模型／思考级别以及子工具依赖；不要猜测别名、遗漏思考级别、降级、安装先决条件或在未告知的情况下切换宿主。在现有运行状态中记录每项值及其来源、后端生效的配置对，以及阻塞项。

3. 准备所有权和验证

修改需要使用 Git。核实规范仓库、干净且已批准的基线，以及所选宿主的工作树支持情况。使用清单和简报记录简要的运行状态；链接现有的宿主／任务产物，而不要重复其内容。在分配写入者之前，阅读 Git 交接：固定受支持的命名基线，并在临时工作区可能消失之前保留已提交的结果。

所有新分配的工作者／修复、父级审查／重建以及候选工作树，都使用共享状态根目录 ${XDG_STATE_HOME:-$HOME/.local/state}/worktrees/。在分配主机上解析一次，并记录其绝对规范路径；状态目录不是绝对路径或主机侧路径不可用时，应阻止操作。允许分配器支持的子目录：原生 Pi 会添加仓库基名和运行标识；Paseo 会添加检出哈希和工作区标识。父级创建的检出使用经过冲突检查的源检出标识，并结合运行／泳道／角色／尝试命名，因此互不相关的仓库和同名克隆不会复用同一路径。记录实际仓库／Git 公共目录及路径映射；共享根目录并不意味着共享所有权。

分配之前，验证物理路径组件／符号链接、权限、路径冲突，以及该路径是否位于活动检出和 Pi 扩展自动发现范围之外；只创建已验证的根目录。保留已配置的分配器；根目录不兼容时，需要单独取得所有者批准后更改配置，绝不可在派发期间重新配置或重试到根目录之外。不得将现有工作树作为此策略变更的一部分迁移；保留其已记录的位置和生命周期所有权。不安全或不受支持的根目录会阻止新分配。

每个隔离且已注册的工作树只允许一名写入者。授予写入权限之前，验证每个返回的规范路径均位于共享根目录之下，且属于预期仓库／基线，并确认其所有权是独占的。提示词中的路径并不代表工作区位置。通过无写入预检确认实际子进程 cwd／仓库／分支和生效的模型／思考设置；不匹配时应阻止修改。

运行或记录最精简且有用的基线。区分预先存在的失败和任务要求；基线为红色时，必须先取得所有者决定，再开始实现。为每个连贯单元分配有针对性的验证，而非为每个检查项分别验证：

• existing-check：现有覆盖已检验所述变更行为；运行该检查，不要添加冗余测试。
• new-test：明确指出的可复现失败缺少覆盖；添加一个有针对性的测试，其预期值来自已批准的验收标准或独立判定依据，绝不可从实现输出中照搬。修复前，缺陷复现测试应当失败；影响行为的重构应在修改前固定当前行为。只有针对不同且实质性的失败模式时，才添加更多测试。
• no-new-test：文档、元数据或机械性／不影响行为的工作；使用有意义的解析、构建、冒烟或差异检查。

选择能捕获所述失败且成本最低的稳定切入点；绝不模拟被测单元，也不要为了通过而放宽断言。只有在相关代码、测试、输入和环境仍然一致时，才可复用已核实的针对性检查证据；树完全相同是充分条件，但不是唯一条件，父级也绝不可重复运行已通过的结果。重新运行必须有相关变更或具体假设作为依据。工作者仅声称通过，不构成已核实的证据。运行仓库要求的检查和受影响的验收检查，而不是所有可用命令。

向每位工作者提供精确的验证范围和预算——明确指出失败、独立判定依据、一次针对性检查或适用的复用决定，以及会使其失效的变更——并将其原样沿用到修复和恢复简报及审查者上下文中。子任务不得扩大分配给自己的验证范围；失败时只调查所述失败，不得据此运行更广泛的测试套件或放宽预期。

4. 调度并收集

根据清单和简报，为新启动的子任务提供范围明确的简报和内联角色约定。单项任务使用直接子任务；脚本仅用于有实际价值的排序、扇出或分支。只读子任务只要不修改项目状态，就可以共用稳定的检出。向审查者发送确切的差异范围和实际使用场景，而不是整段聊天记录。

优先使用宿主的异步完成通知。让独立且安全的工作继续推进；只剩子任务时就让出控制权。超时、空闲轮次、收到消息或注意信号都不代表任务已成功完成。启动替代写入者前，使用宿主的状态／控制 API 确认所有权。取消会停止执行并保留现有工作；是否清理是另一项独立决定。

使用 pi-intercom 进行 Herdr 注册、进度同步、提问，以及与明确指定的 Pi 对等方通信。Paseo/T3 Pi 会话也可以使用它，前提是两个端点都已连接工具，且可以访问同一个代理。原生子任务默认使用其主管通道。Intercom 用于消息传递，不负责工作区放置或生命周期管理，也不能证明任务已完成；远程主机不会自动获得本地路径或代理连接。

5. 验证、审查并修正

验证已提交的结果并检查其实际差异；在使用方仍需要时，保持其引用不变。释放写入者所有权后，可以直接检查仍存在的工作树。如果只能通过补丁交接，请阅读审查和恢复，并通过摘要、树状态和清洁度检查，将其重建到固定的基线上。对于已经验证并提交的结果，不要要求重建补丁。

每项结果都必须由父级检查。依赖该结果的写入者使用前，应独立审查高风险变更和契约；否则，在汇总候选结果后统一审查即可（仅涉及低风险工作的情况下，父级检查已足够，除非项目／用户规则要求独立审查）。候选结果的准备可以使用已经验证且经过父级检查、但尚未完成独立审查的工作流；独立审查通过后，才能接受这些工作流。候选结果审查应覆盖尚未审查的变更和集成影响，不要重复审查已确定的发现。

修复前先处理审查发现：用一句话驳回未通过的证据关卡；授权范围内的小幅修正；将大型或超出范围的修复交由人工处理；或者询问尚未验证的标准。使用完整的内联审查者约定。只允许一轮修复和一次差异复查；汇总候选结果时不得开启第三轮，也不得重置预算。优先在冻结的结果上创建修复提交；只审查原结果到修复之间的差异，以及受影响的行为。补丁替换恢复也遵循相同的预算。

6. 交付与清理

按依赖顺序在隔离的候选工作树中组装，并将已接受的上游候选提交作为依赖工作线的基线。保留源引用和结果引用，并记录候选基线和提交头。验证组合后的行为；如果相关代码、测试、输入和环境仍然匹配，则复用先前的证据，并记录复用了哪些证据。冲突或依赖基线变更时，应暂停并进行协调，而不是安排其他写入者或自动扩大范围。

接受之前，检查确切的最终差异和证据，逐项解决所有实质性标准，并将每个子项标记为终结或受阻，同时注明后续操作。重述已批准的任务并对照结果，然后选择 accept / fix / hand back / ask；额外想法只写一行，不要编写代码。报告跳过的检查和剩余风险。审核者的裁定不授权集成到目标中或发布。

只有在写入者释放所有权、交接已持久保存、使用者已完成且清理获得授权后，才移除自己拥有的资源。保留失败或状态不确定的工作及引用；不得强制移除、关闭可见窗格，也不得擅自归档共享工作区或顾问工作区。原生自动收尾由适配器负责，并且必须留下其文档规定的交接。受监督的交付应在经过审核的候选项及其 merge-worktree 交接处暂停，而不是在候选审核之前暂停。