> ## Content Index
> Fetch the complete content index at: https://www.notatechguy.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# wayfinder: map AI projects too big for one session
- URL: https://www.notatechguy.com/wayfinder-map-ai-projects-too-big-for-one-session/
- Published: 2026-08-28T08:47:24.000Z
- Updated: 2026-08-28T08:47:24.000Z
- Description: wayfinder charts AI efforts too large for one agent session as decision tickets on your issue tracker. Engineers install it with one npm command.
- Author: Marcello Babbili
- Tags: Technology & AI, Anthropic

Matt Pocock's wayfinder skill, part of his open-source "AI Skills for Real Engineers" collection with 237,000-plus GitHub stars, turns multi-session AI projects into a shared map of decision tickets on your issue tracker [S¹](https://www.aihero.dev/skills?ref=notatechguy.com)[P⁵](https://github.com/mattpocock/Skills?ref=notatechguy.com). By entering the /wayfinder command, the agent plots an unclear path toward your end goal and then stops, leaving the actual coding for later [S²](https://www.aihero.dev/skills-wayfinder?ref=notatechguy.com)[S³](https://github.com/mattpocock/skills/blob/master/skills/engineering/wayfinder/SKILL.md?ref=notatechguy.com). When your project is too big for one agent session, do you plan it manually or let the agent draw the map?

**My read:** This is the first AI planning skill I have seen that treats decisions as first-class objects rather than tasks. Most agent tools try to do more, but Wayfinder deliberately does less, mapping the route and then stopping. That restraint is the whole point, and it is what makes it credible for work that spans days or weeks rather than minutes. I do not buy that every team will adopt the decision-ticket model overnight, but the design is sound for the narrow problem it targets.

## How the map works

