task-handoff

任务交接

此技能无需协调：对于其声明的工作，跳过 ai-coord 门禁。

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

将一个后续任务整理成一份完整、独立的任务交接说明，供新的 Agent 对话使用。只撰写交接说明。不要实施任务、编辑受版本控制的文件、提交、推送、启动 Codex 或更改忽略配置。

任务交接会创建一个可供全新独立会话使用、包含完整决策的一份文件。对于简单任务，这个独立文件足以让接收会话直接执行。对于复杂任务，请解析 ~/.agents/skills/orchestration，得到其展开后的绝对路径，并要求该目录中存在可读的 SKILL.md，然后在交接说明中写入该技能的绝对路径。指示接收会话从 Plan 模式加载该技能，并将交接说明作为任务规范，以便 Codex 子 Agent 实施任务。不要依赖对 $orchestration 的裸路径发现。

任务交接仍然只创建一个文件，绝不自行启动编排。工作将在之后或其他地方继续时，使用任务交接；现在要实施已批准的计划时，使用会话内交接技能。

选择工作

如果存在 $ARGUMENTS，则使用它。否则，根据上一条助手回复和相关记录推断下一个未完成的步骤。将任务视为范围选择器：仅保留该项工作所需的证据。

写作前先查明可查证的事实。在保留用户和并行 Agent 所做更改的同时，检查每个涉及仓库的说明、相关任务范围和工作树状态，并区分已完成、部分完成和剩余工作。涉及多个仓库时，在同一批次中并行执行这些读取操作。如果任务已完成，则报告证据，不要创建任何内容。只有当尚未解决的选择会实质影响范围、安全性、执行方式、验证、仓库归属或交接位置时，才提问。

根据用户要求的结果、预期证据和获准执行的操作，判定交接类别。结合任务内容进行判断，不要仅靠关键词匹配。恰好选择一个小写类别：

• implementation：更改代码、配置、文档或数据，以达到明确的最终状态。
• investigation：基于证据说明范围明确的症状、行为或故障，并给出建议的下一步行动。
• research：根据收集到的证据回答或比较选项，并提供建议或决策记录。
• audit：根据明确标准评估特定范围，并报告按优先级排序、有证据支持的发现。
• operations：执行有界的维护、发布、迁移或协调工作流，并检查状态、设定回滚边界。

如果任务包含其他类别的辅助工作，则使用主要交付成果所属的类别。

将执行方式判定为 simple 或 complex。只有当委派能显著提高速度、正确性或验证效果时，才标记为复杂，例如可独立实施的范围、依赖关系分阶段执行、涉及多个或不熟悉的子系统，或预计简报会超过约 25–30 分钟。文件和仓库数量本身不代表复杂度。其他情况标记为简单。

根据本地路径和相关上下文推断涉及的仓库。如果任务仅选择其他仓库，不要仅仅因为技能在当前仓库运行就将当前仓库纳入其中。无论任务涉及一个还是多个仓库，都只创建一个交接文件。单仓库交接文件应放在该仓库的 <REPOSITORY>/.ai/task-handoffs/<HANDOFF_NAME.md>。仅当跨仓库工作涉及至少两个仓库时，才将交接文件放在 ~/Desktop/.ai/task-handoffs/<HANDOFF_NAME.md>。跨仓库工作须列出所有涉及的仓库，并选择首先处理的仓库作为 Codex 启动目录。如果仓库集合或操作顺序不明确，则停止，不要写入。

选择一个有意义且唯一的文件名，并使其符合 ^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*[.]md$。不要强行使用 PLAN_ 前缀。如果目标文件已存在，则添加语义明确的限定词；只有在没有合适的语义限定词时，才使用 _YYYY_MM_DD_HHMMSS。

创建交接文件

在所有涉及仓库之外的新临时文件中起草语义内容，例如放在 $TMPDIR 下。一次性写入草稿。草稿不得为空，并且必须以一个 H1 标题直接开头。不要添加 YAML frontmatter，也不要以 --- 开头。绝不要添加 ## Handoff category、## Execution status 或 ## Handoff cleanup。ai-handoff create 会预留并追加这些部分。

草稿中的所有决定都必须完整，确保能让可访问指定仓库、但无法查看本记录的 Agent 据此开展工作。包括：

• 目标、成功标准和明确排除项。

• 已核实的当前状态、部分变更和已完成的前置条件。

