wayfinder
Skill4 starsChanged 4 months agoApache-2.0View on GitHub
Plan a large, decision-heavy body of work as a durable map and resolve one semantic decision at a time until downstream work is clear.
195 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 42 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 87 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 124 projects that use this
RoentekSkillloop-me
Grill me about specs for the workflows I want to build, within this workspace.
Also in 50 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 54 projects that use this
ryotaroh180105Skillclaude-handoff
Hand the current conversation off to a fresh background agent that picks up the work immediately.
Also in 40 projects that use this
- +2 more from aws
Other versions195 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 195
- mattpocock/skills★ 325ksame name
- QuivrHQ/quivr★ 40ksame name
- The-Vibe-Company/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 repository51 other files it gives its agents.
- AGENTS.mdAGENTS.md
- architecture-remediationSkill
- attentionSkill
- classify-docSkill
- codebase-designSkill
- codebase-memory-mcpSkill
- codegraphSkill
- coding-standardsSkill
- contract-ledgerSkill
- conventional-commitsSkill
- database-migrationsSkill
- deduplicate-codeSkill
- diagnosing-bugsSkill
- domain-modelingSkill
- format-codeSkill
- github-issue-dependenciesSkill
- graphifySkill
- grillingSkill
- grill-meSkill
- grill-with-docsSkill
- handoffSkill
- implement-ticketSkill
- improve-codebase-architectureSkill
- project-delivery-managementSkill
- project-trackingSkill
- prototypeSkill
- repowiseSkill
- researchSkill
- resolving-merge-conflictsSkill
- review-architectureSkill
- review-specSkill
- setup-matt-pocock-skillsSkill
- spec-contractSkill
- spec-merge-cleanupSkill
- tddSkill
- teachSkill
- to-adr-docSkill
- to-docSkill
- to-specsSkill
- to-ticketsSkill
- triageSkill
- verify-architectureSkill
- verify-codeSkill
- verify-spec-closureSkill
- verify-specSkill
- verify-ticket-closureSkill
- verify-ticket-decompositionSkill
- wiki-lintSkill
- wiki-syncSkill
- wiki-synthesizeSkill
- writing-great-skillsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
26 rules. 0 are common, 15 are distinctive, and 11 are very specific to this project.
0
Common
Most of the 183 edited versions we read keep these.
15
Distinctive
This author's own choices. Worth a look.
11
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 25
Use when a destination still contains material planning fog.
- Distinctive: line 34
Use when the human supplies a Wayfinder map or decision ticket.
- Distinctive: line 39
Before substantive work on an existing map:
- Distinctive: line 46
Never switch or broaden focus automatically.
- Distinctive: line 53
Do not mutate the decision/map and do not inspect or reproduce Project Delivery singleton logic to guess the current focused set.
- Very specific: line 64
After the human sees current canonical delivery state, they may explicitly invoke the exact focus, switch-focus, or parallel-focus …
- Distinctive: line 110
If yes, the decision is not acceptance-ready until the exact semantic payload is explicit.
- Distinctive: line 118
Before human acceptance require one exact durable proposal containing map/decision identity, origin mode, complete typed revision …
- Very specific: line 126
Before a HITL decision persist one ## Decision Analysis comment with current-state evidence, constraints, alternatives, trade-offs, and …
- Very specific: line 130
If the recommendation materially changes, persist ## Recommendation Revision and create a new CCL proposal/hash when semantics changed.
- Very specific: line 148
After acceptance, determine ADR qualification through $to-adr-doc.
- Distinctive: line 160
use a clean isolated worktree at that base.
- Distinctive: line 164
commit once under repository conventional-commit policy.
- Distinctive: line 166
read back and revalidate CCL plus any ADR projection.
- Very specific: line 248
If accepted authority must be inherited into an existing continuation branch, attempt a clean merge only after canonical-main persistence.
- Very specific: line 269
Only after required repository authority is canonical and the Decision closure gate has returned WAYFINDER DECISION CLOSURE: ALLOWED:
- Very specific: line 277
update newly surfaced tickets/fog/out-of-scope state.
- Distinctive: line 283
Every material destination obligation must be exactly one of:
- Very specific: line 297
Run $attention before declaring route clear.
- Distinctive: line 300
If closure finds a missing semantic choice, route it to its owning decision.
- Distinctive: line 305
When Route Clarity resolves to downstream specification or specification reconciliation, Wayfinder may not terminate successfully from …
- Very specific: line 317
Write the exact formal $attention result for this checkpoint to a temporary file outside repository candidate state.
- Distinctive: line 362
if no fog exists, finish the bounded decision directly rather than manufacturing a map.
- Distinctive: line 376
run human gate and persist acceptance.
- Distinctive: line 381
run Route Clarity; when it resolves to specification/reconciliation, pass the Specification handoff gate and emit its exact terminal block.
- Very specific: line 408
When continuation inheritance requires semantic reconciliation, $to-specs owns downstream Spec reconciliation.
“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
Wayfinder is the planning workflow for work whose destination is clear enough to pursue but whose route still contains multiple or coupled material decisions.
For material software decisions, the Canonical Contract Ledger (CCL) is the frozen semantic output. Decision-analysis prose explains the choice; it is not a second semantic contract.
Session independence
Recover correctness-critical state from the invocation, repository, issue tracker, active architecture, CCL, and durable workflow artifacts. Chat/session summaries are context only.
Modes
Chart the Map
Use when a destination still contains material planning fog. Charting may define destination
and boundaries, create the canonical wayfinder:map, create currently specifiable
research/prototype/decision/task tickets, wire genuine semantic dependencies, and preserve
not-yet-specifiable fog.
Charting is planning and does not establish/switch project delivery focus.
Work Through the Map
Use when the human supplies a Wayfinder map or decision ticket. Resolve at most one non-research decision ticket per human session.
Project delivery guard
Before substantive work on an existing map:
- resolve the exact governing Wayfinder;
- invoke
$project-delivery-management reconcile; - invoke
guard <Wayfinder>; - require exact
PROJECT DELIVERY GUARD: ALLOWEDbefore claiming/mutating a decision.
Never switch or broaden focus automatically.
Human focus handoff
A guard failure caused only by the target Wayfinder not being focused is a human focus
boundary, not a generic dead end and not permission for $wayfinder to choose focus.
Do not mutate the decision/map and do not inspect or reproduce Project Delivery singleton logic to guess the current focused set. Surface this exact ownership handoff:
PROJECT DELIVERY: HUMAN FOCUS HANDOFF
Target Wayfinder: #<n>
Reason: not focused
Next human action:
$project-delivery-management statusAfter the human sees current canonical delivery state, they may explicitly invoke the exact
focus, switch-focus, or parallel-focus operation they choose. Resume Wayfinder work
only after a later current-run guard <Wayfinder> returns exact
PROJECT DELIVERY GUARD: ALLOWED.
A guard failure for not frontier-eligible, invalid control state, or unreadable blockers
is not a focus-choice handoff. Report the exact guard reason/blocker and stop without
suggesting an ineligible focus mutation.
Map model
The map is one issue labelled wayfinder:map with:
## Destination
<completion meaning>
## Notes
<constraints/context>
## Decisions so far
- [<closed decision>](url) — <result; CCL refs when applicable>
## Not yet specified
<in-scope fog>
## Out of scope
<excluded work>Decision/research/prototype/task tickets are children. Native issue dependencies express real prerequisites.
Semantic decision boundary
A decision requires a CCL proposal when accepting it creates or changes a material product, domain, architecture, persistence, temporal, authority, failure, public, or downstream contract.
Private implementation mechanics do not require CCL.
Use this test:
Could two reasonable downstream implementations satisfy the recommendation while creating materially different externally meaningful contracts?
If yes, the decision is not acceptance-ready until the exact semantic payload is explicit.
One semantic compiler
For material software decisions invoke $contract-ledger wayfinder-decision internally.
Wayfinder supplies context/recommendation; $contract-ledger owns typed normalization,
proposal hashing, revision checks, and transaction contribution.
Before human acceptance require one exact durable proposal containing map/decision identity, origin mode, complete typed revision snapshots, proposal hash, affected contract@revision identities, non-authoritative human rendering, and governing/constraint sources.
Persist one ## CCL Proposal comment with the lossless proposal payload and rendering.
Decision Analysis
Before a HITL decision persist one ## Decision Analysis comment with current-state
evidence, constraints, alternatives, trade-offs, and recommendation. For CCL-backed work it
is explanation only and may not add semantics absent from the proposal.
If the recommendation materially changes, persist ## Recommendation Revision and create a
new CCL proposal/hash when semantics changed.
Human acceptance
For CCL-backed decisions ask exactly:
Do you approve this recommendation and CCL proposal
<proposal-hash>? (yes/no)
yes approves only that hash. Immediately persist ## CCL Acceptance with proposal hash,
decision identity, human owner, and accepted state. The final transaction points to this
durable acceptance artifact.
For genuinely non-material planning decisions ask the ordinary yes/no recommendation gate without manufacturing CCL state.
Architecture records
After acceptance, determine ADR qualification through $to-adr-doc. When qualified, the
ADR consumes the same accepted CCL transaction; its Decision section is deterministic CCL
projection and its Context/Rationale remain explanatory only.
Other architecture docs remain owned by their document workflows; derived wiki state
remains owned by $wiki-sync.
Atomic repository persistence
A CCL-backed acceptance is one authority transaction. When repository files change:
- freeze current canonical
origin/mainand caller-worktree identity; - use a clean isolated worktree at that base;
- have
$contract-ledgercontribute the accepted transaction; - have
$to-adr-docand$wiki-synccontribute required derived records; - require every changed path to belong to this accepted decision;
- commit once under repository conventional-commit policy;
- recheck canonical-main concurrency and push without force;
- read back and revalidate CCL plus any ADR projection;
- prove the protected caller worktree unchanged.
Persistence failure never changes the accepted semantic hash. The decision remains open until canonical repository authority is durable.
Decision closure gate
An accepted decision may not proceed from canonical repository persistence to final resolution by prose alone. Before posting final resolution, closing the decision, or mutating the Wayfinder map frontier, generate a structured closure receipt outside repository candidate state and pass the machine gate:
python .agents/skills/wayfinder/scripts/decision_closure.py \
--repo-root <clean-canonical-authority-worktree> \
--receipt <decision-closure-receipt.json>Require exact first line:
WAYFINDER DECISION CLOSURE: ALLOWEDThe receipt schema is:
{
"schema": "polaris.wayfinder-decision-closure/v1",
"decision": {
"number": 123,
"url": "https://github.com/<owner>/<repo>/issues/123"
},
"canonical_commit": "<full 40-hex commit>",
"semantic_mode": "ccl-backed",
"ccl_proposal": "sha256:<64-hex>",
"ccl_transaction": "contracts/ccl/transactions/<64-hex>.json",
"adr": {
"disposition": "CREATED | UPDATED | UNCHANGED | NOT-QUALIFIED",
"path": "docs/adr/<qualified-adr>.md | null",
"projection_check": "PASS | N/A"
},
"wiki_sync": {
"disposition": "UPDATED | NO_DURABLE_KNOWLEDGE_CHANGED",
"affected_knowledge_routing": [
{
"candidate": "WK-1",
"changed_surface_authority": "<exact source>",
"candidate_entity_claim": "<exact entity + claim/section>",
"routing_basis": "<routing evidence>",
"disposition": "affected | not-affected",
"reason_evidence": "<non-empty reason/evidence>"
}
],
"mutations": ["wiki/<changed-path>"]
}
}For a CCL-backed decision, $wiki-sync is mandatory even when no wiki text changes. A
claimed no-op is valid only after $wiki-sync has produced the complete Affected Knowledge
Routing Record required by its own workflow. NO_DURABLE_KNOWLEDGE_CHANGED is rejected if
any candidate remains affected, unresolved, or lacks reason/evidence. UPDATED requires
at least one affected candidate, exact wiki/ mutation paths, and wiki/log.md.
The gate independently requires the persisted transaction to match the accepted proposal,
requires its origin to be wayfinder-decision with durable acceptance, checks any qualified
ADR binds the exact proposal/transaction, and requires the gate worktree to be clean at the
recorded canonical commit. NOT-QUALIFIED is legal only as the $to-adr-doc disposition;
it is not permission to skip $wiki-sync for a CCL-backed decision.
For a genuinely non-material planning decision, use semantic_mode: non-material, omit CCL
coordinates, and record exact NOT-APPLICABLE child dispositions. Do not manufacture CCL,
ADR, or wiki work merely to satisfy the gate.
A failed or missing closure gate means the decision remains open. Do not post final resolution, close the decision, or mutate the map frontier, even when the semantic answer and repository persistence are otherwise correct.
Continuation reconciliation
If accepted authority must be inherited into an existing continuation branch, attempt a
clean merge only after canonical-main persistence. A merge conflict is downstream semantic
reconciliation work, not permission for Wayfinder to choose ours/theirs.
Record an actual conflict with one machine-managed block:
<!-- continuation-reconciliation:v1 -->
## Continuation Reconciliation
**Status:** required | synchronized | not-applicable
**Canonical authority:** <main commit | None>
**Continuation branch:** <branch | None>
**Conflict paths:** <exact paths | None>
**Reconciliation owner:** <$to-specs | None>required is legal only for a real semantic merge conflict and names $to-specs.
Resolution persistence
Only after required repository authority is canonical and the Decision closure gate has
returned WAYFINDER DECISION CLOSURE: ALLOWED:
- post a concise final resolution comment;
- include proposal hash, transaction path, contract@revision identities, ADR path when any, canonical commit, and Decision closure receipt SHA-256 for CCL-backed decisions;
- close the decision ticket;
- append it to
Decisions so far; - update newly surfaced tickets/fog/out-of-scope state;
- reconcile project-delivery state.
Route clarity
Wayfinder is complete when the route is clear, not merely when current tickets are closed. Every material destination obligation must be exactly one of:
accepted CCL contract/assertion
implementation-equivalent/private mechanic
explicitly out of scope
open decision/fogRoute clarity requires zero open/blocking decisions, zero unresolved fog, zero unresolved
material semantic obligations, zero CCL source conflicts, no pending required ADR/docs/wiki
or repository persistence, current project-delivery reconciliation, and continuation state
synchronized | semantic-reconciliation-required | not-applicable.
Run $attention before declaring route clear. Do not rebuild prose contract matrices or
independent semantic challenger domains around accepted CCL assertions.
If closure finds a missing semantic choice, route it to its owning decision. If it finds only an implementation-equivalent private mechanic, do not create architecture work.
Specification handoff gate
When Route Clarity resolves to downstream specification or specification reconciliation, Wayfinder may not terminate successfully from prose alone. Generate and admit the exact terminal handoff mechanically from the final durable map snapshot and the formal Route Clarity Attention result.
Capture the final map after all resolution/map/project-delivery mutations:
gh issue view <wayfinder-map> --repo <owner/repo> --json title,url,body \
> <wayfinder-map-json>Write the exact formal $attention result for this checkpoint to a temporary file outside
repository candidate state. The checkpoint must be exactly:
Checkpoint: $wayfinder route clarityA FINDINGS result must use the complete $attention finding shape. Only findings whose
Blocking basis is none are compatible with a specification handoff; a blocking finding
means Route Clarity is not terminal yet.
Then run:
python .agents/skills/wayfinder/scripts/route_handoff.py specification \
--map-json <wayfinder-map-json> \
--attention-result <route-clarity-attention-result>Require exact first line:
WAYFINDER HANDOFF: SPECIFICATIONThe helper does not decide semantic Route Clarity. It admits terminal output only after that
decision exists. It validates formal Attention shape, map identity, and any current
continuation-reconciliation:v1 record. When continuation status is required, it requires
full canonical authority SHA, continuation branch, exact conflict paths, and $to-specs as
reconciliation owner.
A failed gate means Wayfinder has not terminated successfully. Do not replace the failed handoff with explanatory prose.
For a successful specification/reconciliation terminal, the final user-visible response
must end with the helper stdout byte-for-byte as one terminal block. Do not paraphrase,
omit, reorder, or replace the generated $to-specs command or reconciliation coordinates.
Invocation flow
Chart the Map
- define destination/boundaries;
- recover current architecture/CCL;
- identify decisions and fog breadth-first;
- if no fog exists, finish the bounded decision directly rather than manufacturing a map;
- otherwise create map/tickets/dependencies/fog state;
- persist authorized repository artifacts;
- reconcile project-delivery state;
- stop.
Work Through the Map
- recover map/frontier;
- pass project-delivery guard;
- claim one decision;
- investigate only enough to close it;
- persist Decision Analysis;
- prepare exact CCL proposal when material semantics change;
- run human gate and persist acceptance;
- atomically persist CCL + ADR/docs/wiki when required;
- pass the Decision closure gate against the clean canonical authority worktree;
- persist resolution/close ticket/update map;
- reconcile project-delivery state;
- run Route Clarity; when it resolves to specification/reconciliation, pass the Specification handoff gate and emit its exact terminal block; otherwise hand off the next frontier decision.
Human handoffs
Next frontier decision:
$wayfinder - <Decision Title> (<Decision URL>)Route clear for specification is machine-generated. The canonical terminal shape is:
WAYFINDER HANDOFF: SPECIFICATION
$to-specs - <Wayfinder Map Title> (<Map URL>)
Canonical authority: <full main SHA> # only when continuation reconciliation is required
Continuation branch: <branch> # only when continuation reconciliation is required
Conflict paths: <exact paths> # only when continuation reconciliation is required
Route Clarity Attention SHA-256: <sha256>The route_handoff.py specification stdout is the handoff authority for terminal output.
Successful specification/reconciliation termination without that exact emitted stdout is an
invalid Wayfinder termination, even when explanatory prose correctly names $to-specs.
When continuation inheritance requires semantic reconciliation, $to-specs owns downstream
Spec reconciliation.
Wayfinder never implements destination code, lets implementation choose missing semantics,
reinterprets CCL through downstream prose, mutates CCL outside $contract-ledger, or
creates duplicate ADR semantics beside CCL.
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.

