agentleFS
rorerore/Pallium/.claude/skills/minimap-roadmap/SKILL.md

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.

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
  1. Distinctive:

    When the user asks to see the roadmap, give them a URL.

    line 14
  2. Distinctive:

    Read the files that own the truth before editing.

    line 41
  3. Distinctive:

    When completed work affects a roadmap item, reconcile its state using Completion Reconciliation.

    line 45
  4. Distinctive:

    When an assigned feature is named but its exact reference was not supplied, read its canonical roadmap item and resolve the tuple with …

    line 59
  5. Distinctive:

    If only this skill is installed, the user can still drive the conversation through any other client (the running minimap server serves both …

    line 71
  6. Distinctive:

    Do not create parallel roadmap trackers.

    line 75
  7. Distinctive:

    Do not treat chat as the source of truth when roadmap files exist.

    line 76
  8. Distinctive:

    Always pass the absolute repo path in the URL hash.

    line 77
  9. Very specific:

    Do not curl the server, send signals, or edit $MINIMAP_HOME/server.json or its participant preference by hand.

    line 78
  10. Very specific:

    If Minimap's documentation, CLI, HTTP API, server, UI, or lifecycle scripts fail or contradict documented behavior, load …

    line 79

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.cjs

The 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=board

The 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

  1. Find the roadmap root from roadmap.config.json, or use roadmap/.
  2. Read the files that own the truth before editing.
  3. Edit the smallest owning file set.
  4. 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> --json

The 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.json or 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.