For projects that exceed the capacity of a single agent interaction, where the end goal is known but the path is not, Wayfinder creates a collective set of decision tickets within your existing issue tracker [P⁴](https://github.com/mattpocock/skills/blob/main/docs/engineering/wayfinder.md?ref=notatechguy.com)[S²](https://www.aihero.dev/skills-wayfinder?ref=notatechguy.com). The map is a single issue on your repo's tracker, labelled `wayfinder:map` [S³](https://github.com/mattpocock/skills/blob/master/skills/engineering/wayfinder/SKILL.md?ref=notatechguy.com). Its tickets are child issues of that map [S³](https://github.com/mattpocock/skills/blob/master/skills/engineering/wayfinder/SKILL.md?ref=notatechguy.com).

The map is an index, not a store. It lists the decisions made and points at the tickets that hold their detail. A decision lives in exactly one place: its ticket. The map never restates it, only gists it and links [S³](https://github.com/mattpocock/skills/blob/master/skills/engineering/wayfinder/SKILL.md?ref=notatechguy.com).

Each ticket contains a query that culminates in a choice, rather than a portion of a build to be carried out [S²](https://www.aihero.dev/skills-wayfinder?ref=notatechguy.com)[S³](https://github.com/mattpocock/skills/blob/master/skills/engineering/wayfinder/SKILL.md?ref=notatechguy.com). Once the map is finalized, wayfinder steps back and refrains from proceeding into the coding phase [S²](https://www.aihero.dev/skills-wayfinder?ref=notatechguy.com)[S³](https://github.com/mattpocock/skills/blob/master/skills/engineering/wayfinder/SKILL.md?ref=notatechguy.com). An effort can override this in its Notes, carrying execution into the map itself, but absent that override, wayfinder produces decisions, not deliverables [S³](https://github.com/mattpocock/skills/blob/master/skills/engineering/wayfinder/SKILL.md?ref=notatechguy.com).

![A single wayfinder:map issue at the top of an issue tracker, with arrows pointing down to child ticket issues. Each child ticket contains a decision question. The map issue acts as an index, linking to its children without restating their content.](https://storage.ghost.io/c/6e/89/6e896869-22ef-4281-a213-b4c462c17cff/content/images/2026/08/fig_0_wayfinder-map-structure.png)

## Why it runs only on command

The skill specification includes a metadata flag `disable-model-invocation` set to true [S³](https://github.com/mattpocock/skills/blob/master/skills/engineering/wayfinder/SKILL.md?ref=notatechguy.com)[P⁶](https://github.com/mattpocock/skills/blob/HEAD/skills/engineering/wayfinder/SKILL.md?ref=notatechguy.com). The agent will not reach for wayfinder on its own. It is triggered manually via the /wayfinder command [S²](https://www.aihero.dev/skills-wayfinder?ref=notatechguy.com). This is deliberate. Wayfinder is the heaviest, densest flow in the set, so the trigger is narrow: the scope must truly surpass what one agent session can manage, and the path to the end goal must be unclear [S²](https://www.aihero.dev/skills-wayfinder?ref=notatechguy.com).

Pocock suggests an alternative skill, /grill-with-docs, for planning within a single session. The division is straightforward: use /grill-with-docs for single-session tasks and /wayfinder for those spanning multiple sessions [S²](https://www.aihero.dev/skills-wayfinder?ref=notatechguy.com).

## The advantages

**Decisions before code.** Wayfinder forces you to answer the questions that block progress before you write implementation. Each ticket is a decision, not a task, so you resolve ambiguity first [S²](https://www.aihero.dev/skills-wayfinder?ref=notatechguy.com)[S³](https://github.com/mattpocock/skills/blob/master/skills/engineering/wayfinder/SKILL.md?ref=notatechguy.com).

**Human-readable by design.** Maps and tickets are referred to by their title names, never by bare IDs, numbers, or slugs in anything the human reads [S³](https://github.com/mattpocock/skills/blob/master/skills/engineering/wayfinder/SKILL.md?ref=notatechguy.com). The map's Decisions-so-far section uses plain language.

**Works with your existing tracker.** The skill writes to your repo's issue tracker. If no tracker is provided, it defaults to a local-markdown tracker [S³](https://github.com/mattpocock/skills/blob/master/skills/engineering/wayfinder/SKILL.md?ref=notatechguy.com). You do not need a new tool.

**Domain-agnostic.** The map works for engineering work, course content, or anything that fits the shape: a destination you can name, a route you cannot [S³](https://github.com/mattpocock/skills/blob/master/skills/engineering/wayfinder/SKILL.md?ref=notatechguy.com).

**Planning-only by default.** Upon finishing the map, Wayfinder transfers control. It avoids slipping into code generation unless a specific override is provided in the effort's Notes [S²](https://www.aihero.dev/skills-wayfinder?ref=notatechguy.com)[S³](https://github.com/mattpocock/skills/blob/master/skills/engineering/wayfinder/SKILL.md?ref=notatechguy.com).

**Two install paths.** Run `npx skills@latest add mattpocock/skills` for the full source, or `claude plugins install mattpocock-skills` for a managed, read-only Claude Code plugin [S¹](https://www.aihero.dev/skills?ref=notatechguy.com).

![A side-by-side comparison: on the left, /grill-with-docs handling a single session with a clear, short route from idea to destination. On the right, /wayfinder handling multiple sessions with a foggy route broken into numbered decision tickets, each clearing a section of fog until the full path is visible.](https://storage.ghost.io/c/6e/89/6e896869-22ef-4281-a213-b4c462c17cff/content/images/2026/08/fig_1_wayfinder-vs-grill-with-docs.png)

## Use cases

**Migrating a monolith to microservices.** You know the destination: independent services deployed separately. You do not know which boundaries to draw first, which database to split first, or how to handle shared authentication. Wayfinder turns each of those into a decision ticket, resolves them one at a time, and leaves you with a clear route before any code is written.

**Designing a new API surface.** The destination is a public API. The route is foggy: REST or GraphQL? Versioned or unversioned? How do you handle auth? Each question becomes a ticket. The map tracks which decisions are made and which remain open.

**Building a course curriculum.** Wayfinder is domain-agnostic [S³](https://github.com/mattpocock/skills/blob/master/skills/engineering/wayfinder/SKILL.md?ref=notatechguy.com). A course creator who knows the destination (what students can do at the end) but not the route (which modules, in what order, assessed how) can use the same decision-ticket structure to plan.

**Refactoring a legacy codebase.** The destination is a clean architecture. The route requires dozens of decisions: which module first, which patterns to adopt, how to handle the test gap. Wayfinder maps those decisions as child issues of a single planning ticket.

**Planning a multi-team feature rollout.** The destination is a shipped feature. The route involves API contracts, migration plans, rollout sequencing, and rollback strategy. Each becomes a decision ticket on the shared map.

![A flowchart showing a foggy path from a loose idea to a clear destination. Decision tickets resolve one at a time, each clearing a section of fog until the full route is visible. The final state shows a clear path with no fog remaining.](https://storage.ghost.io/c/6e/89/6e896869-22ef-4281-a213-b4c462c17cff/content/images/2026/08/fig_2_wayfinder-decision-flow.png)

## What to do about it

If you are an engineer using Claude Code or a similar agent, install the skills and try wayfinder on your next project that is too big for one session. Run `npx skills@latest add mattpocock/skills` or `claude plugins install mattpocock-skills` [S¹](https://www.aihero.dev/skills?ref=notatechguy.com). The repository is MIT-licensed and open on GitHub [P⁵](https://github.com/mattpocock/Skills?ref=notatechguy.com).

A concrete example: a backend team planning a payment system rewrite would type /wayfinder, let the agent create a map issue labelled `wayfinder:map`, and watch it spawn child tickets for each blocking decision. Which payment provider? Which idempotency strategy? Which webhook retry policy? The team resolves those decisions across days or weeks. When the map clears, they hand off to implementation.

One thing to check this week: read the SKILL.md specification in the repository [S³](https://github.com/mattpocock/skills/blob/master/skills/engineering/wayfinder/SKILL.md?ref=notatechguy.com)[P⁶](https://github.com/mattpocock/skills/blob/HEAD/skills/engineering/wayfinder/SKILL.md?ref=notatechguy.com) before you install. The skill is opinionated about how planning should work, and the decision-ticket model is a design choice, not an industry standard.

## What we don't know yet

The repository was created in February 2026 and has already drawn 237,000-plus stars [P⁵](https://github.com/mattpocock/Skills?ref=notatechguy.com). Documentation for wayfinder was released during the current week [S²](https://www.aihero.dev/skills-wayfinder?ref=notatechguy.com). Watch the repo's issue tracker for real-world wayfinder maps as they appear.

---

*Sources: [S1 — skills](https://www.aihero.dev/skills?ref=notatechguy.com) · [S2 — skills-wayfinder](https://www.aihero.dev/skills-wayfinder?ref=notatechguy.com) · [S3 — skills/engineering/wayfinder/SKILL.md](https://github.com/mattpocock/skills/blob/master/skills/engineering/wayfinder/SKILL.md?ref=notatechguy.com) · [P4 — docs/engineering/wayfinder.md](https://github.com/mattpocock/skills/blob/main/docs/engineering/wayfinder.md?ref=notatechguy.com) · [P5 — mattpocock/skills](https://github.com/mattpocock/Skills?ref=notatechguy.com) · [P6 — skills/engineering/wayfinder/SKILL.md](https://github.com/mattpocock/skills/blob/HEAD/skills/engineering/wayfinder/SKILL.md?ref=notatechguy.com)*

## More from Not A Tech Guy

- [AI coding agent defense cuts malware severity 83%](https://www.notatechguy.com/ai-coding-agent-defense-cuts-malware-severity-83/)
- [WebMCP-Phalanx blocks 80 of 80 prompt injection attacks in browser agents](https://www.notatechguy.com/webmcp-phalanx-blocks-80-of-80-prompt-injection-attacks-in-browser-agents/)
- [StepGuard blocks AI agent attacks 77% before they run](https://www.notatechguy.com/stepguard-blocks-ai-agent-attacks-77-before-they-run/)

---

*Generated from an audited evidence pack with primary-source research. Social-media items are discussion signals, not verified facts. Nothing here is financial, legal or medical advice.*