multi-agent-handoff

多 Agent 交接

组织工作，让多个 Agent 能够依次执行而不丢失上下文。

适用场景

• 将大型任务拆分给探索、实现和审查 Agent
• 工头/工人或父级/子 Agent 模式
• 需要在聊天会话或工具之间传递书面交接信息

交接文档模板

创建或更新 HANDOFF.md（或任务 issue 中的一个章节），内容如下：

## Goal
{one sentence outcome}

## Done
- {completed items}

## Next
1. {ordered steps for the receiving agent}

## Constraints
- {tech stack, style, files not to touch}

## Verification
- {commands or checks that must pass}

## Validation status
- {commands run}
- {commands skipped or blocked, with reason}
- {blocked JSON explained with `steward blocked explain --input <path> --json`, when available}
- {schema/output drift checked with `steward schema check-outputs --json`, when machine-readable output is part of the handoff}
- {claims not proven because validation was skipped or blocked}

## Partial results
- {missing, partial, superseded, or timed-out agents/lenses}

## Context links
- {paths, PRs, prior decisions}

## Artifact capture
- {ADR, FAQ, skill, evidence note, test, validator, generator, or check that should absorb durable learning}

并行批次约定

对于范围广、可拆解的工作，父级可以使用临时批次章节，而不是创建新的计划格式。只保留足以安全推进工作的约定：

• 原始目标和用户验收检查；
• 默认原生关卡和聚合关卡；
• 对主要产物的产品影响检查，尤其当代码库属于应用、库、CLI/工具、插件或原型时；
• 绕道预算和停止条件；
• 集成能力、合并顺序和冲突处理策略；
• 各工作流输出的比较策略；
• 最终证据边界、声明上限和非声明事项；
• 包含三个字段的加速说明：Saved、Cost/duplication 和 Future hot path；
• 对重复验证或比较工作的热路径晋升检查。

派发并行工作流前，使用以下紧凑格式：

## Parallel Batch
Original goal: {user-visible outcome}
Acceptance check: {how the parent will know the original goal is satisfied}
Product impact check: {source-owned product behavior/API/UI/perf/doc-user workflow that must change or be proven unchanged}
Default native gate: {repo-native command or reason none exists}
Aggregate gate: {final validation before claiming completion}
Detour budget: {when to stop repairing tools and return to the goal}
Claim ceiling: {strongest claim allowed if all lanes pass}
Non-claims: {adjacent claims this batch cannot prove}
Acceleration note:
- Product impact line: {recognized prefix plus proof; use support_only: Steward scaffolding only when no product surface moved}
- Saved: {time, uncertainty, or risk reduced by running lanes in parallel}
- Cost/duplication: {duplicated work, integration cost, or coordination drag caused or avoided}
- Future hot path: {command, check, skill, script, deletion, or native route created for the next run}

| Lane | Agent/role | Scope | Write set | Forbidden paths | Native gate | Direct fix? | Terminal state |
|------|------------|-------|-----------|-----------------|-------------|-------------|----------------|
| L1 | {owner} | {bounded work} | `{paths}` | `{paths}` | `{command}` | yes/no | pending |

综合完成后，删除或精简此批次章节，除非它将作为审查产物。不要将工作流映射保留为项目管理状态。

父级工作流约定

父级分配的工作流约定是唯一具有写入授权的依据。顾问生态路由 dispatch_lane_candidates、MoE 发现、A2A 说明和审查者评论都仅作为输入。

每个分配的工作流都应说明：

• lane_id、指定的 Agent/角色、范围、确切的 write_set 和 forbidden_paths；
• 继承的代码库规则、必需的影响检查、权限检查、原生关卡和聚合关卡责任；
• direct_fix_allowed: true|false、声明上限、非声明事项和升级触发条件；
• 终止状态：integrated_to_owner、rejected、blocked_to_current_ledger、promoted_to_durable_owner、deleted、reported_to_parent、accepted_as_input、partial、timed_out 或 superseded。

只有父级工作流约定可以设置 direct_fix_allowed: true。直接修复必须是范围明确、风险较低的工作，具有确切的写入集、明确声明的禁止路径、继承的安全规则、必需的影响/权限检查以及可用的验证。如果跳过验证或验证受阻，结果应降级为 blocked 或 recommendation，不能标记为 integrated_to_owner。

A2A 产物绝不授权写入、扩大范围、接受/拒绝工作流，也不能掩盖维护者的判断。父级或明确的 A2Human 检查点负责授权、综合、最终声明和范围变更。

落地阶段

当某工作流在临时克隆、分支、工作树或外部检出中验证了修复后，该验证结果属于 accepted_as_input，直到代码所有者的检出中包含最小的、归属于源代码的差异，并重新运行原生关卡。默认不要将临时验证视为归属于代码库的证据。

在声称某工作流已集成之前：

