wayfinder

Plans large multi-session efforts as a shared map of decision tasks in a project's tasks directory.

Updated May 9, 2024
One-click install
npx skills add https://github.com/AceCodePt/dotfiles --skill wayfinder-acecodept
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: wayfinder
Source: https://github.com/AceCodePt/dotfiles/tree/main/.config/opencode/flows/wayfinder
Command: npx skills add https://github.com/AceCodePt/dotfiles --skill wayfinder-acecodept

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Large 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 tasks stored in the project's tasks/ directory, so each session resolves one decision at a time until the route is clear. ## Core Features & Use Cases - Map charting: Names the destination, runs breadth-first grilling to surface open decisions, and creates a spec task plus decision tasks with dependency wiring. - Typed decision tasks: Supports Research (AFK subagent), Prototype, Grilling, and manual Task types, each claimed via orch task start and resolved one per session. - Fog of war tracking: Records not-yet-specifiable questions in a Not yet specified section and graduates them into tasks as the frontier advances, while out-of-scope work is explicitly ruled out. - Use Case: You need to plan a data-structure migration too big for one session. Invoke wayfinder to chart the destination, create decision tasks for schema choices and rollback strategy, then work through them one at a time across sessions. ## Quick Start Ask the agent to use the wayfinder skill to chart a map for your large effort, naming the destination and the first decisions you can already see.

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 names the destination, runs a breadth-first grilling session to surface open decisions, then creates a map task and decision tasks in tasks/ that are resolved one per session until the route is clear.

How do decision tasks get claimed and resolved in wayfinder?▼

A session claims a task by running `orch task start <slug>`, which creates the branch that acts as the claim. The task is resolved through its type's method, the decision is committed, and the task is archived with a one-line gist added to the map.

What task types does wayfinder support?▼

Wayfinder supports four types: Research (AFK, resolved by a research subagent), Prototype (HITL, produces a rough artifact), Grilling (HITL conversation, the default), and Task (manual work that unblocks a decision). HITL tasks use `hitl: true`; AFK tasks are scheduler-eligible.

Can multiple agent sessions work on the same wayfinder map?▼

Yes. Unblocked tasks can run in parallel, and the tasks/ tree is designed for concurrent editing. Claiming via `orch task start` before any work ensures concurrent sessions skip already-claimed tasks.

When should a question stay in Not yet specified instead of becoming a task?▼

Keep it in Not yet specified when you cannot yet phrase the question precisely, even if you sense it is coming. Create a task only when the question is sharp, regardless of whether it can be answered yet.

Does wayfinder execute the work it plans?▼

No. Wayfinder is planning by default: each task resolves a decision, and the map is done when nothing remains to decide. An effort can override this in its Notes section to carry execution into the map itself.