npx skills add https://github.com/dmmulroy/overseer --skill overseerOverseer 任务是工单——具有完整上下文的结构化制品:
思考:"仅凭此任务,某人是否能理解其内容、原因、方法以及成功的样子?"
切勿在外部制品(提交、PR、文档)中引用任务 ID。像 task_01JQAZ... 这样的任务 ID 在任务完成后就变得毫无意义。描述工作本身,而不是跟踪它的任务。
| Overseer | TodoWrite
---|---|---
持久性 | SQLite 数据库 | 仅限会话
上下文 | 丰富(描述 + 上下文 + 结果) | 基础
层级结构 | 3 级(里程碑 -> 任务 -> 子任务) | 扁平
使用 Overseer 处理持久性工作。仅将 TodoWrite 用于临时的会话内跟踪。
在以下情况使用 Overseer:
在以下情况跳过 Overseer:
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
// 获取下一个就绪任务及其完整上下文(推荐用于工作会话)
const task = await tasks.nextReady(milestoneId); // TaskWithContext | null
if (!task) {
console.log("No ready tasks");
return;
}
// 获取所有就绪任务(用于进度概览)
const readyTasks = await tasks.list({ ready: true }); // Task[]
开始工作时使用 nextReady()——返回 TaskWithContext | null(最深的就绪叶子节点,包含完整的上下文链和继承的学习成果)。进行状态/进度检查时使用 list({ ready: true })——返回不带上下文链的 Task[]。
// 1. 获取下一个就绪任务(返回 TaskWithContext | null)
const task = await tasks.nextReady();
if (!task) return "No ready tasks";
// 2. 查看上下文(TaskWithContext 上可用)
console.log(task.context.own); // 此任务的上下文
console.log(task.context.parent); // 父任务的上下文(如果深度 > 0)
console.log(task.context.milestone); // 根里程碑的上下文(如果深度 > 1)
console.log(task.learnings.own); // 附加到此任务的学习成果(从子任务冒泡而来)
// 3. 开始工作(需要 VCS - 创建书签,记录起始提交)
await tasks.start(task.id);
// 4. 实施...
// 5. 完成任务并附带学习成果(需要 VCS - 提交更改,将学习成果冒泡至父任务)
await tasks.complete(task.id, {
result: "Implemented login endpoint with JWT tokens",
learnings: ["bcrypt rounds should be 12 for production"]
});
// 替代方案:如果放弃则取消(不会满足阻塞条件)
await tasks.cancel(task.id);
// 6. 归档已完成的任务,使其从默认列表中隐藏
await tasks.archive(task.id);
详细的工作流程指南请参阅 @file references/workflow.md。
任务具有渐进式上下文——从祖先继承而来:
const task = await tasks.get(taskId); // 返回 TaskWithContext
// task.context.own - 此任务的上下文(始终存在)
// task.context.parent - 父任务的上下文(如果深度 > 0)
// task.context.milestone - 根里程碑的上下文(如果深度 > 1)
// 任务自身的学习成果(从已完成的子任务冒泡而来)
// task.learnings.own - 附加到此任务的学习成果
| 方法 | 返回 | 备注 |
|---|---|---|
tasks.get(id) | TaskWithContext | 完整的上下文链 + 继承的学习成果 |
tasks.nextReady() | `TaskWithContext | null` |
tasks.list() | Task[] | 仅包含基础任务字段 |
tasks.create() | Task | 无上下文链 |
tasks.start/complete() | Task | 无上下文链 |
阻塞项会阻止任务进入就绪状态,直到阻塞项完成。
约束条件:
阻塞项不能是任务自身
阻塞项不能是祖先(父任务、祖父任务等)
阻塞项不能是后代
创建/重新设置父任务时若包含无效阻塞项会被拒绝
// 添加阻塞项 - taskA 等待 taskB await tasks.block(taskA.id, taskB.id);
// 移除阻塞项 await tasks.unblock(taskA.id, taskB.id);
三个层级:里程碑(深度 0) -> 任务(深度 1) -> 子任务(深度 2)。
| 层级 | 名称 | 目的 | 示例 |
|---|---|---|---|
| 0 | 里程碑 | 大型计划 | "添加用户认证系统" |
| 1 | 任务 | 重要工作项 | "实现 JWT 中间件" |
| 2 | 子任务 | 原子步骤 | "添加令牌验证函数" |
选择合适的层级:
详细指南请参阅 @file references/hierarchies.md。
在实施并验证后立即完成任务:
您的结果必须包含明确的验证证据。请参阅 @file references/verification.md。
| 任务 | 文件 |
|---|---|
| 理解 API | @file references/api.md |
| 实施工作流程 | @file references/workflow.md |
| 任务分解 | @file references/hierarchies.md |
| 好/坏示例 | @file references/examples.md |
| 验证清单 | @file references/verification.md |
| 文件 | 目的 |
|---|---|
references/api.md | Overseer MCP 代码模式 API 类型/方法 |
references/workflow.md | 开始 -> 实施 -> 完成工作流程 |
references/hierarchies.md | 里程碑/任务/子任务组织 |
references/examples.md | 好/坏的上下文和结果示例 |
references/verification.md | 验证清单和流程 |
每周安装量
108
代码仓库
GitHub 星标数
222
首次出现
2026 年 1 月 27 日
安全审计
安装于
opencode106
codex79
gemini-cli75
amp74
github-copilot73
kimi-cli70
Overseer tasks are tickets - structured artifacts with comprehensive context:
Think: "Would someone understand the what, why, and how from this task alone AND what success looks like?"
Never reference task IDs in external artifacts (commits, PRs, docs). Task IDs like task_01JQAZ... become meaningless once tasks complete. Describe the work itself, not the task that tracked it.
| Overseer | TodoWrite
---|---|---
Persistence | SQLite database | Session-only
Context | Rich (description + context + result) | Basic
Hierarchy | 3-level (milestone -> task -> subtask) | Flat
Use Overseer for persistent work. Use TodoWrite for ephemeral in-session tracking only.
Use Overseer when:
Skip Overseer when:
// Get next ready task with full context (recommended for work sessions)
const task = await tasks.nextReady(milestoneId); // TaskWithContext | null
if (!task) {
console.log("No ready tasks");
return;
}
// Get all ready tasks (for progress overview)
const readyTasks = await tasks.list({ ready: true }); // Task[]
UsenextReady() when starting work - returns TaskWithContext | null (deepest ready leaf with full context chain + inherited learnings). Uselist({ ready: true }) for status/progress checks - returns Task[] without context chain.
// 1. Get next ready task (returns TaskWithContext | null)
const task = await tasks.nextReady();
if (!task) return "No ready tasks";
// 2. Review context (available on TaskWithContext)
console.log(task.context.own); // This task's context
console.log(task.context.parent); // Parent's context (if depth > 0)
console.log(task.context.milestone); // Root milestone context (if depth > 1)
console.log(task.learnings.own); // Learnings attached to this task (bubbled from children)
// 3. Start work (VCS required - creates bookmark, records start commit)
await tasks.start(task.id);
// 4. Implement...
// 5. Complete with learnings (VCS required - commits changes, bubbles learnings to parent)
await tasks.complete(task.id, {
result: "Implemented login endpoint with JWT tokens",
learnings: ["bcrypt rounds should be 12 for production"]
});
// Alternative: Cancel if abandoning (does NOT satisfy blockers)
await tasks.cancel(task.id);
// 6. Archive finished tasks to hide from default list
await tasks.archive(task.id);
See @file references/workflow.md for detailed workflow guidance.
Tasks have progressive context - inherited from ancestors:
const task = await tasks.get(taskId); // Returns TaskWithContext
// task.context.own - this task's context (always present)
// task.context.parent - parent task's context (if depth > 0)
// task.context.milestone - root milestone's context (if depth > 1)
// Task's own learnings (bubbled from completed children)
// task.learnings.own - learnings attached to this task
| Method | Returns | Notes |
|---|---|---|
tasks.get(id) | TaskWithContext | Full context chain + inherited learnings |
tasks.nextReady() | `TaskWithContext | null` |
tasks.list() | Task[] | Basic task fields only |
tasks.create() | Task |
Blockers prevent a task from being ready until the blocker completes.
Constraints:
Blockers cannot be self
Blockers cannot be ancestors (parent, grandparent, etc.)
Blockers cannot be descendants
Creating/reparenting with invalid blockers is rejected
// Add blocker - taskA waits for taskB await tasks.block(taskA.id, taskB.id);
// Remove blocker await tasks.unblock(taskA.id, taskB.id);
Three levels: Milestone (depth 0) -> Task (depth 1) -> Subtask (depth 2).
| Level | Name | Purpose | Example |
|---|---|---|---|
| 0 | Milestone | Large initiative | "Add user authentication system" |
| 1 | Task | Significant work item | "Implement JWT middleware" |
| 2 | Subtask | Atomic step | "Add token verification function" |
Choosing the right level:
See @file references/hierarchies.md for detailed guidance.
Complete tasks immediately after implementing AND verifying :
Your result must include explicit verification evidence. See @file references/verification.md.
| Task | File |
|---|---|
| Understanding API | @file references/api.md |
| Implementation workflow | @file references/workflow.md |
| Task decomposition | @file references/hierarchies.md |
| Good/bad examples | @file references/examples.md |
| Verification checklist | @file references/verification.md |
| File | Purpose |
|---|---|
references/api.md | Overseer MCP codemode API types/methods |
references/workflow.md | Start->implement->complete workflow |
references/hierarchies.md | Milestone/task/subtask organization |
references/examples.md | Good/bad context and result examples |
references/verification.md | Verification checklist and process |
Weekly Installs
108
Repository
GitHub Stars
222
First Seen
Jan 27, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode106
codex79
gemini-cli75
amp74
github-copilot73
kimi-cli70
开源项目教练指南 - 诊断问题、制定行动计划、优化开源项目运营
43,100 周安装
| No context chain |
tasks.start/complete() | Task | No context chain |