docs(bin): give every bin skill a README

The bin skills were the only plugin without per-skill READMEs, so a reader
had to open SKILL.md — an agent-facing contract, not an explainer — to learn
what a skill does and when it fires. Each README states purpose, triggers and
boundaries for a human audience, leaving SKILL.md free to stay terse.

plugins/bin/.apm/skills/caveman/README.md

@@ -0,0 +1,29 @@
+# caveman
+
+Ultra-compressed output mode: drop articles, filler and pleasantries, keep the technical substance exact.
+
+## What it does
+
+Switches the agent into a terse register — no articles, no hedging, no pleasantries, fragments allowed, arrows for causality — while leaving technical terms, code blocks and quoted error strings untouched. The mode is *sticky*: once turned on it stays on for every subsequent response until the user says "stop caveman" or "normal mode", rather than decaying back to normal prose after a few turns.
+
+It carries one built-in escape hatch. Security warnings, confirmations for irreversible actions, multi-step sequences where fragment order could be misread, and any request to clarify are answered in normal prose, then the compressed register resumes.
+
+## Hand-invoked only
+
+`SKILL.md` sets `disable-model-invocation: true`. This is the single most important thing to know about this skill: **the model cannot route to it.** No other skill can hand off to it, and no phrasing in a user's request will cause it to be selected automatically. The only way in is the human typing `/caveman`.
+
+That is deliberate — output style is the user's choice, not an inference the router should make on their behalf. It is also why the description reads as one plain human-facing sentence rather than carrying the trigger phrasing and boundary clause a routable skill needs.
+
+## Usage
+
+```text
+/caveman
+```
+
+Then keep working normally. To leave the mode, say "stop caveman" or "normal mode".
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The whole skill — persistence rule, compression rules, worked examples, and the auto-clarity exception |

plugins/bin/.apm/skills/diagnose/README.md

@@ -0,0 +1,35 @@
+# diagnose
+
+A six-phase discipline for hard bugs and performance regressions: feedback loop → reproduce → hypothesise → instrument → fix with a regression test → clean up.
+
+## What it does
+
+Imposes an order of operations on debugging so the agent cannot skip to guessing. The load-bearing phase is the first one: build a fast, deterministic, agent-runnable pass/fail signal for the bug. Everything downstream — bisection, hypothesis testing, instrumentation — just consumes that signal, so the skill refuses to advance to Phase 2 without one, and says so explicitly rather than hypothesising blind.
+
+The remaining phases each carry a constraint worth knowing about: hypotheses are generated 3–5 at a time and must be falsifiable, so the first plausible idea cannot anchor the whole investigation; every debug log is tagged with a unique prefix (`[DEBUG-a4f2]`) so cleanup is a single grep; the regression test is written before the fix and only at a seam that exercises the real bug pattern; and the run closes by asking what would have prevented the bug, handing off to `improve-codebase-architecture` when the answer is architectural.
+
+Performance regressions take a branch of their own inside Phase 4 — baseline measurement and bisection, not logs.
+
+## Conditional reading
+
+Neither reference file is read on every run; `SKILL.md` names the condition for each.
+
+- `references/feedback-loops.md` is read when Phase 1 has no signal yet, or when the loop you have is slow or intermittent.
+- `references/regression-seams.md` is read when Phase 5 leaves you unsure whether the available seam is deep enough — or whether one exists at all.
+
+## Usage
+
+```text
+/diagnose
+```
+
+Describe the bug or the regression. For filing and triaging a reported bug rather than diagnosing it, use `triage`; for test-first feature work, use `tdd`.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The six phases and their gates — what must be true before each one ends |
+| `references/feedback-loops.md` | Loaded when Phase 1 has no loop or the loop is too weak: ten ways to construct one ordered by cost, how to sharpen an existing loop, handling intermittent bugs, and what to ask the user for when the bug resists reproduction |
+| `references/regression-seams.md` | Loaded when Phase 5 is unsure about the seam: what makes a seam correct, the four shapes of a too-shallow seam, and what to do when no correct seam exists |
+| `assets/hitl-loop.template.sh` | Copy-and-edit bash template for the last-resort human-in-the-loop feedback loop, cited by `references/feedback-loops.md`. Provides `step` and `capture` helpers and prints captured values as `KEY=VALUE` for the agent to parse |

plugins/bin/.apm/skills/grill-me/README.md

@@ -0,0 +1,27 @@
+# grill-me
+
+Interview the user relentlessly about a plan or design until the decision tree is fully resolved.
+
+## What it does
+
+Turns the agent into an interviewer rather than an implementer. It walks the design tree branch by branch, resolving dependencies between decisions one at a time, and offers its own recommended answer alongside each question so the user has something concrete to push against. Two rules give it its shape: **one question at a time**, and **never ask what the codebase can answer** — if a question is settleable by reading the code, the agent goes and reads the code instead of spending the user's attention on it.
+
+## Composition
+
+This is the plain grilling loop, with no documentation side effects. The sibling `grill-with-docs` skill runs the same interview but additionally challenges answers against the project's `CONTEXT.md` glossary and existing ADRs, and writes decisions back into those files as they crystallise. Reach for that one when the project has a domain model worth defending; reach for this one when it does not, or when nothing should be written down yet.
+
+`triage` composes the documented variant, not this one, when an issue needs fleshing out.
+
+## Usage
+
+```text
+/grill-me
+```
+
+Describe the plan or design to be stress-tested. Expect questions one at a time, each with a recommended answer.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The whole skill — the interview instruction, the one-question-at-a-time rule, and the explore-instead-of-asking rule |

