Goblin-mode doc-create-roadmap-omega

{{ 𝛀𝛀𝛀 }} Create a project roadmap document in structured milestone format

install

source · Clone the upstream repo

git clone https://github.com/JasonWarrenUK/goblin-mode

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/JasonWarrenUK/goblin-mode "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/doc-create-roadmap-omega" ~/.claude/skills/jasonwarrenuk-goblin-mode-doc-create-roadmap-omega && rm -rf "$T"

manifest: skills/doc-create-roadmap-omega/SKILL.md

source content

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)

<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:

Confirm file created at
```
docs/roadmaps/{name}.md
```
Confirm
```
.claude/roadmaps.json
```
updated
Summarize structure:
- Number of milestones
- Total tasks defined
- Tasks per section (In Progress, To Do, Blocked, Completed)
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.