roadmap-upkeep

Maintain a project's roadmap as data (roadmap.json with stages, items, status and evidence) so ROADMAP.md and the project website's Roadmap page stay true while you work. Use when starting, finishing or re-planning any piece of work, and when setting up a roadmap for a new project.

roadmap.json is the plan. It is a hybrid of two Knot Vector roadmaps:

  • 10Fold: work is grouped into stages, each delivered as a thin slice that works end to end.
  • Grey Goose Press: every item has a status and evidence. "Done" means there is proof: a merged PR, a passing test, a release, a screenshot.

tools/roadmap.cjs validates the file and generates ROADMAP.md. The website renders the same JSON. The full schema is in the header of roadmap.cjs, and a starter is in templates/data/roadmap.json.

The loop (do this as you work, not afterwards)#

  1. Starting work: set the item to active, and its stage to active if needed. Commit with the first change.
  2. Finishing work:
    • set the item to done,
    • add evidence: { "kind": "pr", "label": "Alt-SAMP/Engine#4", "url": "..." } plus the test result ({ "kind": "test", "label": "autotest mp 23/23" }),
    • set updated to today.
  3. Discovering new work: add a planned item to the right stage. Big new areas become a new planned stage.
  4. Blocked: set the item to blocked with detail saying on what or whom.
  5. Dropped: set the item to dropped, keep it, and say why in detail.
  6. Every time: run node tools/roadmap.cjs (regenerates ROADMAP.md) and node tools/roadmap.cjs --check, then commit both files with the work.

Writing good items#

  • Title names an outcome ("Players can sign in"), not a task ("Write AuthService").
  • Stage goal states what is true when the stage is done.
  • Future ideas: keep them as planned items, so the roadmap doubles as a reference for later development.

How you know it's right#

  • --check passes.
  • Every done item links proof.
  • The website's Roadmap page matches ROADMAP.md.