plugins/bin/.apm/skills/grill-with-docs/README.md

@@ -0,0 +1,36 @@
+# grill-with-docs
+
+The grilling interview, run against the project's domain model — and writing decisions back into `CONTEXT.md` and ADRs as they land.
+
+## What it does
+
+Runs the same relentless one-question-at-a-time interview as `grill-me`, with the project's own documentation as an active participant. During codebase exploration it also locates the domain documentation — a root `CONTEXT.md` and `docs/adr/`, or a `CONTEXT-MAP.md` pointing at per-context glossaries and ADR directories in a multi-context repo — and then uses it four ways:
+
+- **Challenges terms against the glossary.** When the user's usage conflicts with what `CONTEXT.md` already defines, that is raised immediately rather than absorbed.
+- **Sharpens fuzzy language** by proposing a precise canonical term ("you're saying 'account' — do you mean the Customer or the User?").
+- **Cross-references claims against the code**, and surfaces contradictions between what the user says happens and what the code does.
+- **Updates `CONTEXT.md` inline**, the moment a term is resolved, rather than batching changes to the end of the session where they get lost.
+
+Files are created lazily — only when there is something real to write.
+
+ADRs are offered *sparingly*, and only when all three tests pass: the decision is hard to reverse, it would surprise a future reader without the context, and it was a genuine trade-off with real alternatives. Missing any one of the three means no ADR.
+
+## Composition
+
+`grill-me` is the same interview without the documentation side effects — use it when there is no domain model to defend or nothing should be written down yet. `triage` composes this skill (not `grill-me`) at step 4 when an issue needs fleshing out. `improve-codebase-architecture` runs its own grilling loop and borrows this skill's `CONTEXT.md` and ADR discipline for the decisions that come out of it.
+
+## Usage
+
+```text
+/grill-with-docs
+```
+
+Describe the plan or design. Expect questions one at a time, each with a recommended answer, and expect `CONTEXT.md` to be edited during the session rather than after it.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The interview instruction plus the domain-awareness rules: file layout discovery, the four during-session behaviours, and the three-part ADR test |
+| `CONTEXT-FORMAT.md` | Skill-root document, cited when a term is resolved: the structure of a `CONTEXT.md` and how to write a Language entry |
+| `ADR-FORMAT.md` | Skill-root document, cited when an ADR is offered: `docs/adr/` naming, sequential numbering, and the ADR template |

plugins/bin/.apm/skills/improve-codebase-architecture/README.md

@@ -0,0 +1,36 @@
+# improve-codebase-architecture
+
+Surface architectural friction and propose deepening opportunities — refactors that turn shallow modules into deep ones.
+
+## What it does
+
+Looks for places where a codebase is hard to understand, hard to test, or hard for an agent to navigate, and proposes refactors that concentrate behaviour behind smaller interfaces. It runs in three stages:
+
+1. **Explore.** Reads the domain glossary and any ADRs in the area first, then walks the codebase with an `Explore` sub-agent — organically, noting friction rather than applying fixed heuristics. The **deletion test** is the filter: imagine deleting the module; if complexity vanishes it was a pass-through, if complexity reappears across N callers it was earning its keep.
+2. **Present candidates.** A numbered list, each with files, problem, solution and benefits — benefits stated in terms of *locality* and *leverage* and of how tests would improve. No interfaces are proposed yet; the user picks one.
+3. **Grilling loop.** Walks the design tree for the chosen candidate, with documentation side effects landing inline as decisions crystallise.
+
+The skill is opinionated about vocabulary, and that is the point: **module, interface, implementation, depth, seam, adapter, leverage, locality**, used exactly, with no drift into "component", "service", "API" or "boundary". Domain nouns come from `CONTEXT.md`, architecture nouns from `LANGUAGE.md` — so a proposal reads as "the Order intake module", never "the FooBarHandler".
+
+ADRs are treated as decisions not to be re-litigated. A candidate that contradicts one is surfaced only when the friction is real enough to warrant reopening it, and is marked as such.
+
+## Composition
+
+`diagnose` hands off here when a bug's post-mortem concludes that no correct test seam exists, or that callers are tangled — the recommendation is made after the fix is in, not before. The grilling loop follows `grill-with-docs`'s discipline for `CONTEXT.md` entries and ADR offers, and `SKILL.md` names that skill's format documents directly.
+
+## Usage
+
+```text
+/improve-codebase-architecture
+```
+
+Point at a codebase or an area of one. Expect a numbered candidate list and a "which of these would you like to explore?" before any interface design happens.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Condensed glossary, key principles, and the three-stage process |
+| `LANGUAGE.md` | Skill-root document, cited throughout `SKILL.md`: full definitions of every term, the words each one replaces, and the full principle list |
+| `INTERFACE-DESIGN.md` | Skill-root document, read at stage 3 when the user wants alternative interfaces explored: the parallel sub-agent "Design It Twice" pattern, framing the problem space, and the per-agent design constraints |
+| `DEEPENING.md` | Skill-root document, cited from `INTERFACE-DESIGN.md`: how to deepen a cluster of shallow modules safely, the four dependency categories (in-process, local-substitutable, remote-but-owned, true external), seam discipline, and the replace-don't-layer testing strategy |

plugins/bin/.apm/skills/prototype/README.md

