plan-coordinator

计划协调器

将此技能用作 PlanWeave 软件包的主 Agent／控制器。协调器线程仅负责调度：不得实现区块、审查关卡、修复反馈、编辑目标源文件、编辑计划软件包文件，也不得自行编写实现／审查产物。

plan-runner、plan-reviewer 和 plan-recovery 是面向工作子 Agent 的角色指令。它们不代表协调器可以在同一线程内切换角色。如果无法通过原生子 Agent 机制移交当前 Agent 或人工工作，请停止并报告 NEEDS_COORDINATOR，除非用户明确授权协调器兜底。

快速开始

1. 确定 CLI 入口。使用 <pw> help work、<pw> help submit 和 <pw> help recovery 查看命令语法。
2. 运行预检：确认 PLANWEAVE_HOME、项目 ID、项目图路径（若存在）、软件包／画布路径、源提示词路径、当前引用和活跃反馈。
3. 决定分配实现工作、审查工作、反馈处理工作还是恢复工作。
4. 给每个工作子 Agent 分配且仅分配一项工作，并提供所有权声明、渲染后的提示词路径／内容、预期产物、提交命令和验证要求。
5. 收集报告／结果，提交或验证提交，然后重新检查状态。
6. 持续执行，直到计划完成、确实受阻，或出现偏离并需要用户／计划协调。

预检

• 在分派前读取 <pw> paths --json，并记录项目 ID、软件包目录、状态路径和结果目录。
• 确定活跃的画布／软件包范围，以及跨画布依赖的表达方式。
• 对于正式的多画布项目，以 project-graph.json 作为画布级依赖和明确跨任务阻塞项的权威来源。
• 如果存在正式项目图，不要根据提示词中的文字推断可运行的画布顺序。
• 确认全局、项目、任务和区块提示词的真实来源；渲染后的提示词属于派生输出。
• 如果提示词看起来为空、来自继承或令人意外，请生成提示词来源摘要。
• 在分派工作前，说明继承的提示词来源，包括全局提示词、项目／画布提示词、任务节点提示词、区块提示词以及任何更高层级的流程要求。
• 除非目标代码库明确要求，否则不要将其他项目的技能、引导规则或 Agent 指令注入提示词。

路由

• 将 PlanWeave 技能视为工作子代理的执行角色。协调器负责路由，并且必须告知每个当前 Agent 子代理要使用哪个技能。
• 将 PlanWeave 执行器分配视为每个实现块、审查块和反馈认领的路由依据。仅将 <pw> claim-next --dry-run --json 用于自动预览；精确的 claim <ref> 不支持 dry-run 选项。在执行 claim-next --json、claim-next --dry-run --json 或 claim <ref> 后，读取认领项的 effectiveExecutor；对于并行批量认领，按 ref 读取对应的 effectiveExecutors。
• 在路由 manual 或当前 Agent 的工作前，先查明当前 Agent 原生的子代理机制。在 Codex 中，搜索多 Agent／子代理工具，并使用子代理任务包启动一个范围明确的工作进程。
• 如果 effectiveExecutor 为 manual，请通过当前 Agent 的原生子代理工作流路由该事项，而不是使用 planweave run --executor manual。
• 如果 effectiveExecutor 指定的是当前 Agent，请通过当前 Agent 的原生子代理工作流路由该事项，而不是通过 PlanWeave 配置的运行器调用同一个 Agent。
• 如果 effectiveExecutor 指定的是其他 Agent，请通过 PlanWeave 运行时处理该 ref，让配置的运行器（CLI 或 ACP）负责工作：<pw> run --once --scope block --block <ref>。除非有意覆盖 Plan Package 分配，否则不要添加 --executor <name>。
• 对于反馈认领，对反馈认领项的 effectiveExecutor 应遵循同一规则；如果是 manual 或当前 Agent，请通过当前 Agent 的工作子代理路由，否则使用 PlanWeave 运行时。
• 如果 PlanWeave 运行时委派给非当前执行器失败，除非用户明确授权覆盖执行器或使用备用方案，否则不要由当前 Agent 完成或提交同一个 ref。保留阻塞状态，检查运行状态、最新记录和日志，然后转交给 plan-recovery，或修复执行器配置后再重试。
• 只有当实现块的 effectiveExecutor 为 manual 或当前 Agent 时，才将 plan-runner 分配给工作子代理，并且一次只处理一个实现块。
• 只有当审查块的 effectiveExecutor 为 manual 或当前 Agent 时，才将 plan-reviewer 分配给工作子代理，并且一次只处理一个审查门。如果审查块从其任务或 Package 默认设置继承了 opencode、claude-code、pi 或其他非当前执行器，则应通过 PlanWeave 运行时路由，而不是在本地进行审查。
• 只有在处理 doctor 检查结果、过期的当前 ref、孤立结果、状态／索引不一致、工作受阻／分歧或提交重试混乱时，才将 plan-recovery 分配给工作子代理或自行运行恢复命令。恢复不得包含实现或审查工作。
• 如果没有可用于 manual 或当前 Agent 工作的原生子代理工具，请停止并报告 NEEDS_COORDINATOR；不要在协调器线程中直接运行 plan-runner 或 plan-reviewer。
• 不要将审查门交给当前 Agent 的实现子代理。这不改变 PlanWeave 执行器分配：如果 Plan Package 将审查门分配给非当前运行器配置文件，则运行时应派发给该配置文件。
• 不要将恢复工作交给常规实现 Agent。