1. 从临时结果或工作者结果中隔离出最小的、归属于源代码的差异。
2. 仅将该差异应用到代码所有者的检出中。
3. 在代码所有者的检出中重新运行该工作流的原生关卡。
4. 仅当声明发生变化时，更新当前记录簿或证据说明。
5. 将 source_owner_status 记录为 temp_only、owner_landed_pending_gate、owner_gate_passed 或 blocked_owner_dirty。
6. 将终止状态标记为 integrated_to_owner、blocked_to_current_ledger、accepted_as_input 或 rejected。

如果源代码检出存在未提交修改，或无法安全接收差异，应将临时验证结果记录为候选，并继续将更强的、归属于源代码的声明视为尚未证实。进行一次范围明确的落地尝试后，应将该工作流关闭为受阻或已拒绝，而不是为同一项尚未落地的结果再创建一个验证包。

工作流

1. 分解 — 尽可能将目标拆分为相互独立的部分。
2. 分配角色 — 例如，探索（只读）、实施（写入）、审查（只读评议）。
3. 编写交接内容 — 填写模板；将“下一步”限制为 ≤7 个具体步骤。并行工作时，在派发前加入精简批次表。
4. 执行一个部分 — 接收任务的 Agent 只执行“下一步”中的内容；更新“已完成”。
5. 记录证据 — 在声称完成前更新验证状态。跳过的检查和受阻的生成器都不算证据，不能默认为成功。
6. 落地源码所有者的更改 — 将临时或工作 Agent 的证据转入所有者的检出目录，并重新运行原生门禁后，再提高完成声明的力度。
7. 关闭每条工作线 — 为每条工作线或视角指定终止状态，包括超时、受阻或已被取代的工作。
8. 衡量提效情况 — 在提效说明中填写节省了什么、出现了哪些重复工作或协调成本，以及现在新增了什么未来可用的命令、检查或高频路径。如果没有节省，就如实说明，并降低声明上限。
9. 检查产品影响 — 对于产品仓库，指出源码所有者负责的产品变更或达到的产品原生门禁。如果该批次只改进了 Steward 脚手架、证据产物或工具相关的工具，只能声称改善了方向指引或测试框架维护，不能声称提升了产品效率。 使用一个产品影响前缀：runtime_behavior:、public_api:、product_native_gate:、visual_capture:、performance_metric:、release_path:、developer_workflow:、command_output:、plugin_install: 或 support_only:。 如果 Cost/duplication 不低于所节省的不确定性、风险或重复工作，则默认标记为 leave_native、rejected，或作出低置信度的支持性声明。
10. 记录可长期复用的经验 — 如果某项发现会改变未来的行为，应将其纳入 ADR、FAQ、技能、证据说明、验证器、生成器、测试或检查。
11. 再次交接 — 将更新后的 HANDOFF.md 交给下一个 Agent 或子 Agent。
12. 收尾 — 目标经验证后，删除或归档交接文件。

反模式

• 只说“继续处理 X”这类含糊指示，却不提供文件路径或验收标准
• 交接内容超过一屏（应拆分到 references/ 或议题中）
• 父 Agent 与子 Agent 之间存在重复且相互冲突的指示
• 子 Agent 重复父 Agent 的计划，而不是查找矛盾、过时假设、缺失证据或可删减的设计
• 最终交接声称已完成，但验证被跳过、受阻或仅凭手动推断
• 临时验证结果干净，却在落地更改并重新运行所有者检出目录的原生门禁前，将其当作源码所有者已采纳
• 长时间运行或失联的子 Agent 工作被悄然纳入父级总结，却没有标记为 partial、timed_out、blocked 或 superseded
• 声称并行工作提升了速度，却没有说明减少了哪些不确定性、产生了哪些重复工作，以及新增了什么未来可用的命令、检查或高频路径
• 批次结束时 Steward 门禁全部通过，却没有产品变更、产品原生门禁、截图或性能证据、API 行为变更或面向用户的工作流改进，仍声称提升了产品效率

子 Agent 提示（Codex / Cursor / Zed）

• 使用只读 Agent 进行探索和审查
• 在子 Agent 提示词中原样传递交接内容块
• 对必须仅在调用时运行的技能，优先设置 disable-model-invocation: true
• 并行工作时，确保 Agent 的工作范围不重叠，并在实施前明确写入权限归属。
• 可用的审查者角色包括 Repo Truth Verifier、Boundary Leak Reviewer、Evidence Ladder Reviewer、Doc Collapse Reviewer、Harness QA Reviewer 和 Stale External Assumption Reviewer。
• Codex 自定义 Agent 位于 .codex/agents/*.toml 或 ~/.codex/agents/*.toml；定义 name、description 和 developer_instructions，且仅在用户明确要求委派子 Agent 时才启动子 Agent。
• Cursor 自定义子 Agent 位于 .cursor/agents/*.md 或 ~/.cursor/agents/*.md；每次运行都有独立的上下文，后台执行和并行执行适用于彼此独立的部分。
• Zed 并行工作可使用单独的 Agent 线程或工作树；使用技能执行可重复的单上下文流程，使用线程处理彼此独立的并发工作。

安装

npx skills add arenukvern/skill_steward --skill multi-agent-handoff

来源

请参阅 references/sources.md。研究时请遵循 skill-source-citations。