Wayfinder

Hermes Wayfinder

Lineage

This is an MIT-licensed adaptation of Matt Pocock's public wayfinder. It retains the destination, map, decision-ticket, frontier, fog, and one-ticket-at-a-time concepts while adding Hermes-specific authority, persistence, recovery, mode, and handoff contracts.

The complete upstream MIT notice is preserved in [references/third-party-notices.md](references/third-party-notices.md).

Overview

Wayfinder charts a durable route through an effort too large or uncertain for one session. It owns the map, fog, frontier, ticket lifecycle, persistence, handler routing, and readiness handoff. It resolves decisions and evidence—not the destination itself.

Bounded Grill -> Wayfinder
  DECISION     -> Bounded Grilling
  EVIDENCE     -> verified evidence handler
  PROTOTYPE    -> `/prototype`: runnable artifact + human reaction
  PREREQUISITE -> bounded task/checklist
Wayfinder -> To-Spec -> `/to-tickets` (separate explicit authority)

The canonical shared handler contracts live in:

• references/evidence-handler.md
• references/prototype-handler.md

For a small effort whose route is already clear:

Bounded Grill -> To-Spec

Adaptive invocation and operating level

When /wf is manually invoked or its automatic ambiguity gate detects one genuine route-affecting unknown, enter Wayfinder LIGHT immediately when this skill is the selected handler; the ordinary multi-signal heuristic below is not required. Investigate discoverable facts first and route one human-owned value to Bounded Grilling rather than assuming it. Do not create FULL artifacts from this standing ambiguity authority alone.

Otherwise choose LIGHT or FULL before applying the workflow.

LIGHT — model-invokable, non-persistent

Use LIGHT automatically when structure would reduce drift but a durable map would be disproportionate. Typical signals include two or more of:

• the task has at least three meaningful steps or two material choices;
• dependencies or ordering matter;
• the route is partly uncertain but likely resolvable in the current session;
• tools, agents, or people need a concise handoff;
• explicit scope, frontier, or acceptance boundaries would prevent rework.

LIGHT stays inside the current conversation. It creates no map, ticket, tracker item, branch, or project file. Keep only a compact route:

Destination
Decisions and constraints
Unknowns / fog
Current frontier
Out of scope

LIGHT may be embedded in an already-authorized task and return control to that task. It does not impose the one-ticket-per-invocation rule, emit a durable handoff packet, or claim a FULL completion state.

FULL — durable protocol

Use FULL when the user explicitly invokes Wayfinder, or automatically when any of these hard signals makes recovery and persistence materially valuable:

• the effort will likely outlive the current session;
• three or more unresolved route-changing decisions remain;
• multiple agents or people may work concurrently;
• a durable handoff, restart point, or authoritative decision history is

required.

When selecting FULL automatically, announce that choice in one sentence and name the persistence target. Create a project-local package only when the current task already authorizes project artifacts; otherwise obtain approval before mutation. External tracker creation or mutation always requires current project policy or explicit user authorization.

An explicit FULL chart invocation, or an automatically selected FULL chart with artifact authority, authorizes:

• one Bounded Grill opening-router call when no valid route packet exists; and
• creation of a local Wayfinder package in the active project when no

externally authorized tracker is available.

Neither level authorizes external issue publication, destination implementation, deployment, or unrelated side effects.

Authority boundary

• Plan and resolve uncertainty; do not deliver the destination.
• Never answer the human side of a HITL decision.
• Never silently turn evidence into a human preference.
• Never create or mutate an external tracker unless current project policy or

the user explicitly authorizes that tracker.

• Prerequisite work may only expose evidence needed for a decision; it may not

become destination implementation.

• Research dispatch is not ticket resolution: cited results require parent

verification and persistence before closure.

• Prototype authority permits only the named throwaway decision artifact. It

never authorizes production implementation, main-branch integration, publication, deployment, or cleanup.

• Stop immediately on a user stop signal.
• A FULL To-Spec handoff requires either an explicit user request or an

already-authorized workflow whose endpoint includes specification. LIGHT To-Spec may follow automatically without persistence or publication.

FULL operation mode

When operating at FULL, choose exactly one:

• CHART — create a new map from a valid route packet or loose idea.
• ADVANCE — claim and resolve exactly one ticket on an existing map.
• ASSESS — read-only readiness, consistency, or frontier inspection.

Never chart and advance in the same FULL invocation. LIGHT may orient and make progress in one ordinary task because it creates no authoritative tickets.

Persistence backend

This section applies only to FULL. LIGHT never selects a persistence backend.

Choose before any FULL map mutation:

1. Use an existing project tracker only when it is already configured and

authorized for this effort.

1. Otherwise use a project-local package:

