🥮 skills.mooncakes.ioexperimental

wayfinder

// Plan work too large or uncertain for one agent session by charting a shared map of dependency-aware decision tickets, resolving one frontier ticket per session, and handing off when the route to the destination is clear. Use for huge features, migrations, programs, or ambiguous efforts whose key decisions cannot fit in one planning conversation.

moon runwasm

moon runwasm Yoorkin/wayfinder@0.1.0

$ files

SKILL.md

readonly

Wayfinder

Find the route before attempting the destination. Represent a large, foggy effort as a shared map plus decision tickets. Resolve decisions, investigations, and prerequisite tasks until nothing material remains to decide.

Planning is the default. Do not turn the map into an implementation backlog unless the map's Notes explicitly authorize execution. The urge to start building usually means the route is clear enough to hand off.

Never resolve more than one non-research ticket in one session.

Core concepts

Destination

Name what completion of the map produces: a settled spec, a locked decision, a migration route, or another clear planning outcome. The destination fixes scope and shapes every ticket.

Map

Maintain one canonical map issue or local map file. It is a low-resolution index, not a duplicate store. Each detailed decision lives in exactly one ticket; the map records only its title, link, and one-line gist.

Use this body:

## Destination

<One or two lines describing the planning outcome.>

## Notes

<Domain, standing preferences, required skills, and any explicit permission to execute.>

## Decisions so far

- [<Closed ticket title>](link): <One-line gist of the answer.>

## Not yet specified

<In-scope fog that cannot yet be stated as a precise ticket.>

## Out of scope

<Work deliberately beyond the destination.>

Do not list all open tickets in the map; query child tickets or the local ticket directory instead.

Tickets

Each ticket resolves one question sized to one large agent session:

## Question

<The decision or investigation this ticket resolves.>

Give every ticket one type: research, prototype, grilling, or task. Record blocking edges explicitly. A ticket is on the frontier when it is open, unblocked, and unclaimed.

Refer to maps and tickets by linked title in human-facing text, never by a bare number or slug.

Tracker model

Use the configured issue tracker when available:

create one map issue labeled wayfinder:map;
create tickets as child issues where supported;
use native blocking relationships where supported;
claim a ticket by assigning it before work;
treat the assignee as the concurrency lock.

If no tracker is configured, use this local fallback:

.scratch/wayfinder/<map-slug>/
├── map.md
└── tickets/
    ├── 01-<slug>.md
    └── 02-<slug>.md

In local ticket files add Type, Status, Claimed by, and Blocked by fields. A blank Claimed by means unclaimed. Use numbers and titles for local blocking references. Preserve the same frontier semantics.

Ticket types

Every ticket is either HITL, requiring a live human decision, or AFK, executable by the agent alone. Never fabricate the human side of a HITL exchange.

Research — AFK

Use when a decision waits on facts from documentation, specifications, third-party APIs, source code, or knowledge bases.

Investigate primary sources rather than secondary summaries.
Cite every material claim to the source that owns it.
Save findings as one Markdown artifact following repository convention.
Link the artifact from the ticket; do not paste a long report into the map.
When parallel agents are supported, delegate independent research and keep working on unrelated frontier tickets.

Prototype — HITL

Use when a cheap concrete artifact will answer “how should this behave?” or “what should this look like?”

State the exact question before building.
Make the artifact clearly throwaway, trivial to run, and free of production polish.
Keep state in memory unless persistence is the question.
Surface relevant state after every interaction.
Present it to the human for reaction; the agent cannot approve its own prototype.
Capture the verdict and link the throwaway artifact from its ticket; keep validated decisions, not prototype clutter, on the main route.

Grilling — HITL

Use for the default decision conversation. Apply the embedded grilling and domain-modeling discipline below.

Task — HITL or AFK

Use only for manual work required before a decision can be made: provisioning access, obtaining representative data, signing up for a service, or similar prerequisites. A task earns its place by unblocking a decision, not by delivering the destination. Record what was done and the resulting facts.

Embedded grilling discipline

Model the subject as a decision tree. The frontier is every open decision whose prerequisites are settled.

For each grilling round:

