Converting Markdown Documents to Overseer Tasks

/overseer-plan

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

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

Hierarchy Levels

Breakdown Decision

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

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

Task Quality Criteria

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

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

After Creating

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)

start

complete

NotARepository

When NOT to Use

• Document incomplete or exploratory
• Content not actionable
• No meaningful planning content

Reading Order

In This Reference

references/api.md

references/implementation.md

references/examples.md