codex-handoff

Codex 交接

Codex-handoff 会在当前会话中协调只读调查，或规划并实施所请求的工作。 Task-handoff 会为一个全新、独立的会话编写一份决策完备的文件。工作将在稍后或 其他地方继续时使用它。若要现在实施所请求的工作，请使用会话内交接技能。

如果斜杠命令或美元符号调用已在对话中提供这些说明，请直接遵循。在这种 情况下，不要再通过技能工具调用此技能。

遵循以下共享契约，准确选择一个宿主适配器，并将其用于所有特定于宿主的操作。

选择宿主

检查可调用的编排工具，而不是环境变量、进程祖先关系或用户提供的宿主名称：

• 如果 spawn_agent、wait_agent、send_message、followup_task 可用：完整阅读 references/codex-cli-host.md。
• 否则，如果 Claude Code 的 Agent 和 Bash 工具可用：完整阅读 references/claude-code-host.md。
• 两者都不可用：停止并返回兼容性错误。Codex 宿主必须支持原生 Codex 多 Agent 功能。绝不要 回退到嵌套的 Codex CLI 进程。

所有特定于宿主的操作都只能使用一个适配器。绝不要加载两个适配器，也不要混用它们的启动、进度、重试、 权限或结果传输机制。适配器可以针对宿主机制和清单配置进行专门处理，但不得弱化此共享契约。

契约

• 仅在明确调用后运行。如果任务要求的结果是发现、证据或评估，且不要求修改仓库或制定计划，则将其归类为仅研究任务。所有交接都可以在任何宿主模式下运行。实施交接必须经过规划阶段，然后启动，无需单独征求用户批准。
• 将实施请求视为对制定计划、委派任务并完成该结果的授权。如果结果和重要约束没有变化，则复用现有计划。用户的明确指令优先于技能默认设置。遵守宿主计划模式的限制，以及此技能之外施加的确认要求。仅在缺少必需输入或操作超出现有授权时提问。
• 父级负责决策、最终计划和协调。只有当任务和仓库证据表明在规划前开展调查有帮助时，才委派只读研究 Agent。
• 研究 Agent 只收集证据并报告发现。它们绝不编辑文件、做出设计决策或提供计划。
• 实施 Agent 检查、编辑并验证最终计划中分配给自己的部分。它们绝不重新设计或另行提供计划。
• 采用规模最小且有效的实施团队。可以只安排一个 Agent。仅在拆分能显著改善延迟、正确性或验证效果时才增加 Agent。实施 Agent 总数不得超过 8 个。
• 确定团队前，估算每项任务所需的实际耗时。凡预计超过约 25–30 分钟的任务，都应拆分为并行且范围互不重叠的部分，或划分为依赖阶段，而不是交给一个 Agent 一次性完成。必要时增加集成 Agent。
• 研究 Agent 最多 3 个，使用稳定 ID R1–R3，并与 8 个实施 Agent 分开计数。
• 父级自身的实施工作仅限于协调、完整性检查、故障处理和有条件的润色。
• 将用户明确指定的模型偏好（例如 GPT-6 Luna）视为对所有研究和实施 Agent 的协调约束，除非用户将其限定在更窄范围内。在该约束范围内，不得使用适配器通常选择的 Luna/Sol/Astra 替代指定模型。如果宿主无法启动指定模型，应报告不兼容情况，并在改用其他模型前征求用户同意。
• 将用户要求的结果视为授权边界，而不是初始清单或其写入范围。实施过程中若发现，为达成该结果需要修复相关的仓库内问题或更改证据，父级可以扩展交接范围。对于新发现的范围，父级可以直接启动后续 Agent，无需再次征求同意。发现此需求的工作者仍应停留在分配给自己的范围内，并返回证据。范围扩展、仓库协调和任务委派均由父级负责。
• 验证的规模应与用户要求的结果相称。除非最终计划明确要求，否则绝不添加验证机制（门禁、清单、检查点、哈希锁定、日志、回执）。用户明确要求赶快完成或收尾时，应跳过可选的重复检查和必需的润色环节。在这种情况下，提交已验证的工作，并说明跳过了哪些内容或哪些内容尚未验证。

如有 $ARGUMENTS，将其用作任务；否则使用当前用户请求。若任务指定了其他技能，则遵循配套技能。

配套技能