@@ -0,0 +1,32 @@
+# prototype
+
+Build a throwaway prototype that answers one design question — either a runnable terminal app or several UI variations.
+
+## What it does
+
+Treats a prototype as **throwaway code that answers a question**, and lets the question decide the artifact. `SKILL.md` opens with a two-row dispatch table and the run resolves exactly one row before doing anything else:
+
+- *"Does this logic / state model feel right?"* → a tiny interactive terminal app that pushes the state machine through the cases that are hard to reason about on paper.
+- *"What should this look like?"* → several radically different UI variations on one route, switchable from a floating bottom bar via a URL search param.
+
+The two branches produce fundamentally different artifacts, so picking wrong wastes the whole prototype. When the question is genuinely ambiguous and the user is unreachable, the skill defaults on the shape of the surrounding code (backend module → logic, page or component → UI) and states the assumption at the top of the prototype rather than silently choosing.
+
+Six rules apply to both branches: throwaway and visibly named as such, one command to run, no persistence by default, no polish, surface the full state after every action or variant switch, and delete or absorb the prototype when it is done. The *answer* is the only durable output — the skill captures it in a commit message, ADR, issue or `NOTES.md` before the code is deleted.
+
+## Usage
+
+```text
+/prototype
+```
+
+State the design question. For production code, use `tdd`; for talking a design through without building anything, use `grill-me`.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The branch dispatch table and the rules that apply to both branches |
+| `references/logic.md` | The logic branch, read only when that row is selected: when it is the right shape, and how to build the interactive terminal app |
+| `references/ui.md` | The UI branch, read only when that row is selected: when it is the right shape, and how to build and switch between the variations |
+
+Each reference is self-contained — a run reads one of the two, never both.

plugins/bin/.apm/skills/research/README.md

@@ -0,0 +1,31 @@
+# research
+
+Research a tool, library or API from canonical documentation into a directory of structured per-topic reference files.
+
+## What it does
+
+Runs a six-step pipeline: scope against the working directory (what version is actually in use, what is already documented), resolve the topic through Context7, websearch for canonical docs covering whatever Context7 missed, read those sources, deepen one level into the links worth following, then write one markdown file per topic area plus a `sources.md` provenance record.
+
+Four gotchas at the top of `SKILL.md` shape the whole run, and each exists because of a specific failure: the output path is never inferred (a guessed destination scatters a directory's worth of files through someone's source tree); nothing is written outside that path; no empty topic file is ever written (a stub `troubleshooting.md` reads downstream as researched and closed); and a Context7 "no results", redirect or header-only response does not count as coverage. If no topic area has content, the run writes nothing at all — `sources.md` included — and reports what it searched.
+
+The frontmatter pins `model: sonnet` and a closed `allowed-tools` list. Notably it grants no subagent tool, so every `WebFetch` is serial and each fetched page lands in the run's own context — which is why steps 4 and 5 insist on reducing each page to notes before fetching the next, and cap deepening at roughly ten extra pages.
+
+## Composition
+
+`references/file-format.md` is not optional reading before the write step: the `sources.md` field names it defines are matched literally by the downstream provenance validator. Prose written in their place parses as nothing and the check passes having verified nothing.
+
+## Usage
+
+```text
+/research
+```
+
+Name the topic and the output path — the skill will stop and ask if the path is missing. Supplying starting URLs is treated as a deliberate source choice and skips Context7 resolution and discovery. For documentation derived from existing code or specs, use `write-docs`; for a bug or incident, use `diagnose`.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The four gotchas and the six research steps |
+| `references/topics.md` | Read at Step 1 before narrowing scope: the default topic list (`overview`, `installation`, `configuration`, `cli-reference`, `api-reference`, `examples`, and more) and what each file covers |
+| `references/file-format.md` | Read at Step 6 before writing: the frontmatter schema for a topic file and the exact `sources.md` field names the provenance validator matches |

plugins/bin/.apm/skills/tdd/README.md

@@ -0,0 +1,32 @@
+# tdd
+
+Test-driven development as a strict red-green-refactor loop, one behaviour at a time.
+
+## What it does
+
+Two convictions drive this skill. The first is about what a test is for: tests verify behaviour through public interfaces, not implementation details. A good test reads like a specification ("user can checkout with valid cart") and survives refactors because it does not care about internal structure. The warning sign for a bad one is precise — the test breaks when you refactor but behaviour has not changed.
+
+The second is an explicit anti-pattern: **do not write all the tests first, then all the implementation.** Horizontal slicing treats RED as "write every test" and GREEN as "write every implementation", and it produces tests of *imagined* behaviour — tests of the shape of things, insensitive to real change, committed to before the implementation was understood. The correct shape is vertical: one test → one implementation → repeat, each cycle informed by what the last one taught you.
+
+The workflow is four stages: plan (confirm the interface and which behaviours matter, with the user — you cannot test everything), fire a tracer bullet (one test proving the path works end to end), loop incrementally one behaviour at a time, then refactor once everything is green. Refactoring while RED is forbidden.
+
+Codebase exploration uses the project's domain glossary, so test names and interface vocabulary match the project's language, and ADRs in the area are respected.
+
+## Usage
+
+```text
+/tdd
+```
+
+Describe the feature or bug. Expect the skill to ask what the public interface should look like and which behaviours matter most before any code is written. For diagnosing an existing bug rather than building test-first, use `diagnose`; for throwaway exploratory code, use `prototype`.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Philosophy, the horizontal-slicing anti-pattern, the four-stage workflow, and the per-cycle checklist |
+| `tests.md` | Skill-root document, cited from Philosophy: worked good and bad test examples |
+| `mocking.md` | Skill-root document, cited from Philosophy: mock at system boundaries only, and what not to mock |
+| `deep-modules.md` | Skill-root document, cited from stage 1: what a deep module is (small interface, large implementation) and why it is the design to aim for |
+| `interface-design.md` | Skill-root document, cited from stage 1: designing interfaces for testability, starting with accepting dependencies rather than creating them |
+| `refactoring.md` | Skill-root document, cited from stage 4: the refactor-candidate checklist — duplication, long methods, shallow modules, feature envy, primitive obsession |

