@complexthings/superpowers-agent 9.2.1 → 10.0.0

package/.agents/skills/qa/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: qa
+description: Interactive QA session where user reports bugs or issues conversationally, and the agent files GitHub issues. Explores the codebase in the background for context and domain language. Use when user wants to report bugs, do QA, file issues conversationally, or mentions "QA session".
+---
+
+# QA Session
+
+Run an interactive QA session. The user describes problems they're encountering. You clarify, explore the codebase for context, and file GitHub issues that are durable, user-focused, and use the project's domain language.
+
+## For each issue the user raises
+
+### 1. Listen and lightly clarify
+
+Let the user describe the problem in their own words. Ask **at most 2-3 short clarifying questions** focused on:
+
+- What they expected vs what actually happened
+- Steps to reproduce (if not obvious)
+- Whether it's consistent or intermittent
+
+Do NOT over-interview. If the description is clear enough to file, move on.
+
+### 2. Explore the codebase in the background
+
+While talking to the user, kick off an Agent (subagent_type=Explore) in the background to understand the relevant area. The goal is NOT to find a fix — it's to:
+
+- Learn the domain language used in that area (check UBIQUITOUS_LANGUAGE.md)
+- Understand what the feature is supposed to do
+- Identify the user-facing behavior boundary
+
+This context helps you write a better issue — but the issue itself should NOT reference specific files, line numbers, or internal implementation details.
+
+### 3. Assess scope: single issue or breakdown?
+
+Before filing, decide whether this is a **single issue** or needs to be **broken down** into multiple issues.
+
+Break down when:
+
+- The fix spans multiple independent areas (e.g. "the form validation is wrong AND the success message is missing AND the redirect is broken")
+- There are clearly separable concerns that different people could work on in parallel
+- The user describes something that has multiple distinct failure modes or symptoms
+
+Keep as a single issue when:
+
+- It's one behavior that's wrong in one place
+- The symptoms are all caused by the same root behavior
+
+### 4. File the GitHub issue(s)
+
+Create issues with `gh issue create`. Do NOT ask the user to review first — just file and share URLs.
+
+Issues must be **durable** — they should still make sense after major refactors. Write from the user's perspective.
+
+#### For a single issue
+
+Use this template:
+
+```
+## What happened
+
+[Describe the actual behavior the user experienced, in plain language]
+
+## What I expected
+
+[Describe the expected behavior]
+
+## Steps to reproduce
+
+1. [Concrete, numbered steps a developer can follow]
+2. [Use domain terms from the codebase, not internal module names]
+3. [Include relevant inputs, flags, or configuration]
+
+## Additional context
+
+[Any extra observations from the user or from codebase exploration that help frame the issue — e.g. "this only happens when using the Docker layer, not the filesystem layer" — use domain language but don't cite files]
+```
+
+#### For a breakdown (multiple issues)
+
+Create issues in dependency order (blockers first) so you can reference real issue numbers.
+
+Use this template for each sub-issue:
+
+```
+## Parent issue
+
+#<parent-issue-number> (if you created a tracking issue) or "Reported during QA session"
+
+## What's wrong
+
+[Describe this specific behavior problem — just this slice, not the whole report]
+
+## What I expected
+
+[Expected behavior for this specific slice]
+
+## Steps to reproduce
+
+1. [Steps specific to THIS issue]
+
+## Blocked by
+
+- #<issue-number> (if this issue can't be fixed until another is resolved)
+
+Or "None — can start immediately" if no blockers.
+
+## Additional context
+
+[Any extra observations relevant to this slice]
+```
+
+When creating a breakdown:
+
+- **Prefer many thin issues over few thick ones** — each should be independently fixable and verifiable
+- **Mark blocking relationships honestly** — if issue B genuinely can't be tested until issue A is fixed, say so. If they're independent, mark both as "None — can start immediately"
+- **Create issues in dependency order** so you can reference real issue numbers in "Blocked by"
+- **Maximize parallelism** — the goal is that multiple people (or agents) can grab different issues simultaneously
+
+#### Rules for all issue bodies
+
+- **No file paths or line numbers** — these go stale
+- **Use the project's domain language** (check UBIQUITOUS_LANGUAGE.md if it exists)
+- **Describe behaviors, not code** — "the sync service fails to apply the patch" not "applyPatch() throws on line 42"
+- **Reproduction steps are mandatory** — if you can't determine them, ask the user
+- **Keep it concise** — a developer should be able to read the issue in 30 seconds
+
+After filing, print all issue URLs (with blocking relationships summarized) and ask: "Next issue, or are we done?"
+
+### 5. Continue the session
+
+Keep going until the user says they're done. Each issue is independent — don't batch them.

