Wayfinder

All work enters through wayfinder regardless of size, but not all work earns a map. Grill first; if the way to the destination is already clear, take the no-fog early exit (Mode 1, step 3) and proceed without one. A trivial task's map might have 1 grilling ticket and 1 task ticket; a large migration might have 20+. The process is consistent; only the map size varies.

The map

A single document (on the configured tracker) containing:

• Destination — one sentence: where are we trying to get.
• Decisions so far — one line per resolved ticket: enough to judge relevance, plus a link to the ticket holding the detail.
• Open tickets — the sharp questions, with blocking relationships.
• Not yet specified — in-scope fog: questions you can tell are coming but cannot yet phrase sharply. Graduates into tickets as the frontier advances.
• Out of scope — work ruled beyond the destination. Closed, and it never graduates.

The map is an index, not a store

A decision lives in exactly one place — its ticket. The map gists and links; it does not restate. Load the map at low resolution to orient, then zoom into individual tickets on demand.

Keep it this way for a concrete reason: a decision written in two places starts drifting between them the moment one is edited, and a map that restates every decision grows until it no longer fits the context window it exists to save.

When fog graduates into a ticket, clear the graduated patch from Not yet specified so it lives only as its new ticket.

Fog or ticket?

The test is whether you can state the question precisely now — not whether you can answer it now.

• Ticket when the question is already sharp, even if it is blocked and cannot be acted on yet.
• Not yet specified when you cannot phrase it that sharply. Leave the patch coarse: one patch may graduate into several tickets, or none, once the frontier reaches it.

Not yet specified is for work inside the destination. Fog gathers only toward the destination — work beyond it belongs under Out of scope, where it does not read as takeable frontier.

Ticket types

HITL = human in the loop. AFK = agent works unattended.

Grilling discipline

Grilling happens inside tickets typed as "grilling". The full grilling methodology lives in skills/grilling/SKILL.md. Key points:

1. One question at a time. Never batch multiple questions.
2. Propose before asking. State a recommended answer; user confirms or corrects. Faster than open-ended questions.
3. Facts vs decisions. If it can be found by reading the codebase, look it up. Only ask about decisions the user must make.
4. Challenge every answer. After each response, explore what it implies, what it breaks, and what happens at the edge. Do not move on until the downstream effects are mapped.
5. Spot and reject vagueness. Push abstract answers ("flexible", "whatever makes sense") to concrete specifics.
6. No question cap. Could be 3 or 50 — driven by ambiguity. The session ends when you cannot generate another question whose answer would change what gets built.
7. Domain modeling inline. Terms captured to CONTEXT.md as they surface. ADRs written when non-obvious decisions are made.
8. Confirmation gate. Do not proceed from grilling tickets until user confirms shared understanding is reached.

Mode 1: Chart the map

1. Name the destination in one sentence. It fixes the scope and shapes every ticket, so settle it first.
2. Map the frontier — grill breadth-first, fanning out across the whole space rather than deep on any one thread, to surface the open questions and what is takeable now.
3. No-fog early exit. If that breadth-first pass surfaces no fog — the way to the destination is already clear and the whole journey fits one session — stop and ask the user how they would like to proceed. Do not build a map nobody needs. This fires before any map exists, and is cheaper than the post-map fork in "Completion".
4. Otherwise create the map: destination filled in, decisions empty, and the fog sketched into Not yet specified.
5. Create the tickets you can specify now, then mark blocking relationships. Everything you cannot yet phrase sharply stays as fog.

Refer to tickets by name

In everything the user reads — narration, the map's Decisions so far — a ticket goes by its name, not a bare id. #42, #43, #44 is illegible; names read at a glance. Keep the id or link, but carry it inside the name rather than in place of it.

Mode 2: Work through the map

1. Load the map at low resolution — the index, not every ticket body. Orient to the destination before choosing.
2. Find the next unblocked ticket. Zoom into related or closed tickets on demand as the work needs them.
3. Resolve it (grilling → ask user; research → delegate to research skill; prototype → delegate to skills/prototype/SKILL.md; bug → delegate to skills/diagnosing-bugs/SKILL.md; task → do it).
4. Record the detail on the ticket, and a one-line gist plus link on the map's "Decisions so far" — the map indexes, the ticket holds.
5. Graduate whatever the answer made specifiable into fresh tickets, clearing each graduated patch from Not yet specified. Add any newly revealed fog. If the answer shows a ticket sits beyond the destination, rule it out of scope rather than resolving it.
6. Repeat until all tickets are closed.

Evidence-bearing STOP gates

A phase does not advance because you assert it is done. It advances when you can show evidence it is done. Before moving a phase forward, PASTE the evidence — do not merely claim it:

Assertion alone ("tests pass", "looks good", "that's complete") is NOT sufficient and does not advance the flow. No evidence → the phase stays open. This replaces V1's hard checkpoint state-machine: same resistance to premature completion, without a rigid stage enum.

Tangential work: STOP and classify, never execute

The single biggest source of drift is doing related-but-off-ticket work the moment it surfaces — the pull to "just fix this while I'm here." That pull is not a task; it is a signal you have reached the edge of the map.

When you notice work that is not part of the current ticket, you MUST:

1. STOP. Do not touch it. Do not start "just a quick fix."
2. Name it. State plainly: "this is off the current ticket."
3. Classify it into exactly one of:
   • Graduate → it is in scope and you can state the question sharply: create a new ticket, add it to the map with any blocking relationships.
   • Park as fog → it is in scope but you cannot phrase it sharply yet: log it under Not yet specified, never under open tickets. Fog in the ticket list reads as takeable frontier and will be picked up as work before it is ready.
   • Rule out of scope → log it under "Out of scope" and close it. An out-of-scope item never silently graduates later without a new decision.
