wayfinder
Skill4 starsChanged 12 days agoMITView on GitHub
Chart a too-big effort as a shared map of decision tickets on the Gaia headquarters issue tracker, then resolve them one at a time until the way to the destination is clear. Use when someone says: "this is too big for one session", "chart a map", "wayfinder map", "plan this effort", "what do we need to decide first", "open a wayfinder", "work the map", "what's on the frontier", or /wayfinder. Covers any gaia-research org repo — gaia-skill-tree, gaia-research, gaia-skill-heaven and beyond — but every map and every ticket lives on ONE tracker: gaia-research/gaia-skill-tree. This is cartography (planning an effort as decisions), NOT triage of an existing backlog — for that use /gaia-triage.
196 other projects use a version of this.
Adopted by
Most recently taken up by
- bamlab/flashlighttheir own version, first seen Nov 16, 2026
- dhruvsaxena1998/skillstheir own version, first seen Nov 16, 2026
- moisesrj97/skillstheir own version, first seen Nov 16, 2026
- endalk200/skillstheir own version, first seen Nov 16, 2026
- gfunc/skillstheir own version, first seen Nov 16, 2026
- devdeepjs/kobayashi-marutheir own version, first seen Nov 16, 2026
Used with
Projects with it also use setup-ts-deep-modules, to-questionnaire and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
liufeng1976Skillsetup-ts-deep-modules
Wire dependency-cruiser into a TypeScript repo so each package is a deep module — implementation hidden in subfolders, reachable only through its entry-point files. User-invoked.
Also in 47 projects that use this
AWSSkillto-questionnaire
Turn a decision you can't fully answer into a questionnaire for someone else to fill in.
Also in 101 projects that use this
LesaniSkillwriting-beats
Shape an article as a journey of beats, choose-your-own-adventure style. The user picks a starting beat from the raw material, you write only that beat, then offer options for where to pivot next, beat by beat, until the article reaches a natural end. Use when the user has raw material and wants to assemble it as a narrative rather than an argument.
Also in 62 projects that use this
RoentekSkillloop-me
Grill me about specs for the workflows I want to build, within this workspace.
Also in 57 projects that use this
AWSSkillwizard
Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.
Also in 137 projects that use this
richard12511Skillclaude-handoff
Hand the current conversation off to a fresh background agent that picks up the work immediately.
Also in 46 projects that use this
- +2 more from aws
Other versions196 projects use a version of this.
Word for word · 1
- gaia-research/gaia-skill-tree★ 22100% same
Edited · 0
None found.
Wrote their own version · 195
- mattpocock/skills★ 325ksame name
- The-Vibe-Company/quivr★ 40ksame name
- QuivrHQ/quivr★ 40ksame name
- ArcReel/ArcReel★ 6.6ksame name
- vinvcn/mattpocock-skills-zh-CN★ 5.8ksame name
- withcoral/coral★ 5ksame name
- epicenter-md/epicenter★ 4.8ksame name
- EpicenterHQ/epicenter★ 4.8ksame name
- bestofjs/bestofjs★ 3.1ksame name
- bamlab/flashlight★ 1.6ksame name
185 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository14 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- gaia-issue-resolverSkill
- gaia-triageSkill
- impeccableSkill
- lucy-image-productionSkill
- lucy-riveSkill
- lucy-tunerSkill
- gaia-issue-resolverSkill
- gaia-triageSkill
- impeccableSkill
- lucy-riveSkill
- wayfinderSkill
- impeccableSkill
The file
We split this skill into the rules it gives an agent
7 rules. 0 are common, 2 are distinctive, and 5 are very specific to this project.
0
Common
Most of the 183 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 59
Use a repo's full owner/name.
- Very specific: line 96
Use --body-file with real newlines (repo convention — escaped \n in --body produces a mangled issue).
- Distinctive: line 193
When a blocker closes, the blocked ticket does not update itself.
- Very specific: line 196
Re-check this before trusting it: If GitHub issue dependencies become reachable from gh or the MCP server, they supersede the convention …
- Very specific: line 283
Every ticket carries exactly one wayfinder:<type> label.
- Very specific: line 288
All six are declared in .github/labels.yml.
- Distinctive: line 315
Run the frontier query (§2.5), take the first ticket, claim it (§2.6).
“Common” is measured: kept by at least 6 in 10 of the 183 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
wayfinder (Gaia)
This is the Gaia expression of Matt Pocock's wayfinder skill. Upstream is deliberately
tracker-agnostic: it says "the issue tracker should have been provided to you… consult
the tracker doc's 'Wayfinding operations' section for how THIS repo expresses them."
This file is that document. Upstream owns the method; this file pins down the mechanics — where maps live, how tickets are created and nested, how blocking is expressed, how the frontier is queried, how a ticket is claimed, how a resolution is recorded. Read the upstream SKILL.md for the method (mattpocock/skills → engineering/wayfinder); read this for how Gaia does it.
Wayfinder is cartography: planning an effort too big for one agent session as a map of decision tickets, worked one at a time until nothing is left to decide. It is not backlog hygiene and not issue resolution — see Not this skill.
1. Headquarters — one tracker, many repos
Every map and every ticket lives on the gaia-research/gaia-skill-tree issue tracker,
regardless of which repository the resulting code lands in. There is no second map
tracker, and a map is never split across repos.
export GAIA_HQ=gaia-research/gaia-skill-tree # headquarters — all wayfinder issuesWhy: a map's whole value is that one issue holds the low-resolution view of an entire
effort. Efforts here routinely cross repo boundaries — a Skill Heaven benchmark decision
made in gaia-research changes door code in gaia-skill-heaven and registry vocabulary
in gaia-skill-tree. A map fragmented across three trackers is not a map.
Target-repo tagging
A ticket in HQ can point at work landing anywhere in the gaia-research org. Say where,
on the ticket body, as the first line:
**Target repo:** `gaia-research/gaia-skill-heaven`Use a repo's full owner/name. Multiple targets are allowed (one line, comma-separated);
n/a is valid for a pure-decision ticket that lands no code anywhere. Minimum supported
scope is the big three:
| Target repo | What lands there |
gaia-research/gaia-skill-tree | registry, CLI, site, curation, HQ itself |
gaia-research/gaia-research | research lab, benchmarks, ledger, reports, Next.js site |
gaia-research/gaia-skill-heaven | product monorepo — engine + per-harness doors |
Any other gaia-research/* repo is fair game; the convention is deliberately open-ended,
and nothing beyond the string needs to change to extend it.
Cross-repo linking is by URL, not by number. #1648 inside an HQ issue resolves to
HQ. When referring to an issue or PR in another repo, write the full
gaia-research/<repo>#<n> form or a full URL — a bare number silently points at the
wrong repo.
2. Wayfinding operations (the tracker contract)
This is the section upstream defers to. Everything here is verified against the live map Wayfinder map: Trust Magnitude recalibration backlog (post-Yggdrasil III) (#1636), which is the reference implementation. Read it before charting your first map.
2.1 Create the map
One issue, labelled wayfinder:map, titled Wayfinder map: <destination in a phrase>.
gh issue create --repo "$GAIA_HQ" \
--title "Wayfinder map: <destination in a phrase>" \
--label "wayfinder:map" \
--body-file map-body.mdUse --body-file with real newlines (repo convention — escaped \n in --body produces
a mangled issue). Verify after creating:
gh issue view <n> --repo "$GAIA_HQ" --json body --jq .bodyThe body uses upstream's five sections exactly, in this order — ## Destination,
## Notes, ## Decisions so far, ## Not yet specified, ## Out of scope — and ends
with the pointer line:
---
Frontier tickets are linked below as they're created (see this issue's timeline / linked issues).The map is an index: Decisions so far gists each closed ticket in one line and links
it; the detail lives in the ticket, never restated on the map. #1636's Notes section shows
the local register — it carries measured numbers, named root causes, and founder rulings,
because those are what every session working that map must load first.
2.2 Create a child ticket
Two passes: create, then nest. Titles are sentences that state the decision, not nouns
(Determine cause of garrytan/gstack suite-component uniform undercount (16 skills, -3.67 each),
not gstack undercount).
gh issue create --repo "$GAIA_HQ" \
--title "<the decision, stated>" \
--label "wayfinder:research" \
--body-file ticket-body.mdTicket body:
**Target repo:** `gaia-research/<repo>`
Part of #<map> (Wayfinder map).
**Blocked by:** #<n>, #<m> <!-- omit the line entirely when unblocked -->
## Question this ticket answers
<the decision or investigation, stated so a fresh session can act on it cold>
## How to resolve
<the concrete route: commands, files, who to ask>
## Not this ticket
<the adjacent thing a reader will assume is in scope and isn't>## Question this ticket answers is upstream's ## Question; on a task ticket, title it
## Decision this ticket resolves (as #1648 does) — a task ticket earns its place by
unblocking a decision, and naming the decision keeps that honest.
2.3 Nest it under the map (hierarchy)
Hierarchy is GitHub native sub-issues. Verified working on #1636 — 6 sub-issues,
6/6 closed, sub_issues_summary reported by the API. Do not use task-list checkboxes for
hierarchy; they do not produce the parent/child relation.
Sub-issues take the child's issue id, not its number:
# resolve the child's id, then attach it to the map
CHILD_ID=$(gh api repos/$GAIA_HQ/issues/<child-number> --jq .id)
gh api --method POST repos/$GAIA_HQ/issues/<map-number>/sub_issues -f sub_issue_id=$CHILD_IDAgents on the GitHub MCP server use sub_issue_write with method: "add" (issue_number
= the map, sub_issue_id = the child's id, again not its number).
2.4 Blocking — body convention, not a native edge
Use the body convention. Verified, and it is a fallback, not a preference.
Upstream prefers a tracker's native dependency relationship because it renders the frontier visually. We do not have a usable one here:
- The GitHub MCP toolset these agents run on exposes sub-issue writes and nothing for issue dependencies — there is no blocked-by verb to call.
ghships nogh issue dependencycommand; reaching the REST dependency endpoints means hand-rolledgh apicalls that the org's app installation does not currently answer.- The live map #1636 wires no native blocking edges; its ordering is carried in prose.
So blocking is a line in the ticket body:
**Blocked by:** #1643, #1600Rules: HQ-relative #<n> (blockers are always HQ tickets — a blocker in another repo means
that work needs its own HQ ticket); one line, comma-separated; omit the line entirely when
nothing blocks — an empty or none value makes the frontier query below unreliable.
When a blocker closes, the blocked ticket does not update itself; the session that closes
the blocker edits the line, dropping the closed number, and deletes the line when it empties.
Re-check this before trusting it. If GitHub issue dependencies become reachable from
gh or the MCP server, they supersede the convention and this section should be rewritten
rather than kept alongside:
gh api repos/$GAIA_HQ/issues/1636/dependencies/blocked_by # 404/403 ⇒ convention still stands
gh issue --help | grep -i depend # empty ⇒ convention still stands2.5 The frontier query
The frontier is the open, unblocked, unclaimed children of the map. Because blocking is
a body convention, the query is two steps: ask GitHub for open unassigned children, then
filter on the Blocked by: line.
MAP=1636
gh api repos/$GAIA_HQ/issues/$MAP/sub_issues --jq \
'.[] | select(.state=="open") | select(.assignee==null) | "\(.number)\t\(.title)"' |
while IFS=$'\t' read -r n title; do
blockers=$(gh issue view "$n" --repo "$GAIA_HQ" --json body --jq \
'.body | capture("(?m)^\\*\\*Blocked by:\\*\\* (?<b>.*)$").b // ""')
open_blockers=0
for b in $(echo "$blockers" | grep -o '[0-9]\+'); do
[ "$(gh issue view "$b" --repo "$GAIA_HQ" --json state --jq .state)" = "OPEN" ] &&
open_blockers=$((open_blockers+1))
done
[ "$open_blockers" -eq 0 ] && printf 'FRONTIER #%s %s\n' "$n" "$title"
doneTake the first frontier ticket in order unless the user named one.
2.6 Claiming
Assign the ticket to yourself before any work — the assignee is the claim, and an open unassigned child is by definition unclaimed. Concurrent sessions work the same map.
gh issue edit <n> --repo "$GAIA_HQ" --add-assignee "@me"Claim first, then read. A session that reads for ten minutes and then claims has raced.
2.7 Resolution
Four steps, in this order:
# 1. post the answer as a resolution comment
gh issue comment <n> --repo "$GAIA_HQ" --body-file resolution.md
# 2. close the ticket
gh issue close <n> --repo "$GAIA_HQ" --reason completed
# 3. append a one-line context pointer to the map's "Decisions so far"
gh issue edit <map> --repo "$GAIA_HQ" --body-file updated-map.md
# 4. drop this number from any "Blocked by:" line that names itThe map line takes the shape #1636 uses — name, number, gist, and where the work landed:
- **#1643 (closed):** Fixed the role-stripping regression — `role` no longer stripped from `buildMergedSkillMap()`. Landed in #1647 → `dev/yggdrasil-iii-newmeta` (`ff9ba51`). → #1648.Refer to tickets by name in everything a human reads (narration, comments, the map's
prose). A wall of #42, #43, #44 is illegible. The number rides inside the name; it never
stands in for it.
Then graduate any fog the answer sharpened into fresh tickets, clearing each graduated
patch from Not yet specified. If the answer shows a ticket sits past the destination,
close it and add one line to Out of scope — it never appears in Decisions so far,
which records only the route actually walked.
2.8 Labels
| Label | Meaning |
wayfinder:map | The map issue itself. Exactly one per effort. |
wayfinder:research | AFK — read docs/APIs/local resources to surface a fact a decision waits on. |
wayfinder:prototype | HITL — build a cheap rough artifact to react to. |
wayfinder:grilling | HITL — conversation. The default ticket type. |
wayfinder:task | Manual work that must happen before a decision can be made. |
Every ticket carries exactly one wayfinder:<type> label. Stack ordinary repo labels on
top freely — #1637 is tech-debt + wayfinder:task, #1643 is tech-debt +
wayfinder:task + trust-model. Priority (P0–P4) is optional on a map ticket and
means what /gaia-triage says it means.
All six are declared in .github/labels.yml. Never create a wayfinder label ad hoc —
labels-sync.yml reconciles from that file with skip-delete: false on every push to
main, so an undeclared label is deleted off live issues at the next sync.
3. Charting and working a map
Upstream owns this; the short version, with the Gaia-specific hooks.
Chart the map (one session, resolves nothing)
- Name the destination.
/grilling+ domain modelling. The destination fixes the scope, so it is settled first. - Map the frontier breadth-first. If no fog surfaces — the whole journey fits one session — stop and say so; you don't need a map.
- Create the map on HQ (§2.1): Destination and Notes filled, Decisions-so-far empty,
fog sketched into
Not yet specified. - Create the tickets you can specify now (§2.2), nest them (§2.3), then wire
Blocked by:lines in a second pass — issues need numbers before they can name each other. - Fire research subagents for each
wayfinder:researchticket, in parallel. - Stop. Charting hand-resolves nothing.
Work through the map
- Load the map — the low-res view, not every ticket body.
- Run the frontier query (§2.5), take the first ticket, claim it (§2.6).
- Resolve it. Zoom into closed tickets on demand; call the skills the map's
## Notesnames. - Record the resolution (§2.7).
- Graduate fog; rule out-of-scope work out of scope.
Never resolve more than one ticket per session, except research tickets, which parallelise.
Fog or ticket? The test is whether you can state the question precisely now, not whether you can answer it now. Sharp-but-blocked ⇒ ticket. Not yet sharp ⇒ fog.
4. Gaia house rules that bind a map
- Decisions of record live in
gaia-research/founder/RATIFICATION.md, not on the map. A ticket whose resolution changes a ratified decision does not edit RATIFICATION.md by itself: the delta rides the implementing PR (D9), and the resolution comment says so. - Programmatic-first. A
wayfinder:taskticket that mutates the registry resolves throughgaia devverbs. Hand-editingregistry/nodes/is forbidden; so is hand-editing atrustMagnitudenumber. #1636's Notes say this out loud, and that is the pattern to copy. - A map is not a sprint.
gaia-skill-tree's sprint-completeness rule bans closing a sprint by filing its own remainder as follow-ups. A map is the opposite artifact: it is supposed to keep graduating fog into new tickets. Do not use a map to launder a sprint's unfinished work — if it was in the sprint's scope, it stays in the sprint. - Founder rulings settle scope. #1636 records one inline ("no separate Wayfinder ticket for this batch, #1600 stays the tracker"). Record rulings on the map where they change scope; that is what keeps the next session from re-litigating.
- Frontend work stays human-gated. A map ticket cannot merge a gated frontend PR. Resolving the decision is in scope; merging is not.
Not this skill
| You want to | Use |
| Plan an effort too big for one session as decisions | this skill |
| Sort, size, prioritize, link, and assign an existing backlog | /gaia-triage |
| Take one triaged issue end-to-end to a merged PR | /gaia-issue-resolver |
| Rank registry skills needing review | /gaia-meta-audit |
Wayfinder charts unknowns. Triage sorts knowns. Keep them apart: a map that fills with already-specified build slices has stopped being a map.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

