Roadmap: Create

Create a roadmap as three synchronised artefacts:

• .claude/roadmaps.json: machine-readable source of truth, an array of phase objects each {name, path, archived?, externalGates, milestones}. The active phase is the entry without archived: true; archived entries are retained as historical record.
• docs/roadmaps/{PHASE}.md: human-readable task list and dependency diagram (a projection).
• docs/reports/ROADMAP_OVERVIEW.md: prose overview (a projection).

When creating a new phase alongside existing ones, append a new element and mark the superseded phase "archived": true.

Shared conventions (status vocabulary, colour table, graph rules, formatting) live in ~/.claude/library/references/roadmap-conventions.md; read it before writing anything. The CLI is python3 "$HOME"/.claude/library/scripts/roadmap.py.

Behaviour

Steps

1. Determine scope, context, and format

• Check if docs/roadmaps/ exists and contains roadmaps; check if .claude/roadmaps.json exists.
• If $ARGUMENTS is given, use it as the phase name (e.g. PHASE_2). If no arguments and no existing roadmap, propose a phase name drawn from the project's goal and confirm it; never default to a bare PHASE_1. If no arguments but roadmaps exist, ask the user to clarify intent.
• If a roadmap already exists, check its format first: run python3 "$HOME"/.claude/library/scripts/roadmap.py detect. Exit 3 = old simple format: stop and tell the user to run the roadmap-migrate skill first, so the new phase is appended to a consistent phase array. Exit 2 = could not locate/parse: ask the user for the path. Only proceed on exit 0 (or when no roadmap exists yet).

2. Gather project context

Read what is available to understand the project: README.md, CLAUDE.md, docs/ (architecture, proposals, ADRs), and any existing roadmaps in docs/roadmaps/.

3. Elicit the work; let the structure emerge

Feature first, structure second: milestones reveal themselves as the conversation groups the work, so never open with "how many milestones?". Ask targeted questions (2–3 per round, not a long form):

• The work: what must exist by the end of this phase? What's frustrating enough to fix, and what does each piece unlock?
• Grouping (proposed, not demanded): once the features are on the table, propose a milestone grouping (typically 3–5, each with a goal and completion criterion) and 2–3 letter category prefixes (e.g. EV = evaluation, IN = ingestion). The user corrects a concrete proposal rather than designing structure cold.
• Dependencies: which groups are sequential vs parallel; any known external blockers or prerequisites.
• Assignees (optional): if the user wants to attribute tasks to people up front, ask who owns what. Never infer an assignee from category, milestone, or anything else; leave it unset for any task the user doesn't name an owner for.

For a big batch of half-formed ideas, roadmap-create-interview is the deeper feature interview; its approved proposal can seed this step's grouping.

4. Assign task IDs

Format: {MilestoneNum}{Category}.{Seq}, e.g. 1EV.1, 3IN.6. Sub-tasks use an alpha suffix: 3IN.2a. Never reuse an ID; number sequentially within each category; new tasks append (never renumber).

5. Compute initial statuses (mechanical)

The mechanical status rule from the conventions reference applies: empty dependsOn → todo; any non-done dependency → blocked. No task starts done unless the user says the work is already complete. paused/deferred are only for tasks parked behind a gate or a later phase. softDependsOn never feeds this rule.

6. Generate .claude/roadmaps.json

The top level is an array of phase objects. Append + archive the superseded phase if others exist; otherwise write a one-element array. Tabs for indentation, British spelling.

[
  {
    "name": "{Phase Name}",
    "path": "docs/roadmaps/{PHASE}.md",
    "archived": false,
    "externalGates": [],
    "milestones": [
      {
        "id": "M{N}",
        "name": "{Milestone Name}",
        "goal": "{One-sentence objective}",
        "tasks": [
          { "id": "{ID}", "description": "{Task description}", "status": "todo", "dependsOn": [] }
        ]
      }
    ]
  }
]