plugins/bin/.apm/skills/triage/README.md

@@ -0,0 +1,35 @@
+# triage
+
+Move issues on the project issue tracker through a small state machine of triage roles.
+
+## What it does
+
+Gives issue triage an explicit state model and a fixed set of moves. Every issue carries exactly one **category** role (`bug`, `enhancement`) and one **state** role (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`); conflicting state roles are flagged to the maintainer before anything else happens. Unlabeled issues normally enter at `needs-triage`; `needs-info` returns there once the reporter replies. The maintainer can override at any point, and unusual transitions are questioned rather than executed silently.
+
+A run does one of three things depending on what the maintainer asks for:
+
+- **Show what needs attention** — three buckets, oldest first: unlabeled, `needs-triage`, and `needs-info` with reporter activity since the last triage notes.
+- **Triage a specific issue** — gather context (including prior triage notes, so resolved questions are not re-asked, and `.out-of-scope/` records that resemble the issue), recommend a category and state with reasoning, attempt reproduction for bugs *before* any grilling, run a `grill-with-docs` session if the issue needs fleshing out, then apply the outcome.
+- **Quick state override** — "move #42 to ready-for-agent" is trusted and applied directly, skipping grilling, after confirming the exact changes.
+
+Two hard rules: every comment or issue the skill posts during triage must open with the AI-generated disclaimer, and the canonical role names above are *not* necessarily the label strings in the tracker — the mapping has to be supplied to the run.
+
+## Composition
+
+`grill-with-docs` is invoked at step 4 when an issue needs fleshing out; whatever that session establishes is carried into the triage notes so the work is not lost. The reverse direction also exists: `diagnose` names this skill as the place to send a *reported* bug that needs filing rather than debugging.
+
+## Usage
+
+```text
+/triage
+```
+
+Then describe what you want in natural language — "show me anything that needs my attention", "let's look at #42", "move #42 to ready-for-agent", "what's ready for agents to pick up?".
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The roles and state machine, the three invocation modes, the needs-info template, and how to resume a prior session |
+| `AGENT-BRIEF.md` | Skill-root document, cited when an issue moves to `ready-for-agent` (and reused for `ready-for-human`): how to write a brief that stays durable for weeks while the codebase moves under it — describe interfaces and behavioural contracts, not line numbers |
+| `OUT-OF-SCOPE.md` | Skill-root document, cited when an enhancement is closed `wontfix` and when checking for prior rejections: how the `.out-of-scope/` knowledge base is laid out and what it is for — institutional memory, and deduplication against re-litigated requests |

plugins/bin/.apm/skills/write-docs/README.md

@@ -0,0 +1,30 @@
+# write-docs
+
+Produce technical documentation derived from code and spec, one section at a time, with a confirmation gate on every section.
+
+## What it does
+
+Casts the agent as a technical writer with one non-negotiable constraint: **every claim must be traceable to a source file line, a spec section, or an explicit user statement.** Nothing is invented, and behaviour that genuinely cannot be documented from the available sources is marked out-of-scope rather than explained away.
+
+The process is eight steps — identify scope, read and extract, gap check, draft section by section, confirmation gate, delta summary, reader testing, finalise — and several of them are deliberately gated on the human:
+
+- Files are read only after the user approves them by name. The skill may propose candidates; it waits.
+- The **gap check** presents what the code does say and asks the user to fill only what it does not: caller intent, error-handling rationale, non-obvious side effects.
+- No section is finalised until the full revised text has been shown. The skill never gates on output the user has not seen, and never reprints the whole document — all edits are surgical.
+- **Reader testing** predicts 5–10 questions a target reader would ask, then spawns a sub-agent that receives only the finished doc and the questions — no source files. If the doc cannot answer them, neither can the sub-agent, and the run loops back to drafting.
+
+Summary and overview sections are written last, once the detail sections are stable.
+
+## Usage
+
+```text
+/write-docs
+```
+
+Name the files or modules to document, the target audience (developer / user / contributor / internal), and the documentation type (reference, guide, README section, inline comment, changelog entry). For a PRD, ADR or decision doc, use `grill-me` or `grill-with-docs` instead — those have dedicated handling.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The whole skill — role, use/do-not-use boundaries, required inputs, constraints, the eight-step process, output format, failure handling, and a nine-item self-check |

plugins/bin/.apm/skills/zoom-out/README.md

@@ -0,0 +1,25 @@
+# zoom-out
+
+Ask the agent to go up a layer of abstraction and map the modules and callers around unfamiliar code.
+
+## What it does
+
+A single-purpose prompt for the moment you land in a part of the codebase you do not know. Instead of answering at the level of the file in front of it, the agent climbs one layer and produces a map of the relevant modules and their callers — and names them using the project's own domain glossary vocabulary, so the map lines up with the language the rest of the repo already uses.
+
+## Hand-invoked only
+
+`SKILL.md` sets `disable-model-invocation: true`, so the router never selects this skill on its own and no other skill can hand off to it. It runs when the human asks for it. That also means its description is written as one plain human-facing sentence — it carries no trigger phrasing or boundary clause, because nothing routes on it.
+
+## Usage
+
+```text
+/zoom-out
+```
+
+Best used with the unfamiliar code already in context — the skill widens the view around what you are looking at rather than picking a starting point for you.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The whole skill — a single instruction, no supporting files |

plugins/bin/skills/caveman/README.md

@@ -0,0 +1,29 @@
+# caveman
+
+Ultra-compressed output mode: drop articles, filler and pleasantries, keep the technical substance exact.
+
+## What it does
+
+Switches the agent into a terse register — no articles, no hedging, no pleasantries, fragments allowed, arrows for causality — while leaving technical terms, code blocks and quoted error strings untouched. The mode is *sticky*: once turned on it stays on for every subsequent response until the user says "stop caveman" or "normal mode", rather than decaying back to normal prose after a few turns.
+
+It carries one built-in escape hatch. Security warnings, confirmations for irreversible actions, multi-step sequences where fragment order could be misread, and any request to clarify are answered in normal prose, then the compressed register resumes.
+
+## Hand-invoked only
+
+`SKILL.md` sets `disable-model-invocation: true`. This is the single most important thing to know about this skill: **the model cannot route to it.** No other skill can hand off to it, and no phrasing in a user's request will cause it to be selected automatically. The only way in is the human typing `/caveman`.
+
+That is deliberate — output style is the user's choice, not an inference the router should make on their behalf. It is also why the description reads as one plain human-facing sentence rather than carrying the trigger phrasing and boundary clause a routable skill needs.
+
+## Usage
+
+```text
+/caveman
+```
+
+Then keep working normally. To leave the mode, say "stop caveman" or "normal mode".
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The whole skill — persistence rule, compression rules, worked examples, and the auto-clarity exception |

plugins/bin/skills/diagnose/README.md

@@ -0,0 +1,35 @@
+# diagnose
+
+A six-phase discipline for hard bugs and performance regressions: feedback loop → reproduce → hypothesise → instrument → fix with a regression test → clean up.
+
+## What it does
+
+Imposes an order of operations on debugging so the agent cannot skip to guessing. The load-bearing phase is the first one: build a fast, deterministic, agent-runnable pass/fail signal for the bug. Everything downstream — bisection, hypothesis testing, instrumentation — just consumes that signal, so the skill refuses to advance to Phase 2 without one, and says so explicitly rather than hypothesising blind.
+
+The remaining phases each carry a constraint worth knowing about: hypotheses are generated 3–5 at a time and must be falsifiable, so the first plausible idea cannot anchor the whole investigation; every debug log is tagged with a unique prefix (`[DEBUG-a4f2]`) so cleanup is a single grep; the regression test is written before the fix and only at a seam that exercises the real bug pattern; and the run closes by asking what would have prevented the bug, handing off to `improve-codebase-architecture` when the answer is architectural.
+
+Performance regressions take a branch of their own inside Phase 4 — baseline measurement and bisection, not logs.
+
+## Conditional reading
+
+Neither reference file is read on every run; `SKILL.md` names the condition for each.
+
+- `references/feedback-loops.md` is read when Phase 1 has no signal yet, or when the loop you have is slow or intermittent.
+- `references/regression-seams.md` is read when Phase 5 leaves you unsure whether the available seam is deep enough — or whether one exists at all.
+
+## Usage
+
+```text
+/diagnose
+```
+
+Describe the bug or the regression. For filing and triaging a reported bug rather than diagnosing it, use `triage`; for test-first feature work, use `tdd`.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The six phases and their gates — what must be true before each one ends |
+| `references/feedback-loops.md` | Loaded when Phase 1 has no loop or the loop is too weak: ten ways to construct one ordered by cost, how to sharpen an existing loop, handling intermittent bugs, and what to ask the user for when the bug resists reproduction |
+| `references/regression-seams.md` | Loaded when Phase 5 is unsure about the seam: what makes a seam correct, the four shapes of a too-shallow seam, and what to do when no correct seam exists |
+| `assets/hitl-loop.template.sh` | Copy-and-edit bash template for the last-resort human-in-the-loop feedback loop, cited by `references/feedback-loops.md`. Provides `step` and `capture` helpers and prints captured values as `KEY=VALUE` for the agent to parse |

plugins/bin/skills/grill-me/README.md

@@ -0,0 +1,27 @@
+# grill-me
+
+Interview the user relentlessly about a plan or design until the decision tree is fully resolved.
+
+## What it does
+
+Turns the agent into an interviewer rather than an implementer. It walks the design tree branch by branch, resolving dependencies between decisions one at a time, and offers its own recommended answer alongside each question so the user has something concrete to push against. Two rules give it its shape: **one question at a time**, and **never ask what the codebase can answer** — if a question is settleable by reading the code, the agent goes and reads the code instead of spending the user's attention on it.
+
+## Composition
+
+This is the plain grilling loop, with no documentation side effects. The sibling `grill-with-docs` skill runs the same interview but additionally challenges answers against the project's `CONTEXT.md` glossary and existing ADRs, and writes decisions back into those files as they crystallise. Reach for that one when the project has a domain model worth defending; reach for this one when it does not, or when nothing should be written down yet.
+
+`triage` composes the documented variant, not this one, when an issue needs fleshing out.
+
+## Usage
+
+```text
+/grill-me
+```
+
+Describe the plan or design to be stress-tested. Expect questions one at a time, each with a recommended answer.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The whole skill — the interview instruction, the one-question-at-a-time rule, and the explore-instead-of-asking rule |

plugins/bin/skills/grill-with-docs/README.md

@@ -0,0 +1,36 @@
+# grill-with-docs
+
+The grilling interview, run against the project's domain model — and writing decisions back into `CONTEXT.md` and ADRs as they land.
+
+## What it does
+
+Runs the same relentless one-question-at-a-time interview as `grill-me`, with the project's own documentation as an active participant. During codebase exploration it also locates the domain documentation — a root `CONTEXT.md` and `docs/adr/`, or a `CONTEXT-MAP.md` pointing at per-context glossaries and ADR directories in a multi-context repo — and then uses it four ways:
+
+- **Challenges terms against the glossary.** When the user's usage conflicts with what `CONTEXT.md` already defines, that is raised immediately rather than absorbed.
+- **Sharpens fuzzy language** by proposing a precise canonical term ("you're saying 'account' — do you mean the Customer or the User?").
+- **Cross-references claims against the code**, and surfaces contradictions between what the user says happens and what the code does.
+- **Updates `CONTEXT.md` inline**, the moment a term is resolved, rather than batching changes to the end of the session where they get lost.
+
+Files are created lazily — only when there is something real to write.
+
+ADRs are offered *sparingly*, and only when all three tests pass: the decision is hard to reverse, it would surprise a future reader without the context, and it was a genuine trade-off with real alternatives. Missing any one of the three means no ADR.
+
+## Composition
+
+`grill-me` is the same interview without the documentation side effects — use it when there is no domain model to defend or nothing should be written down yet. `triage` composes this skill (not `grill-me`) at step 4 when an issue needs fleshing out. `improve-codebase-architecture` runs its own grilling loop and borrows this skill's `CONTEXT.md` and ADR discipline for the decisions that come out of it.
+
+## Usage
+
+```text
+/grill-with-docs
+```
+
+Describe the plan or design. Expect questions one at a time, each with a recommended answer, and expect `CONTEXT.md` to be edited during the session rather than after it.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The interview instruction plus the domain-awareness rules: file layout discovery, the four during-session behaviours, and the three-part ADR test |
+| `CONTEXT-FORMAT.md` | Skill-root document, cited when a term is resolved: the structure of a `CONTEXT.md` and how to write a Language entry |
+| `ADR-FORMAT.md` | Skill-root document, cited when an ADR is offered: `docs/adr/` naming, sequential numbering, and the ADR template |

plugins/bin/skills/improve-codebase-architecture/README.md

@@ -0,0 +1,36 @@
+# improve-codebase-architecture
+
+Surface architectural friction and propose deepening opportunities — refactors that turn shallow modules into deep ones.
+
+## What it does
+
+Looks for places where a codebase is hard to understand, hard to test, or hard for an agent to navigate, and proposes refactors that concentrate behaviour behind smaller interfaces. It runs in three stages:
+
+1. **Explore.** Reads the domain glossary and any ADRs in the area first, then walks the codebase with an `Explore` sub-agent — organically, noting friction rather than applying fixed heuristics. The **deletion test** is the filter: imagine deleting the module; if complexity vanishes it was a pass-through, if complexity reappears across N callers it was earning its keep.
+2. **Present candidates.** A numbered list, each with files, problem, solution and benefits — benefits stated in terms of *locality* and *leverage* and of how tests would improve. No interfaces are proposed yet; the user picks one.
+3. **Grilling loop.** Walks the design tree for the chosen candidate, with documentation side effects landing inline as decisions crystallise.
+
+The skill is opinionated about vocabulary, and that is the point: **module, interface, implementation, depth, seam, adapter, leverage, locality**, used exactly, with no drift into "component", "service", "API" or "boundary". Domain nouns come from `CONTEXT.md`, architecture nouns from `LANGUAGE.md` — so a proposal reads as "the Order intake module", never "the FooBarHandler".
+
+ADRs are treated as decisions not to be re-litigated. A candidate that contradicts one is surfaced only when the friction is real enough to warrant reopening it, and is marked as such.
+
+## Composition
+
+`diagnose` hands off here when a bug's post-mortem concludes that no correct test seam exists, or that callers are tangled — the recommendation is made after the fix is in, not before. The grilling loop follows `grill-with-docs`'s discipline for `CONTEXT.md` entries and ADR offers, and `SKILL.md` names that skill's format documents directly.
+
+## Usage
+
+```text
+/improve-codebase-architecture
+```
+
+Point at a codebase or an area of one. Expect a numbered candidate list and a "which of these would you like to explore?" before any interface design happens.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Condensed glossary, key principles, and the three-stage process |
+| `LANGUAGE.md` | Skill-root document, cited throughout `SKILL.md`: full definitions of every term, the words each one replaces, and the full principle list |
+| `INTERFACE-DESIGN.md` | Skill-root document, read at stage 3 when the user wants alternative interfaces explored: the parallel sub-agent "Design It Twice" pattern, framing the problem space, and the per-agent design constraints |
+| `DEEPENING.md` | Skill-root document, cited from `INTERFACE-DESIGN.md`: how to deepen a cluster of shallow modules safely, the four dependency categories (in-process, local-substitutable, remote-but-owned, true external), seam discipline, and the replace-don't-layer testing strategy |

plugins/bin/skills/prototype/README.md

@@ -0,0 +1,32 @@
+# prototype
+
+Build a throwaway prototype that answers one design question — either a runnable terminal app or several UI variations.
+
+## What it does
+
+Treats a prototype as **throwaway code that answers a question**, and lets the question decide the artifact. `SKILL.md` opens with a two-row dispatch table and the run resolves exactly one row before doing anything else:
+
+- *"Does this logic / state model feel right?"* → a tiny interactive terminal app that pushes the state machine through the cases that are hard to reason about on paper.
+- *"What should this look like?"* → several radically different UI variations on one route, switchable from a floating bottom bar via a URL search param.
+
+The two branches produce fundamentally different artifacts, so picking wrong wastes the whole prototype. When the question is genuinely ambiguous and the user is unreachable, the skill defaults on the shape of the surrounding code (backend module → logic, page or component → UI) and states the assumption at the top of the prototype rather than silently choosing.
+
+Six rules apply to both branches: throwaway and visibly named as such, one command to run, no persistence by default, no polish, surface the full state after every action or variant switch, and delete or absorb the prototype when it is done. The *answer* is the only durable output — the skill captures it in a commit message, ADR, issue or `NOTES.md` before the code is deleted.
+
+## Usage
+
+```text
+/prototype
+```
+
+State the design question. For production code, use `tdd`; for talking a design through without building anything, use `grill-me`.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The branch dispatch table and the rules that apply to both branches |
+| `references/logic.md` | The logic branch, read only when that row is selected: when it is the right shape, and how to build the interactive terminal app |
+| `references/ui.md` | The UI branch, read only when that row is selected: when it is the right shape, and how to build and switch between the variations |
+
+Each reference is self-contained — a run reads one of the two, never both.

plugins/bin/skills/research/README.md

@@ -0,0 +1,31 @@
+# research
+
+Research a tool, library or API from canonical documentation into a directory of structured per-topic reference files.
+
+## What it does
+
+Runs a six-step pipeline: scope against the working directory (what version is actually in use, what is already documented), resolve the topic through Context7, websearch for canonical docs covering whatever Context7 missed, read those sources, deepen one level into the links worth following, then write one markdown file per topic area plus a `sources.md` provenance record.
+
+Four gotchas at the top of `SKILL.md` shape the whole run, and each exists because of a specific failure: the output path is never inferred (a guessed destination scatters a directory's worth of files through someone's source tree); nothing is written outside that path; no empty topic file is ever written (a stub `troubleshooting.md` reads downstream as researched and closed); and a Context7 "no results", redirect or header-only response does not count as coverage. If no topic area has content, the run writes nothing at all — `sources.md` included — and reports what it searched.
+
+The frontmatter pins `model: sonnet` and a closed `allowed-tools` list. Notably it grants no subagent tool, so every `WebFetch` is serial and each fetched page lands in the run's own context — which is why steps 4 and 5 insist on reducing each page to notes before fetching the next, and cap deepening at roughly ten extra pages.
+
+## Composition
+
+`references/file-format.md` is not optional reading before the write step: the `sources.md` field names it defines are matched literally by the downstream provenance validator. Prose written in their place parses as nothing and the check passes having verified nothing.
+
+## Usage
+
+```text
+/research
+```
+
+Name the topic and the output path — the skill will stop and ask if the path is missing. Supplying starting URLs is treated as a deliberate source choice and skips Context7 resolution and discovery. For documentation derived from existing code or specs, use `write-docs`; for a bug or incident, use `diagnose`.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The four gotchas and the six research steps |
+| `references/topics.md` | Read at Step 1 before narrowing scope: the default topic list (`overview`, `installation`, `configuration`, `cli-reference`, `api-reference`, `examples`, and more) and what each file covers |
+| `references/file-format.md` | Read at Step 6 before writing: the frontmatter schema for a topic file and the exact `sources.md` field names the provenance validator matches |

plugins/bin/skills/tdd/README.md

@@ -0,0 +1,32 @@
+# tdd
+
+Test-driven development as a strict red-green-refactor loop, one behaviour at a time.
+
+## What it does
+
+Two convictions drive this skill. The first is about what a test is for: tests verify behaviour through public interfaces, not implementation details. A good test reads like a specification ("user can checkout with valid cart") and survives refactors because it does not care about internal structure. The warning sign for a bad one is precise — the test breaks when you refactor but behaviour has not changed.
+
+The second is an explicit anti-pattern: **do not write all the tests first, then all the implementation.** Horizontal slicing treats RED as "write every test" and GREEN as "write every implementation", and it produces tests of *imagined* behaviour — tests of the shape of things, insensitive to real change, committed to before the implementation was understood. The correct shape is vertical: one test → one implementation → repeat, each cycle informed by what the last one taught you.
+
+The workflow is four stages: plan (confirm the interface and which behaviours matter, with the user — you cannot test everything), fire a tracer bullet (one test proving the path works end to end), loop incrementally one behaviour at a time, then refactor once everything is green. Refactoring while RED is forbidden.
+
+Codebase exploration uses the project's domain glossary, so test names and interface vocabulary match the project's language, and ADRs in the area are respected.
+
+## Usage
+
+```text
+/tdd
+```
+
+Describe the feature or bug. Expect the skill to ask what the public interface should look like and which behaviours matter most before any code is written. For diagnosing an existing bug rather than building test-first, use `diagnose`; for throwaway exploratory code, use `prototype`.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Philosophy, the horizontal-slicing anti-pattern, the four-stage workflow, and the per-cycle checklist |
+| `tests.md` | Skill-root document, cited from Philosophy: worked good and bad test examples |
+| `mocking.md` | Skill-root document, cited from Philosophy: mock at system boundaries only, and what not to mock |
+| `deep-modules.md` | Skill-root document, cited from stage 1: what a deep module is (small interface, large implementation) and why it is the design to aim for |
+| `interface-design.md` | Skill-root document, cited from stage 1: designing interfaces for testability, starting with accepting dependencies rather than creating them |
+| `refactoring.md` | Skill-root document, cited from stage 4: the refactor-candidate checklist — duplication, long methods, shallow modules, feature envy, primitive obsession |

plugins/bin/skills/triage/README.md

@@ -0,0 +1,35 @@
+# triage
+
+Move issues on the project issue tracker through a small state machine of triage roles.
+
+## What it does
+
+Gives issue triage an explicit state model and a fixed set of moves. Every issue carries exactly one **category** role (`bug`, `enhancement`) and one **state** role (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`); conflicting state roles are flagged to the maintainer before anything else happens. Unlabeled issues normally enter at `needs-triage`; `needs-info` returns there once the reporter replies. The maintainer can override at any point, and unusual transitions are questioned rather than executed silently.
+
+A run does one of three things depending on what the maintainer asks for:
+
+- **Show what needs attention** — three buckets, oldest first: unlabeled, `needs-triage`, and `needs-info` with reporter activity since the last triage notes.
+- **Triage a specific issue** — gather context (including prior triage notes, so resolved questions are not re-asked, and `.out-of-scope/` records that resemble the issue), recommend a category and state with reasoning, attempt reproduction for bugs *before* any grilling, run a `grill-with-docs` session if the issue needs fleshing out, then apply the outcome.
+- **Quick state override** — "move #42 to ready-for-agent" is trusted and applied directly, skipping grilling, after confirming the exact changes.
+
+Two hard rules: every comment or issue the skill posts during triage must open with the AI-generated disclaimer, and the canonical role names above are *not* necessarily the label strings in the tracker — the mapping has to be supplied to the run.
+
+## Composition
+
+`grill-with-docs` is invoked at step 4 when an issue needs fleshing out; whatever that session establishes is carried into the triage notes so the work is not lost. The reverse direction also exists: `diagnose` names this skill as the place to send a *reported* bug that needs filing rather than debugging.
+
+## Usage
+
+```text
+/triage
+```
+
+Then describe what you want in natural language — "show me anything that needs my attention", "let's look at #42", "move #42 to ready-for-agent", "what's ready for agents to pick up?".
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The roles and state machine, the three invocation modes, the needs-info template, and how to resume a prior session |
+| `AGENT-BRIEF.md` | Skill-root document, cited when an issue moves to `ready-for-agent` (and reused for `ready-for-human`): how to write a brief that stays durable for weeks while the codebase moves under it — describe interfaces and behavioural contracts, not line numbers |
+| `OUT-OF-SCOPE.md` | Skill-root document, cited when an enhancement is closed `wontfix` and when checking for prior rejections: how the `.out-of-scope/` knowledge base is laid out and what it is for — institutional memory, and deduplication against re-litigated requests |

