# Roadmap Visualizer

> >

- **Type:** Skill
- **Install:** `agentstack add skill-oldvictech-session-continuity-roadmap-visualizer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Oldvictech](https://agentstack.voostack.com/s/oldvictech)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Oldvictech](https://github.com/Oldvictech)
- **Source:** https://github.com/Oldvictech/session-continuity/tree/main/roadmap-visualizer

## Install

```sh
agentstack add skill-oldvictech-session-continuity-roadmap-visualizer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 ifPhase 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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Oldvictech](https://github.com/Oldvictech)
- **Source:** [Oldvictech/session-continuity](https://github.com/Oldvictech/session-continuity)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-oldvictech-session-continuity-roadmap-visualizer
- Seller: https://agentstack.voostack.com/s/oldvictech
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.