如果某项任务在交接要求中同时指定了另一项技能，例如： run $fresh-eyes-sweep and delegate the implementation，那么这就是一项组合任务。配套技能定义要做的工作；本交接负责委派机制。

• 在父级加载配套技能，并执行其发现、判断和规划阶段。如果能显著提速，则通过本技能的研究 Agent 进行只读发现。然后将配套技能的方法、发现结果和约束纳入交接计划。如果配套技能未出现在宿主的技能列表中，它可能已安装，只是被 disable-model-invocation: true 隐藏。断定其不存在之前，请直接从宿主技能根目录读取其 SKILL.md（Claude Code 中为 ~/.claude/skills/<name>/SKILL.md，Codex 中为 ~/.agents/skills/<name>/SKILL.md）。
• 如果配套技能的大部分工作都是发现，则父级应映射并拆分范围，而不是在行内阅读。例如，对整个代码仓库或大量文件进行审计或检查。规划完成后，每个实现 Agent 按照其任务说明中内嵌的配套技能规则，审计并修复自己负责的部分。
• 本约定优先于配套技能中与之重叠的计划审批、Agent 数量限制和稳定 ID、单一验证负责人及结果字段要求。它也优先于失败分类、提交归属和完成报告要求。即使配套技能规定了自己的子 Agent、验证或提交机制，这些覆盖规则仍然适用。如果现有指令未作出决定，配套技能中涉及用户决策的实质性关卡仍然有效。不要重复执行配套技能中常规的计划审批步骤。仅限计划的配套技能只有在组合调用要求实施且宿主允许写入时，才执行实施。
• Agent 无法加载技能。任务说明中不得仅按名称要求 Agent“使用技能 X”。应在说明中内嵌其需要的具体配套技能指令、惯例或摘录。
• 如果配套技能要求运行 $code-polish 或 $agents-brain maintain，则必须在计划阶段安排该环节。每次完成时仍只运行一次该环节。配套技能中的提交指令不会增加提交次数。
• 完成时须同时满足两项约定：除所选适配器的完成报告外，还须生成配套技能要求的报告产物（台账、表格、结论等）。

研究阶段

对于仅研究任务，启动一到三个研究 Agent，并在返回汇总后的调查结果后停止。 对于此类任务，绝不进入规划阶段或启动实现 Agent。对于实现交接，当范围不明确、任务涉及多个或不熟悉的子系统，或串行收集所需证据会显著拖慢上级时，触发研究。实现交接默认启动零个研究 Agent。上级仅根据任务和仓库证据决定研究 Agent 的数量。绝不询问用户是否愿意启动研究 Agent，也不要求用户指定 Agent。

立即启动研究阶段，或直接进入规划阶段。

触发研究时，为最多三个 Agent 分配稳定 ID R1-R3。立即通过所选适配器的只读机制启动它们。为每个 Agent 提供一份独立完整的提示词，其中包含：

• 未决问题和确切的调查范围。
• 相关的仓库约束和已知的并行工作边界。
• 严格的只读权限边界。
• 停止规则：必须返回证据，而非计划或设计。
• 时间预算，并要求其使用该预算。仅以时间为由提前返回 blocked 不符合要求。
• 确切的结果字段：status、findings、open_questions、evidence 和 blockers。

如果研究 Agent 在大部分预算尚未使用、且未指出具体障碍时仅以时间为由返回 blocked，则说明其尚未完成调查范围。如果它在证据中仍列有未检查的范围路径时返回 completed，也说明其尚未完成。出现任一情况时，通过适配器的同 Agent 机制，使用未检查的文件和剩余预算继续执行同一 Agent。此续查不算新研究 Agent。

所有必需的研究 Agent 均完成后，将其发现和证据纳入实现计划或仅研究任务的回复。只有当未决问题或阻碍会改变范围或方法时，才通过宿主的用户提问机制提出。不要整理工作树。研究 Agent 不得更改任何内容。任何报告的编辑都是违反约定。

对于仅研究任务，综合证据并以 ### 🔎 Research handoff — <completed|blocked> 结束，其中包含 Agent 数量、发现、证据、未决问题和阻碍。这将取代规划阶段和所选适配器的实现完成报告。如果调查表明需要进行更改，将其作为发现报告并停止。此时不要制定实现计划，也不要开始编辑。

规划阶段

仅在进行实施交接时进入此阶段。

