Skip to content
Back to search

wayfinder-maps

Planetary visualization tool for /wayfinder maps

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/rengwu--wayfinder-maps/badge.svg)](/listings/rengwu--wayfinder-maps)

HTML

<a href="/listings/rengwu--wayfinder-maps"><img src="/api/listings/rengwu--wayfinder-maps/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](https://github.com/mattpocock/skills); the copies under [`skills/`](skills/) are MIT-licensed adaptations.

Skills, drop-in for any harness

Copy [`skills/`](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/`](skills/.optional/) too — [`skills/README.md`](skills/README.md) describes the full set.

The binary

- Download from [Releases](https://github.com/rengwu/wayfinder-maps/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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 15 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "wayfinder-maps",
  3. "description": "The wayfinder planning method as a Claude Code plugin: map big foggy efforts as investigation tickets under .plan/, one decision per session.",
  4. "owner": {
  5. "name": "John Goh",
  6. "url": "https://github.com/rengwu"
  7. },
  8. "plugins": [
  9. {
  10. "name": "wayfinder-maps",
  11. "source": "./",
  12. "description": "Plan huge, foggy efforts as a shared map of investigation tickets (.plan/), plus the skills the method leans on. Original skills by Matt Pocock (github.com/mattpocock/skills). The repo also ships the read-only map viewer binary."
  13. }
  14. ]
  15. }
README.md · README · 224 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <img src="https://i.imgur.com/jv8Bhu0.png" alt="demo app: one wayfinder map at a moment">
  2. # wayfinder-maps
  3. A read-only CLI and viewer for
  4. [wayfinder](https://github.com/mattpocock/skills/tree/main/skills/engineering/wayfinder)
  5. maps — the markdown planning memory an agent leaves under `.plan/<effort>/` as it charts
  6. a large effort as a graph of investigation tickets. The wayfinder method and its skills
  7. were created by [Matt Pocock](https://github.com/mattpocock); this repo adapts them and
  8. adds the tooling.
  9. - **`wayfinder-maps status <dir>`** — what is resolved, what is in flight, and what is ready
  10. to claim (the _frontier_: open, unclaimed, every blocker resolved).
  11. - **`wayfinder-maps lint <dir>`** — does the map still tell the truth?
  12. - **`wayfinder-maps serve` / `app`** — the map as a star-map, in a browser or a native window
  13. ([design notes](docs/starmap-design.md)).
  14. - **[`scripts/wayfinder-pull`](scripts/wayfinder-pull)** — a map kept as GitHub issues,
  15. mirrored into `.plan/` so the three commands above read it unchanged.
  16. ```
  17. $ wayfinder-maps status ../expensif/.plan/daily-timeline
  18. Daily Timeline — continuous days, empty days included
  19. 6 resolved · 0 claimed · 4 open · 0 out of scope
  20. Frontier — ready to claim, first by number wins:
  21. 05 Should HandleDaily's two branches converge grilling
  22. 06 Contain the day-card chrome drift grilling
  23. 07 The infinite-scroll island's contract grilling
  24. 10 Test strategy for the date-indexed timeline grilling
  25. Undermined — resolved on a premise that later changed:
  26. 02 Window size and how older days load broken by 08
  27. Fog: 5 patches, 1 anchored to a ticket
  28. ```
  29. ## Install
  30. ### Skills, as a Claude Code plugin
  31. ```
  32. /plugin marketplace add rengwu/wayfinder-maps
  33. /plugin install wayfinder-maps@wayfinder-maps
  34. ```
  35. `/wayfinder-maps` then works in every project; the map lands in that project's `.plan/`. The
  36. plugin bundles `wayfinder-maps` plus the four skills it invokes by name — `grill-me`,
  37. `research`, `prototype`, `domain-modeling`. All five were originally authored by Matt
  38. Pocock in [mattpocock/skills](https://github.com/mattpocock/skills); the copies under
  39. [`skills/`](skills/) are MIT-licensed adaptations.
  40. ### Skills, drop-in for any harness
  41. Copy [`skills/`](skills/) into your project and tell your agent to read
  42. `skills/wayfinder-maps/SKILL.md` and follow it; the skills it names live alongside.
  43. You may include any of the extras under [`skills/.optional/`](skills/.optional/) too —
  44. [`skills/README.md`](skills/README.md) describes the full set.
  45. ### The binary
  46. - Download from [Releases](https://github.com/rengwu/wayfinder-maps/releases) — no Go
  47. toolchain needed, native window and folder dialog on all three platforms. macOS uses
  48. WKWebView (part of the OS); Windows uses WebView2 (ships with Windows 10/11); the
  49. Linux archive bundles a small helper that binds the system webkit —
  50. `libwebkit2gtk-4.1`, preinstalled on most desktops, one
  51. `sudo apt install libwebkit2gtk-4.1-0` otherwise. `status` and `lint` need nothing
  52. installed at all, even headless. The macOS and Linux archives also carry two
  53. double-clickable launchers — `wayfinder-app` opens the native window, `wayfinder-web`
  54. starts the server and opens your browser — no terminal needed (`.command` on macOS).
  55. - `go install github.com/rengwu/wayfinder-maps/cmd/wayfinder-maps@latest`
  56. Skill and binary are independent — each just reads the on-disk contract.
  57. ## Why
  58. The map is shared memory: sessions orient to it before choosing work, and when it drifts
  59. it lies to them silently. The skill makes most drift unrepresentable and verifies each
  60. session's delta, no tool assumed. What a delta check cannot see is an edit made outside
  61. the protocol, or two parallel sessions taking the same ticket number. `lint` is `fsck`
  62. for those: it runs after the fact and re-establishes the base the next session rests on.
  63. ## The format contract
  64. The contract is the skill's local-markdown adapter,
  65. [`TRACKER-MARKDOWN.md`](skills/wayfinder-maps/TRACKER-MARKDOWN.md) — the skill itself is
  66. tracker-agnostic method. This tool implements that adapter; any other reader should
  67. target the same file. In summary: structure the facts, leave the prose alone. A ticket's
  68. type and edges have exactly one correct value a machine can check. Its **Question** and
  69. **Answer**, the map's **Destination** and **Notes**, and each one-line gist in
  70. Decisions-so-far are lossy prose, never parsed.
  71. A ticket is `.plan/<effort>/tickets/NN-<slug>.md`:
  72. ```markdown
  73. ---
  74. type: research | prototype | grilling | task
  75. blocked_by: [02, 03] # [] when none
  76. claimed_by: <session id> # while a session holds it
  77. claimed_at: 2026-07-10T09:00:00Z # RFC 3339, alongside claimed_by
  78. undermined_by: [08] # optional — resolved on a premise 08 later broke
  79. assets: [../assets/x.html.approved] # optional
  80. ---
  81. # <Ticket title>
  82. ## Question
  83. …
  84. ## Answer # its presence _is_ the resolution
  85. …
  86. ```
  87. ### Status is derived
  88. There is no `status:` field — every value it could hold is already written in the file,
  89. and a second copy is free to go stale:
  90. | Derived status | When |
  91. | -------------- | --------------------------------------------------- |
  92. | `resolved` | the body has an `## Answer` **with prose under it** |
  93. | `out_of_scope` | the body has a `## Ruled out` with prose under it |
  94. | `claimed` | neither, and `claimed_by` is set |
  95. | `open` | none of the above |
  96. Closure is read first, so a `claimed_by` left on a closed ticket is inert litter. And it
  97. is the prose, not the heading, that closes a ticket: a session that types `## Answer` and
  98. dies has resolved nothing — the ticket stays claimed, and its claim goes stale on
  99. schedule. `lint` errors on the empty heading outright.
  100. **`undermined_by`** marks a decision whose premise a later ticket broke; without it a
  101. renderer paints the node green and launders a live problem into a checkmark.
  102. **`claimed_at`** separates a dead session from live work. And `out_of_scope` stays
  103. distinct from `resolved` — a scope boundary is not a step on the route, and a parser that
  104. lumps them in over-counts.
  105. ### Fenced code blocks are not structure
  106. Every scan — headings, titles, bullets, links — ignores what sits inside a ` ``` ` or
  107. `~~~` fence. A ticket that quotes the ticket format contains the line `## Answer`, and
  108. must not thereby resolve itself. The rule cuts one way only: an answer whose entire body
  109. is a code fence is still an answer. Any other reader of these files owes the same rule.
  110. ### One session at a time
  111. The adapter forbids concurrent sessions: git merges a duplicate ticket number cleanly and
  112. neither session can see it. `lint` still reports duplicates, because a merge can happen
  113. anyway.
  114. Fog patches in the map's `## Not yet specified` are bullets with a bolded lead title and
  115. an optional anchor; the rest stays loose prose:
  116. ```markdown
  117. - **Today's row.** Whether today is visually distinguished. <clears-with: 04>
  118. ```
  119. ## Checks
  120. Errors: dangling or self `blocked_by`; `blocked_by` cycles; duplicate ticket numbers; a
  121. ticket carrying both `## Answer` and `## Ruled out`; a closing heading with nothing under
  122. it; a resolved ticket missing from Decisions-so-far; an out-of-scope ticket listed as a
  123. decision, or missing from Out-of-scope; Decisions-so-far pointing at an unresolved
  124. ticket; a fog patch duplicating a live ticket's title, or anchored to a resolved ticket;
  125. a missing Destination; an unknown type; a leftover `status:` field that disagrees with
  126. the body.
  127. Warnings: loose (pre-frontmatter) headers; a `status:` field that merely duplicates the
  128. body; a claim with no owner or older than 72h; a claim left on a closed ticket; a ticket
  129. blocked by something out of scope, which can never unblock.
  130. Checks that need judgment — does a gist say what its answer says, does a fog title
  131. duplicate a live ticket _in substance_ — stay with the skill; no parser can make them.
  132. Exit `0` clean, `1` errors found, `2` no map at that path.
  133. ## Reading legacy maps
  134. Two older shapes still parse, each lints as a warning, and neither is written any more:
  135. - the loose header (`Type:` / `Status:` / `Blocked by:` after the H1), from before
  136. frontmatter;
  137. - a stored `status:` field, from before status was derived. Where it agrees with the
  138. body, `lint` says to delete it; where it disagrees, that is an error and the body wins.
  139. ## Maps kept as GitHub issues
  140. The wayfinder skill is tracker-agnostic: the same method can leave its map in an issue
  141. tracker rather than in `.plan/`. [`scripts/wayfinder-pull`](scripts/wayfinder-pull) mirrors
  142. such a map back into the local layout, so `status`, `lint` and the viewer read it with no
  143. change to the reader — the tool still only knows about files.
  144. ```
  145. scripts/wayfinder-pull <owner/repo> <map-issue-number> [out-dir]
  146. ```
  147. It needs [`gh`](https://cli.github.com) (already logged in) and `jq`; there is no token to
  148. configure. The default out-dir is `.plan/<slug of the map's title>`, wiped and rewritten on
  149. each run — a cache, not a source, so nothing in it should be hand-edited and the directory
  150. belongs in the host repo's `.gitignore`.
  151. The mapping follows the GitHub adapter in the skill's setup notes.
  152. Two adjustments make the round trip parse. Headings inside a resolve comment are demoted one
  153. level, since a comment opening with its own `##` would otherwise end the `## Answer` section
  154. before any prose landed and leave the ticket unresolved. And the map body's ticket references
  155. — issue URLs — are rewritten to `./tickets/NN-<slug>.md`, which is the only form
  156. Decisions-so-far is scanned for; `## Decisions so far` and `## Out of scope` are generated
  157. only when the map body carries no section of that name.
  158. The mirror is one-directional and is a snapshot: claiming or resolving in the viewer changes
  159. nothing in the tracker, and a change made there shows up on the next pull. `undermined_by`
  160. has no GitHub representation, so a mirrored map never paints an undermined node.
  161. ## Build from source
  162. ```
  163. go build ./cmd/wayfinder-maps # pure Go: status, lint, serve
  164. go test ./...
  165. ```
  166. The native window needs cgo on macOS (WKWebView); Windows is pure Go (WebView2). On
  167. Linux the webkit linkage lives in a separate helper, `./cmd/wayfinder-maps-webview`,
  168. built with `libwebkit2gtk-4.1-dev` and kept next to the main binary. Releases are cut
  169. by tagging `v*` — CI builds the helper on Linux runners and GoReleaser packs everything.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.