overseer

Overseer を使ったエージェントの調整

基本原則：Todo ではなくチケット

Overseer のタスクは、包括的なコンテキストを含む構造化された成果物であるチケットです。

• 説明：1 行の概要（課題のタイトル）
• コンテキスト：背景、要件、アプローチの全容（課題の本文）
• 結果：実装の詳細、決定事項、成果（PR の説明）

考えてみてください。「このタスクだけで、何を、なぜ、どのように行うのか、そして成功の条件まで理解できますか？」

タスク ID は一時的なものです

外部の成果物（コミット、PR、ドキュメント）でタスク ID を参照してはいけません。 task_01JQAZ... のようなタスク ID は、タスクの完了後は意味を持ちません。タスクを追跡した ID ではなく、作業そのものを説明してください。

Overseer と OpenCode の TodoWrite

	Overseer	TodoWrite
永続性	SQLite データベース	セッション内のみ
コンテキスト	豊富（説明＋コンテキスト＋結果）	基本
階層	3 階層（マイルストーン -> タスク -> サブタスク）	フラット

永続的な作業には Overseer を使用してください。TodoWrite は、セッション内の一時的な追跡にのみ使用してください。

Overseer を使用するタイミング

次の場合は Overseer を使用してください。

• 複雑な作業をサブタスクに分割する
• 作業が複数のセッションにまたがる
• 引き継ぎのためにコンテキストを保持する必要がある
• 将来参照できるように決定事項を記録する

次の場合は Overseer を使用しないでください。

• 作業が単一の独立したアクションである
• すべてが 1 回のメッセージのやり取りで完了する
• オーバーヘッドが価値を上回る
• TodoWrite で十分である

作業を見つける

// 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[]

作業を開始するときは nextReady() を使用してください。TaskWithContext | null（完全なコンテキストチェーンと継承された学びを含む、最も深い階層の準備完了リーフタスク）が返されます。 ステータスや進捗を確認するときは list({ ready: true }) を使用してください。コンテキストチェーンを含まない Task[] が返されます。

基本的なワークフロー

// 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);

詳しいワークフローのガイダンスについては、@file references/workflow.md を参照してください。

タスクのコンテキストを理解する

タスクには、祖先から継承される段階的なコンテキストがあります。

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

戻り値の概要

メソッド	戻り値	備考
tasks.get(id)	TaskWithContext	完全なコンテキストチェーンと継承された学び
tasks.nextReady()	TaskWithContext | null	完全なコンテキストを持つ、最も深い階層の準備完了リーフタスク
tasks.list()	Task[]	基本的なタスクフィールドのみ
tasks.create()	Task	コンテキストチェーンなし
tasks.start/complete()	Task	コンテキストチェーンなし

ブロッカー

ブロッカーが完了するまで、タスクは準備完了になりません。

制約：

• ブロッカーに自分自身を指定できません
• ブロッカーに祖先（親、祖父母など）を指定できません
• ブロッカーに子孫を指定できません
• 無効なブロッカーを指定した作成や親の変更は拒否されます

// Add blocker - taskA waits for taskB
await tasks.block(taskA.id, taskB.id);

// Remove blocker
await tasks.unblock(taskA.id, taskB.id);

タスク階層

3 つの階層があります：マイルストーン（深さ 0）-> タスク（深さ 1）-> サブタスク（深さ 2）。

階層	名前	目的	例
0	マイルストーン	大規模な取り組み	「ユーザー認証システムを追加する」
1	タスク	重要な作業項目	「JWT ミドルウェアを実装する」
2	サブタスク	独立した作業ステップ	「トークン検証関数を追加する」

適切な階層の選び方：

• 小規模な機能（ファイル 1～2 個）-> 単一のタスク
• 中規模な機能（ステップ 3～7 個）-> サブタスクを含むタスク
• 大規模な取り組み（タスク 5 個以上）-> タスクを含むマイルストーン

詳しいガイダンスについては、@file references/hierarchies.md を参照してください。

結果の記録

実装と検証が完了したらすぐにタスクを完了してください。

• 決定事項を忘れないうちに記録する
• 計画からの逸脱を記録する
• 実施した検証を文書化する
• 技術的負債に対するフォローアップタスクを作成する

結果には、検証を行った明確な証拠を含める必要があります。@file references/verification.md を参照してください。

ベストプラクティス

1. タスクの適切な規模設定：1回の集中したセッションで完了できるようにします
2. 完了基準を明確にする：「完了」の定義をコンテキストで示します
3. 細分化しすぎない：親ごとに子を3～7個にします
4. 行動指向の説明：動詞（「追加」「修正」「更新」）から始めます
5. 完了前に確認する：テストが合格し、手動テストも完了していることを確認します

---

読む順序

タスク	ファイル
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 codemode API の型／メソッド
references/workflow.md	開始->実装->完了のワークフロー
references/hierarchies.md	マイルストーン／タスク／サブタスクの構成
references/examples.md	良い／悪いコンテキストと結果の例
references/verification.md	確認チェックリストと手順