Wayfinder - planning huge multi-session work with agents
- YT :: https://www.youtube.com/watch?v=F3lL98Pj90o
- Original title :: /wayfinder: Nothing is too big to plan anymore
Matt Pocock presents Wayfinder, a single agent skill (in his skills repo, works with any coding agent) for planning work too big for one context window. It charts a "map" of tickets in the issue tracker - research, prototype, grilling and real-world task tickets - each worked in its own session, with blocking relationships and a tracked frontier of decidable items versus fog. When the map is done it becomes a spec, then implementation tickets.
Why single-session planning is not enough
Grilling skills are tied to one session and to the smart zone of the context window. Big work forces you to pre-slice it, and you hit questions you cannot answer and get lost in fog. Wayfinder models planning as a map from a vague start to a destination, where each step on the map is a ticket needing its own agent session. It tracks the frontier (decisions you can make now) and the fog (decisions blocked on research, prototypes or discussion), and orchestrates all of it.
How the map lives in the issue tracker
Maps are parent issues with decision tickets as sub-issues (his example: a map with 12-17 sub-issues in his course video manager repo). Resolving a ticket writes a short summary back to the parent map, so decisions, prototypes and tasks are all tracked. The skill is issue-tracker agnostic (GitHub, Linear, Jira) via a setup skill.
Working through a map
Start by invoking Wayfinder with a destination description; it explores the repo, grills you about what done looks like (he chose a buildable spec for a command-K palette in a diagram window), then creates the map and tickets. Only some tickets are takable at first. Each ticket is then worked by calling Wayfinder with the ticket URL, in a fresh session (he uses a handoff skill that spawns a sub-agent). After each resolution, ask what the frontier has moved to.
Ticket types and blocking
Four types: research (run in a sub-agent, reports back), prototype (high-fidelity feedback; reuses his prototype skill, and keeps this from being waterfall), grilling (discussion of a detail) and task (real-world work the agent cannot do or that is scheduled behind other work). Blocking relationships capture decisions that depend on others.
From map to spec to tickets
A finished map is too dense to implement directly, so he runs a to-spec step on it (the draft exceeded GitHub's character limit), then to-tickets, implementation and code review. Wayfinder replaces the grill-with-docs step in his usual flow. Specs link back to the original decision tickets, giving agents a primary source instead of only a summary.
FAQ - when to use it, and is this SDD
Use it only when work cannot be planned in one session, i.e. there is fog; otherwise plan in a single session. He also uses it for non-coding work such as planning a garden office (surveys, contractors, research). A spec here is just a destination document for multi-session work and is non-persistent: he closes the spec issue once it is in the code, unlike spec-driven development that keeps editing specs. Decision tickets differ from implementation tickets. The destination is up to you: a spec for an AFK agent, or direct implementation.