package/.agents/skills/request-refactor-plan/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: request-refactor-plan
+description: Create a detailed refactor plan with tiny commits via user interview, then file it as a GitHub issue. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps.
+---
+
+This skill will be invoked when the user wants to create a refactor request. You should go through the steps below. You may skip steps if you don't consider them necessary.
+
+1. Ask the user for a long, detailed description of the problem they want to solve and any potential ideas for solutions.
+
+2. Explore the repo to verify their assertions and understand the current state of the codebase.
+
+3. Ask whether they have considered other options, and present other options to them.
+
+4. Interview the user about the implementation. Be extremely detailed and thorough.
+
+5. Hammer out the exact scope of the implementation. Work out what you plan to change and what you plan not to change.
+
+6. Look in the codebase to check for test coverage of this area of the codebase. If there is insufficient test coverage, ask the user what their plans for testing are.
+
+7. Break the implementation into a plan of tiny commits. Remember Martin Fowler's advice to "make each refactoring step as small as possible, so that you can always see the program working."
+
+8. Create a GitHub issue with the refactor plan. Use the following template for the issue description:
+
+<refactor-plan-template>
+
+## Problem Statement
+
+The problem that the developer is facing, from the developer's perspective.
+
+## Solution
+
+The solution to the problem, from the developer's perspective.
+
+## Commits
+
+A LONG, detailed implementation plan. Write the plan in plain English, breaking down the implementation into the tiniest commits possible. Each commit should leave the codebase in a working state.
+
+## Decision Document
+
+A list of implementation decisions that were made. This can include:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+## Testing Decisions
+
+A list of testing decisions that were made. Include:
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Out of Scope
+
+A description of the things that are out of scope for this refactor.
+
+## Further Notes (optional)
+
+Any further notes about the refactor.
+
+</refactor-plan-template>

package/.agents/skills/research/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: research
+description: Investigate a question against high-trust primary sources and capture the findings as a Markdown file in the repo. Use when the user wants a topic researched, docs or API facts gathered, or reading legwork delegated to a background agent.
+---
+
+Spin up a **background agent** to do the research, so you keep working while it reads.
+
+Its job:
+
+1. Investigate the question against **primary sources** — official docs, source code, specs, first-party APIs — not a secondary write-up of them. Follow every claim back to the source that owns it.
+2. Write the findings to a single Markdown file, citing each claim's source.
+3. Save it where the repo already keeps such notes; match the existing convention, and if there is none, put it somewhere sensible and say where.

package/.agents/skills/resolving-merge-conflicts/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: resolving-merge-conflicts
+description: "Use when you need to resolve an in-progress git merge/rebase conflict."
+---
+
+1. **See the current state** of the merge/rebase. Check git history, and the conflicting files.
+
+2. **Find the primary sources** for each conflict. Understand deeply why each change was made, and what the original intent was. Read the commit messages, check the PRs, check original issues/tickets.
+
+3. **Resolve each hunk.** Preserve both intents where possible. Where incompatible, pick the one matching the merge's stated goal and note the trade-off. Do **not** invent new behaviour. Always resolve; never `--abort`.
+
+4. Discover the project's **automated checks** and run them — typically typecheck, then tests, then format. Fix anything the merge broke.
+
+5. **Finish the merge/rebase.** Stage everything and commit. If rebasing, continue the rebase process until all commits are rebased.

