# Wayfinder

> Use for medium-to-large work with multiple material decisions, dependencies, fog, or multi-session coordination. Applies a lightweight in-session route automatically when useful and a durable full Wayfinder package when explicitly invoked or scale requires persistence.

- **Type:** Skill
- **Install:** `agentstack add skill-saikaaco-saika-hermes-skills-wayfinder`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [SaikaAco](https://agentstack.voostack.com/s/saikaaco)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [SaikaAco](https://github.com/SaikaAco)
- **Source:** https://github.com/SaikaAco/saika-hermes-skills/tree/main/skills/wayfinder

## Install

```sh
agentstack add skill-saikaaco-saika-hermes-skills-wayfinder
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Hermes Wayfinder

## Lineage

This is an MIT-licensed adaptation of Matt Pocock's public
[`wayfinder`](https://github.com/mattpocock/skills/tree/main/skills/engineering/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.

```text
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:

```text
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:

```text
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.
2. Otherwise use a project-local package:

```text
/.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:

```markdown
# 

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:

```markdown
# 

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.
2. Verify handler-specific evidence and all referenced artifacts.
3. Classify outputs as durable shared context, ticket evidence, disposable
   intermediate, or potential implementation.
4. Reconcile durable shared context into its canonical location. Never strand
   it on a research/prototype branch or isolated workspace.
5. Persist the full resolution in the ticket first, then reconcile the map.
6. 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.
3. 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.
4. Select the persistence backend.
5. 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.
6. Create one map with destination, authority, accepted-decision pointers,
   boundaries, and fog.
7. Create only questions precise enough to be tickets. Leave coarser
   uncertainty under `Not yet specified`.
8. 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.
9. Write and verify every imported and open ticket before writing the map
   index.
10. Re-read the persisted map and tickets.
11. 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.
12. 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.
3. Claim it before work. If the claim cannot be made safely, return `BLOCKED`.
4. 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.
5. Apply the handler and closure gate. Persist the full resolution in the
   ticket first.
6. 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.
7. Append only a one-line gist and ticket handle to `Decisions so far`.
8. Graduate newly precise fog into new tickets, create-then-link blockers, and
   remove the graduated text from `Not yet specified`.
9. Mark invalidated tickets or assumptions `SUPERSEDED`; never erase history.
10. 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.
2. Every route-changing decision is accepted, blocked, or explicitly deferred
   as non-blocking by the product acceptor.
3. No material in-scope fog remains hidden or unclassified.
4. No eligible decision, evidence, prototype, or prerequisite ticket remains.
5. 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:

```yaml
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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-saikaaco-saika-hermes-skills-wayfinder
- Seller: https://agentstack.voostack.com/s/saikaaco
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.