• 按稳定路径、符号、接口、架构或命令标识的变更，而非按行号标识。

• 针对任务的证据、步骤、重要边缘情况和失败行为。

• 有针对性的验证、验收场景，以及发布、兼容性或权限要求。

• 发布前记录的精确仓库相对写入范围，使用 ai-coord draft --name <handoff-slug> '<label>' '<path>'...。对于两个或更多 Git 根目录，使用 ai-coord bundle draft --name <handoff-slug> '<label>' '<absolute-path>'...。根据交接文件名（不含扩展名）生成名称：转换为小写，将 _ 和 [A-Za-z0-9._-] 之外的字符替换为 -，并截断至 40 个字符（例如，NAMED_DRAFTS_IN_HANDOFF_SKILLS.md 会变成 named-drafts-in-handoff-skills）。

  在显式 ai-coord start '<label>' '<path>'... 后备命令（或针对相同范围并集的 ai-coord bundle start '<label>' '<absolute-path>'...）之前，提供可直接运行的提升命令 ai-coord start --draft <handoff-slug>（或 ai-coord bundle start --draft <handoff-slug>）。只有在提升报告 no draft named ... 时才使用后备命令，例如草稿在七天后过期或台账被替换。仅当交接确实无法枚举某个子树时才使用 --recursive。记录草稿只会更改协调状态，不会授予任何范围权限，并且仍属于此技能的协调豁免范围。自主发现项分流是例外：请参阅下方的非交互式分流章节。

• 通过仓库证据或用户明确决定解决的假设。

将现有用户批准及其精确范围、条件和排除项带入交接。将其与仍待批准的操作区分开来，以便接收会话可以继续执行已获授权的工作，而不必重复已解决的问题。交接本身不会授予批准，也不会覆盖接收主机的限制。

添加 ## Execution approach 部分。对于简单任务，指示接收会话执行这份独立交接，不调用会话内交接技能。对于复杂任务，在执行方法中写入 ~/.agents/skills/orchestration 的已解析绝对目录路径。复用之前的解析结果和可读的 SKILL.md 检查。只有在尚未解析过该路径或位置已更改时，才重新解析并验证。明确指示接收会话进入 Plan 模式，从该路径加载技能，并将此文件作为已完整说明决策的任务规范。不要只写 $orchestration。让 orchestration 选择最精简有效的子 Agent 团队，不要在此处规定其清单。

对于复杂任务，验证和发布时保留已解析的目录，以便用于 --before-work-skill，从而生成的 Codex 提示词也会点明该技能，并指示接收会话在开始任何任务工作前加载它。如果无法解析已安装的技能，请在编写交接前停止。

根据任务类别定制正文。实施交接需说明预期变更、数据流和兼容性。调查交接需说明问题或症状、可用证据、复现或观察方法，以及调查结果必须支持的决策。研究交接需说明问题、要收集的来源或证据、备选方案和建议标准。审计交接需说明评估范围、标准、取证方法，以及严重性或优先级模型。运维交接需说明前置条件、有序的状态转换、权限边界、可观测性，以及回滚或恢复方法。 对于跨仓库交接，请添加 ## Repository order 章节，其中包含上方的单条 bundle promote 命令，并在其后列出编号步骤。同时保留明确的 bundle 后备方案。第一项必须指出要优先处理的仓库。每一项都必须写明规范根目录、角色、确切的写入范围、前置条件或交接条件、仓库本地验证方式，以及各自可直接运行的 ai-coord start 命令。还要说明组合验收标准。

对于此类跨仓库交接，请使用字面形式的仓库相对路径，不要使用 glob。仅在搭配 --recursive 时使用目录。若精确措辞很重要，请直接引用对话记录摘录；否则，请概述相关背景，使交接内容简洁。不要留下占位符、待选择的任务选项，或任何需要查阅旧聊天记录的引用。CLI 要求每份跨仓库草稿都必须包含确切的行 ## Repository order。

若目标位置或仓库集合不确定，请先进行预验证，再投入编写正文。使用 --repo 传入所有涉及的仓库。对于跨仓库工作，请使用 --launch-repo 指定要优先处理的仓库。只有在恰好涉及一个仓库且其默认值合适时，才省略 --launch-repo：

ai-handoff create --check \
  --repo '<candidate-repository>' \
  [--repo '<additional-repository>' ...] \
  [--launch-repo '<first-repository-to-tackle>'] \
  [--before-work-skill '<resolved-orchestration-directory>'] \
  --category '<task-category>' \
  --task '<concise-task>' \
  '<HANDOFF_NAME.md>'

