Wayfinder Maps

wayfinder-maps

A read-only CLI and viewer for wayfinder maps — the markdown planning memory an agent leaves under .plan/<effort>/ as it charts a large effort as a graph of investigation tickets. The wayfinder method and its skills were created by Matt Pocock; this repo adapts them and adds the tooling.

• wayfinder-maps status <dir> — what is resolved, what is in flight, and what is ready to claim (the frontier: open, unclaimed, every blocker resolved).
• wayfinder-maps lint <dir> — does the map still tell the truth?
• wayfinder-maps serve / app — the map as a star-map, in a browser or a native window (design notes).

$ wayfinder-maps status ../expensif/.plan/daily-timeline
Daily Timeline — continuous days, empty days included
6 resolved · 0 claimed · 4 open · 0 out of scope

Frontier — ready to claim, first by number wins:
  05  Should HandleDaily's two branches converge      grilling
  06  Contain the day-card chrome drift               grilling
  07  The infinite-scroll island's contract           grilling
  10  Test strategy for the date-indexed timeline     grilling

Undermined — resolved on a premise that later changed:
  02  Window size and how older days load             broken by 08

Fog: 5 patches, 1 anchored to a ticket

Install

Skills, as a Claude Code plugin

/plugin marketplace add rengwu/wayfinder-maps
/plugin install wayfinder-maps@wayfinder-maps

/wayfinder-maps then works in every project; the map lands in that project's .plan/. The plugin bundles wayfinder-maps plus the four skills it invokes by name — grill-me, research, prototype, domain-modeling. All five were originally authored by Matt Pocock in mattpocock/skills; the copies under skills/ are MIT-licensed adaptations.

Skills, drop-in for any harness

Copy skills/ into your project and tell your agent to read skills/wayfinder-maps/SKILL.md and follow it; the skills it names live alongside. You may include any of the extras under skills/.optional/ too — skills/README.md describes the full set.

The binary

• Download from Releases — no Go toolchain needed, native window and folder dialog on all three platforms. macOS uses WKWebView (part of the OS); Windows uses WebView2 (ships with Windows 10/11); the Linux archive bundles a small helper that binds the system webkit — libwebkit2gtk-4.1, preinstalled on most desktops, one sudo apt install libwebkit2gtk-4.1-0 otherwise. status and lint need nothing installed at all, even headless. The macOS and Linux archives also carry two double-clickable launchers — wayfinder-app opens the native window, wayfinder-web starts the server and opens your browser — no terminal needed (.command on macOS).
• go install github.com/rengwu/wayfinder-maps/cmd/wayfinder-maps@latest

Skill and binary are independent — each just reads the on-disk contract.

Why

The map is shared memory: sessions orient to it before choosing work, and when it drifts it lies to them silently. The skill makes most drift unrepresentable and verifies each session's delta, no tool assumed. What a delta check cannot see is an edit made outside the protocol, or two parallel sessions taking the same ticket number. lint is fsck for those: it runs after the fact and re-establishes the base the next session rests on.

The format contract

The contract is the skill's local-markdown adapter, TRACKER-MARKDOWN.md — the skill itself is tracker-agnostic method. This tool implements that adapter; any other reader should target the same file. In summary: structure the facts, leave the prose alone. A ticket's type and edges have exactly one correct value a machine can check. Its Question and Answer, the map's Destination and Notes, and each one-line gist in Decisions-so-far are lossy prose, never parsed.

A ticket is .plan/<effort>/tickets/NN-<slug>.md:

---
type: research | prototype | grilling | task
blocked_by: [02, 03] # [] when none
claimed_by: <session id> # while a session holds it
claimed_at: 2026-07-10T09:00:00Z # RFC 3339, alongside claimed_by
undermined_by: [08] # optional — resolved on a premise 08 later broke
assets: [../assets/x.html.approved] # optional
---

# <Ticket title>

## Question

…

## Answer # its presence _is_ the resolution

…

Status is derived

There is no status: field — every value it could hold is already written in the file, and a second copy is free to go stale: