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)#
- Starting work: set the item to
active, and its stage toactiveif needed. Commit with the first change. - 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
updatedto today.
- set the item to
- Discovering new work: add a
planneditem to the right stage. Big new areas become a newplannedstage. - Blocked: set the item to
blockedwithdetailsaying on what or whom. - Dropped: set the item to
dropped, keep it, and say why indetail. - Every time: run
node tools/roadmap.cjs(regeneratesROADMAP.md) andnode 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
goalstates what is true when the stage is done. - Future ideas: keep them as
planneditems, so the roadmap doubles as a reference for later development.
How you know it's right#
--checkpasses.- Every
doneitem links proof. - The website's Roadmap page matches
ROADMAP.md.