wayfinder

Plan large efforts as decision tickets tracked on an issue tracker.

Updated Sep 11, 2026
One-click install
npx skills add https://github.com/CYRUS-pinto/pi-bot --skill wayfinder-cyrus-pinto
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: wayfinder
Source: https://github.com/CYRUS-pinto/pi-bot/tree/main/.agents/skills/wayfinder
Command: npx skills add https://github.com/CYRUS-pinto/pi-bot --skill wayfinder-cyrus-pinto

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Large, ambiguous efforts often exceed what a single agent session can hold, leaving the path from idea to destination unclear. Wayfinder breaks such work into a shared map of decision tickets on the repo's issue tracker, resolving them one at a time until the route is clear. ## Core Features & Use Cases - Map-based planning: Creates a single map issue (labelled wayfinder:map) holding the destination, notes, decisions-so-far index, fog of war, and out-of-scope sections. - Typed decision tickets: Each ticket is a child issue labelled research, prototype, grilling, or task, with native blocking relationships defining the workable frontier. - Two invocation modes: Chart a new map from a loose idea, or work through an existing map by claiming and resolving one ticket per session. - Use Case: You have a vague migration project too big for one session. Invoke wayfinder to grill out the destination, chart the open decisions as tickets, fire research subagents in parallel, then resolve tickets session by session until the spec is fully decided. ## Quick Start Ask the agent to use the wayfinder skill to chart a map for your loosely defined project idea on the issue tracker.

Frequently Asked Questions about wayfinder

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I plan a project too big for one agent session?

Invoke wayfinder with your loose idea. It grills you to name the destination, maps the open decisions breadth-first, creates a map issue plus child decision tickets on the issue tracker, and wires blocking edges so later sessions can work the frontier one ticket at a time.

What is a decision ticket in wayfinding?

A decision ticket is a child issue of the map whose body states one question sized to a single agent session. Each carries a type label: research, prototype, grilling, or task, and is resolved by posting a resolution comment and closing the issue.

Does wayfinder work with any issue tracker?

Wayfinder is tracker-agnostic but expects a tracker doc describing how the repo expresses maps, child tickets, blocking, and frontier queries. If no tracker is provided, it defaults to a local-markdown tracker and asks you to run the setup command.

Can multiple agent sessions work the same map in parallel?

Yes. A session claims a ticket by assigning it before starting work, so concurrent sessions skip claimed tickets. Only open, unblocked, unassigned tickets form the workable frontier, and each session resolves at most one ticket, except research tickets.

When should I not use wayfinder for planning?

Skip wayfinding when charting surfaces no fog: if the way to the destination is already clear and the whole journey fits one session, no map is needed. Wayfinder also produces decisions, not deliverables, so pure execution work belongs elsewhere.