wayfinder — Turn Big Projects That Don’t Fit in a Single Session into a Decision-Ticket Map

Skill Overview

wayfinder is a planning-oriented agent skill: when you have only a vague big idea and the path from here to the destination is still unclear, it first draws the route as a shared map in an issue tracker, then processes the decision tickets on the map one by one until the path is clear and ready to be handed off for execution.

Use Cases

1. The request is too large for a single session — When a piece of work clearly exceeds the capacity of a single 100K-token session, trying to do it all at once will only result in lost context halfway through. Use wayfinder first to settle the key decisions ahead one by one, then implement in stages so each session only needs to focus on its own ticket.
2. The approach is not yet clear, so don’t write code yet — For work such as large-scale refactoring, data-structure migrations, or selecting a new system—where choosing incorrectly is costly—the map lets you lock in the necessary decisions before taking action and avoid rework.
3. Multiple sessions or agents are advancing the same effort in parallel — The map and tickets are all stored in the issue tracker. Each session claims a ticket, which immediately assigns it to itself. Blocking relationships are directly visible in the tracker’s native interface, so no one steps on anyone else’s work.

Core Features

1. The Map as an Index — The map itself is an issue tagged wayfinder:map. It contains only four things: the destination, notes, decisions already made, and items not yet clarified or out of scope. It does not store details; it only points to the tickets that hold them. Each decision exists in exactly one place, while the map provides only a one-sentence summary and a link.
2. Four Ticket Types — Each ticket is a child issue of the map, categorized by whether human presence is required, into HITL and AFK types: research (AFK) checks documentation and third-party APIs to determine the facts needed for a decision; prototype (HITL) produces a rough but concrete sample for a human to react to; grilling (HITL) is the default type and uses dialogue to clarify; task covers miscellaneous work that must be completed before a decision can be made, such as enabling a service so its API can be evaluated.
3. Fog of War & Frontier — It does not pre-divide areas that are still unclear: questions that cannot yet be stated precisely remain under “not yet clarified,” while those that can be stated precisely are immediately turned into tickets. Open tickets with no unresolved blockers and no assignee form the “frontier”—the boundary that can actually be advanced at this moment. Each time a ticket is resolved, some of the fog ahead clears and new tickets emerge.

Frequently Asked Questions

How is wayfinder different from an ordinary task list?

A TODO list contains “things to do”; wayfinder contains “things to decide first.” The default output of this skill is a decision, not a deliverable—resolving a ticket means that a decision has been recorded or a question has been answered, not that a piece of code has been written. Only when execution itself is a necessary step toward the next decision does it appear as a task ticket.

What needs to be prepared before using wayfinder?

You need an issue tracker: the map, child tickets, blocking relationships, and frontier queries all live in the tracker. Its native dependency features make “what can be worked on now” visible directly in the tracker’s own interface. If no tracker is provided, it falls back to a local Markdown-based approach. In addition, HITL tickets (prototypes and grilling) require human participation. The agent will not answer the human’s side of the questions for them—an interrogation process where the agent asks and answers its own questions would already violate the premise of this skill.

How many tickets can one session handle?

A session resolves only one ticket, except for research tickets, which may dispatch sub-agents to investigate in parallel. There are two ways to invoke it: when you first have a vague idea, “draw the map,” create the destination and the tickets that can currently be stated clearly, then stop; or take an existing map and “advance it ticket by ticket.” If you do not specify one, it takes the first ticket on the frontier in order. Note that if drawing the map reveals there is no real fog at all—that the entire effort can be completed in a single session—it will not fabricate a map, but will stop and ask what you want to do.