overseer-plan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Converting Markdown Documents to Overseer Tasks

将Markdown文档转换为Overseer任务

Use

/overseer-plan

to convert any markdown planning document into trackable Overseer tasks.

使用

/overseer-plan

命令将任何Markdown规划文档转换为可追踪的Overseer任务。

When to Use

适用场景

After completing a plan in plan mode
Converting specs/design docs to implementation tasks
Creating tasks from roadmap or milestone documents

在计划模式下完成规划后
将规格说明/设计文档转换为落地任务
从路线图或里程碑文档创建任务

Usage

使用方法

/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

/overseer-plan <markdown-file-path>
/overseer-plan <file> --priority 1           # 设置优先级（0-2，0为最高）
/overseer-plan <file> --parent <task-id>     # 作为现有任务的子任务创建

What It Does

功能说明

Reads markdown file
Extracts title from first
```
#
```
heading (strips "Plan: " prefix)
Creates Overseer milestone (or child task if
```
--parent
```
provided)
Analyzes structure for child task breakdown
Creates child tasks (depth 1) or subtasks (depth 2) when appropriate
Returns task ID and breakdown summary

读取Markdown文件
从第一个
```
#
```
标题中提取任务名称（去除“Plan: ”前缀）
创建Overseer里程碑（如果提供
```
--parent
```
参数则创建为子任务）
分析文档结构以拆分子任务
适当时创建一级子任务或二级子任务
返回任务ID和拆分摘要

Hierarchy Levels

层级结构

Depth	Name	Example
0	Milestone	"Add user authentication system"
1	Task	"Implement JWT middleware"
2	Subtask	"Add token verification function"

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

Breakdown Decision

拆分决策

Create subtasks when:

3-7 clearly separable work items
Implementation across multiple files/components
Clear sequential dependencies

Keep single milestone when:

1-2 steps only
Work items tightly coupled
Plan is exploratory/investigative

创建子任务的情况：

存在3-7个可明确拆分的工作项
需要在多个文件/组件中实现
存在清晰的顺序依赖关系

保留为单个里程碑的情况：

仅包含1-2个步骤
工作项高度耦合
规划为探索性/调研性质

Task Quality Criteria

任务质量标准

Every task must be:

Atomic: Single committable unit of work
Validated: Has tests OR explicit acceptance criteria in context ("Done when: ...")
Clear: Technical, specific, imperative verb

Every milestone must:

Demoable: Produces runnable/testable increment
Builds on prior: Can depend on previous milestone's output

每个任务必须满足：

原子性：单一可提交的工作单元
可验证：包含测试或上下文明确的验收标准（“完成标志：...”）
清晰性：技术化、具体、使用祈使动词

每个里程碑必须满足：

可演示：产出可运行/可测试的增量成果
可衔接：可基于之前里程碑的输出构建

Review Workflow

审核流程

Analyze document → propose breakdown
Invoke Oracle to review breakdown and suggest improvements
Incorporate feedback
Create in Overseer (persists to SQLite via MCP)

分析文档 → 提出拆分方案
调用Oracle审核拆分方案并提出改进建议
整合反馈意见
在Overseer中创建任务（通过MCP持久化到SQLite）

After Creating

创建后操作

javascript

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 Required:

start

and

complete

require jj or git (fail with

NotARepository

if none found). CRUD operations work without VCS.

Note: Priority must be 1-5. Blockers cannot be ancestors or descendants.

javascript

await tasks.get("<id>");                    // TaskWithContext（完整上下文+经验总结）
await tasks.list({ parentId: "<id>" });     // Task[]（不含上下文链的子任务列表）
await tasks.start("<id>");                  // Task（需要VCS - 创建书签，记录开始提交）
await tasks.complete("<id>", { result: "...", learnings: [...] });  // Task（需要VCS - 提交代码，同步经验总结）

需要VCS支持：

start

和

complete

命令需要jj或git（如果未找到仓库会返回

NotARepository

错误）。CRUD操作无需VCS支持。

注意：优先级范围为1-5。阻塞任务不能是祖先或后代任务。

When NOT to Use

不适用场景

Document incomplete or exploratory
Content not actionable
No meaningful planning content

文档不完整或为探索性内容
内容不具备可执行性
无有意义的规划内容

Reading Order

阅读顺序

Task	File
Understanding API	@file references/api.md
Agent implementation	@file references/implementation.md
See examples	@file references/examples.md

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

In This Reference

参考文档说明

File	Purpose
`references/api.md`	Overseer MCP codemode API types/methods
`references/implementation.md`	Step-by-step execution instructions for agent
`references/examples.md`	Complete worked examples

文件	用途
`references/api.md`	Overseer MCP代码模式的API类型/方法
`references/implementation.md`	Agent的分步执行说明
`references/examples.md`	完整的实操示例