• Field order for tasks: id, description, status, dependsOn, softDependsOn, iterative, notes, assignee; gates: id, name, status, imposes, blocks, notes. Include softDependsOn/notes/iterative/assignee only when meaningful; assignee is free-text with no roster, and must never be guessed.
• External gates (externalGates, per phase, beside milestones) model things outside the team's control that block work: {id, name, status:"external", imposes?, blocks[], notes?}. imposes (default blocked; may be paused or deferred) is the status the gate forces on its blocked children; blocks[] is the reverse edge: every task ID that lists this gate in its dependsOn. A gate ID can appear in a task's dependsOn.
• A dependsOn entry may be a milestone ID (M1, MP…): it resolves done only when every task in that milestone is done.
• The iterative: true flag marks a task that loops to convergence: descriptive only, never a cyclic dependsOn.
• A softDependsOn entry authors an optional, best-effort link that renders dotted in the diagram (X -.-> Y) but imposes no status, no cycle constraint, and no sink effect (full semantics in the conventions reference). Use it for relationships worth showing but not worth blocking on; never hand-draw a dotted line into the generated diagram instead.

7. Generate docs/roadmaps/{PHASE}.md

# {Project Name} {Phase} Roadmap

{1–3 sentence intro.}

**Critical path:** `{key IDs in sequence}`; {brief explanation}.

---

## Milestone 1: {Name}

**Goal:** {Milestone objective}

- [ ] **{ID}**: {description}
- [ ] **{ID}**: {description} _(depends on {ID})_
- [ ] **{ID}**: {description} _(blocked: depends on {ID}, {ID})_
  - Note: {optional note}

---

## Dependency Diagram

```mermaid
{output of roadmap.py graph --mermaid}
```

Task line annotations follow the conventions reference (none / _(depends on {IDs})_ / _(blocked: depends on {IDs})_ / _(paused: reconvene {gateId})_ / _(deferred to a later phase)_).

The diagram is generated, never hand-written. Once the JSON is written, run:

python3 "$HOME"/.claude/library/scripts/roadmap.py graph --mermaid --direction LR

and paste the output verbatim into the fenced mermaid block. It emits the classDefs (canonical status colours), nodes, edges (terminal milestone convention) and class statements in the right order. Do not add, remove or recolour lines by hand.

8. Generate docs/reports/ROADMAP_OVERVIEW.md

# {Project} {Phase}: Roadmap Overview

**{N} tasks across {M} milestones.** Files: `.claude/roadmaps.json` (machine-readable), `docs/roadmaps/{PHASE}.md` (full task list with Mermaid dependency diagram).

> {Rescope/context note if relevant}

---

## What we're building
{2–3 paragraphs on the key deliverables and the reasoning behind the phase structure.}

## Milestone sequence and the reasoning behind it
{One paragraph per milestone.}

## Decisions that shaped the structure
{Key decisions that explain non-obvious choices.}

## External blockers (flag early)
{Dependencies on external parties, unconfirmed decisions, etc.}

The header task count must match roadmaps.json. Get it from python3 "$HOME"/.claude/library/scripts/roadmap.py stats rather than counting by hand.

9. Validate, confirm, and report

1. Run python3 "$HOME"/.claude/library/scripts/roadmap.py validate; it must report clean (dependsOn/blocks parity, acyclicity, status recompute). Fix any discrepancy before finishing.
2. Report the three paths created, the milestone and task counts (from roadmap.py stats), and the status breakdown.
3. Note any assumptions or areas needing user refinement.

Conventions

• ID format {MilestoneNum}{Category}.{Seq}; never reuse IDs.
• roadmaps.json is the source of truth; the PHASE file and overview are projections.
• Everything else (statuses, colours, graph rules, formatting): ~/.claude/library/references/roadmap-conventions.md.

These roadmaps are maintained by roadmap-maintain (status synchronisation) and roadmap-update-tasks (adding tasks). Old simple-format roadmaps are upgraded by roadmap-migrate; the HTML dashboard comes from artefact-roadmap (roadmap.py render).