package/.agents/skills/scaffold-exercises/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: scaffold-exercises
+description: Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.
+---
+
+# Scaffold Exercises
+
+Create exercise directory structures that pass `pnpm ai-hero-cli internal lint`, then commit with `git commit`.
+
+## Directory naming
+
+- **Sections**: `XX-section-name/` inside `exercises/` (e.g., `01-retrieval-skill-building`)
+- **Exercises**: `XX.YY-exercise-name/` inside a section (e.g., `01.03-retrieval-with-bm25`)
+- Section number = `XX`, exercise number = `XX.YY`
+- Names are dash-case (lowercase, hyphens)
+
+## Exercise variants
+
+Each exercise needs at least one of these subfolders:
+
+- `problem/` - student workspace with TODOs
+- `solution/` - reference implementation
+- `explainer/` - conceptual material, no TODOs
+
+When stubbing, default to `explainer/` unless the plan specifies otherwise.
+
+## Required files
+
+Each subfolder (`problem/`, `solution/`, `explainer/`) needs a `readme.md` that:
+
+- Is **not empty** (must have real content, even a single title line works)
+- Has no broken links
+
+When stubbing, create a minimal readme with a title and a description:
+
+```md
+# Exercise Title
+
+Description here
+```
+
+If the subfolder has code, it also needs a `main.ts` (>1 line). But for stubs, a readme-only exercise is fine.
+
+## Workflow
+
+1. **Parse the plan** - extract section names, exercise names, and variant types
+2. **Create directories** - `mkdir -p` for each path
+3. **Create stub readmes** - one `readme.md` per variant folder with a title
+4. **Run lint** - `pnpm ai-hero-cli internal lint` to validate
+5. **Fix any errors** - iterate until lint passes
+
+## Lint rules summary
+
+The linter (`pnpm ai-hero-cli internal lint`) checks:
+
+- Each exercise has subfolders (`problem/`, `solution/`, `explainer/`)
+- At least one of `problem/`, `explainer/`, or `explainer.1/` exists
+- `readme.md` exists and is non-empty in the primary subfolder
+- No `.gitkeep` files
+- No `speaker-notes.md` files
+- No broken links in readmes
+- No `pnpm run exercise` commands in readmes
+- `main.ts` required per subfolder unless it's readme-only
+
+## Moving/renaming exercises
+
+When renumbering or moving exercises:
+
+1. Use `git mv` (not `mv`) to rename directories - preserves git history
+2. Update the numeric prefix to maintain order
+3. Re-run lint after moves
+
+Example:
+
+```bash
+git mv exercises/01-retrieval/01.03-embeddings exercises/01-retrieval/01.04-embeddings
+```
+
+## Example: stubbing from a plan
+
+Given a plan like:
+
+```
+Section 05: Memory Skill Building
+- 05.01 Introduction to Memory
+- 05.02 Short-term Memory (explainer + problem + solution)
+- 05.03 Long-term Memory
+```
+
+Create:
+
+```bash
+mkdir -p exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer
+mkdir -p exercises/05-memory-skill-building/05.02-short-term-memory/{explainer,problem,solution}
+mkdir -p exercises/05-memory-skill-building/05.03-long-term-memory/explainer
+```
+
+Then create readme stubs:
+
+```
+exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer/readme.md -> "# Introduction to Memory"
+exercises/05-memory-skill-building/05.02-short-term-memory/explainer/readme.md -> "# Short-term Memory"
+exercises/05-memory-skill-building/05.02-short-term-memory/problem/readme.md -> "# Short-term Memory"
+exercises/05-memory-skill-building/05.02-short-term-memory/solution/readme.md -> "# Short-term Memory"
+exercises/05-memory-skill-building/05.03-long-term-memory/explainer/readme.md -> "# Long-term Memory"
+```

package/.agents/skills/setup-matt-pocock-skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup-matt-pocock-skills
-description: Sets up an `## Agent skills` block in AGENTS.md/CLAUDE.md and `docs/agents/` so the engineering skills know this repo's issue tracker (GitHub or local markdown), triage label vocabulary, and domain doc layout. Run before first use of `to-issues`, `to-prd`, `triage`, `diagnose`, `tdd`, `improve-codebase-architecture`, or `zoom-out` — or if those skills appear to be missing context about the issue tracker, triage labels, or domain docs.
+description: Configure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.
 disable-model-invocation: true
 ---
 
@@ -14,8 +14,6 @@ Scaffold the per-repo configuration that the engineering skills assume:
 
 This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.
 
-> **USE AVAILABLE TOOLS AND SKILLS** - For asking the user questions, if you have access to any question-asking tools use them (e.g. `askQuestions`, or `askUserQuestion`) instead of asking in the main conversation. Instead of using the usual CLI tools, the skill `leveraging-cli-tools` is recommended as it includes recommendations for better tools to use for searching and reading files (e.g. `rg`, `fd`, `bat`, `ast-grep`) which can make the exploration more efficient and effective.
-
 ## Process
 
 ### 1. Explore
@@ -29,17 +27,15 @@ Look at the current repo to understand its starting state. Read whatever exists;
 - `docs/agents/` — does this skill's prior output already exist?
 - `.scratch/` — sign that a local-markdown issue tracker convention is already in use
 
