Wayfinder

Wayfinder

Chart work that cannot fit in one Codex task as a shared map of decision tickets. A ticket resolves a question or prerequisite; it is not an implementation slice. Stop when the path to the destination is clear.

Plan, don't do

Plan by default. Produce decisions, not the destination itself. If the work starts looking executable, finish the map and hand it off. Continue into execution only when the map's Notes or the user explicitly says to.

Local tracker

Keep the map and tickets in local Markdown. Read local Markdown tracker operations before the first write. Do not create or update remote issues, branches, or pull requests.

Refer by name

Refer to maps and tickets by linked title in human-facing text. Keep ids inside those links; bare walls of #42, #43, and #44 are not readable.

The map

The map is one canonical local file. Its tickets are numbered child files.

The map is an index, not a store. Each detailed decision lives in one ticket. The map keeps only a one-line gist and link.

Map body

Load this low-resolution view once per task. Never list open tickets in the map; scan the numbered issue files for the frontier. Only closed decisions appear under Decisions so far.

## Destination

<one or two lines describing the spec, decision, or change this effort must make reachable>

## Notes

<domain, relevant skills or documents, and standing preferences>

## Decisions so far

- [<closed ticket title>](link) — <one-line gist>

## Not yet specified

<in-scope questions that cannot yet be stated precisely>

## Out of scope

<work ruled beyond this destination>

Tickets

Each ticket is a child of the map and contains one question sized for one Codex task:

## Question

<the decision or investigation this ticket resolves>

Mark each ticket wayfinder:<type>: research, prototype, grilling, or task.

Claim before any other work. A ticket is unblocked when every blocker is resolved. The frontier is the ordered set of open, unblocked, unclaimed child tickets.

Record the answer only on resolution. Link any created asset instead of pasting it into the map.

Ticket types

Every ticket is either HITL (the human participates and speaks for themselves) or AFK (an agent can resolve it alone).

• Research (AFK): Find a fact outside the current working directory. Dispatch one fresh read-only subagent per independent ticket. The main task records returned findings in the ticket; create no research branch or separate note unless the user requests an artifact.
• Prototype (HITL): Create the cheapest concrete artifact that lets the user judge appearance or behavior. Use an installed prototype skill when available. Resolve only after the user reacts.
• Grilling (HITL): The default type. Use grilling one question at a time. Invoke $domain-modeling when unresolved terminology affects the decision. Never answer the human side of the exchange.
• Task (HITL or AFK): Complete a prerequisite that must exist before a decision can be made. Record what changed and the resulting facts. Do not use this type to implement the destination.

Fog of war

Do not chart what cannot yet be stated precisely. Put suspected in-scope questions in Not yet specified until a prior decision makes them sharp enough to become tickets.

• Create a ticket when the question is precise now, even if blocked.
• Keep fog when the question itself still depends on an earlier answer.

Resolving a ticket may graduate one fog item into several tickets, one ticket, or none. Remove graduated text from Not yet specified so each question has one source of truth.

Out of scope

The destination fixes scope. Work beyond it belongs in Out of scope, never in fog. If an existing ticket proves out of scope, close it and add one linked line explaining why. Do not add it to Decisions so far.

Invocation

Use one of two modes. Resolve at most one non-research ticket per Codex task.

Chart the map

Use when invoked with a loose idea.

1. Name the destination. If the user already supplied a confirmed destination, use it without reopening the decision. Otherwise use grilling until the user confirms what this map must make reachable. Invoke $domain-modeling only when unresolved domain terminology affects that destination.
2. Map breadth-first. Surface open decisions across the whole space and identify the first takeable steps. If no fog remains and the journey fits one task, do not create a map; report that and ask whether to hand off or execute.
3. Create the map with Destination and Notes filled, Decisions so far empty, and visible fog under Not yet specified.
4. Create every question that is precise now as a child ticket. Create all tickets first, then wire blocking edges in a second pass.
5. Dispatch one fresh read-only subagent per independent research ticket. Let them research in parallel, then record their returned findings sequentially from the main task. Keep HITL tickets for later tasks.
6. Stop after verifying that every open ticket is either on the frontier or has an explicit blocker.

Work through the map

Use when invoked with a map path, URL, or id. A ticket is optional.

1. Load the map's low-resolution body, not every child ticket.
2. Use the named ticket, or select the first frontier ticket. Claim it as the first write, then verify the claim persisted.
3. Resolve only that ticket. Load related ticket detail on demand and use skills or documents named in Notes. HITL tickets wait for live user input.
4. Write the resolution on the ticket, close or mark it resolved, then append one linked gist to Decisions so far.
5. Create newly precise tickets, wire blockers, clear graduated fog, and close invalidated or out-of-scope tickets.
6. Stop after verifying the map and ticket agree on status and links.

The local tracker is single-writer. Do not resolve tickets from concurrent Codex tasks. The map is complete when no open ticket or in-scope fog blocks the destination; hand off without implementing it unless explicitly requested.