Converting Markdown Documents to Overseer Tasks

Use /overseer-plan to convert any markdown planning document into trackable Overseer tasks.

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 3           # Set priority (1-5)
/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 with full markdown as context
4. Analyzes structure for subtask breakdown
5. Creates subtasks when appropriate
6. Returns task ID and breakdown summary

Hierarchy Levels

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

After Creating

await tasks.get("<id>");                    // View task
await tasks.list({ parentId: "<id>" });     // List children
await tasks.start("<id>");                  // Start work (creates VCS bookmark)
await tasks.complete("<id>", "result");     // Complete (squashes commits)

VCS Integration: start and complete automatically manage VCS bookmarks and commits. No manual VCS operations needed.

When NOT to Use

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

Reading Order

In This Reference