overseer-plan

将 Markdown 文档转换为 Overseer 任务

使用 /overseer-plan 将任意 Markdown 规划文档转换为可跟踪的 Overseer 任务。

适用场景

• 在计划模式下完成计划后
• 将规格说明／设计文档转换为实现任务
• 根据路线图或里程碑文档创建任务

用法

/overseer-plan <markdown-file-path>
/overseer-plan <file> --priority 1           # Set priority (0-2, 0=highest)
/overseer-plan <file> --parent <task-id>     # Create as child of existing task

功能说明

1. 读取 Markdown 文件
2. 从第一个 # 标题中提取标题（移除 "Plan: " 前缀）
3. 创建 Overseer 里程碑（如果提供了 --parent，则创建子任务）
4. 分析结构，拆分子任务
5. 在适当情况下创建子任务（深度 1）或子子任务（深度 2）
6. 返回任务 ID 和拆分摘要

层级

深度	名称	示例
0	里程碑	"添加用户身份验证系统"
1	任务	"实现 JWT 中间件"
2	子任务	"添加令牌验证函数"

拆分判断

在以下情况下创建子任务：

• 有 3-7 个可明确拆分的工作项
• 实现涉及多个文件／组件
• 存在明确的顺序依赖关系

在以下情况下保留为单个里程碑：

• 只有 1-2 个步骤
• 工作项紧密耦合
• 计划属于探索性／调查性工作

任务质量标准

每项任务都必须：

• 原子化：单个可提交的工作单元
• 可验证：包含测试，或在上下文中明确写明验收标准（"完成条件：……"）
• 清晰：技术性、具体，并使用祈使动词

每个里程碑都必须：

• 可演示：产出可运行／可测试的增量
• 建立在先前成果之上：可以依赖上一个里程碑的输出

审查工作流

1. 分析文档 → 提出拆分方案
2. 调用 Oracle 审查拆分方案并提出改进建议
3. 纳入反馈
4. 在 Overseer 中创建（通过 MCP 持久化到 SQLite）

创建后

await tasks.get("<id>");                    // TaskWithContext (full context + learnings)
await tasks.list({ parentId: "<id>" });     // Task[] (children without context chain)
await tasks.start("<id>");                  // Task (VCS required - creates bookmark, records start commit)
await tasks.complete("<id>", { result: "...", learnings: [...] });  // Task (VCS required - commits, bubbles learnings)

必须使用 VCS：start 和 complete 需要 jj 或 git（如果未检测到，则会因 NotARepository 失败）。CRUD 操作不需要 VCS。

注意：优先级必须为 1-5。阻塞项不能是祖先或后代。

不适用场景

• 文档尚未完成或属于探索性内容
• 内容不可执行
• 不包含有意义的规划内容

---

阅读顺序

任务	文件
了解 API	@file references/api.md
Agent 实现	@file references/implementation.md
查看示例	@file references/examples.md

本参考文档包含

文件	用途
references/api.md	Overseer MCP codemode API 类型／方法
references/implementation.md	Agent 的逐步执行说明
references/examples.md	完整示例