Plan Worker Orchestrator

不要在 plan.md 和 verify.md 出来之前抢先派实现 worker。 此时不要让 plan agent 预写 log4human.md。

2. plan agent 的要求

plan.md 必须：

• 用 checkbox 列出任务
• 显式区分：
  • 串行前置
  • 可并行实施
  • 串行集成
• 假设后续执行完全由 subagents 完成，而不是默认主 agent 亲自做所有细活
• 提前写清文件 ownership，避免 worker 冲突

verify.md 必须：

• 是验收门禁，而不是随手 checklist
• 至少包含：
  • file gate
  • content gate
  • runtime gate
  • build/test gate（如适用）
• 末尾有 task_complete checkbox
• 明确写出：只有所有门禁通过，才允许勾选 task_complete

log4human.md 必须：

• 面向人类，不面向 agent
• 简洁，不写推理过程和废话
• 至少回答五件事：
  • 任务是什么
  • 具体完成了什么
  • 关键结果是什么
  • 成果文件在哪里
  • 如何快速验证
• 写法应接近“秘书向老板汇报”，而不是执行日志回放
• 必须包含一个 Quick Verify 区块，明确写：
  • 先看哪个文件
  • 再跑哪条命令
  • 预期会看到什么现象

但这个文件不属于 planner 阶段；它应在真实实现完成后，由 worker 或串行集成阶段产出。

2.1 Planner Isolation Contract

plan agent 只允许修改缓存目录中的：

• plan.md
• verify.md

除此之外的任何文件改动，都视为越权，不算成功完成计划阶段。

主 agent 在接受 plan agent 结果前，必须做一次越权检查：

• 查看 git status --short、文件列表或等价证据
• 确认 plan agent 没有改动缓存目录之外的目标文件

如果发现越权：

• 不接受该 planner 的“任务已完成”说法
• 不把其正文改动视为有效实现
• 重新派一个 planner，或由主 agent 亲自重写计划文件

这条规则的目的不是惩罚 subagent，而是防止“计划阶段偷偷实现任务”导致串并行编排失真。

2.2 Planner Prompt Requirements

给 plan agent 的提示词至少要包含四层约束：

1. 明确写出它的唯一写入范围
2. 明确声明“不要实现任务本体”
3. 明确声明“越权修改 = 失败”
4. 要求它在回报时列出修改文件，供主 agent 复核
5. 明确声明“不要预写 log4human.md”

如有命令占位符，例如 <harder_demo_file>.py，在主 agent 最终验收前要替换成真实路径。

worker 派发规则

• 先读 plan.md，再按其中的串并行设计派 worker。
• log4human.md 默认分配给最后一个 worker 或 serial integration 阶段，而不是 planner。
• 每个 worker 必须有清晰 ownership，写入范围不能重叠。
• 如果任务可拆为多个互不冲突的文件面：
  • README / 文档说明
  • 新代码或 benchmark
  • 英文主文档
  • 中文翻译文档 可一次并发派出。
• 若 agent 线程数达到上限，先关闭已完成使命的 agent，再补发剩余 worker。

主 agent 的职责

主 agent 不能把 subagent 的“已完成”“已验收”原样照单全收。主 agent 必须亲自做：

• 抽样或全文检查关键文件
• 先做 planner 越权检查，再进入 worker 阶段
• 运行门禁中的关键命令
• 复核 verify.md 的勾选是否真实
• 清理运行残留物，例如 __pycache__
• 做最后的统一口径和风格收敛

特别是：

• 不要仅因为 subagent 说 task_complete 已勾选，就直接结束
• 要以仓库真实状态和实跑结果为准

默认复核清单

• plan.md 是否真的覆盖了串行、并行、集成三层
• verify.md 是否包含客观门禁，而不是空泛描述
• log4human.md 是否让人类不翻聊天记录也能迅速看懂任务、结果、产物位置和快速验证方法
• plan agent 是否严格只改了缓存目录中的计划文件
• worker 是否遵守了 ownership
• 最终命令是否由主 agent 亲自跑过至少一轮
• 若生成了文档或 PDF，主 agent 要亲自确认构建成功

资源

• references/plan-template.md
• references/verify-template.md
• references/log4human-template.md
• references/planner-prompt-template.md

如果任务要用共享 Python 环境，额外读取：

• ../shared-python-env/SKILL.md