Skip to content
Back to search

roadmap

SkillWorks with Claude CodeGitHub

Build a living, AI-era roadmap of how Ryan's apps and projects have progressed — derived from claude-mem, shiplog and git history instead of a hand-written plan. Produces a self-updating local dashboard (Gantt lanes, momentum, ships, explore-vs-execute, agent mix, decisions) plus a director-level 16:9 deck view (print to PDF). Use when the user says "roadmap", "gantt", "portfolio review", "exec deck of my projects", "how have my projects progressed", "project timeline", "director deck", or invokes /roadmap. Not for a quick status check (that's `minimize`).

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ryanramtin--roadmap-skill/badge.svg)](/listings/ryanramtin--roadmap-skill)

HTML

<a href="/listings/ryanramtin--roadmap-skill"><img src="/api/listings/ryanramtin--roadmap-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone --depth 1 https://github.com/ryanramtin/roadmap-skill.git ~/.claude/skills/roadmap

Then ask your agent:

roadmap

or `portfolio review`, `exec deck of my projects`, `project timeline`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 70 lines
  1. ---
  2. name: roadmap
  3. description: Build a living, AI-era roadmap of how Ryan's apps and projects have progressed — derived from claude-mem, shiplog and git history instead of a hand-written plan. Produces a self-updating local dashboard (Gantt lanes, momentum, ships, explore-vs-execute, agent mix, decisions) plus a director-level 16:9 deck view (print to PDF). Use when the user says "roadmap", "gantt", "portfolio review", "exec deck of my projects", "how have my projects progressed", "project timeline", "director deck", or invokes /roadmap. Not for a quick status check (that's `minimize`).
  4. ---
  5. # Roadmap — the derived, self-updating kind
  6. Old roadmaps were **declared**: someone drew bars and then the work drifted away from them.
  7. With agents doing the building, the record of what happened already exists. Every
  8. observation, ship, decision and commit is logged. So this roadmap is **derived** from that record:
  9. - **Lanes** = real activity spans (git commits where a repo exists, claude-mem otherwise).
  10. - **Milestones** = `feature`/`decision` observations; **ships** = shiplog entries (shipped vs held).
  11. - **Next** = the agents' own `next_steps` from session summaries, which in effect is the backlog.
  12. - **How it got built** = explore-vs-execute ratio (discoveries vs build work), agent mix (claude/opencode/codex), and the decision log.
  13. - **Honesty**: the page shows the share of activity it couldn't attribute to a project and flags suspected backfill bursts.
  14. Data stays computed (scripts). Opus adds only the **director narrative**: takeaway titles, now/next/risks.
  15. ## Files
  16. ```
  17. ~/.claude/skills/roadmap/
  18. aliases.json project canonicalization + repo paths + junk buckets (edit freely)
  19. scripts/collect.py claude-mem (read-only SQL) + shiplog + git → roadmap.json + digest.md (redacts private text)
  20. scripts/render.py roadmap.json (+ narrative.json) → index.html (Dashboard + Deck views, self-contained)
  21. scripts/serve.py 127.0.0.1-only live server; rebuilds only when sources changed (cheap fingerprint check every N s, default 900), /refresh forces; page polls /roadmap.json
  22. scripts/build.sh collect + render in one go
  23. ```
  24. ## Workflow
  25. 1. **Build the data** (default window 180d; pass `--since 90d` etc.):
  26. ```bash
  27. OUT=~/.roadmap # durable default; or a scratchpad dir for one-offs
  28. bash ~/.claude/skills/roadmap/scripts/build.sh "$OUT"
  29. ```
  30. 2. **Read `$OUT/digest.md`** (compact, bounded). Don't read roadmap.json raw unless you need to.
  31. 3. **Write `$OUT/narrative.json`** as the director (Opus does this, not a sub-agent):
  32. ```json
  33. {"headline": "…one sentence, the takeaway…",
  34. "exec_bullets": ["…", "…", "…"],
  35. "projects": {"Ok Stewie": {"headline": "…", "now": "…", "next": "…", "risks": ["…"]}},
  36. "closing": {"decisions": ["…"], "next": ["…"]}}
  37. ```
  38. Rules: slide titles state a **takeaway**, never a label ("NxtSteps went quiet after the v2 cutover", not "NxtSteps"). Be specific, use the numbers, and don't invent anything not in the digest. If a project is unclear, leave it out and let the fallback text stand. render.py works without this file.
  39. 4. **Render**: `python3 ~/.claude/skills/roadmap/scripts/render.py --out "$OUT"` → `$OUT/index.html`.
  40. 5. **Look at it.** Screenshot both views (headless Chrome: `"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless --screenshot=… --window-size=1600,1000 file://…`, or the playwright skill). Check Gantt overlap, label overflow, empty lanes. Fix, then re-render.
  41. 6. **Live mode** (the "dashboard that updates itself"):
  42. ```bash
  43. python3 ~/.claude/skills/roadmap/scripts/serve.py --out "$OUT" --port 8797 --interval 900
  44. # open http://127.0.0.1:8797 (Deck view: toggle top-right, or #deck)
  45. ```
  46. Run it in the background (`run_in_background`) if the user wants it up. For always-on, offer a launchd agent and only install it if they say yes. The narrative stays from the last time Opus wrote it, and the numbers keep refreshing.
  47. 7. **Sharing**: the deck prints to PDF (one slide per page, landscape). Offer an Artifact publish in one line. **Don't auto-publish**, since this is personal cross-project data.
  48. ## Focus mode (one project, split into workstreams)
  49. ```bash
  50. python3 scripts/collect.py --out ~/.roadmap/ok-stewie --since 2026-07-01 \
  51. --aliases focus-ok-stewie.json --title "Ok Stewie Roadmap"
  52. python3 scripts/render.py --out ~/.roadmap/ok-stewie
  53. # live: serve.py --out ~/.roadmap/ok-stewie --aliases focus-ok-stewie.json --title "Ok Stewie Roadmap"
  54. ```
  55. A focus file is a lane map like aliases.json, with `drop_patterns: [".*"]` so everything else stays off the board. KPIs, momentum and agent mix are scoped to the listed lanes, and the copy says "workstreams". Write the focus narrative into that out dir. Copy `focus-ok-stewie.json` to make one for another project.
  56. ## Hard rules
  57. - **Privacy:** collect.py drops SAM / companion / private-mode text by default (patterns in gitignored `denylist.local.txt` at the skill root, one regex per line; collect.py refuses to run if it is missing or empty; redacted items still count in every total, only their text is withheld), and masks emails, phones and tokens. Never pass `--no-redact` when the output will be published. SAM content never goes into Artifacts.
  58. - **Read-only:** the claude-mem DB opens with `mode=ro` and git is `log` only. Never write to repos, ATTIC or the mem DB.
  59. - **Bounded:** at most 14 Gantt lanes (the rest roll into "Other") and at most 8 project slides.
  60. - If attribution coverage is low, say so in the exec summary. Don't hide it. Improve it by adding `keywords` and `exact` names to aliases.json.
  61. - Voice to Ryan: punk-stoner. Deck copy stays crisp and executive.
