minimap-roadmap
Skill2 starsChanged 14 days agoMITView on GitHub
Use when showing or updating roadmap state, or picking up, resuming, investigating, testing, reviewing, or completing assigned roadmap work in a repo with the minimap roadmap convention (board.md, scope.md, features/, ideas/). Not for arbitrary spec review.
In this repository4 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- agent-workflowSkill
- agent-workflowSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 8 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
When the user asks to see the roadmap, give them a URL.
- Distinctive: line 41
Read the files that own the truth before editing.
- Distinctive: line 45
When completed work affects a roadmap item, reconcile its state using Completion Reconciliation.
- Distinctive: line 59
When an assigned feature is named but its exact reference was not supplied, read its canonical roadmap item and resolve the tuple with …
- Distinctive: line 71
If only this skill is installed, the user can still drive the conversation through any other client (the running minimap server serves both …
- Distinctive: line 75
Do not create parallel roadmap trackers.
- Distinctive: line 76
Do not treat chat as the source of truth when roadmap files exist.
- Distinctive: line 77
Always pass the absolute repo path in the URL hash.
- Very specific: line 78
Do not curl the server, send signals, or edit $MINIMAP_HOME/server.json or its participant preference by hand.
- Very specific: line 79
If Minimap's documentation, CLI, HTTP API, server, UI, or lifecycle scripts fail or contradict documented behavior, load …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Minimap Roadmap
Roadmap files are the source of truth. The UI is a lens; agents and humans operate on the same files.
Quick Workflow
For assigned roadmap work, follow Agent Handoffs on pickup, resume, pause, handoff, and completion. Assigned implementation, investigation, testing, and substantive review qualify for optional Pallium participation when its MCP work-reference tools are available; passive browsing and clerical edits do not. Assignment alone does not require starting the server.
When the user asks to see the roadmap, give them a URL. When they ask to edit roadmap state, edit the files directly. Both paths share step 1.
1. Make sure the server is running
node <path-to-this-skill>/scripts/start-server.cjsThe launcher prints one line: Minimap running at http://localhost:<port> (just started) or Minimap already running at http://localhost:<port> (reused). Capture the port — default 4312, but the launcher falls forward if busy.
For status / stop / restart, see references/server.md.
Compatible APIs can reuse different releases. A refused start/restart is not permission to stop the shared server: inspect running/source identity and coordinate before explicitly replacing it with restart-server.mjs --replace-runtime.
2a. Showing the roadmap
Build the URL with the active repo's absolute path and reply with it:
http://localhost:<port>/#repo=<absolute-path-to-active-repo>&view=boardThe active repo is the directory the user is working in. Always pass an absolute path — the same server can serve any repo, switching is just a URL change.
2b. Editing roadmap state
- Find the roadmap root from
roadmap.config.json, or useroadmap/. - Read the files that own the truth before editing.
- Edit the smallest owning file set.
- Preserve unknown frontmatter and sections.
When completed work affects a roadmap item, reconcile its state using Completion Reconciliation.
For metadata-first roadmaps, keep classification in item metadata and the single shared traversal order in board.md. A membership move changes only metadata; moving to Unassigned removes that field rather than writing a placeholder; a metadata reorder uses visible before/after neighbors, preserves filtered-out items, and cannot silently cross freeform board groups. Configure group order with lenses.fields.<field>.order and optionally set the top-level defaultLens. An explicit board-view URL, including lens=board, overrides a remembered repository/mode view; a remembered grouping overrides defaultLens. Unknown URL or configured groupings fall back with a warning; removed remembered groupings fall back quietly. Do not perform automatic migration: check the installed skill version and follow the manual migration steps in references/roadmap-contract.md.
For ownership rules, item shape, board rules, and edit constraints, read references/roadmap-contract.md.
Pallium is optional: never install it, use shell/HTTP substitutes, or block ordinary Minimap work when its MCP work-reference tools are absent or unavailable.
Agent Handoffs
For assigned roadmap work, use the manager-designated shared checkout and make roadmap edits there; do not automatically sync changes across worktrees. On pickup or resume, confirm the canonical item id and read its current file and relevant roadmap state. On pause or handoff, report the exact item id, repository-relative item path, feature reference when available, changed files, and current worktree state, including any uncommitted work. The receiving agent re-reads the item and attaches its own Pallium association when applicable; the sender detaches only an association it attached and only after leaving the work. On completion, reconcile the owning roadmap item under Completion Reconciliation and report the resulting state and changed files. These notes do not transfer roadmap file ownership or imply an Agent Workflow requirement.
Feature references in handoffs
When an assigned feature is named but its exact reference was not supplied, read its canonical roadmap item and resolve the tuple with Minimap's existing CLI:
node <skill>/runtime/cli.js roadmap item-ref <item-id> --repo <absolute-repo-path> --jsonThe result supplies scope_ref and local_ref; carry provider: minimap and those exact returned values in the manager handoff. Do not reconstruct them from a title, branch, path, or item id. If repository or item identity cannot be resolved, say the source reference is unverified; do not report an empty source list or guess a tuple. When a supported Agent Workflow relationship capture procedure is available, pass the exact tuple to its Work Record capture/save/readback procedure at creation or transition. Agent Workflow owns the stored relationship and verification; this skill does not write a backlink or replace that procedure. Otherwise, continue ordinary roadmap work and the handoff without claiming a stored Work Record relationship. Pallium participation remains separately optional.
Composing With Spec Review
A roadmap item is just a markdown file. To open a review thread on one item (anchored comments, suggestions), attach the item file via the minimap-spec-review skill if it is installed alongside this one. Spec sessions never auto-mutate the file, so the layers compose safely.
If only this skill is installed, the user can still drive the conversation through any other client (the running minimap server serves both modes).
Guardrails
- Do not create parallel roadmap trackers.
- Do not treat chat as the source of truth when roadmap files exist.
- Always pass the absolute repo path in the URL hash; do not assume the running server is rooted in your repo.
- Do not curl the server, send signals, or edit
$MINIMAP_HOME/server.jsonor its participant preference by hand. Use the bundled scripts only. - If Minimap's documentation, CLI, HTTP API, server, UI, or lifecycle scripts fail or contradict documented behavior, load
references/upstream-feedback.md; otherwise do not load it.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

