# Roadmap Visualizer > Maintain a project's roadmap as a single canonical ROADMAP.md and render it as a scannable visual — a diagram plus a status table — instead of a wall of text. ROADMAP.md is the required source of truth: this skill always reads it before rendering and always writes changes back to it, so the plan never drifts into scattered chat messages. If no ROADMAP.md exists yet, it creates one. It picks the right diagram for the roadmap's shape: a flowchart for dependency- or evidence-gated sequences, a Gantt for time-bound plans, swimlanes for parallel workstreams. Use this whenever the user says "roadmap", "show roadmap", "where are we", "what's the plan", "status", "what's left", "update the roadmap", "visualise progress", "/roadmap", or "/status" — and proactively when a long discussion has changed the plan and the roadmap should be refreshed. Especially useful in long or multi-session chats where both the user and the assistant lose track of the plan. - Skill: `oldvictech/roadmap-visualizer` (Agent Skill) - Install (CLI): `npx skillmds@latest add oldvictech/roadmap-visualizer` - Raw SKILL.md: https://api.skillmd.com/api/skills/oldvictech/roadmap-visualizer/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: Oldvictech (https://skillmd.com/u/oldvictech) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/oldvictech/roadmap-visualizer --- # Roadmap Visualizer Keeps one canonical roadmap file and turns it into a visual that can be read in seconds. It fights the wall-of-text problem — so it must not reproduce the wall. ## Operating principle **`ROADMAP.md` is the single source of truth — not the chat, not this skill.** Every render reads it first. Every agreed change is written back to it immediately. The chat is where the roadmap is discussed; `ROADMAP.md` is where it lives. These must never drift apart. --- ## The canonical file: ROADMAP.md The skill reads and writes this exact structure so the file stays machine-reliable and human-readable. The **status table is the canonical data**; the diagram is a generated view of it (regenerated from the table on every change, so they can't disagree). ```markdown # Project Roadmap _Last updated: YYYY-MM-DD · ROADMAP.md is the source of truth for project sequencing._ ## Shape ## Diagram ## Status | # | Item | Status | Gated on / Next | |---|------|--------|-----------------| | 1 | ... | ✅ Done | — | | 2 | ... | 🔄 In flight | ... | | 3 | ... | ⏳ Pending | depends on #2 | | 4 | ... | ❌ Blocked | blocker: ... | | 5 | ... | 🅿️ Parked | ... | ## Constraints / Invariants - ## Amendment log - YYYY-MM-DD: ``` Status legend: ✅ done · 🔄 in flight · ⏳ pending · ❌ blocked · 🅿️ parked --- ## Step 1 — Ensure ROADMAP.md exists, then read it 1. Look for `ROADMAP.md` (project root, or wherever the project keeps it). 2. **If it does not exist, create it** (see "First run" below) — the roadmap must be a durable file, not chat scrollback. 3. Read it fully before rendering. Render only what it states. If `ROADMAP.md` and the recent conversation **disagree** (common when work happens across more than one channel or session), surface the discrepancy plainly and ask which is current — do not silently pick one, and do not overwrite the file until the user resolves it. --- ## Step 2 — Diagnose the roadmap's shape (this picks the diagram) Record the shape in the `## Shape` field. The wrong diagram misrepresents the plan, so choose by what actually drives sequencing: | If the plan is driven by… | …it is a | …render as | |---|---|---| | dependencies or evidence gates ("X only after Y proves out") | gated sequence | **flowchart** with gate edges | | dates and durations | time-bound plan | **Gantt** | | several tracks progressing in parallel | multi-stream | **swimlanes** (flowchart LR + subgraphs) | | a branching decision ("if A then B else C") | decision tree | **flowchart** with decision nodes | | a simple list of states (todo/doing/done) | status board | **table only**, no diagram | When ambiguous, ask ONE question before drawing. Never default to a dated Gantt — timelines invent precision that gated sequences don't have. --- ## Step 3 — Render (and write back) On render, output the **diagram + status table** to the chat. On any change, also update `ROADMAP.md`: edit the Status table, regenerate the Diagram from it, bump `Last updated`, and append an Amendment-log line. ### Diagram — examples by shape **Gated sequence (flowchart):** ```mermaid flowchart TD classDef done fill:#A7D8A7,stroke:#2E7D32,color:#1B3D1B classDef active fill:#FFE08A,stroke:#C79100,color:#3D3000 classDef pending fill:#E0E0E0,stroke:#9E9E9E,color:#333 classDef blocked fill:#F5C6C6,stroke:#C62828,color:#3D1414 A["Phase 1"]:::done --> B["Phase 2"]:::active B -. "gate: only if
Phase 2 proves out" .-> C["Phase 3"]:::pending ``` **Time-bound plan (Gantt):** ```mermaid gantt title Roadmap dateFormat YYYY-MM-DD section Track Phase 1 :done, p1, 2026-01-01, 2026-01-20 Phase 2 :active, p2, after p1, 21d Phase 3 : p3, after p2, 14d ``` **Parallel workstreams (swimlanes):** ```mermaid flowchart LR subgraph S1 [Stream A] A1[Task] --> A2[Task] end subgraph S2 [Stream B] B1[Task] --> B2[Task] end ``` Set each node's status class to match the table. Keep node labels ≤6 words. ### Constraints / invariants If `ROADMAP.md` carries standing constraints (locked decisions, immutable items, guardrails), echo a short list under the render so they stay visible. Omit if none. --- ## /status — compact view Quick check, no diagram, one screen. Still read from `ROADMAP.md`: ``` NOW: [what's in flight] DONE: [recently completed] NEXT: [the immediate next action] GATED: [what's waiting, and on what] BLOCKED: [anything stuck, and why] ``` --- ## First run — creating ROADMAP.md If no `ROADMAP.md` exists when the skill is triggered: 1. Say so: "No ROADMAP.md yet — I'll create one from this discussion." 2. Extract decisions, phases, priorities, and any stated constraints from the conversation (or from a handover/plan doc the user points to). 3. Diagnose the shape (Step 2). 4. Draft `ROADMAP.md` in the canonical structure above and show it for confirmation. 5. On confirmation, save it. From here on it is the source of truth — the chat and this skill defer to it. If the project already keeps its roadmap inside another document (e.g. a handover file), recommend migrating it into `ROADMAP.md` and having the other document reference it — one canonical location, to avoid two roadmaps that drift. --- ## Amendment discipline (when the plan changes) When a decision in conversation changes the roadmap: 1. Show the BEFORE state of only the affected rows. 2. State the change and apply it. 3. Update `ROADMAP.md`: edit the table, regenerate the diagram, bump `Last updated`, append an Amendment-log line (`YYYY-MM-DD: what changed and why`). 4. Re-render to the chat. Never change the roadmap silently. Never delete rows — mark them 🅿️ parked or cancelled with a reason. Never rephrase a decision differently from how the user stated it. --- ## Proactive trigger Don't always wait to be asked. Offer a refresh when: - a decision shifts a phase, dependency, or priority, - an item is confirmed done or newly blocked, - the discussion has run long without the roadmap in view. Offer in one line ("That moves Phase 3 — want me to update ROADMAP.md?") and wait for confirmation before writing the file. --- ## Rules - `ROADMAP.md` is the source of truth; read it first, write changes back every time. - The status table is canonical; the diagram is a generated view — keep them in sync. - Match the diagram to the roadmap's shape; never default to a dated Gantt. - Surface ROADMAP.md-vs-conversation disagreements; don't resolve them silently. - Keep chat output visual and short — don't reproduce the wall of text. - This skill visualises and maintains the roadmap. It is not a handoff tool and not a spec/prompt drafter — defer to dedicated skills or processes for those.