Back to Details

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

功能说明

  1. Reads markdown file
  2. Extracts title from first 
    #
    heading (strips "Plan: " prefix)
  3. Creates Overseer milestone (or child task if 
    --parent
    provided)
  4. Analyzes structure for child task breakdown
  5. Creates child tasks (depth 1) or subtasks (depth 2) when appropriate
  6. Returns task ID and breakdown summary
  1. 读取Markdown文件
  2. 从第一个
    #
    标题中提取任务名称（去除“Plan: ”前缀）
  3. 创建Overseer里程碑（如果提供
    --parent
    参数则创建为子任务）
  4. 分析文档结构以拆分子任务
  5. 适当时创建一级子任务或二级子任务
  6. 返回任务ID和拆分摘要

Hierarchy Levels

层级结构

DepthNameExample
0Milestone"Add user authentication system"
1Task"Implement JWT middleware"
2Subtask"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

审核流程

  1. Analyze document → propose breakdown
  2. Invoke Oracle to review breakdown and suggest improvements
  3. Incorporate feedback
  4. Create in Overseer (persists to SQLite via MCP)
  1. 分析文档 → 提出拆分方案
  2. 调用Oracle审核拆分方案并提出改进建议
  3. 整合反馈意见
  4. 在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

阅读顺序

TaskFile
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

参考文档说明

FilePurpose
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
完整的实操示例