/.hermes/wayfinder//
  map.md
  tickets/
    .md

Do not place project-specific maps in the shared Hermes workspace unless that workspace is itself the active project.

If no safe project root or authorized tracker can be identified, return BLOCKED. Never guess an external tracker or create one.

The map is an index, not a store. Full questions, evidence, answers, rationale, constraints, and negative requirements live in exactly one authoritative ticket record. The map stores only status, one-line gists, and handles.

For concurrent work:

• prefer tracker-native assignment or claims;
• local-file mode is serialized by default;
• permit parallel local work only when an available primitive can create an

exclusive claim and fail if the claim already exists;

• otherwise return BLOCKED rather than risk duplicate resolution.

Map contract

Every map records:

# 

Status: CHARTING | ACTIVE | READY_FOR_SPEC | BLOCKED |
  DESTINATION_COMPLETE_WITHOUT_SPEC | RECONCILE_REQUIRED | SUPERSEDED
Map handle: 
Updated: 

## Destination

## Authority and persistence

## Notes

## Decisions so far

## Not yet specified

## Out of scope

## Handoff

Open tickets live in the tracker or tickets/ and are found by query or scan. Do not duplicate their full bodies in the map.

Ticket contract

Each ticket has one stable tracker or local identity and one precise question:

# 

ID: 
Type: DECISION | EVIDENCE | PROTOTYPE | PREREQUISITE
Mode: HITL | AFK
Status: OPEN | CLAIMED | RESOLVED | DEFERRED | BLOCKED | OUT_OF_SCOPE | SUPERSEDED
Blocked by: 
Claim: 

## Question

## Resolution

## Rationale and sources

## Constraints and dependency effects

Ticket types:

• DECISION / HITL — one human-owned route decision, resolved through

Bounded Grill's Wayfinder mode.

• EVIDENCE / AFK — one discoverable factual question. Resolve it through

references/evidence-handler.md, using the active profile's permitted research/inspection tools and source hierarchy.

• PROTOTYPE / HITL — one logic/state or UI-shaped decision that needs a

runnable throwaway artifact and actual human reaction. Invoke /prototype, whose canonical contract is references/prototype-handler.md; prose alone cannot close it.

• PREREQUISITE / AFK or HITL — bounded manual work required to expose

evidence. It needs explicit authority when it has side effects and may not deliver the destination.

Handler and closure gate

Ticket type is a workflow gate, not a category. After claiming a ticket and immediately before resolution, re-read its authoritative type, question, blockers, claim, and current status. If type and prose disagree, stop for reconciliation rather than choosing the easier handler.

Route exactly:

• DECISION -> Bounded Grilling; require one accepted human decision packet.
• EVIDENCE -> references/evidence-handler.md; require a valid

wayfinder-evidence-v1 handoff with parent verification and confirmed persistence.

• PROTOTYPE -> invoke /prototype, whose canonical contract is

references/prototype-handler.md; require a valid wayfinder-prototype-v1 handoff, a smoke-verified artifact, actual human reaction, and an accepted decision.

• PREREQUISITE -> perform only the authorized bounded task; require observable

completion evidence, or leave the ticket open with a precise human checklist or blocker.

Before marking any ticket resolved:

1. Re-fetch/re-read the ticket and claim; abort or reconcile stale, closed, or

rival work.

1. Verify handler-specific evidence and all referenced artifacts.
2. Classify outputs as durable shared context, ticket evidence, disposable

intermediate, or potential implementation.

1. Reconcile durable shared context into its canonical location. Never strand

it on a research/prototype branch or isolated workspace.

1. Persist the full resolution in the ticket first, then reconcile the map.
2. If evidence persists but context/map reconciliation fails, return

RECONCILE_REQUIRED; do not duplicate or silently close the ticket.

An ADVANCE invocation becomes spent after one handler outcome, including a blocker, deferral, or PROTOTYPE_REQUIRED escalation. It may repair bookkeeping for that ticket but may not claim another ticket.

CHART mode

1. Orient to the user's named effort and available sources.
2. Consume a grill-route-v1 packet when present. If absent, invoke Bounded

Grill's opening router once under the active FULL invocation's authority.

1. Handle the route:

• DIRECT_SPEC — create no map; return the Grill packet and stop.
• BLOCKED — create no map; return the named blocker and stop.
• WAYFINDER — continue only when destination, accepted decisions,

constraints, evidence handles, and suspected fog are internally consistent.

1. Select the persistence backend.
2. Import every accepted Grill decision:

• when its handle resolves to a durable authoritative record, reference

that record without copying it;

• when persistence: pending or no durable handle exists, create one