-> **Parallelize with subagents** - If your environment/harness supports subagents (e.g. a Task/Agent tool), it is recommended to dispatch **up to 3 in parallel**, each on a fast, inexpensive model (e.g. Claude Sonnet or Claude Haiku) to explore these different areas simultaneously and converge faster on the right answers and information. Give each a distinct, non-overlapping focus - for example, one on git remotes and issue tracker conventions, one on domain docs, and one on vocabularies and triage labels, etc. Ask each to return **concise findings summary** (key facts and suggested conclusions) to the orchestrator, not raw file dumps - this keeps the main agent's context clean while widening the insight it draws on. If subagents aren't available, do the exploration directly. If you find that you need more information than the checks provide you can use the information they provided to guide further targed exploration.
-
 ### 2. Present findings and ask
 
-Summarise what's present and what's missing. Then walk the user through the three decisions **one at a time** — present a section, get the user's answer, then move to the next. Don't dump all three at once. **USE AVAILABLE QUESTION TOOLS** (e.g. `askQuestion` `askUserQuestion`) when asking the questions one at a time, waiting for feedback on each quesiton before continuing.
+Summarise what's present and what's missing. Then walk the user through the three decisions **one at a time** — present a section, get the user's answer, then move to the next. Don't dump all three at once.
 
 Assume the user does not know what these terms mean. Each section starts with a short explainer (what it is, why these skills need it, what changes if they pick differently). Then show the choices and the default.
 
 **Section A — Issue tracker.**
 
-> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-issues`, `triage`, `to-prd`, and `qa` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.
+> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-tickets`, `triage`, `to-spec`, and `qa` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.
 
 Default posture: these skills were designed for GitHub. If a `git remote` points at GitHub, propose that. If a `git remote` points at GitLab (`gitlab.com` or a self-hosted host), propose GitLab. Otherwise (or if the user prefers), offer:
 
@@ -48,6 +44,12 @@ Default posture: these skills were designed for GitHub. If a `git remote` points
 - **Local markdown** — issues live as files under `.scratch/<feature>/` in this repo (good for solo projects or repos without a remote)
 - **Other** (Jira, Linear, etc.) — ask the user to describe the workflow in one paragraph; the skill will record it as freeform prose
 
