wayfinder

Before applying another skill below, load it through the Skill tool when available; otherwise read its SKILL.md. A skill name alone does not load its instructions.

A loose idea has arrived, too big for one agent session and wrapped in fog: the way from here to the destination isn't visible yet. Wayfinding is about finding that way, not charging at the destination. This skill charts the way as a shared map in the repo, then works its decision tickets (questions whose resolution is a decision, not slices of a build to execute) one at a time until the route is clear.

The destination varies per effort, and naming it is the first act of charting: it shapes every ticket. It might be a spec to hand off and iterate on, a decision to lock before planning starts, or a change made in place like a data-structure migration. The map is domain-agnostic: engineering work, course content, whatever fits the shape.

Plan, don't do

Wayfinder is planning by default: each ticket resolves a decision, and the map is done when the way is clear, with nothing left to decide before someone goes and does the thing. The pull to just do the work is usually the signal you've reached the edge of the map and it's time to hand off. An effort can override this in its Notes, carrying execution into the map itself, but absent that, produce decisions, not deliverables.

Refer by name

Every map and ticket has a name: its title. In narration and the map's Decisions-so-far, refer to it by that name rather than a bare id, number, or slug. Use the name as the link text; the path or issue id remains in the link target.

The Map

The map is a single markdown file under the configured agent root by default: {agentRoot}/wayfinding/<effort>/map.md. Its tickets are child markdown files under {agentRoot}/wayfinding/<effort>/tickets/. Read the ## Agent skills block in AGENTS.md/CLAUDE.md for the agent root; run /setup-skills if it is missing.

The map is an index, not a store. It lists the decisions made and points at the tickets that hold their detail; a decision lives in exactly one place, its ticket, so the map never restates it, only gists it and links.