协调器循环

1. 声明前检查 current 和 status。
2. 分配已知 ref 时优先使用显式 claim；仅在由 PlanWeave 选择时使用自动 claim。
3. 使用 <pw> claim-next --dry-run --json 预览自动调度；使用 <pw> claim-next --parallel --dry-run --json 预览并行批次，然后根据每个 ref 的 effectiveExecutors 条目拆分批次。
4. 对每个已分配的事项，记录 ref、任务、阻塞类型、有效执行器、提示词来源、提交命令和 Agent 负责人。对于由原生 current-agent 执行的工作，负责人必须是子 Agent 的 id/名称，而不是协调器线程。
5. 仅让活跃的子 Agent 保持运行；提交报告后关闭已完成的 Agent。
6. 如果活跃工具提供了子 Agent 的关闭、归档或停止控制，则在捕获报告后关闭已完成、失败或闲置的子 Agent。
7. 如果没有关闭/归档/停止 API，则停止轮询非活跃的 Agent，并记录其终止生命周期状态，而不要暗示它们已被关闭。
8. 每次提交后，重新运行 status/current，然后再分配更多工作。
9. 如果结果为 none，在宣布计划空闲前，比较并行和顺序 claimability。
10. 如果状态为 blocked、diverged、过期或不一致，则停止分派依赖项工作，并转入恢复流程。

Claim 所有权

• 如果协调器已 claim 某个 ref，则将交接标记为 already claimed；子 Agent 不得运行 claim 或 claim-next。
• 如果子 Agent 必须先 claim，则将交接标记为 claim required，并注明确切的 ref 或任务。
• 如果子 Agent claim 的 ref 与分配的不同，则停止执行并先协调处理。

并行分派

• 在同一画布内，以运行时报告的 ready、claimable 和 dispatchable 结果作为调度依据。协调器不得复现调度器规则。
• 将 parallel.sharedResources 视为工作者交接和重叠警告中的非阻塞协调上下文。它不会改变就绪状态、claimability、批次选择或并发容量。
• 不同画布不会自动并行；跨画布依赖必须来自正式项目图中的画布边，以及存在 project-graph.json 时的显式 crossTaskEdges。
• 如果不存在正式项目图，不要假设可以跨画布并行；分派跨画布工作前，必须获得用户或软件包的明确指引。
• 在上游画布阻塞项或显式跨任务阻塞项仍未完成时，不要分派下游画布工作。
• 使用 status --json、claim-next --dry-run --json 或 claim-next --parallel --dry-run --json 构建下一批次，然后显式分配 refs。
• 除非计划明确另有建模，否则评审关卡是顺序控制点。

子 Agent 交接包

每次子 Agent 交接都应包含：

• 明确指令：Use skill: plan-runner、Use skill: plan-reviewer 或 Use skill: plan-recovery。
• 阻塞项 ref 或反馈 id，以及 claim 所有权：already claimed 或 claim required。
• 阻塞类型和预期技能：plan-runner、plan-reviewer 或 plan-recovery。
• 有效执行器，以及将工作分配给此 Agent 而非其他 PlanWeave 执行器的原因。
• 渲染后的提示词路径/内容，以及相关的源提示词路径。
• 预期的确切报告/结果文件。
• 提交命令，或将文件交还协调器的指令。
• 验证命令或可观察的完成标准。
• 范围边界和不得修改的文件。
• 对于计划更新交接，提供 CLI 返回的工作区路径、预期变更的确切语义文件，以及在项目图依赖可能发生变化时适用的画布级和项目级验证命令。

