jasonwarrenuk/doc-create-roadmap-omega

Create a project roadmap at docs/roadmaps/{name}.md with milestone-based task organization and dependency tracking via Mermaid diagrams.

Behaviour

| Codebase Context | Arguments Passed | Action | | -------------------- | ---------------- | ------------------------------------------------------------------- | | No other roadmaps | 0 | Create overall project roadmap (probably mvp.md) | | N/A | 1 | Create roadmap for feature/phase specified in argument | | Other roadmaps exist | 0 | Ask user which roadmap to create or if creating a new feature phase |

Steps

1. Determine roadmap scope and context

• Check if docs/roadmaps/ directory exists and contains roadmaps
• Check if .claude/roadmaps.json exists and parse its contents
• If $ARGUMENTS provided, use as roadmap name (e.g., "mvp", "v2-features")
• If no arguments and no existing roadmaps, default to "mvp"
• If no arguments but roadmaps exist, ask user to clarify intent

2. Gather project context

Read available documentation to understand:

• Project purpose and technical scope
• Existing architecture and technology stack
• Development status (what's done, what's planned)
• Key features and requirements

Sources to check:

• README.md (project overview)
• docs/ directory (all markdown files)
• .claude/CLAUDE.md (project-specific conventions)
• Existing roadmaps in docs/roadmaps/ (if creating additional roadmap)

3. Elicit roadmap structure from user

Ask targeted questions to define:

Milestone count and themes:

• How many major milestones? (typical: 3-5 for MVP)
• What is each milestone's goal? (e.g., "Core Library", "TUI Interface", "CLI Commands")
• What defines completion for each milestone?

Task categories per milestone:

• What are the logical groupings? (e.g., TUI screens, workflows, commands)
• Use 2-3 letter prefixes (e.g., WA = workflows, TI = TUI, DC = direct commands)

Dependencies:

• Which milestones are sequential vs parallel?
• Any known blockers or prerequisites?

4. Generate roadmap structure

Create file at docs/roadmaps/{name}.md with:

File Header

---
description: [Brief one-line description from user]
---

# {Project Name}: {Roadmap Title}

|          | Status                  | Next Up           | Blocked           |
| -------- | ----------------------- | ----------------- | ----------------- |
| **{Cat}** | [current status]       | [next priority]   | [key blockers]    |

---

## Contents

- [Milestones](#milestones)
  - [Milestone 1: {Name}](#m1)
  - [Milestone 2: {Name}](#m2)
  - ...
- [Progress Map](#map)
- [Links](#links)
- [Beyond MVP](#post-mvp)

Milestone Structure (for each milestone)

<a name="m{N}"><h3>Milestone {N}: {Name}</h3></a>

> [!IMPORTANT]
> **Goal:** {Milestone objective}

<a name="m{N}-doing"><h4>In Progress (Milestone {N})</h4></a>

- [ ] {MilestoneCategory}.{Seq}. {Task description}

<a name="m{N}-todo"><h4>To Do (Milestone {N})</h4></a>

- [ ] {MilestoneCategory}.{Seq}. {Task description} — **depends on {TaskID}**

<a name="m{N}-blocked"><h4>Blocked (Milestone {N})</h4></a>

- [ ] {MilestoneCategory}.{Seq}. {Task description} — **depends on {TaskID}**

<a name="m{N}-done"><h4>Completed (Milestone {N})</h4></a>

- [x] {MilestoneCategory}.{Seq}. {Task description}

Progress Map (single aggregated diagram)

At <a name="map"> section, include ONE Mermaid diagram showing ALL tasks across ALL milestones with full dependency graph:

---
title: Progress Map
---
graph TD

{TaskID}["`*{TaskID}*<br/>**{Category}**<br/>{short desc}`"]:::open --> {DepTaskID}

m{N}{"`**Milestone {N}**<br/>{Name}`"}:::mile

classDef default,blocked fill:#fff7fb;
classDef open fill:#fff9e5;
classDef mile fill:#c4fffe;

5. Task numbering convention

Format: {Milestone}{Category}.{Seq}

Examples:

• 1WA.1 - Milestone 1, Workflow Abstractions, task 1
• 2TI.7 - Milestone 2, TUI Interface, task 7
• 3DC.2 - Milestone 3, Direct Commands, task 2

Sub-tasks:

• Use alpha suffix: 2TI.3a, 2TI.3b

Rules:

• Never reuse task IDs
• Sequential numbering within each category
• New tasks append to category sequence (no renumbering)

6. Dependency tracking

In task descriptions:

- [ ] 2TI.14. Build validate screen — **depends on 2TI.13, 2TI.7**

In Mermaid diagrams:

2TI.13 --> 2TI.14
2TI.7 --> 2TI.14

Class assignment:

• :::open - No blocking dependencies (ready to start)
• :::blocked (default) - Has dependencies or explicit blockers
• :::mile - Milestone node

7. Update project configuration

Add/update .claude/roadmaps.json:

{
  "roadmaps": [
    {
      "name": "{Roadmap Name}",
      "path": "docs/roadmaps/{name}.md"
    }
  ]
}

If file exists, append to array. If creating first roadmap, create file.

8. Populate initial tasks

For each milestone:

• Break goal into 5-15 discrete tasks
• Assign task IDs following numbering convention
• Group tasks by category (2-3 letter prefix)
• Mark obvious dependencies
• Place tasks in appropriate sections:
  • In Progress: Only if user specifies active work
  • To Do: Tasks ready to start (no blockers)
  • Blocked: Tasks with explicit dependencies
  • Completed: Only if user specifies already-done work

9. Generate summary status table

At top of roadmap, create status table showing per-category progress:

|          | Status                  | Next Up           | Blocked           |
| -------- | ----------------------- | ----------------- | ----------------- |
| **Core** | ✅ Milestone 1 complete | —                 | —                 |
| **CLI**  | Basic structure         | Direct commands   | `check` (needs X) |
| **TUI**  | Screens implemented     | Keyboard nav      | All screens       |

Output Format

After creating the roadmap:

1. Confirm file created at docs/roadmaps/{name}.md
2. Confirm .claude/roadmaps.json updated
3. Summarize structure:
   • Number of milestones
   • Total tasks defined
   • Tasks per section (In Progress, To Do, Blocked, Completed)
4. Note any assumptions made or areas needing user refinement

Notes

• Be thorough but not prescriptive - user will refine tasks iteratively
• Preserve flexibility - roadmap will evolve with doc:update:roadmap
• Dependency inference - use project context to suggest logical dependencies
• Category naming - short, memorable, distinct (2-3 letters)
• Milestone scope - each should deliver meaningful user value
• Initial state - most tasks likely "To Do" or "Blocked" unless project is mid-flight

Compatibility

This command creates roadmaps compatible with commands/doc/update/roadmap.md:

• Section anchors: #m{N}-doing, #m{N}-todo, #m{N}-blocked, #m{N}-done
• Task format: - [ ] unchecked, - [x] checked
• Dependency format: — **depends on {TaskID}**
• Mermaid class definitions: classDef default,blocked fill:#f9f; etc.