4. Return to the current ticket.

No classification → no action. This applies during grilling, research, and implementation alike. Absorbing the work silently into the current ticket is the prohibited path.

Completion → fork: direct-implement or spec-first

When all map tickets are resolved:

1. Summarize the complete picture on the map.
2. Tell the user the map is complete.
3. Judge the scope and take the fork. Ask: does the entire remaining change fit comfortably in a single context window — needing neither multiple sessions nor a written spec to survive a context reset?
   • Fits one context → direct implement. Treat the map's accumulated decisions as a single ticket and hand straight to skills/implement/SKILL.md. Skip to-spec and to-tickets. State the one-line rationale ("small enough for one context — implementing directly, no separate spec") so the shortcut is never silent.
   • Multiple sessions, or a durable spec would help it survive a reset → spec-first. Hand off to skills/to-spec/SKILL.md to synthesize a spec from the accumulated decisions, then to-tickets.

This mirrors the fork in the canonical flow: trivial changes go straight to implement; larger work earns a spec + tickets so it survives across context windows.

Implementation orchestration

After to-spec → to-tickets produces the implementation tickets, wayfinder orchestrates the implementation phase. One ticket ≈ one context window (see reference/context-budget.md): each ticket was sized to be implemented and reviewed inside a single fresh context, and a clean context per ticket is what keeps the agent in the "smart zone" where it doesn't drift or hallucinate.

• For each implementation ticket, invoke skills/implement/SKILL.md.
• After each ticket completes — commit + tracker update happen inside implement; then persist .agent/state.json (status, next ticket). This makes every ticket boundary a clean resume point: the SessionStart hook re-anchors from state + map, so clearing costs almost nothing.
• When recommending a clear, write a handoff first. state.json and the map carry what is settled; they do not carry the live thread — what was tried, what was ruled out, why this approach. Where that reasoning matters to the next ticket, invoke skills/handoff/SKILL.md and give the user the document path alongside the clear recommendation.
• Risk posture behavior:
  • "standard" — may run tickets back-to-back while the context window is still healthy. Once the window has grown large or the next ticket is substantial, recommend the user clear and resume in a fresh session rather than pushing on in a degrading context: "Ticket N is done and state is saved — good point to /clear and resume, or I can continue." Let the user decide; do not force a reset, and do not silently accumulate every ticket in one window.
  • "careful" — after each implement ticket completes, report what was done, whether tests are green, and what the next ticket is. Wait for user OK before continuing; the next ticket resumes in a fresh context.
• After all tickets pass and per-ticket code-review completes, run the final combined-diff review (see below) before anything else.
• After the final combined-diff review passes:
  • If doc_tier in .agent/state.json is "app" or "system", offer an architecture review: "Implementation is done. Want me to run an architecture review to check for deepening opportunities?"
  • If the user accepts, invoke skills/improve-codebase-architecture/SKILL.md.
  • If candidates are found and the user picks one, create new wayfinder tickets for the chosen refactors (these run as a fresh implementation cycle).
  • If the user declines, skip.
• Update .agent/state.json status to "done".

Final combined-diff review

Per-ticket code-review only sees one ticket's diff. It cannot catch drift that spans tickets, or behavior that crept into the combined diff nobody asked for. So before completion, run one independent pass over the whole change:

1. Dispatch a fresh, isolated subagent — it must NOT be the agent that wrote the code. Delegate to skills/code-review/SKILL.md.
2. Inputs: the combined diff of all implementation tickets + the approved docs/agents/spec.md.
3. Axes:
   • Correctness — real defects in the combined change.
   • Scope-creep — behavior present in the diff but absent from the spec. This is the drift the per-ticket pass misses.
4. Report findings most-severe first.
5. Gate: unresolved scope-creep findings block completion. Either the drift is reverted, or it graduates to a new ticket via the STOP-and-classify reflex — it is never waved through silently.

Bug tickets

When resolving a ticket typed as bug:

1. Delegate to skills/diagnosing-bugs/SKILL.md
2. The skill runs AFK through Phases 1–2 (feedback loop, reproduce)
3. Pause at Phase 3 (hypothesise) — present ranked hypotheses to the user for confirmation before testing
4. Continue AFK through Phases 4–5 (instrument, fix)
5. Phase 6 post-mortem: if the finding is architectural ("no good test seam exists"), create a new wayfinder ticket pointing to skills/improve-codebase-architecture/SKILL.md

Prototypes

Created during "prototype" tickets. Delegates to skills/prototype/SKILL.md. Two types:

• Logic — terminal app testing state/edge cases.
• UI — multiple visual variants switchable via URL params.

Prototypes are throwaway. Once the decision is captured on the map, the prototype code is deleted.

The skill is working if

Stated as the behaviour to hit rather than the behaviour to avoid — prohibitions make the forbidden move more available in context, not less.

• Implementation begins once the map is complete — or once the no-fog early exit has established no map is needed.
• Every grilling ticket resolves through the user's own answer. A HITL ticket resolves only through the live exchange; the agent asking and then answering for the user has, by definition, broken it.
• Each grilling turn puts exactly one question to the user, and waits.
• New discoveries run the STOP-and-classify reflex — graduate, park as fog, or rule out of scope — so every off-ticket pull ends in one of three named places, and the current ticket keeps the scope it started with.
• Blocking relationships are wired for every ticket, so the frontier is always the open unblocked set.
• Questions of fact get looked up in the codebase; questions of decision go to the user. Keeping the split is what stops a grilling agent from racing ahead and answering its own questions.