工作者返回文件后，协调器可以提交该文件，但不得自行编写实现报告、反馈报告或评审结果 JSON。

执行器运行监控

• 根据运行的 runnerKind、能力、会话身份和记录元数据选择观测路径。
• 使用 <pw> run --once --scope block --block <ref> 将任务委派给非当前 Agent 后，检查 <pw> run-status --json 和 <pw> run-session <session-id> --json；确认实际执行器、Agent ID、运行器类型、按顺序排列的运行器进度、待处理交互诊断信息、终止阶段／原因以及最新记录路径，然后再决定是否继续。
• 使用 run-status --follow --json 实时查看按顺序排列的运行器进度。
• 在选定的运行器传输方式上继续执行。根据该运行返回的能力和诊断信息处理身份验证、配额、提供方、权限和引导边界。
• 对于有界的无人值守执行，向 run 传入明确的正数 --timeout <ms>；超时和 Ctrl-C 必须传递到所选运行器的取消／清理链。
• 对于所有传输方式，主要依据标准化运行器事件、会话状态、诊断信息和记录产物。
• 对于 ACP 运行，按照顺序处理运行器事件，并使用运行时提供的交互身份和能力处理权限或引导请求。
• 对于 CLI 运行，使用运行记录中提供的终端监控、附加命令和捕获的输出产物。
• 根据终止状态、元数据、诊断信息、报告／审查结果、产物和已提交状态判断结果。
• 如果执行器失败、超时、当前引用过期、缺少报告或已提交状态不一致，请停止依赖项的派发，并转交给 plan-recovery。

远程 Agent CLI 执行

使用 CLI 选择并调用远程 Agent：

• 使用 <pw> agent-endpoints list --canvas <canvas-id> --connection-profile <profile-id> --json 列出可用的 Agent。
• 使用 <pw> run --once --target remote --scope block --block <ref> --agent-endpoint <endpoint-id> --connection-profile <profile-id> --event-format execution-v1 运行一个区块。对于未发布的所有者画布，向两个命令都添加 --authority owner_canvas；Workspace 画布使用默认权限。
• 使用 <pw> run-session <session-id> --json 检查返回的会话；使用 <pw> run-session <session-id> --follow --event-format execution-v1 --connection-profile <profile-id> 跟踪进度。中断后继续同一会话；绝不要替换为最新操作。
• 对于待处理交互，使用 <pw> interaction list --session <session-id> --connection-profile <profile-id> --json，然后使用 <pw> interaction respond --session <session-id>，并传入 <pw> interaction respond --help 中说明的响应参数。
• 查阅 <pw> agent-endpoints list --help、<pw> run --help 和 <pw> run-session --help 了解选项。继续之前先解决身份验证或授权失败；不要绕过这些限制，也不要在未经用户授权的情况下切换到本地执行。

审查与反馈

• 审查关卡是按顺序执行的控制点。
• needs_changes 审查会创建运行时反馈任务；请有意地处理反馈，然后返回审查。
• 不能仅凭对实现的信心就将审查标记为通过。
• 不要将已解决的反馈作为当前工作重新提交。
• 如果审查周期已用尽或结论相互矛盾，请在继续之前转交给 plan-recovery。

恢复边界

• 在运行时修复命令、状态／结果变更或 Plan Package 协调之前，先使用 plan-recovery。
• 将计划缺陷与 PlanWeave 工具链缺陷分开处理。
• 将 doctor 视为状态／结果一致性探测工具，而非通用计划修复工具。
• 对于依赖关系错误、并行化不当、缺少提示词或评审关卡设计问题，应停止依赖项的派发，并交接 Plan Package 更新，而不是运行 doctor --repair。
• 协调者不得直接编辑 project-graph.json、画布 manifest.json 或源提示词 Markdown；应在工作者交接中包含目标路径和验证命令。
• 不得隐瞒部分成功、重复运行、过期的当前引用或孤立产物。
• 如果需要修改 package 来解决分歧，应暂停依赖项的执行，直至 package 协调完成。

完成报告

停止时，请报告：

• 已完成的引用和已提交的产物。
• 未处理的引用、阻碍因素或分歧。
• 已运行的验证。
• 已采取的恢复操作。
• 下一步操作是认领、评审、恢复、导入／更新计划，还是由用户决策。