authoritative RESOLVED decision ticket in the selected backend, preserving the exact accepted value, source timestamp, rationale, constraints, and negative requirements;

• use the resulting ticket identity as the authoritative handle.

Importing an already-accepted decision persists chart input; it is not resolution of a new frontier ticket.

1. Create one map with destination, authority, accepted-decision pointers,

boundaries, and fog.

1. Create only questions precise enough to be tickets. Leave coarser

uncertainty under Not yet specified.

1. Assign stable identities, types, modes, blockers, and creation order. Use

PROTOTYPE when interaction with a concrete artifact is required; do not disguise it as prose DECISION or generic PREREQUISITE work.

1. Write and verify every imported and open ticket before writing the map

index.

1. Re-read the persisted map and tickets.
2. Optionally dispatch independent EVIDENCE tickets through

references/evidence-handler.md only after their records are durable. Dispatch does not resolve or close them. Use delegate_task only when the parent session can safely receive the result; use authorized Kanban for restart-durable work. Record every dispatch handle.

1. Return MAP_READY, include any evidence dispatch handles, and stop.

Resolve or claim no non-evidence frontier ticket during charting.

ADVANCE mode

1. Load the map at low resolution and verify its current status and backend.
2. Select the user-named ticket or the first open, unblocked, unclaimed ticket

in stable creation order.

1. Claim it before work. If the claim cannot be made safely, return BLOCKED.
2. Re-read the claimed ticket's authoritative type, body, blockers, claim, and

current status, then run exactly one handler:

• DECISION — invoke Bounded Grill Wayfinder mode with the ticket handle,

destination, question, relevant decisions, and direct dependencies. If the decision cannot be judged faithfully in prose, consume a PROTOTYPE_REQUIRED return by leaving the decision open, creating one PROTOTYPE ticket, and then adding a create-then-link edge that makes the decision ticket depend on the prototype ticket; do not fabricate the decision.

• EVIDENCE — follow references/evidence-handler.md; inspect cited

sources and verify the result before persistence.

• PROTOTYPE — invoke /prototype and its canonical

references/prototype-handler.md contract; obtain artifact authority, smoke-run the artifact, collect actual human reaction, and preserve the accepted/rejected alternatives.

• PREREQUISITE — perform only the already-authorized bounded work needed

to expose evidence. Otherwise block with the required authority or exact human checklist.

1. Apply the handler and closure gate. Persist the full resolution in the

ticket first.

1. Close or resolve a decision only after its accepted record is confirmed

persisted. A normal deferral remains open and blocking; close it only when the product acceptor explicitly marks it non-blocking.

1. Append only a one-line gist and ticket handle to Decisions so far.
2. Graduate newly precise fog into new tickets, create-then-link blockers, and

remove the graduated text from Not yet specified.

1. Mark invalidated tickets or assumptions SUPERSEDED; never erase history.
2. Recompute the frontier, release the claim, run the exit gate, and stop.

If ticket persistence succeeds but map reconciliation fails, the ticket remains authoritative. Mark the map RECONCILE_REQUIRED, return that state, and do not repeat or duplicate the resolution.

ASSESS mode

Read only. Report:

• destination and authority;
• persistence health;
• current frontier and blockers;
• unresolved or contradictory route decisions;
• hidden, duplicated, stale, or graduated-but-not-cleared fog;
• exit-gate status;
• exact next eligible ticket or handoff state.

Do not claim, resolve, create, close, or edit anything.

Exit gate

Wayfinder may emit READY_FOR_SPEC only when all five conditions hold:

1. Destination, scope, acceptance boundary, and out-of-scope boundary are

explicit.

1. Every route-changing decision is accepted, blocked, or explicitly deferred

as non-blocking by the product acceptor.

1. No material in-scope fog remains hidden or unclassified.
2. No eligible decision, evidence, prototype, or prerequisite ticket remains.
3. The product acceptor explicitly determines the route is ready for local

specification.

If conditions 1–4 hold but condition 5 has no authoritative record, create one named final DECISION ticket and stop. Resolve it in a later ADVANCE invocation through Bounded Grill.

If the destination is itself a final decision or intentionally ends without a specification, emit DESTINATION_COMPLETE_WITHOUT_SPEC instead.

To-Spec handoff

On exit, persist and return this exact packet:

schema: wayfinder-to-spec-v1
outcome: READY_FOR_SPEC | BLOCKED | DESTINATION_COMPLETE_WITHOUT_SPEC
destination: 
map_handle: 
decision_handles: []
scope: []
out_of_scope: []
evidence_hand

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [SaikaAco](https://github.com/SaikaAco)
- **Source:** [SaikaAco/saika-hermes-skills](https://github.com/SaikaAco/saika-hermes-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.