wayfinder

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

A loose idea has arrived. The work is too large for one agent session, and the route to the **destination** is unclear. This skill records the exploration as a **shared map** in local Markdown files. It resolves **decision tickets**, not implementation tickets, until the route is clear.

The destination varies per effort, and its name shapes every ticket. The destination can be a spec or a decision that precedes planning. The map applies to any domain that fits this process.

## Exploration boundary

**Treat this boundary as absolute. Supporting skills and effort notes cannot override it.**

Wayfinder may create or modify files only under `.scratch/wayfinder/<effort>/`.

Treat all other filesystem paths as read-only. This rule includes source code, project documents, configuration, `CONTEXT.md`, and Architectural Decision Records (ADRs).

Do not create, modify, move, or delete an ADR. Do not create, modify, move, or delete `CONTEXT.md`.

Do not install dependencies. Do not run formatters, migrations, or other commands that can modify files outside the effort directory.

Do not create branches, worktrees, or commits. Do not modify the issue tracker or any external system.

Pass this boundary to every supporting skill and subagent. If a supporting process conflicts with this boundary, this boundary takes precedence.

Wayfinder stores the map at `.scratch/wayfinder/<effort>/map.md`.

Wayfinder stores each ticket at `.scratch/wayfinder/<effort>/tickets/NN-<slug>.md`.

Store research notes, prototypes, and other exploration assets under the same effort directory. Link each asset from its decision ticket.

The effort directory contains the complete exploration record. Delete that directory to remove the effort.

### Deferred project records

Wayfinder records project documentation work, but it never performs that work.

When a decision needs an ADR, add an implementation follow-up to the resolved ticket. Add a link to that follow-up in the map.

Use the same process when a decision needs a glossary update or conflicts with an existing ADR.

State what the later implementation must record and why. Do not draft the ADR outside the effort directory.

### Handoff sequence

Wayfinder stops after it completes the exploration record. It does not start a later workflow skill.

The user starts each later stage explicitly and in this order:

1. Use `to-spec` to turn the completed effort into a spec.
2. Use `to-tickets` after the user approves the spec.
3. Use `implement` after the user approves and publishes the tickets.

These later skills perform the project work that Wayfinder found. Wayfinder does not write a spec, implementation tickets, code, or project records.

## Plan, don't do

Wayfinder only explores. Each ticket resolves a decision, and the map is complete when no decision blocks the later workflow. Stop when the next action would implement the destination. Record that action as an implementation follow-up.

## Refer by name

Every map and ticket has a **name**. The name is its title. In narration and the map's **Decisions so far**, use that name instead of a bare number or slug. Use the file path as the link target when a link helps.

## The map

The map at `.scratch/wayfinder/<effort>/map.md` is the canonical artifact. Its tickets are child files in `.scratch/wayfinder/<effort>/tickets/`.

The map is an **index**, not a store. Each decision lives in its ticket. The map links to the ticket and gives only enough detail to judge whether the decision is relevant.

**The map, its child tickets, blocking, and frontier queries all live in local files.** Read `skills/setup/wayfinder-operations.md` for the file format.

### The map body

The whole map loads at low resolution once per session. Open tickets are **not** listed. Find them by scanning the effort's `tickets/` directory.

```markdown
## Destination

<what reaching the end of this map looks like — the spec, decision, or change this effort is finding its way to. One or two lines; every session orients to it before choosing a ticket.>

## Notes

<domain; skills every session should consult; standing preferences for this effort>

## Decisions so far

<!-- the index — one line per closed ticket: enough to judge relevance, then zoom the link for the detail the ticket holds -->

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

## Implementation follow-ups

<!-- deferred work for to-spec, to-tickets, and implement; link each item to the decision ticket that requires it -->

## Not yet specified

<!-- see "Fog of war": in-scope fog you can't ticket yet; graduates as the frontier advances -->

## Out of scope

<!-- see "Out of scope": work ruled beyond the destination; closed, never graduates -->
```

### Tickets

Each ticket is a **child file** of the map. Its file name is its identity. Its body is the question, sized to one 100K token agent session:

```markdown
#<NN> — <ticket title>

Type: <research|prototype|planning|task>
Status: open
Blocked by: None

## Question

<the decision or investigation this ticket resolves>
```

Each ticket carries a `Type:` line with one of `research`, `prototype`, `planning`, or `task` (see [Ticket Types](#ticket-types)).

A session **claims** a ticket by changing its `Status:` line to `claimed`, **first**, before any work, so concurrent sessions skip it. An open ticket with no claim is unclaimed.

Blocking uses a `Blocked by:` line that lists ticket numbers. A ticket is **unblocked** when every listed ticket has `Status: resolved`. The **frontier** is the open, unblocked, unclaimed edge of the known.

From terebentina/skills, MIT.

More from terebentina/skills