README.md · README · 37 lines
  1. # roadmap
  2. A living, derived roadmap for people who build with AI agents — instead of a hand-drawn plan that drifts.
  3. It reads what already happened: your agent memory (claude-mem), your ship log, and your git history. Then it renders a local dashboard with Gantt lanes, momentum, ships vs held, explore-vs-execute ratio, agent mix, and the decision log, plus a director-level 16:9 deck view you can print to PDF.
  4. ## Install
  5. ```bash
  6. git clone --depth 1 https://github.com/ryanramtin/roadmap-skill.git ~/.claude/skills/roadmap
  7. ```
  8. Then ask your agent:
  9. ```
  10. roadmap
  11. ```
  12. or `portfolio review`, `exec deck of my projects`, `project timeline`.
  13. ## What it produces
  14. - **Lanes** — real activity spans from git and agent memory, per project.
  15. - **Milestones and ships** — features, decisions, and shipped/held work.
  16. - **Next** — the agents' own next steps, which is effectively your live backlog.
  17. - **How it got built** — explore vs execute, agent mix, decision log.
  18. - **Honesty panel** — the share of activity it could not attribute, and any suspected backfill bursts.
  19. ## Requirements
  20. - Python 3 (standard library only)
  21. - Optional: [shiplog](https://github.com/ryanramtin/shiplog) for ship data
  22. - Optional: a claude-mem database for agent memory
  23. Everything runs locally. Nothing is uploaded. Private text is redacted before it reaches the page.
  24. MIT licensed. Use it, change it, ship it.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.