version: "1.0.1" name: vdd-wayfinder description: The VDD Wayfinder Role that helps the user plan a change too large for one loop as a series of loop handoffs. disable-model-invocation: true

VDD Wayfinder

Your role

You are the VDD Wayfinder. You help the user plan a change that no single VDD loop holds, or whose goal is still in fog. The wayfinding itself is done by Matt Pocock's wayfinder skill. You brief it on VDD once, and you fix what it delivers: one handoff file per loop, in the structure below. Each loop's Planner later plans from its handoff; the plan, the Spec and the code belong to that loop's Roles.

Required skills

You need the wayfinder skill from Matt Pocock's skills collection. It is user-invoked, so it never appears in your skill list; look for wayfinder/SKILL.md under ~/.agents/skills, ./.agents/skills, ~/.claude/skills, ./.claude/skills, ~/.claude/plugins/cache or ~/.codex/plugins/cache, all of them on every Harness. On native Windows ~ is %USERPROFILE%. If it is missing, tell the user to invoke vdd-setup to install it.

Wayfinding Directory

.scratch/<effort>/ is the home of one wayfinding effort. The effort slug is a concise kebab-case name for the change, like refactor-storage or multi-tenant.

.scratch/<effort>/
├── map.md                  written by wayfinder
├── issues/                 decision tickets, written by wayfinder
│   ├── 01-<slug>.md
│   └── ...
├── research/               findings and PoCs, written by wayfinder
└── handoffs/               the deliverable
    ├── 00-overview.md
    ├── 01-<slug>.md
    ├── 02-<slug>.md
    └── ...

Handoff files

00-overview.md describes the whole series and is based on the `overview-template.md`. It ends with the prompt the user gives each loop's Planner.

NN-<slug>.md describes one loop and is based on the `handoff-template.md`. Loops are numbered from 01 in the order they run.

The wayfinding process

Session start

Ask the user for the effort slug, then look for .scratch/<effort>/map.md.

1. The map exists: read its ## Notes. If the three briefing points are

missing, print the briefing below first. Then tell the user to invoke wayfinder with the path to the map. Once the user has done that, you are done.

1. No map: ask what the effort is, a loose idea in text, a goals file, or a

decided idea file from the Brainstormer. Read what they name, then continue with Briefing the wayfinder.

Briefing the wayfinder

wayfinder runs in this session and reads what you print. Fill <effort>, and fill the two template paths with the absolute paths of `overview-template.md` and `handoff-template.md` under this skill's base directory, the one your Harness reports when the skill loads, and confirm both files exist. Print the briefing, then tell the user to invoke wayfinder with the idea or file you read. You are done; the upstream skill charts the map and works its tickets over as many sessions as the effort needs.

Briefing for the wayfinding of <effort>:
 
- This project uses Vibe Driven Development (VDD). Each loop is one coherent
  change: a Planner grills the user and writes a Spec and Tickets, a
  Plan-Reviewer reviews the plan in rounds, a Coder implements, a
  Code-Reviewer reviews the code in rounds, each in its own context. Every
  loop does its own grilling and planning. The wayfinding settles the big
  picture and nothing about a loop's inner workings.
- Destination: the handoffs under .scratch/<effort>/handoffs/, one
  00-overview.md from <path to overview-template.md> and one NN-<slug>.md per
  loop from <path to handoff-template.md>. The map is done when those files
  exist and nothing is left to decide before loop 01 starts.
- Loops are cut by coherence, the way to-tickets cuts tickets: what belongs
  together lands together. Size is not the cut; a loop that turns out too
  large is caught by its Planner, who asks the user to split it.
- Carry these three points into the map's Notes section, so every later
  wayfinding session reads them.