plugins/bin/skills/write-docs/README.md

@@ -0,0 +1,30 @@
+# write-docs
+
+Produce technical documentation derived from code and spec, one section at a time, with a confirmation gate on every section.
+
+## What it does
+
+Casts the agent as a technical writer with one non-negotiable constraint: **every claim must be traceable to a source file line, a spec section, or an explicit user statement.** Nothing is invented, and behaviour that genuinely cannot be documented from the available sources is marked out-of-scope rather than explained away.
+
+The process is eight steps — identify scope, read and extract, gap check, draft section by section, confirmation gate, delta summary, reader testing, finalise — and several of them are deliberately gated on the human:
+
+- Files are read only after the user approves them by name. The skill may propose candidates; it waits.
+- The **gap check** presents what the code does say and asks the user to fill only what it does not: caller intent, error-handling rationale, non-obvious side effects.
+- No section is finalised until the full revised text has been shown. The skill never gates on output the user has not seen, and never reprints the whole document — all edits are surgical.
+- **Reader testing** predicts 5–10 questions a target reader would ask, then spawns a sub-agent that receives only the finished doc and the questions — no source files. If the doc cannot answer them, neither can the sub-agent, and the run loops back to drafting.
+
+Summary and overview sections are written last, once the detail sections are stable.
+
+## Usage
+
+```text
+/write-docs
+```
+
+Name the files or modules to document, the target audience (developer / user / contributor / internal), and the documentation type (reference, guide, README section, inline comment, changelog entry). For a PRD, ADR or decision doc, use `grill-me` or `grill-with-docs` instead — those have dedicated handling.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The whole skill — role, use/do-not-use boundaries, required inputs, constraints, the eight-step process, output format, failure handling, and a nine-item self-check |

plugins/bin/skills/zoom-out/README.md

@@ -0,0 +1,25 @@
+# zoom-out
+
+Ask the agent to go up a layer of abstraction and map the modules and callers around unfamiliar code.
+
+## What it does
+
+A single-purpose prompt for the moment you land in a part of the codebase you do not know. Instead of answering at the level of the file in front of it, the agent climbs one layer and produces a map of the relevant modules and their callers — and names them using the project's own domain glossary vocabulary, so the map lines up with the language the rest of the repo already uses.
+
+## Hand-invoked only
+
+`SKILL.md` sets `disable-model-invocation: true`, so the router never selects this skill on its own and no other skill can hand off to it. It runs when the human asks for it. That also means its description is written as one plain human-facing sentence — it carries no trigger phrasing or boundary clause, because nothing routes on it.
+
+## Usage
+
+```text
+/zoom-out
+```
+
+Best used with the unfamiliar code already in context — the skill widens the view around what you are looking at rather than picking a starting point for you.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The whole skill — a single instruction, no supporting files |