overseer

Agent Coordination with Overseer

Core Principle: Tickets, Not Todos

Overseer tasks are tickets - structured artifacts with comprehensive context:

• Description: One-line summary (issue title)
• Context: Full background, requirements, approach (issue body)
• Result: Implementation details, decisions, outcomes (PR description)

Think: "Would someone understand the what, why, and how from this task alone AND what success looks like?"

Task IDs are Ephemeral

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 vs OpenCode's TodoWrite

	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.

When to Use Overseer

Use Overseer when:

• Breaking down complexity into subtasks
• Work spans multiple sessions
• Context needs to persist for handoffs
• Recording decisions for future reference

Skip Overseer when:

• Work is a single atomic action
• Everything fits in one message exchange
• Overhead exceeds value
• TodoWrite is sufficient

Finding Work

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

Use nextReady() when starting work - returns TaskWithContext | null (deepest ready leaf with full context chain + inherited learnings). Use list({ ready: true }) for status/progress checks - returns Task[] without context chain.

Basic Workflow

// 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.

Understanding Task Context

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

Return Type Summary

Method	Returns	Notes
tasks.get(id)	TaskWithContext	Full context chain + inherited learnings
tasks.nextReady()	TaskWithContext | null	Deepest ready leaf with full context
tasks.list()	Task[]	Basic task fields only
tasks.create()	Task	No context chain
tasks.start/complete()	Task	No context chain

Blockers

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

Task Hierarchies

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:

• Small feature (1-2 files) -> Single task
• Medium feature (3-7 steps) -> Task with subtasks
• Large initiative (5+ tasks) -> Milestone with tasks

See @file references/hierarchies.md for detailed guidance.

Recording Results

Complete tasks immediately after implementing AND verifying:

• Capture decisions while fresh
• Note deviations from plan
• Document verification performed
• Create follow-up tasks for tech debt

Your result must include explicit verification evidence. See @file references/verification.md.

Best Practices

1. Right-size tasks: Completable in one focused session
2. Clear completion criteria: Context should define "done"
3. Don't over-decompose: 3-7 children per parent
4. Action-oriented descriptions: Start with verbs ("Add", "Fix", "Update")
5. Verify before completing: Tests passing, manual testing done

---

Reading Order

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

In This Reference

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