v1.1: /wayfinder, /to-spec, /to-tickets, /grilling improvements, and much more

After an extended development period, version 1.1 of the skills repo is finally ready to merge. This release contains an astonishing amount of changes, including an entirely new approach to grilling, a bunch of updates to existing skills, and a rename of two main flow skills.

Rather than try to summarize everything here, we're just going to dive into the changes.

How to Migrate

Since this release includes skill renames and merges, you'll need to update your installation. The skills installer won't pick these up automatically.

Run this command to grab all the new skills:

npx skills add mattpocock/skills

This gives you the freedom to pick and choose which skills you want. Once done, go through your skills folder and make sure no old skills are lingering.

The new public documentation pages are at:

• docs/engineering/to-spec.md
• docs/engineering/to-tickets.md

Major Renames: /to-spec and /to-tickets

The two changes that are probably going to be most annoying—but for very good reasons—are skill renames. These have been bothering me for a long time because the naming didn't accurately reflect what we were actually building.

From /to-prd to /to-spec

The /to-prd skill has been renamed to /to-spec. The key insight here is that what we were creating wasn't actually a PRD (Product Requirements Document). A PRD describes things about the actual product itself, whereas we were allowing non-product stuff to leak in. What we were really building was a specification—a much broader term that can be technical, non-technical, or a blend of both.

"Spec" is now the single through-line term across the entire skills suite. You may still know this document as a PRD, but "spec" is the unified language we're using going forward.

From /to-plan and /to-issues to /to-tickets

Two skills have been merged into one: /to-plan and /to-issues are now unified as /to-tickets. The old name felt biased towards GitHub and Linear, which use "issues" as their terminology. But really, the concept we're working with is more general: you have a spec, and underneath that spec you have tickets—the journey you take to actually enact the spec and create it.

/to-tickets breaks a plan, spec, or conversation into a set of tickets—tracer-bullet vertical slices, each declaring its blocking edges. This one artifact works two ways depending on your tracker setup:

• Local file (tickets.md) – Edges are written as text and you work through them top-to-bottom by hand
• Real tracker – Edges become native blocking links, so any ticket whose blockers are done is on the frontier and multiple agents can work in parallel

This naming clarity brings me joy after years of wishing the names were right.

Grilling Skill Improvements

The next set of changes fixes bugs that people were experiencing with /grill-me and /grill-with-docs. Both rely on a central reference grilling skill that shows the LLM how to grill a person effectively.

Three Key Fixes

1. Clearer guidance on asking questions

The original guidance said "asking multiple questions at once is bewildering." Even with this instruction, the model would occasionally ignore it and ask multiple questions anyway. So I've been more explicit about why we don't want multiple questions at once.

2. Confirmation gate before implementation

Added a confirmation step at the end: "Do not enact the plan until I confirm we've reached a shared understanding." Many people reported that grilling sessions would just end and then the model would jump straight into implementation. This gate prevents that.

3. Preventing self-grilling

In some odd situations, the model would grill itself—exploring the code base and grilling without human input. This was especially happening with Fable. To fix this, I added leading words to distinguish between two types of information:

Just a couple of sentences added and a few things rearranged has made the skill much more consistent. These tweaks have significantly reduced the weird issues people were reporting.

Complete Development Lifecycle Flow

I've added a couple of new skills that transform the grilling process from primarily a planning exercise into a proper software development lifecycle. Many people ask me: "What's the main flow I'm supposed to use with the skills?" Here it is:

The Flow: From Grilling to Deployment

1. Start with grilling

Instead of using plan mode directly, you get an agent to grill you about your goals. This uses two supporting docs:

• A glossary to help the agent understand your domain better
• Architectural Decision Records (ADRs) to capture the non-obvious stuff

2. Generate a spec

The output from grilling goes into a spec, which defines your destination—where you're going with this feature or project.

3. Break into tickets

You then turn that spec into individual tickets using /to-tickets. This spreads the development work across multiple agent sessions, each focused on one ticket.

4. Implement each ticket

Implement each ticket using the /implement skill, which is refreshingly simple:

Implement the work described by the user in the spec or tickets.
Use TDD where possible at pre-agreed seams.
Run type checking regularly.
Single test files regularly.
Full test sweep once at the end.

The /implement skill mostly relies on the agent's priors and what your agents.md file teaches it. I almost didn't create a skill for this because it's so simple, but people kept asking "what's the flow?" So now you have a clear endpoint: once you have tickets, just implement each one in a separate coding session.

