Draft: this page sits outside the guide's focus.
Skill packLesson
Planning with the pack
An agent that starts building before it knows what you want builds the wrong thing quickly. The Skill pack's planning Skills slow that first step down: an interview settles the decisions, and the result is written to the issue tracker as a spec and tickets that a later session can pick up cold.
Know these Skills already? Skip to In Terrarium.
Outside the box · General
The concept
The pack splits planning into four , each with one job.
grilling is an interview. The agent maps the plan as a design tree, where each decision branches into the decisions that depend on it. It asks in rounds: each round holds every question whose prerequisites are already settled, numbered, each with the agent's recommended answer, worded so that "yes" accepts it. Facts are the agent's job, so it looks them up instead of asking; decisions are the person's. The interview ends when no open question is left, and the agent acts only once the person agrees they share an understanding.
wayfinder is for work too big for one session, where the way to the goal can't be seen yet. It charts a map: one issue that names the destination and indexes the decisions made so far. Each open question is a child issue, a decision ticket typed research, prototype, grilling or task. A ticket worked with a person is HITL (human in the loop); one the agent can drive alone is AFK. Tickets block each other through the tracker's own dependency links. A session claims a ticket by assigning it, and resolves at most one ticket, research tickets excepted. The frontier is every open ticket that is unblocked and unclaimed. Questions that can't be phrased sharply yet wait in the map's "Not yet specified" section until resolved tickets clear the way. The map produces decisions, not deliverables: when the way is clear, it hands off to to-spec.
to-spec writes the conversation up as a spec, without asking anything new apart from checking the test seams. Its template covers the problem, the solution, a long list of user stories, implementation and testing decisions, and what is out of scope, and it leaves out file paths and code because they go stale.
to-tickets breaks a plan or spec into tracer-bullet tickets: thin slices that each cut through every layer and can be checked on their own, each listing the tickets that block it. It shows the breakdown to the person, revises it until they approve, then publishes blockers first. A wide refactor that no single slice can land green goes through expand, migrate and contract steps instead.
The pack's own route through them: grill, then to-spec, then to-tickets, then build ticket by ticket. grilling can be reached for by the agent itself; the other three set disable-model-invocation: true, so they run only when a person types them (Claude Code docs: Skills). Both to-spec and to-tickets label what they publish ready-for-agent.
Full referencemattpocock/skills on GitHub
In Terrarium
All four are pack Skills in .agents/skills/, kept exactly as installed (Skill packs). They don't hard-code a tracker. Each expects to be told where issues live, and Terrarium tells them in docs/agents/issue-tracker.md, a doc the pack's setup Skill seeded and Terrarium now owns.
Its Wayfinding operations section maps the map onto GitHub. The map is an issue labelled wayfinder:map. Each ticket is a sub-issue of it, labelled with its type. Blocking uses GitHub's native issue dependencies, so the frontier shows in GitHub's own issue view. A claim is an assignment, and a resolution is a comment, a close and one line added to the map's index. The same doc says how a spec looks here: an ordinary issue, with each user story a sub-issue that also starts with a Part of line naming the spec.
The pack's text keeps triage labels such as ready-for-agent off wayfinder tickets, because they hold decisions, not work to build. Terrarium's auto-triage sweep adds them anyway, beside the wayfinder labels, and follows wayfinder's rules for which tickets an agent may take:
74- **Skip** a **claimed** (assigned) ticket and a **blocked** ticket (an open
75 native dependency *or* a `Blocked by:` body line; `docs/agents/issue-tracker.md`'s
76 Wayfinding operations): wayfinder's frontier is open + unblocked + unclaimed,
77 so a blocked ticket is not takeable and must not be stamped `ready-for-agent`.
78- **Preserve** every `wayfinder:*` label — this is an overlay, never a replacement.
79- Honour the ticket type: `wayfinder:grilling` and `wayfinder:prototype` are
80 **HITL** (human-in-the-loop) → `ready-for-human`; `wayfinder:research` is
81 **AFK** and, when unblocked and unclaimed, is eligible for `ready-for-agent`.
grilling also runs inside other Skills. The pack's triage grills a vague request into shape, together with domain-modeling, which writes the settled terms into GLOSSARY.md and ADRs. Terrarium's own .agents/skills/clear-backlog/SKILL.md gathers every open question from a backlog run into one grilling with the owner, and leaves wayfinder issues alone, since the wayfinder Skill drives those with the owner. How much each planning Skill matters here is graded in the .
Why it's built this way
Pack Skills left as installed: ADR-0015 (docs/adr/0015-audit-skills-and-conditional-importance.md).
Docs copied from a pack template: ADR-0005 (docs/adr/0005-skill-model.md).
ready-for-agent as approval: ADR-0003 (docs/adr/0003-agent-operating-model-and-governance.md).
The triage sweep: ADR-0022 (docs/adr/0022-autonomous-triage-sweep.md).
What to watch for
- The pack's default label is an approval here.
to-specandto-ticketsapplyready-for-agent, and in Terrarium that label is a user's approval to build, so leave it off a spec on hold, and off a request until a Trusted user approves it (ADR-0020, docs/adr/0020-requester-trust-tiers.md). - A dependency link needs the issue's database id. GitHub's endpoint takes the blocker's numeric id, not its
#number. Write cross-references only once the issues exist: a placeholder#nlinks to whatever unrelated issue has that number. - Keep both label sets. A wayfinder ticket can carry a triage label and a
wayfinder:label at once. Never swap one for the other:wayfinderreads a ticket's type from its label alone, never from its body.
Try it in your project
Before your next change that would take more than an afternoon, ask your agent to grill you: one round of numbered questions, each with its recommended answer. Write the spec only after the last round leaves nothing open.
Where next
- PageSkill packs
- PageEngineering skills
- PageIssue triage labels
- PageOut-of-scope records
- JournalSkill Inventory
Walkthroughs through this Lesson
- WalkthroughPlanning a big change
Last updated · Latest source on GitHub ↗