+If — and only if — the user picked **GitHub** or **GitLab**, ask one follow-up:
+
+> Explainer: Open-source repos often receive feature requests as pull requests, not just issues — a PR is an issue with attached code. If you turn this on, `/triage` pulls *external* PRs into the same queue and runs them through the same labels and states as issues (collaborators' in-flight PRs are left alone). Leave it off if PRs aren't a request surface for you.
+
+- **PRs as a request surface** — yes / no (default: no). Record the answer in `docs/agents/issue-tracker.md`. For local-markdown and other trackers, skip this question — there are no PRs.
+
 **Section B — Triage label vocabulary.**
 
 > Explainer: When the `triage` skill processes an incoming issue, it moves it through a state machine — needs evaluation, waiting on reporter, ready for an AFK agent to pick up, ready for a human, or won't fix. To do that, it needs to apply labels (or the equivalent in your issue tracker) that match strings *you've actually configured*. If your repo already uses different label names (e.g. `bug:triage` instead of `needs-triage`), map them here so the skill applies the right ones instead of creating duplicates.
@@ -64,7 +66,7 @@ Default: each role's string equals its name. Ask the user if they want to overri
 
 **Section C — Domain docs.**
 
-> Explainer: Some skills (`improve-codebase-architecture`, `diagnose`, `tdd`) read a `CONTEXT.md` file to learn the project's domain language, and `docs/adr/` for past architectural decisions. They need to know whether the repo has one global context or multiple (e.g. a monorepo with separate frontend/backend contexts) so they look in the right place.
+> Explainer: Some skills (`improve-codebase-architecture`, `diagnosing-bugs`, `tdd`) read a `CONTEXT.md` file to learn the project's domain language, and `docs/adr/` for past architectural decisions. They need to know whether the repo has one global context or multiple (e.g. a monorepo with separate frontend/backend contexts) so they look in the right place.
 
 Confirm the layout:
 
@@ -99,7 +101,7 @@ The block:
 
 ### Issue tracker
 
-[one-line summary of where issues are tracked]. See `docs/agents/issue-tracker.md`.
+[one-line summary of where issues are tracked, plus whether external PRs are a triage surface]. See `docs/agents/issue-tracker.md`.
 
 ### Triage labels
 

package/.agents/skills/setup-matt-pocock-skills/domain.md

@@ -8,7 +8,7 @@ How the engineering skills should consume this repo's domain documentation when
 - **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
 - **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
 
-If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The producer skill (`/grill-with-docs`) creates them lazily when terms or decisions actually get resolved.
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
 
 ## File structure
 
@@ -42,7 +42,7 @@ Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
 
 When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
 
-If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/grill-with-docs`).
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
 
 ## Flag ADR conflicts
 

package/.agents/skills/setup-matt-pocock-skills/issue-tracker-github.md

@@ -13,6 +13,18 @@ Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all op
 
 Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
 
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
+
+- **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff.
+- **List external PRs for triage**: `gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments` then keep only `authorAssociation` of `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`, or `NONE` (drop `OWNER`/`MEMBER`/`COLLABORATOR`).
+- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
+
+GitHub shares one number space across issues and PRs, so a bare `#42` may be either — resolve with `gh pr view 42` and fall back to `gh issue view 42`.
+
 ## When a skill says "publish to the issue tracker"
 
 Create a GitHub issue.
@@ -20,3 +32,14 @@ Create a GitHub issue.
 ## When a skill says "fetch the relevant ticket"
 
 Run `gh issue view <number> --comments`.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
+- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitHub's **native issue dependencies** — the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only — the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
+- **Claim**: `gh issue edit <n> --add-assignee @me` — the session's first write.
+- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

package/.agents/skills/setup-matt-pocock-skills/issue-tracker-gitlab.md

@@ -14,6 +14,18 @@ Issues and PRDs for this repo live as GitLab issues. Use the [`glab`](https://gi
 
 Infer the repo from `git remote -v` — `glab` does this automatically when run inside a clone.
 
+## Merge requests as a triage surface
+
+**MRs as a request surface: no.** _(Set to `yes` if this repo treats external merge requests as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, MRs run through the same labels and states as issues, using the `glab mr` equivalents:
+
+- **Read an MR**: `glab mr view <number> --comments` and `glab mr diff <number>` for the diff.
+- **List external MRs for triage**: `glab mr list -F json`, then keep only MRs whose author is not a project member/owner (a contributor's MR, not a maintainer's in-flight work).
+- **Comment / label / close**: `glab mr note`, `glab mr update --label`/`--unlabel`, `glab mr close`.
+
+Unlike GitHub, GitLab numbers issues and MRs separately, so `#42` is unambiguous once you know which surface the maintainer means.
+
 ## When a skill says "publish to the issue tracker"
 
 Create a GitLab issue.
@@ -21,3 +33,14 @@ Create a GitLab issue.
 ## When a skill says "fetch the relevant ticket"
 
 Run `glab issue view <number> --comments`.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `glab issue create --label wayfinder:map`. (On GitLab tiers with native epics, an epic may hold the map instead; a labelled issue works everywhere.)
+- **Child ticket**: an issue carrying `Part of #<map>` at the top of its description and labels `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitLab's **native blocking link** — the canonical, UI-visible representation. Add it with the `/blocked_by #<n>` quick action, posted as a note (`glab issue note <child> --message "/blocked_by #<blocker>"`). Native blocking links are a Premium/Ultimate feature; on the free tier (or where unavailable) fall back to a `Blocked by: #<n>, #<n>` line at the top of the description. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: `glab issue list -F json` scoped to the map's children, drop any with an open blocker — a native `blocked_by` link to an open issue (`glab api projects/:id/issues/:iid/links`), or an open issue in the `Blocked by` line — or an assignee; first in map order wins.
+- **Claim**: `glab issue update <n> --assignee @me` — the session's first write.
+- **Resolve**: `glab issue note <n> --message "<answer>"`, then `glab issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

package/.agents/skills/setup-matt-pocock-skills/issue-tracker-local.md

@@ -17,3 +17,14 @@ Create a new file under `.scratch/<feature-slug>/` (creating the directory if ne
 ## When a skill says "fetch the relevant ticket"
 
 Read the file at the referenced path. The user will normally pass the path or the issue number directly.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a file with one **child** file per ticket.
+
+- **Map**: `.scratch/<effort>/map.md` — the Notes / Decisions-so-far / Fog body.
+- **Child ticket**: `.scratch/<effort>/issues/NN-<slug>.md`, numbered from `01`, with the question in the body. A `Type:` line records the ticket type (`research`/`prototype`/`grilling`/`task`); a `Status:` line records `claimed`/`resolved`.
+- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked when every file it lists is `resolved`.
+- **Frontier**: scan `.scratch/<effort>/issues/` for files that are open, unblocked, and unclaimed; first by number wins.
+- **Claim**: set `Status: claimed` and save before any work.
+- **Resolve**: append the answer under an `## Answer` heading, set `Status: resolved`, then append a context pointer (gist + link) to the map's Decisions-so-far in `map.md`.