ARTICLE
Getting Started with Wayfinder
Russ Painter
Software Architect, 8 West Consulting
October 02, 2026
Introduction
Most of us have already learned the hard way that pure vibe coding outputs results that are far from clean and maintainable. We know we need planning and specs before letting an agent loose on a codebase, but finding the right planning tool is still a struggle. There's no one size fits all tool that I'm aware of.
If you’ve been watching the SDD options, you’ve probably hit two extremes:
- Heavyweights (like BMAD): Frameworks that try to own your entire process from end to end. They overwhelm you with decision artifacts and lots of planning layers. They take lots of time, and burn a lot of tokens. The output is a ton of documentation that seems human readable, but who has time to read all of that?
- Lightweights (like Spec Kit): These tools put a cap on clarification. Spec Kit literally stops asking questions after five questions, and instruct the AI to fill in the rest using "reasonable default" assumptions. That means AI guesses get mixed into written specs that look like deliberate architectural choices.
So I’ve been trying Matt Pocock’s skills ecosystem and its flagship planning skill "Wayfinder". Wayfinder embraces the "fog of war", keeping track of decisions that need to be made, and helping you research or think through the options. It charts big, multi-session efforts on your issue tracker (or folder of markdown files) as a live map of decision tickets (grilling, prototype, research, task), clearing uncertainty one ticket at a time while strictly requiring human input where it matters. It outputs planning artifacts that are meant to be temporary, combines these into a PRD, and then breaks these into tasks for implementation. There are also other bonuses like code review and architecture re-analysis among other hidden gems.
Here’s how to get started with Wayfinder in a greenfield or brownfield project to scope out the entire thing, or just a new feature.
Prerequisites
Root documentation structure
Every project should include a root AGENTS.md file. This should be minimal and link to other documents for each focused topic of the overall project structure. For an existing project, check that you already have adequate overall project overview docs similar to below.
| AGENTS.md docs/ CodingStandards.md Glossary.md MonoRepo.md TechStack.md |
I begin with a very minimal AGENTS file that links to the individual docs like this:
| # Project Name ## Repository Overview Details of the sub-projects are in [`docs/MonoRepo.md`](docs/MonoRepo.md) ## Tech Stack Tech used is documented in [`docs/TechStack.md`](docs/TechStack.md) ## Coding Standards Coding standards are documented in [`docs/CodingStandards.md`](docs/CodingStandards.md) ## Ubiquitous Language Terminology is maintained in [`docs/Glossary.md`](docs/Glossary.md) ## Agent Persona * In all interactions and commit messages, be extremely concise and sacrifice grammar for the sake of concision. * Ask one brief question at a time. State what decision is needed concisely without long explanations. |
Any design decisions and domain knowledge known ahead of time can be pre-populated into these documents, or they can be left blank as stubs to be filled in later either manually or by the AI agents.
Issue tracking decision
With this process, you can track progress either in markdown files within the source directory, or with project planning tickets. Decide how you would like to work.
Install the skills
| pnpx skills@latest add mattpocock/skills --skill=setup-matt-pocock-skills |
You'll be prompted with a list of skills to install, I'll just choose all of them. Then you're asked if you're using any agents other than the ones that use the .agents/skills standard. GitHub Copilot is standard, so I won't need any others. You can install the skills in the project, or globally for the developer. I like having these skills in the project so the rest of the team can be aligned on the same set of skills.
Bootstrap the skills
In your agent window or agent cli type
| /setup-matt-pocock-skills |
What it does next depends on your project. If your repository has a GitHub remote, then it will ask if you want to use GitHub's tickets to keep track of tasks and track progress, or if you would like to just work locally using markdown files in the .scratch/<feature>/ folder.
It will then ask if you want to change the triage stats labels which default to: needs-triage, needs-info, ready-for-agent, ready-for-human, and wontfix.
Next you can customize the domain docs structure, or just stick with the default of a root CONTEXT.md and /docs/adr/ folder
Phase 1: Planning
Model Selection
These skills were optimized with Claude models, but work best with medium to low thinking. So I'm going to switch to Claude Opus 5 set to Low/200K.
Initial Rough Plan
Tell wayfinder about what we want to make. We don't need to be too specific at this point:
Now it'll ask me clarifying questions. It asks me to clarify what the distinction is between a visit and a story, if privacy is at the visit or story level, how locations are input, and then start getting into other functional and technical questions.
This took about 15 minutes of chatting and then 5 minutes for the agent to put together a plan. The output was this map and 10 issues files. From this point forward, keep an eye on the /.scratch/ folder.
| # Map: Social travel log Type: wayfinder:map ## Destination A written spec for v1 of a phone-first social travel log — good enough to hand off and iterate on. Not a build, not a prototype. ## Notes Domain (user's words): *"A visit is a time that I went to a location. During that visit, I may create one or more stories. Each of these could be a specific place review, a slideshow, or just general tips."* - `Visit` — one user, one location, one time. Owns privacy (public/private). - `Story` — content nested under a Visit. Inherits the Visit's privacy. Types: place review, slideshow, general tips. - `Location` — free-text input that resolves to a real geocoded place (stable id + coords). Rolls up to a **city** for browse; city page drills down to the exact place. Settled during charting: - Public content is readable by logged-out visitors and publicly searchable (SEO-indexable). Sign-in required only to create. - Sign-up is email + password. Auth is owned by the .NET API. - Photos: object storage, cap **20 per story**. - Platform: installable PWA. - Stack: .NET 10 API + Supabase (Postgres + object storage) + Vue frontend. **All** client traffic goes through the .NET API; Supabase is never called directly from the browser, so privacy rules live in exactly one place. - Abuse: account self-delete, plus a "report content" button feeding an admin queue. Implies an admin role. Standing preferences: be extremely concise; one brief question at a time. Never commit without explicit approval. ⚠️ [docs/TechStack.md](../../docs/TechStack.md) has been updated to match. Ticket 10 records the *why* as an ADR. ## Decisions so far <!-- one line per resolved ticket --> ## Not yet specified - Hosting and deploy target for the API and the PWA; CI/CD shape. - Supabase free-tier limits vs expected photo volume; cost ceiling. - SEO specifics: URL scheme for city and visit pages, sitemap generation, server-rendering vs prerender for a Vue SPA. - Rate limiting and bot protection on public read endpoints. - Automated image moderation (nudity/abuse scanning) on upload. - Analytics and what success looks like for v1. - Internationalisation and non-Latin city names. ## Out of scope - Follow/friends and a feed — backlogged to a future version. - Likes and comments on stories — backlogged to a future version. - Social login (Google/Apple) — backlogged. - Native iOS/Android apps. - Full moderation tooling beyond the report queue. |
Below are some examples of the different types: 1-3 Research, 4-8 Grilling, 9 Prototype, 10 Task.
| # 01 — Pick the geocoding provider Type: research Status: open ## Question Location is free text that must resolve to a real place with a stable id and coordinates, and must roll up to a city for browse. Which provider do we use? Compare Google Places, Mapbox Search, and OpenStreetMap/Nominatim on: - Autocomplete quality for free-text place entry on mobile. - Whether the returned place id is stable and safe to persist long-term. - Whether the response carries a reliable city-level field we can group by, worldwide. - Licensing: may we store the id, name, and coords in our own database and show them publicly? - Pricing at low volume, and the free-tier ceiling. - .NET client library availability, since only the API calls the provider. |
| # 05 — City rollup and browse model Type: grilling Blocked by: 01 Status: open ## Question Browse is by city, drilling down to the exact place. What does a city page actually contain? Decide: - Is `City` a stored entity with its own id, or derived from each Location's geocoded city field at query time? - What the city page lists: visits, stories, or places — and how it's ordered (recent, most-storied, something else). - Disambiguation for duplicate city names across countries. - What happens to a Visit whose location resolves to no city (remote places, at sea). - Whether private visits contribute to city-level counts. Blocked because the answer depends on what city data the provider actually returns. |
| # 09 — Browse and create flows on a phone Type: prototype Blocked by: 04, 05 Status: open ## Question Two flows carry the product: logging a visit with a story, and discovering someone else's. Do they feel right on a phone? Prototype throwaway screens for: - Create a Visit: location entry, date, privacy toggle, then adding a story. - A city page and the drill-down to a specific place. - Search by username or city, and what the empty state looks like. Looking for: whether Visit-then-Story feels like one step or two, and whether privacy-at-the-Visit-level is obvious to a user who is thinking about the story they're writing. Blocked because the screens can't be drawn before the story shapes and the city page contents are settled. |
| # 10 — ADR: record the stack rationale Type: task Blocked by: 02, 03 Status: open ## Question `docs/TechStack.md` now states .NET 10 + EF Core + Supabase + Vue PWA, replacing the earlier React line. The doc says *what*; an ADR should say *why*, so a future reader doesn't quietly reverse it. Write an ADR under `docs/adr/` covering: - Why Supabase over self-hosted Postgres, and how EF Core sits in front of it. - Why Vue replaced React. - Why all traffic goes through the .NET API rather than the browser talking to Supabase, and why Supabase Auth is unused. - What would make us revisit any of these. Blocked because the Supabase and auth decisions are the substance of the ADR. |
Plan Refinement
Now that it has 3 research tickets, it's anxious to get started on these. If we give the go-ahead, it will laucnch 3 research sub-agents and record their progress on issues 1-3. The research took 23 minutes and cost $3.90.
While it's working on these research issues, I can continue with grilling sessions for issues not dependent on the research. And because progress is being recorded in our map/issue files, we don't have to do this all in one session. I can come back later and use the command
| /wayfinder status |
to get a summary of the current state of the map file, like this:
| Map: Social travel log — map.md Destination: a written spec for v1 of a phone-first social travel log, to hand off and iterate on. Resolved (3/10) Pick the geocoding provider → Google Places API (New); persist the place id only Photo upload and delivery on Supabase Storage → two buckets, no RLS, signed direct upload Auth implementation on .NET over Supabase Postgres → ASP.NET Core Identity + cookie, GoTrue rejected Frontier (open, unblocked, unclaimed) Shape the three story types — grilling City rollup and browse model — grilling Usernames and the public profile page — grilling Reporting, admin queue, and account deletion — grilling PWA scope — grilling ADR: record the stack rationale — task Blocked (1) Browse and create flows on a phone — prototype, waits on story types + city rollup Fog: 11 patches, notably transactional email provider and the Supabase connection-string mode (both newly forced by the research). Next by number: Shape the three story types. |
Now I have to work through all of the unresolved decisions before moving on to creating the spec.
Phase 2: Create the Spec
Run the /to-spec skill to create the specification document. This will contain links to the decision tickets from the planning phase.
Phase 3: Create Tickets
Run the /to-tickets skill to break the spec into tickets to be implmented. These will include blocking information to control what is ready to be implmented and what can be done in parallel.
Phase 4: Implementation
You can use either the /implement skill to directly start creating code, or the /tdd skill if you prefer the Test Driven Development approach.
Phase 5: Code Review
Run the /code-review skill to check the work.
BONUS 1: Re-think previous decisions
At any point during the coding or after you can run the /improve-codebase-arch command to scan the code for opportunities for improvment. This will output a recomendations document which can be used to drive future iterations.
BONUS 2: Other Skills
Check out all of the other skills in this Matt Pocock collection. Some of these are stand-alone and some are launched from other skills. Reading how the skills are put together is very informative.
Addendum
The new HydraFusion "model" in VsCode should make this even more powerful by launching sub-agents with models appropriate for the type of work they're doing:
References:
