| name | plan-docs |
| description | 为项目生成可执行的波次计划文档。当用户进入 Plan 模式、要求开发计划、任务拆分、 并行执行、依赖排序、实施波次或 AI/Subagent 协作时使用。简单且范围明确的短任务 保持主线执行；跨模块、调用链未知、存在兼容性或多个独立工作面的任务生成依赖图、 Wave 顺序、并行边界和完成门。兼容 Cursor Agent Skills 与 cursor-byok-source。 |
| metadata | {"version":"1.0.0"} |
plan-docs
把用户目标转成可独立阅读、可按依赖执行、可恢复的 Markdown 计划。
使用顺序
- 判断任务是否简单。
- 简单任务直接调查并生成精简计划，不派 Subagent。
- 非平凡任务先做有限侦察；若存在至少两个独立调查角度，按运行环境能力并行派遣只读 Explore。
- 收齐调查证据后，构建任务 DAG 和执行 Wave。
- 使用
CreatePlan 提交完整计划；Markdown 是跨 Cursor 环境的事实源。
- 用户启动计划后，只执行最早未完成 Wave；通过完成门后再推进下一 Wave。
简单任务判定
仅当以下条件全部满足时不派 Subagent：
- 目标可由 1–2 个明确文件或单一调用链完成。
- 不需要比较多个实现方案。
- 不涉及协议、持久化、兼容性、迁移或跨模块状态。
- 不需要独立证据复核。
“描述很短”不等于简单。满足任一升级信号时，按非平凡任务处理。
计划格式
必须使用 templates/wave-plan.md 的结构，并遵守 references/wave-execution.md。
每个任务必须包含：
- 稳定 ID，例如
T1。
- 目标与范围。
depends_on。owned_paths。- 执行者：
main、subagent:explore 或 subagent:generalPurpose。
- 产出、验收与并行限制。
每个 Wave 必须包含：
- 准入条件。
- 同波任务及 parallel/sequential 标记。
- 完成门。
- 失败策略。
执行契约
main：短链路、共享文件、强耦合或无法证明并行安全的任务。subagent:explore：只读调查，只回传结论、文件证据和风险；调用 Task 时必须使用 subagent_type="explore" 与 access_mode="inspect"。subagent:generalPurpose：独立实现；调用 Task 时必须使用 subagent_type="generalPurpose" 与 access_mode="act"，要求在 owned_paths 内实际落盘并执行验收；普通实现优先显式选择 model="gpt-5.6-terra"，只有高难度推理、架构决策或高质量审查才升级为 model="gpt-5.6-sol"；thinking_effort 按任务需要选择 disabled|low|medium|high|xhigh|max，未指定时继承父运行配置；只有 owned_paths 不重叠且可独立验收时并行。- 同波直接 Subagent 不超过 4 个；超过时拆成批次或后续 Wave。
- 父代理不重复执行已委派工作；等待同波全部结果后统一综合。
- Task 启动不等于完成。只有结果返回且验收通过，任务才能完成。
- 任一必需任务失败、超时或结果不明时，当前 Wave 标记 blocked，不得跳波。
- 每次推进前更新 Todo；Todo ID 与计划任务 ID 对齐。
- 用户明确禁止 Subagent 时，主线按 Wave 顺序完成全部任务。
兼容边界
- 不依赖私有 JSON 字段、tool call ID、Agent ID 或客户端内部路径。
phases、todo dependencies 等结构化字段可以作为增强投影，但不能取代 Markdown。- 官方 Cursor 无额外服务端支持时，Agent 仍应仅依据计划文本执行。
- cursor-byok-source 会增强 ExecutePlan 的计划承接，但 Skill 不假设该增强必然存在。