Recompute the frontier.
Ask the whole frontier, numbered, without guessing unresolved prerequisites.
Give a concrete recommended answer and rationale for every question.
Wait for the human's answers.
Apply answers, reshape the tree, and repeat.

Use:

❓ **Q1** - **<question title>**: <question, context, and useful choices>

➡️ <recommended answer and rationale>

Investigate facts available from the environment instead of asking the human. Decisions remain the human's. Do not act on the result until shared understanding is confirmed.

Embedded domain-modeling discipline

While resolving decisions:

read the relevant CONTEXT.md, CONTEXT-MAP.md, code, and ADRs;
challenge conflicting or overloaded terminology immediately;
test boundaries with concrete edge cases;
verify behavioral claims against code;
update the correct CONTEXT.md as soon as a canonical term is resolved;
keep glossary definitions to project-specific concepts, one or two sentences, with _Avoid_ synonyms where useful;
offer an ADR only for a hard-to-reverse, surprising decision produced by a real trade-off;
number ADRs sequentially under the relevant docs/adr/ and default to a title plus one short context/decision/reason paragraph.

Create domain files lazily. Never turn CONTEXT.md into a spec or implementation log.

Fog of war

Keep the map deliberately incomplete.

Create a ticket when the question can be stated precisely now, even if blocked.
Put an item in Not yet specified when the in-scope question is still too fuzzy to phrase precisely.
Do not pre-slice fog. One fog patch may later become several tickets or none.
Keep decided items, live tickets, and out-of-scope work out of Not yet specified.

Resolving a ticket clears nearby fog. Graduate newly precise questions into tickets and remove their text from Not yet specified so each concern has one home.

Scope boundary

The destination defines scope. Work beyond it belongs in Out of scope, not fog.

If an existing ticket proves to be beyond the destination, close it as out of scope, add one linked gist and reason to the map, and do not add it to Decisions so far. It can return only if the destination is redrawn as a new effort.

Mode A: chart a map

Use when the user provides a loose, oversized idea.

Name the destination. Grill the user and sharpen domain language until the planning outcome and scope are explicit.
Map breadth-first. Fan out across the space to identify precise decisions, investigations, and visible fog without diving deeply into one branch.
If no fog remains and the whole route fits one session, stop and ask whether the user wants an ordinary plan instead; do not create ceremonial map overhead.
Create the map with Destination and Notes, an empty Decisions-so-far index, visible fog, and explicit Out of scope.
Create every currently precise ticket first, then wire blocking edges in a second pass after stable identifiers exist.
Launch independent research tickets in parallel when supported.
Stop. Charting creates and wires the map; it does not hand-resolve a decision ticket in the same session.

Mode B: work through a map

Use when the user supplies a map URL, identifier, or local path. A ticket argument is optional.

Load the low-resolution map, not every ticket body.
If the user names a ticket, verify it is eligible. Otherwise select the first frontier ticket in tracker order.
Claim it before reading deeply or working, so concurrent sessions skip it.
Fetch related ticket details only as needed. Apply the correct ticket-type workflow and any skill named in Notes.
Record the answer as a resolution comment or resolution section, then close the ticket.
Append one linked title and one-line gist to Decisions so far.
Create newly surfaced tickets before wiring edges; graduate clarified fog; close newly out-of-scope tickets; update or remove invalidated tickets.
Stop after this one non-research ticket. Expect other sessions to modify the tracker concurrently and re-query before every mutation.

Completion and handoff

The map is complete when no open ticket or in-scope fog remains and the route to the destination is clear.

Create a compact handoff document in the operating system's temporary directory, not the repository:

state what the next session is expected to do;
link the map, resolved tickets, spec, ADRs, commits, prototypes, and research instead of duplicating them;
list suggested skills for the next agent;
record remaining operational cautions and the immediate next action;
redact API keys, passwords, personal data, and other secrets.

Report the handoff path and destination status. Do not begin executing the destination unless Notes explicitly authorized execution.

Origin

This self-contained adaptation combines Matt Pocock's wayfinder, grilling, domain-modeling, research, prototype, and handoff behaviors without requiring a host-specific Skill dispatcher.

$ cat moon.mod

Author