如果研究结果（无论是委派进行的研究还是父级自行开展的研究）与用户明确陈述的事实（数量、具体项目、账户）相矛盾，请在编写计划前通过宿主的用户提问机制询问。在这种情况下，绝不要扩大计划的默认范围以符合研究结果。

制定一份决策完整的计划，包含此部分和所选适配器的准确清单表：

## Codex Handoff

- Research: `<none | R1..Rn — key findings used>`
- Companion skills: `<none | $x — phases the parent runs / what is folded into briefs>`
- Strategy: `<sequential|parallel|hybrid>`
- Agents: `<1-8>` — `<why this is the smallest effective count>`
- Validation owner: `<agent-id|parent>` — `<aggregate checks it runs once>`

<host-adapter manifest table>

- Code polish: `<required|not required>` — `<reason>`
- Agent-context maintenance: `<required|not required>` — `<reason>`

完成计划时，使用 ai-coord draft --name <plan-slug> '<label>' '<path>'... 记录所有清单写入范围的并集；仅对目录范围使用 --recursive。根据计划的简短标识（例如 debarrel-lib）推导 <plan-slug>：将其转换为小写，把 [A-Za-z0-9._-] 以外的字符替换为 -，并截断至 40 个字符。对于两个或更多 Git 根目录，使用 ai-coord bundle draft --name <plan-slug> '<label>' '<absolute-path>'...。在计划的“等待冲突中的 Agent”部分，写出确切的提升命令 ai-coord start --draft <plan-slug>（或 ai-coord bundle start --draft <plan-slug>），并保留针对同一范围并集的显式 ai-coord start '<label>' '<path>'... 备用命令（或 ai-coord bundle start '<label>' '<absolute-path>'...）。

新的实施会话必须直接从计划中获得这些命令，不得从散文描述中重新推导范围。只有在提升操作报告 no draft named ... 时才使用备用命令。命名草稿不授予任何权限，并在七天后过期。

根据仓库证据和请求的工作选择执行方式：

• 顺序执行：一个 Agent 依赖另一个 Agent、写入范围重叠，或后续 Agent 负责集成或总体验证。
• 并行执行：仅用于彼此独立的工作，并明确划分互不重叠的写入范围。Agent 可以检查共享上下文，但不得在分配范围之外写入。
• 混合执行：按依赖关系划分波次——在每个波次内并行运行独立的 Agent，协调完该波次的全部工作后，再启动其依赖项。

一个波次以其中最慢的 Agent 完成为准。尽量缩小最高级别 Agent 的范围，将可延后的验证交给验证负责人。如果并行工作无法共同证明整体计划，则安排后续顺序执行的 Agent 负责集成和总体验证。整个交接过程中使用稳定的 Agent ID，并明确标注依赖关系。

总体验证必须且只能分配给一个负责人。包级或仓库级检查只运行一次。存在集成 Agent 时，由其运行这些检查；否则，父级在波次后协调期间运行。其他 Agent 只运行能够证明自身修改正确的最小范围检查。例如，针对具体文件运行格式检查、lint 或类型检查，以及针对性测试。

对于非局部不变量、并发或状态机、迁移或解析、身份验证或安全、重试或错误语义，以及公共 API 或数据契约变更，必须使用 $code-polish。文件数量本身不构成触发条件。

当请求的工作会更改其维护工作流支持的目标时，必须使用 $agents-brain maintain：README.md、AGENTS.md 或 CLAUDE.md、持久上下文文档、现有项目安装的 .agents/skills 下的技能，或 skills/ 下现有的 Git 跟踪源目录技能（仅限事实性上下文的更正为纯文本修改时）。排除由托管 Agent 配置根目录管理的已安装副本。两项触发规则同时适用时，标记两项检查均为必需。两者均不适用时，均标记为非必需。

将计划作为进度更新呈现，然后直接继续协调和启动实施。不要结束本轮并等待计划批准。如果用户仅请求计划，或宿主禁止写入，则在规划后停止。

实施提示词约定

为每个实施 Agent 编写独立、以结果为先的提示词。包括：