此命令会验证仓库根目录、可选的启动仓库、类别、文件名、目标位置和必需的忽略规则，但不会读取草稿或写入任何内容。对于复杂交接，请使用 --before-work-skill 指定已解析的绝对 orchestration 目录。对于简单交接，请省略此选项。该选项会验证目录是否为绝对路径，以及其中是否包含可读取的 SKILL.md。此命令会输出制表符分隔的 target、launch_repo 和 category 行。

正文完成后，通过一次调用发布：

ai-handoff create \
  --repo '<candidate-repository>' \
  [--repo '<additional-repository>' ...] \
  [--launch-repo '<first-repository-to-tackle>'] \
  [--before-work-skill '<resolved-orchestration-directory>'] \
  --category '<task-category>' \
  --task '<concise-task>' \
  --draft '<scratch-draft-path>' \
  '<HANDOFF_NAME.md>'

ai-handoff 会将每个仓库规范化为其物理 Git 顶层目录，并去重。可选的启动仓库必须属于涉及的仓库之一。若恰好涉及一个仓库，则默认使用该仓库。对于复杂交接，请传入验证时使用的同一个 --before-work-skill 值。此操作会追加一句最终提示，直接写明 <resolved-orchestration-directory>/SKILL.md，并要求在执行任何任务工作前先加载它。

CLI 会验证草稿，追加 YAML frontmatter 以记录 category、created、launch_repo、repos、origin 和 task，以及固定的类别、执行状态和清理约定，然后以原子方式发布到新的目标位置，不会覆盖现有内容。它会复制生成的 Codex 命令，并通过平台的剪贴板工具校验字节完全一致。错误会以 ai-handoff: 前缀写入 stderr。用法错误以代码 2 退出，操作错误以代码 1 退出。若遇到可修正的验证错误，请修正草稿或参数后重新运行同一命令：失败不会留下交接文件。不存在临时运行目录、取消命令或手动清理目标的操作。

追加的 ## Handoff cleanup 章节包含一条命令：

ai-handoff archive '<absolute-handoff-path>'

接收方 Agent 仅在完成交接后运行该命令。该命令会将文件归档到 $HOME/.local/share/task-handoffs/archive/<origin-name>/，其中 <origin-name> 是包含 .ai 的目录的基本名称。若发生命名冲突，则会添加 UTC _YYYY_MM_DD_HHMMSS 后缀。此技能本身不会归档交接文件。

对于非交互式 ai-coord 发现项分流，仅在确定性的文件名 FINDING_<UPPERCASE_ID>.md 中将发现项 ID 转为大写。在语义草稿正文中，机器可读的精确行 Source finding: <ID> 必须保留台账 ID 的原始大小写，然后在不访问剪贴板的情况下发布：

ai-handoff create --no-clipboard \
  --repo '<candidate-repository>' \
  --category '<task-category>' \
  --task '<concise-task>' \
  --draft '<scratch-draft-path>' \
  'FINDING_<UPPERCASE_ID>.md'

此模式会保留发布和结构验证，但跳过剪贴板复制和验证。自治分流工作器作为 ai-coord 委托运行，会拒绝生命周期命令，因此会跳过 ai-coord draft 和 promote 命令，并且只会记录作用于范围并集的显式 ai-coord start '<label>' '<path>'...（或 ai-coord bundle start '<label>' '<absolute-path>'...）命令。切勿覆盖现有的确定性发现交接记录：创建新记录前，先处理现有交接记录。通过交互方式而非自治分流运行时创建发现交接记录时，仅在成功发布后运行以下命令，以便账本记录从 pending 变为 handed-off。保留账本 ID 的原始拼写：

ai-coord finding handoff '<original-id>' --path '.ai/task-handoffs/FINDING_<UPPERCASE_ID>.md'

将以制表符分隔的标准输出行视为最终记录：handoff、launch_repo、category 和 command。切勿执行该命令。

报告

成功时，以 ### ✅ 任务交接已就绪 — <task> 结束。用一个代码块列出最终记录中的交接路径、规范启动仓库、类别、选定的执行方式，以及确切的 Codex 命令。不要重复交接正文，也不要提及剪贴板复制或验证。

遇到阻碍时，以 ### ⛔ 未写入任务交接记录 — <reason> 结束，并说明未创建交接文件。