shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringAPI key requirement unconfirmed

track-roadmap

Plan, update, audit, and resume work from a high-level project roadmap. Use when asked to "create a roadmap", "plan features", "what should we build next", "update the roadmap", "audit the roadmap", "review project direction", "prioritize features", "resume from roadmap", "pick up where I left off", "what should I work on next", or when starting a new project and needing to map out future work.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

Track Roadmap

Overview

Maintain ROADMAP.md in the project root as a living, high-level feature plan, so decisions about what to build next are intentional, not reactive. Keep it to features (user-visible capabilities), not tasks — task-level work belongs in track-session. A healthy roadmap is 5-15 committed features readable in under 2 minutes.

Workflow

Every mode runs the same four beats — read the current state, propose a change, confirm with the user, write the file. Only the middle two differ:

| Mode | Command | Propose / confirm | |------|---------|-------------------| | Generate | /track-roadmap or generate | Offer a codebase scan, ask 4 discovery questions, propose a feature list, write after the user confirms | | Update | /track-roadmap update | Ask what changed (add/remove/complete/reword), apply after confirmation | | Audit | /track-roadmap audit | Scan code to mark each feature Done/In-Progress/Not-Started/Unclear, review relevance with the user, update | | Brainstorm | /track-roadmap brainstorm | Divergent ideation — explore directions before committing; viable ideas land in "Future Ideas" as status:idea | | Resume | /track-roadmap resume | Check session state, present remaining features, user picks one, hand off to /track-session |

Update is the common case: adding an item, marking one done, or logging shipped work all land there. There is no save mode — treat /track-roadmap save as Update. When the user asks to work through the whole roadmap, Resume takes the open features in file order, one session per feature, and moves to the next without asking once each session closes. In Update and Audit, edit the affected items in place rather than regenerating the file — ids, ordering, and untouched text survive, and a whole-file rewrite costs more tokens for the same result. Generate is the only mode that writes the file from scratch.

Full per-mode procedures (discovery questions, brainstorm question banks, audit steps): reference/MODES.md.

ROADMAP.md format

---
schema: cc-dash/roadmap@1
project: project-name-here
description: One-line project purpose
last_updated: YYYY-MM-DDTHH:MM:SS-TZ
---

# Roadmap

> Project purpose in one sentence.

## Core Features

<!-- category:core -->

- <!-- id:r_XXXXX status:planned --> **Feature Name** - What it does and why it matters.
  > Research finding, with its source link.
  > Open: the question still to settle.
- <!-- id:r_XXXXX status:in-progress started:YYYY-MM-DD --> **Feature Name** - Short description.

## Future Ideas

<!-- category:future -->

- <!-- id:r_XXXXX status:idea --> **Feature Name** - Short description.

## Completed

<!-- category:completed -->

- <!-- id:r_XXXXX status:done completed:YYYY-MM-DD --> ~~**Feature Name**~~ - Short description. *(Completed: YYYY-MM-DD)*

Format rules. The cc-dash dashboard parses this file, so a dropped marker silently removes the item from the board:

  • Frontmatter requires schema, project, description, last_updated.
  • Every item: an id and a status. Ids are r_ + 2–10 [a-z0-9_] chars and permanent — never change; new ones default to 5 random chars. Grep the file for a new id before writing it, because a duplicate makes two items indistinguishable on the board.
  • Statuses: idea / planned / in-progress / done, plus deferred (still wanted, not now) and dropped / skipped / rejected / cancelled when the user wants a record kept of why an item stopped instead of deleting it. The last four land in the board's Closed column.
  • Optional metadata: started: and completed: as YYYY-MM-DD, and depends:r_abc12,r_def34. cc-dash ignores any other date key (at:, done_date:) and deletes it on its next write, so convert those to completed: when you touch the item.
  • Every category heading gets <!-- category:slug --> on the next line. Categories themselves are flexible — invent whatever groups fit the project.
  • One line per feature: bold title + 1-2 sentence description.
  • Notes hold what the description can't: research findings with their source, open questions, and rejected alternatives with the reason. Write them as > lines directly under the item; cc-dash shows them on the card and keeps them through its own writes. Keep an item to about five note lines — when research outgrows that, move it to a file under docs/ and leave one note linking to it, because a roadmap that carries its research inline stops being readable in two minutes. Don't put notes in the description or in a second paragraph under the item; the dashboard reads neither.
  • When an item moves to Completed, cut its notes to what a later audit needs (the decision and why), since the research has done its job.

Rules

  • The user drives the roadmap — propose changes and wait for confirmation rather than adding, rewording, or removing features on your own judgment.
  • High-level only — "User authentication", not "Add bcrypt to hash passwords".
  • ROADMAP.md is the source of truth — if it's not in the file, it's not on the roadmap.
  • Completed features move, they don't disappear — relocate them to the Completed section with a completed: date instead of deleting, because audits use that history as evidence.

Examples

❌ Bad — - tasks / - lists / - make it look good / - fix bugs: no descriptions, no groupings, mixes features with tasks, no IDs or purpose. The format block above is the ✅ counterpart.

✅ Good — update mode, user says "dark mode shipped yesterday": keep the id, flip the status, add the date, move the line to Completed:

- <!-- id:r_j4t8v status:done completed:2026-03-14 --> ~~**Dark mode**~~ - System-level dark/light theme preference. *(Completed: 2026-03-14)*

Full ✅/❌ comparisons for generate, audit, update, brainstorm, and resume modes: reference/EXAMPLES.md.

Integration

  • track-session — after picking a feature, use track-session to plan and track the implementation; SESSION_PROGRESS.md references the ROADMAP item ID.
  • Hands-on verification (a playthrough, a parity gate, a release sign-off) is an ordinary roadmap item here — there is no separate checklist file, so nothing files back from one.

Gotchas

  • Renaming a feature keeps its id. Edit the title text but leave <!-- id:r_XXXXX --> alone — SESSION_PROGRESS.md roadmap_ref values and cc-dash history both point at it. On a merge, keep the surviving id; on a split, keep the original on one half and generate a new id for the other.
  • roadmap_ref holds exactly one id. cc-dash drops a comma list with a warning, which unlinks the session from the board. When one session advances several features, link the main one and name the rest in the session's ## Current Status.
  • Resume overwrites an active session plan. If SESSION_PROGRESS.md has uncompleted tasks, ask whether to continue it before presenting the roadmap; switching features replaces that file, so offer /track-session save first.
  • Ambiguous audit evidence is Unclear, not a guess. Partial or experimental code (a src/auth/ with no tests) gets surfaced to the user for a ruling rather than being scored Done.
  • A 30+ item roadmap is a signal, not a state to preserve. Audit it, move speculative entries to "Future Ideas" as status:idea, and delete what no longer fits — git holds the history, so in-file archiving just adds noise.
  • Roadmap drift is expected. When the file stops matching what's being built, run audit to reconcile rather than patching individual lines from memory.

Extended edge cases (codebase-scan noise, brainstorm dead ends, priority paralysis, tightening vague feature descriptions): reference/TROUBLESHOOTING.md.