1. 所要求的整体结果，以及该 Agent 的实施任务简介、依赖项和完成证据。
2. 其精确的写入范围、相关仓库约束、已知的脏工作边界，以及前置 Agent 的结果。
3. 根据 Plan 阶段指定的唯一验证负责人，分配其验证任务：必须运行的范围内检查；除非它负责验证，否则不得运行汇总检查。不得分配最终计划中未包含的新验证机制。
4. 符合其清单规模估算以及用户或适配器施加的任何硬性运行时间限制的进度预估。仅有软性预估不能作为停止条件。遇到阻塞时，报告部分证据以及具体阻塞原因或已用尽的硬性限制。
5. 此权限边界：检查、仅在分配范围内编辑，并在本地验证。绝不提交、推送、部署、执行外部写入或扩大范围，即使仓库或主机指令倾向于提示立即提交也是如此。协调后由父级提交。
6. 所选适配器的委派与协调上下文，包括为何父级会话和互不重叠的同级任务不构成冲突，以及什么无关的精确范围声明足以支持返回 blocked。受委派者不得运行协调生命周期命令：这些命令会以退出码 64 被拒绝。仅允许使用 ai-coord status、ai-coord touched、ai-coord inbox、ai-coord msg 和 ai-coord finding。
7. 此停止规则：严格实施最终计划。如果无法实施或需要重新设计，则提供证据并返回 blocked，而不是提出替代计划。只要仍有获授权的工作，收到进度更新后就继续。里程碑、继续执行的提议或非阻塞决策列表都不代表工作已完成。
8. 要求返回所有结果字段：status（completed 或 blocked）、summary、仅列出实际改动文件的 changed_files、列出每条命令及其结果的 verification、residual_risks 和 blockers。

在保证完整的前提下，尽量精简每个 Agent 的提示词：包含共享的结果摘要，以及该 Agent 自身的任务简介、范围和约束。不要在每个 Agent 的提示词中重复完整计划。

添加所选适配器的命令、权限、传输和主机工具约束，不要重述本约定。

执行与协调

在第 1 波实现开始前，父级将计划中指定的草案提升为完整清单写入范围的所有者。只有当提升操作报告 no draft named ... 时，才使用计划中记录的显式启动备用方案。启动 Agent 前，必须确认状态为 READY。当提升或启动操作排队或受阻时，切勿结束本轮以暂停。在这种情况下，通过适配器的等待机制运行 ai-coord wait。

它也会在非就绪唤醒事件时返回：消息、覆盖情况未知、工作释放，以及默认的 300 秒超时。每次唤醒时，都要通过 ai-coord inbox 处理 MESSAGE 事件，重新提交记录的提升或启动命令，并诊断过期阻塞项。

通过所选适配器，按计划的策略和依赖波次启动 Agent。不要仅因工作进展缓慢或没有动静，就增加 Agent，或更改模型、工作量、范围或验证负责人。如果已完成的工作发现了请求结果所需但未计划的前置条件，则应修订清单，并启动一个范围严格限定的后续 Agent。保留稳定 ID 和依赖顺序，遵守最多 8 个 Agent 的限制，并指定一名汇总验证负责人。在最终计数和报告中纳入后续 Agent。

对于每个已完成的 Agent，必须要求其提供所有共享结果字段。将 changed_files 视为其事后范围的权威记录。确认所报告的文件存在或已按预期删除、未超出范围，并附有与任务相符的验证证据。将相关的已完成结果传递给依赖 Agent。

每个实现波次结束后，都要将所有结果与当前清单和可见工作树进行协调，不要合并无关的并发更改。若父级负责验证，则在此协调期间运行一次指定的汇总检查。在阻止操作前，先归因汇总检查失败：首先排除交接所做的更改、格式化工具、钩子和生成器造成的影响，包括写入范围之外下游文件中的失败。只有证据确认失败无关，且交接本身的检查仍通过时，才可在检查失败后继续。

意外的范围外编辑、同一波次内的范围重叠，或由交接导致的失败，均属于阻塞项。遇到这些情况时，不要启动依赖项或进行润色，也不要悄悄接手实现工作。

失败分类

• 如果 status: blocked 结果指出，仓库内有一项相关修复或证据更改超出工作者范围，但为实现所请求的结果所必需，那么这属于《契约》范围扩展权限下的后续工作，无需重新授权。让已启动的独立 Agent 完成工作。阻止依赖项。以满足需求所需的最小范围扩展清单。完成该范围所需的仓库协调。

  启动新的或复用的实现 Agent。重复此流程，直到实现目标，或达到真正的授权边界。

• 只有在继续操作会改变所请求的结果、需要重大重新设计或无关工作，或越过现有确认边界（例如破坏性操作、购买、部署或外部写入）时，才向用户询问。切勿悄悄接手实现工作，也不要仅因模型更强就重新启动任务。