5. Code review

After implementation, the /implement skill calls /code-review to review the work before committing.

Code Review with Refactoring Smells

The code review skill reviews code on two axes, using a sub-agent for each:

Both run as parallel sub-agents, walking through each part of the code.

Here's what's cool and new about this skill: I've been reading Martin Fowler's Refactoring again, and I realized the agent already knows about code smells deeply embedded in its training. All you need to do is invoke the idea. Here are some examples:

• Mysterious name
• Duplicated code
• Feature envy
• Data clumps
• Primitive obsession
• Repeated switches
• Divergent change
• Speculative generality
• Message chains
• Middleman

When you describe these, the agent picks up on the terminology and says: "Yes, I found message chains. I need to remove them. I found a middleman situation. I need to fix that."

I tested this for a couple of weeks and it was outrageously useful at improving code quality. The best part? It's really cheap to add—just about 10 lines of guidance.

Introducing Wayfinder for Large Plans

Now for the skill I'm really excited about: a whole new approach to kicking off and shaping specs. It's called /wayfinder, and it's designed to replace /grill-with-docs in many situations.

When to Use Wayfinder

/wayfinder is for situations where you have so much to plan that it's too big for one agent session. You're either going to blow out of the agent's smart zone or even hit its context window limit. You need to split it into multiple parts to figure out where you're going.

Here's the concept:

A loose idea has arrived, too big for one agent session and wrapped in fog. The way from here to the destination isn't visible yet. This skill charts the way as a shared map on the repo's issue tracker, then works its tickets one at a time until the route is clear.

How Wayfinder Works

Wayfinder creates a map saved as GitHub issues, with decisions scoped to be the size of an agent session. Each decision is linked with blocking relationships, so dependent decisions can't be made until prerequisites are resolved.

Here's an example from the Sandcastle repo, investigating whether to pull in the AI SDK as a dependency:

Ticket Types:

• Research – An AFK task for the agent to research and report findings
• Grilling – A grilling session to make decisions
• Prototype – A quick prototype to raise the fidelity of discussion
• Task – Config, provisioning, or other work that doesn't need grilling

Why Prototyping Matters

I've been advocating for more prototyping before you get to a spec. The idea is to raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to—an outline, rough take, stub, or UI logic code.

Use prototyping when:

• How should it look? is a key question
• How should it behave? is a key question

This is essential for almost anything that touches front-end code. I'd definitely recommend using /wayfinder for any front-end work.

After Wayfinder Completes

Once all the tickets are closed, all of that information gets saved onto the map with the original tickets as primary sources. You can then take this map and turn it into a spec the regular way.

The beauty of Wayfinder is that instead of managing session anxiety with /grill-with-docs—worrying about hand-offs and the smart zone—everything is managed for you. You just close a session and open the next Wayfinder ticket. It's all saved in GitHub, so it's collaborative and shareable across your team.

Supporting Skills: Research and Prototype

To support the Wayfinder workflow, two new skills have been added.

The /research Skill

The /research skill is small but handy:

• Spins up a background agent to do the research so you keep working while it reads
• Investigates the question against primary sources
• Writes findings to a simple markdown file
• Saves it where the repo already keeps such notes, matching existing conventions

Use it anytime you need to do a research session without breaking your flow.

The /prototype Skill

The /prototype skill is now model-invoked so that Wayfinder can invoke it itself. It gives you a choice between two types:

They react quite differently and help you explore design space before committing to a spec.

TDD Skill Updates

The final change addresses something people have been asking for: the ability to pass an AFK agent the /tdd skill and have it just work.

Previous Approach

The old /tdd skill would recommend a set of steps and ask you to confirm each one. This was awkward because it didn't fit with how most people actually use TDD—they want the agent to work autonomously.

New Approach

The /tdd skill is now reference material only. It doesn't specify particular steps, just the essential order:

1. Red - Write failing tests
2. Green - Make tests pass
3. Refactor - Improve code (moved out of the loop)

The key change: refactoring is no longer part of the TDD loop. It's now handled in the code review phase, which keeps the implementation focused and cleaner. This way you don't overload the implementation session with refactoring concerns.

What to Watch For

• /to-spec replaces /to-prd – Update any processes or documentation
• /to-tickets replaces /to-plan and /to-issues – These are now unified
• New workflow – Consider adopting the new flow: Grilling → Spec → Tickets → Implement → Code Review
• Wayfinder everywhere – Try using /wayfinder instead of /grill-with-docs for larger planning tasks