• 只有在适配器特定证据支持将工具或基础设施故障归为可重试时，才将其视为可重试。先检查部分编辑，然后使用适配器针对同一 Agent 的机制，恰好进行一次“验证并继续”尝试。这不算一个占用 8 个 Agent 限额的新 Agent。第二次基础设施故障会阻止该 Agent 及其依赖项。

• 切勿将普通超时、返回的阻塞项、无响应或任务级验证失败归类为基础设施故障。只有已证明相互独立的工作才可继续。

技能演进评估

将交接期间对技能进行的已验证修复，与下方的可选评估分开处理。当用户或仓库指令已授权进行修复时，由主 Agent 负责完成。子 Agent 只报告证据，不得扩大其写入范围。验证到一个实例就足够；主任务受阻也不妨碍独立修复。

完成交接所需的工作，或确认阻碍因素。然后根据适用的维护政策，在最终报告前完成独立修复。规划模式仍禁止编辑。

只有在所有必需的 Agent 均成功完成且任务已验证后，主 Agent 才能评估技能演进机会；如果交接受阻、失败或未完成，则绝不能评估。Agent 不得提出建议。只建议稳定、可复用且很可能再次出现的工作流。排除一次性事项、罕见情况、附带清理和价值尚不确定的提议。对于新技能，说明应放在仓库内还是全局的 ~/projects/agent-skills。对于修订，列出具体技能并说明原因。

提议符合此标准时，只在适配器现有的完成报告中追加一条简短建议（≤2 个短句）。保持其格式不变。然后建议下一步使用 $task-handoff。切勿自动调用 $task-handoff，也不要在本次评估期间创建或修订任何内容。若没有符合条件的提议，则保持沉默，不要添加占位内容。

完成

• 每个必需的 Agent 都完成后，对报告的 changed_files 取并集并去重，并确认组合后的验证证据能够证明计划已完成。

• 在完成报告之前，通过后续 Agent 修复所请求结果涵盖的、仍存在的同模式问题，具体遵循 Failure Classification。绝不能将这些问题列为可选事项或范围外事项。

• 如果任何必需的 Agent 失败，或者用户明确要求加快或结束，则跳过所有计划中的润色流程，并报告跳过情况。否则，仅使用该并集中的适用路径，各执行一次必需的流程：先以默认的先简化后审查模式运行 $code-polish，然后运行 $agents-brain maintain，并提供符合条件的上下文目标。若只需要一个流程，则只运行该流程。不得向任一流程提供并集之外的路径，也不得让其超出所声明的工作流权限范围。

• 将每个润色流程实际更改的范围内文件纳入最终变更文件集和验证结果。若必需的润色流程受阻、失败或在其支持范围之外写入文件，则后续润色流程和跨仓库提交均受阻。

• 如果所请求的工作更改了本机上交接开始时所在仓库以外的其他仓库，则在每个额外仓库完成工作、验证和必需的润色后，针对其中更改的文件调用 $commit。不得提交不完整、受阻、意外或范围外的更改。若请求或用户长期有效的指示授权推送，则执行推送。

• 如果交接推送了提交，且仓库定义了 CI 工作流（例如 .github/workflows），则在完成报告之前监控推送头部提交的运行情况（gh run list --commit <sha>，然后执行 gh run watch <run-id>；主机支持时在后台运行）。将交接导致的失败作为后续工作修复，并报告 CI 结果。如果更改后的代码在不同平台上的行为不同，而本地检查只覆盖了一个平台，则列出未经验证的平台并说明风险。

• 使用所选适配器的完成报告结束，其中包括策略、波次和 Agent 数量、每个 Agent 所请求的配置、状态和摘要。还需包括合并后的变更文件和验证结果。运行过润色流程时，列出每个流程及其结果。如有自动跨仓库提交，则提供提交哈希；如有 Issues and caveats，也需包含。其他适用的空值写为 none。绝不暴露机器结果载荷。

• 将问题和注意事项归类为 Resolved（有证据证实的修复）和 Open（遗留问题、限制或未经验证的假设，并说明影响和后续步骤）。省略空分组；若整个部分为空，也省略该部分。每项只报告一次。中性背景和已达成的决定放在更改或范围部分。只有阻止必需工作时才使用 blocker；只有存在具体潜在不良结果时才使用 risk。

  如果底层问题仍会影响结果，则采用变通方案后仍须将该项列为未解决。