diff --git a/plugins/bin/.apm/skills/grill-me/SKILL.md b/plugins/bin/.apm/skills/grill-me/SKILL.md index bd04394..1cc8ede 100644 --- a/plugins/bin/.apm/skills/grill-me/SKILL.md +++ b/plugins/bin/.apm/skills/grill-me/SKILL.md @@ -1,6 +1,10 @@ --- name: grill-me -description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me". +description: > + Use when the user says "grill me" or wants a plan or design stress-tested by + relentless interview — one question at a time, down each branch of the + decision tree. Not a plan to challenge against `CONTEXT.md` and ADRs -> + `grill-with-docs`. --- Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. diff --git a/plugins/bin/.apm/skills/grill-with-docs/SKILL.md b/plugins/bin/.apm/skills/grill-with-docs/SKILL.md index 6dad6ad..8610263 100644 --- a/plugins/bin/.apm/skills/grill-with-docs/SKILL.md +++ b/plugins/bin/.apm/skills/grill-with-docs/SKILL.md @@ -1,6 +1,9 @@ --- name: grill-with-docs -description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions. +description: > + Use when a plan should be stress-tested against the project's domain model — + the interview challenges terms against `CONTEXT.md` and writes decisions into + it and into ADRs as they land. Not a plain interview -> `grill-me`. --- diff --git a/plugins/bin/.apm/skills/improve-codebase-architecture/SKILL.md b/plugins/bin/.apm/skills/improve-codebase-architecture/SKILL.md index 22d02fb..6ec346b 100644 --- a/plugins/bin/.apm/skills/improve-codebase-architecture/SKILL.md +++ b/plugins/bin/.apm/skills/improve-codebase-architecture/SKILL.md @@ -1,6 +1,10 @@ --- name: improve-codebase-architecture -description: Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable. +description: > + Use when the user wants a codebase's architecture improved — deepening + opportunities that turn shallow modules into deep ones, informed by + `CONTEXT.md` and `docs/adr/`. Not debugging a failure -> `diagnose`. Not + test-first feature work -> `tdd`. --- # Improve Codebase Architecture diff --git a/plugins/bin/.apm/skills/prototype/references/ui.md b/plugins/bin/.apm/skills/prototype/references/ui.md index 4de17de..9afb121 100644 --- a/plugins/bin/.apm/skills/prototype/references/ui.md +++ b/plugins/bin/.apm/skills/prototype/references/ui.md @@ -109,3 +109,4 @@ Don't leave variant components or the switcher lying around. They rot fast and c - **Variants that differ only in colour or copy.** That's a tweak, not a prototype. Real variants disagree about structure. - **Sharing too much code between variants.** A shared `
` is fine; a shared `` defeats the point. Each variant should be free to throw out the layout. - **Wiring variants to real mutations.** Read-only prototypes are fine. If a variant needs to mutate, point it at a stub — the question is "what should this look like", not "does the backend work". +- **Promoting the prototype directly to production.** The variant code was written under prototype constraints (no tests, minimal error handling). Rewrite it properly when you fold it in. diff --git a/plugins/bin/.apm/skills/research/README.md b/plugins/bin/.apm/skills/research/README.md index b98c00b..976cd2f 100644 --- a/plugins/bin/.apm/skills/research/README.md +++ b/plugins/bin/.apm/skills/research/README.md @@ -12,7 +12,7 @@ The frontmatter pins `model: sonnet` and a closed `allowed-tools` list. Notably ## 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. +Both reference files are read on condition, never on every run — `SKILL.md` inlines the minimum each step needs (the seven default topic areas at step 1, the four `sources.md` field names and the topic-file frontmatter keys at step 6) and sends the run to the reference only for what it does not carry. Those four field names are matched literally by the downstream provenance validator, so prose written in their place parses as nothing and the check passes having verified nothing — which is why they are inlined rather than deferred. ## Usage @@ -27,5 +27,5 @@ Name the topic and the output path — the skill will stop and ask if the path i | 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 | +| `references/topics.md` | Read at Step 1 only when what belongs in a default topic is unclear or a custom topic is needed: the per-topic coverage table and the custom-topic naming rule | +| `references/file-format.md` | Read at Step 6 only when the inlined field names do not settle the case: slug derivation, the Context7 slug and URL convention, and what belongs in a topic body | diff --git a/plugins/bin/.apm/skills/research/SKILL.md b/plugins/bin/.apm/skills/research/SKILL.md index 1779011..19fffee 100644 --- a/plugins/bin/.apm/skills/research/SKILL.md +++ b/plugins/bin/.apm/skills/research/SKILL.md @@ -30,7 +30,10 @@ model: sonnet Search for existing use of the topic — imports, config files, version pins, reference files already written — and narrow the research to what is missing: the version actually in use, the topics not yet documented. -Read `references/topics.md` before narrowing, for the default topic list. +The default topic areas are `overview`, `installation`, `configuration`, `cli-reference`, +`api-reference`, `examples` and `troubleshooting` — one file each, and only where content exists. +If what belongs in one of them is unclear, or the topic needs a file outside that set, read +`references/topics.md` for the per-topic coverage table and the custom-topic naming rule. ## Step 2 — Resolve against Context7 @@ -56,11 +59,20 @@ If nothing usable comes back, stop and report what was searched, then ask for st ## Step 6 — Write -Merge every set of notes, Context7 and web alike, by topic area. Read `references/file-format.md`, then write, in the output path: +Merge every set of notes, Context7 and web alike, by topic area, then write, in the output path: -- `.md` for each topic area that has content, default or custom -- `sources.md`, always, one section per source in the schema that file gives — URL, description, contributing files, and status — including sources that yielded nothing, marked `no content extracted` +- `.md` for each topic area that has content, default or custom. Frontmatter carries `topic:` (the filename without `.md`) and `source_keys:` (kebab-case slugs matching `sources.md`); the body is prose in `##` sections, with no inline URLs. +- `sources.md`, always, one `##` section per source — including sources that yielded nothing — with exactly these four fields: -Spell the `sources.md` field names exactly as `references/file-format.md` gives them. The downstream provenance validator matches them literally; prose in their place parses as nothing, and the check passes having verified nothing. + ```markdown + - **URL:** + - **Description:** + - **Contributing files:** + - **Status:** `extracted` | `no content extracted` + ``` + +Spell those four field names exactly as given. The downstream provenance validator matches them literally; prose in their place parses as nothing, and the check passes having verified nothing. + +Read `references/file-format.md` when the four fields above do not settle the case: what a slug should be, the `context7-` slug and `context7:` URL convention for a Context7 source, or what belongs in a topic body versus a verbatim copy of the source. If no topic area has content, write nothing at all, `sources.md` included, and report what was searched. diff --git a/plugins/bin/.apm/skills/tdd/SKILL.md b/plugins/bin/.apm/skills/tdd/SKILL.md index 7a98941..d4a97f6 100644 --- a/plugins/bin/.apm/skills/tdd/SKILL.md +++ b/plugins/bin/.apm/skills/tdd/SKILL.md @@ -1,6 +1,9 @@ --- name: tdd -description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development. +description: > + Use when the user wants a feature built or a bug fixed test-first, in a strict + red-green-refactor loop, one behaviour at a time. Not diagnosing an existing + bug -> `diagnose`. Not throwaway exploratory code -> `prototype`. --- # Test-Driven Development diff --git a/plugins/bin/.apm/skills/triage/SKILL.md b/plugins/bin/.apm/skills/triage/SKILL.md index 0254fae..d83ab5e 100644 --- a/plugins/bin/.apm/skills/triage/SKILL.md +++ b/plugins/bin/.apm/skills/triage/SKILL.md @@ -1,6 +1,9 @@ --- name: triage -description: Triage issues through a state machine driven by triage roles. Use when user wants to create an issue, triage issues, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow. +description: > + Use when the user wants an issue created, triaged, or moved through the + tracker's triage states, or an issue prepared for an AFK agent. Not debugging + the bug itself -> `diagnose`. Not fleshing out a design -> `grill-with-docs`. --- # Triage diff --git a/plugins/bin/.apm/skills/write-docs/SKILL.md b/plugins/bin/.apm/skills/write-docs/SKILL.md index 85289e9..309ec6c 100644 --- a/plugins/bin/.apm/skills/write-docs/SKILL.md +++ b/plugins/bin/.apm/skills/write-docs/SKILL.md @@ -1,6 +1,9 @@ --- name: write-docs -description: Write documentation for X, document this module, create docs for this feature. Use when the user wants to produce or update technical documentation derived from code, spec, or existing artifacts. Do NOT use when the user wants a PRD, ADR, decision doc, or skill file — those have dedicated skills. +description: > + Use when the user wants technical documentation produced or updated from code + or spec, every claim traced to a source. Not a PRD, ADR, or decision doc -> + `grill-with-docs`. Not an external tool researched from its docs -> `research`. version: "1.0" updated: 2026-05-17 when: invoked by explicit trigger ("write docs for X", "document this module", "create docs for this feature") or implicit request to produce technical documentation from code or spec diff --git a/plugins/bin/skills/grill-me/SKILL.md b/plugins/bin/skills/grill-me/SKILL.md index bd04394..1cc8ede 100644 --- a/plugins/bin/skills/grill-me/SKILL.md +++ b/plugins/bin/skills/grill-me/SKILL.md @@ -1,6 +1,10 @@ --- name: grill-me -description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me". +description: > + Use when the user says "grill me" or wants a plan or design stress-tested by + relentless interview — one question at a time, down each branch of the + decision tree. Not a plan to challenge against `CONTEXT.md` and ADRs -> + `grill-with-docs`. --- Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. diff --git a/plugins/bin/skills/grill-with-docs/SKILL.md b/plugins/bin/skills/grill-with-docs/SKILL.md index 6dad6ad..8610263 100644 --- a/plugins/bin/skills/grill-with-docs/SKILL.md +++ b/plugins/bin/skills/grill-with-docs/SKILL.md @@ -1,6 +1,9 @@ --- name: grill-with-docs -description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions. +description: > + Use when a plan should be stress-tested against the project's domain model — + the interview challenges terms against `CONTEXT.md` and writes decisions into + it and into ADRs as they land. Not a plain interview -> `grill-me`. --- diff --git a/plugins/bin/skills/improve-codebase-architecture/SKILL.md b/plugins/bin/skills/improve-codebase-architecture/SKILL.md index 22d02fb..6ec346b 100644 --- a/plugins/bin/skills/improve-codebase-architecture/SKILL.md +++ b/plugins/bin/skills/improve-codebase-architecture/SKILL.md @@ -1,6 +1,10 @@ --- name: improve-codebase-architecture -description: Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable. +description: > + Use when the user wants a codebase's architecture improved — deepening + opportunities that turn shallow modules into deep ones, informed by + `CONTEXT.md` and `docs/adr/`. Not debugging a failure -> `diagnose`. Not + test-first feature work -> `tdd`. --- # Improve Codebase Architecture diff --git a/plugins/bin/skills/prototype/references/ui.md b/plugins/bin/skills/prototype/references/ui.md index 4de17de..9afb121 100644 --- a/plugins/bin/skills/prototype/references/ui.md +++ b/plugins/bin/skills/prototype/references/ui.md @@ -109,3 +109,4 @@ Don't leave variant components or the switcher lying around. They rot fast and c - **Variants that differ only in colour or copy.** That's a tweak, not a prototype. Real variants disagree about structure. - **Sharing too much code between variants.** A shared `
` is fine; a shared `` defeats the point. Each variant should be free to throw out the layout. - **Wiring variants to real mutations.** Read-only prototypes are fine. If a variant needs to mutate, point it at a stub — the question is "what should this look like", not "does the backend work". +- **Promoting the prototype directly to production.** The variant code was written under prototype constraints (no tests, minimal error handling). Rewrite it properly when you fold it in. diff --git a/plugins/bin/skills/research/README.md b/plugins/bin/skills/research/README.md index b98c00b..976cd2f 100644 --- a/plugins/bin/skills/research/README.md +++ b/plugins/bin/skills/research/README.md @@ -12,7 +12,7 @@ The frontmatter pins `model: sonnet` and a closed `allowed-tools` list. Notably ## 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. +Both reference files are read on condition, never on every run — `SKILL.md` inlines the minimum each step needs (the seven default topic areas at step 1, the four `sources.md` field names and the topic-file frontmatter keys at step 6) and sends the run to the reference only for what it does not carry. Those four field names are matched literally by the downstream provenance validator, so prose written in their place parses as nothing and the check passes having verified nothing — which is why they are inlined rather than deferred. ## Usage @@ -27,5 +27,5 @@ Name the topic and the output path — the skill will stop and ask if the path i | 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 | +| `references/topics.md` | Read at Step 1 only when what belongs in a default topic is unclear or a custom topic is needed: the per-topic coverage table and the custom-topic naming rule | +| `references/file-format.md` | Read at Step 6 only when the inlined field names do not settle the case: slug derivation, the Context7 slug and URL convention, and what belongs in a topic body | diff --git a/plugins/bin/skills/research/SKILL.md b/plugins/bin/skills/research/SKILL.md index 1779011..19fffee 100644 --- a/plugins/bin/skills/research/SKILL.md +++ b/plugins/bin/skills/research/SKILL.md @@ -30,7 +30,10 @@ model: sonnet Search for existing use of the topic — imports, config files, version pins, reference files already written — and narrow the research to what is missing: the version actually in use, the topics not yet documented. -Read `references/topics.md` before narrowing, for the default topic list. +The default topic areas are `overview`, `installation`, `configuration`, `cli-reference`, +`api-reference`, `examples` and `troubleshooting` — one file each, and only where content exists. +If what belongs in one of them is unclear, or the topic needs a file outside that set, read +`references/topics.md` for the per-topic coverage table and the custom-topic naming rule. ## Step 2 — Resolve against Context7 @@ -56,11 +59,20 @@ If nothing usable comes back, stop and report what was searched, then ask for st ## Step 6 — Write -Merge every set of notes, Context7 and web alike, by topic area. Read `references/file-format.md`, then write, in the output path: +Merge every set of notes, Context7 and web alike, by topic area, then write, in the output path: -- `.md` for each topic area that has content, default or custom -- `sources.md`, always, one section per source in the schema that file gives — URL, description, contributing files, and status — including sources that yielded nothing, marked `no content extracted` +- `.md` for each topic area that has content, default or custom. Frontmatter carries `topic:` (the filename without `.md`) and `source_keys:` (kebab-case slugs matching `sources.md`); the body is prose in `##` sections, with no inline URLs. +- `sources.md`, always, one `##` section per source — including sources that yielded nothing — with exactly these four fields: -Spell the `sources.md` field names exactly as `references/file-format.md` gives them. The downstream provenance validator matches them literally; prose in their place parses as nothing, and the check passes having verified nothing. + ```markdown + - **URL:** + - **Description:** + - **Contributing files:** + - **Status:** `extracted` | `no content extracted` + ``` + +Spell those four field names exactly as given. The downstream provenance validator matches them literally; prose in their place parses as nothing, and the check passes having verified nothing. + +Read `references/file-format.md` when the four fields above do not settle the case: what a slug should be, the `context7-` slug and `context7:` URL convention for a Context7 source, or what belongs in a topic body versus a verbatim copy of the source. If no topic area has content, write nothing at all, `sources.md` included, and report what was searched. diff --git a/plugins/bin/skills/tdd/SKILL.md b/plugins/bin/skills/tdd/SKILL.md index 7a98941..d4a97f6 100644 --- a/plugins/bin/skills/tdd/SKILL.md +++ b/plugins/bin/skills/tdd/SKILL.md @@ -1,6 +1,9 @@ --- name: tdd -description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development. +description: > + Use when the user wants a feature built or a bug fixed test-first, in a strict + red-green-refactor loop, one behaviour at a time. Not diagnosing an existing + bug -> `diagnose`. Not throwaway exploratory code -> `prototype`. --- # Test-Driven Development diff --git a/plugins/bin/skills/triage/SKILL.md b/plugins/bin/skills/triage/SKILL.md index 0254fae..d83ab5e 100644 --- a/plugins/bin/skills/triage/SKILL.md +++ b/plugins/bin/skills/triage/SKILL.md @@ -1,6 +1,9 @@ --- name: triage -description: Triage issues through a state machine driven by triage roles. Use when user wants to create an issue, triage issues, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow. +description: > + Use when the user wants an issue created, triaged, or moved through the + tracker's triage states, or an issue prepared for an AFK agent. Not debugging + the bug itself -> `diagnose`. Not fleshing out a design -> `grill-with-docs`. --- # Triage diff --git a/plugins/bin/skills/write-docs/SKILL.md b/plugins/bin/skills/write-docs/SKILL.md index 85289e9..309ec6c 100644 --- a/plugins/bin/skills/write-docs/SKILL.md +++ b/plugins/bin/skills/write-docs/SKILL.md @@ -1,6 +1,9 @@ --- name: write-docs -description: Write documentation for X, document this module, create docs for this feature. Use when the user wants to produce or update technical documentation derived from code, spec, or existing artifacts. Do NOT use when the user wants a PRD, ADR, decision doc, or skill file — those have dedicated skills. +description: > + Use when the user wants technical documentation produced or updated from code + or spec, every claim traced to a source. Not a PRD, ADR, or decision doc -> + `grill-with-docs`. Not an external tool researched from its docs -> `research`. version: "1.0" updated: 2026-05-17 when: invoked by explicit trigger ("write docs for X", "document this module", "create docs for this feature") or implicit request to produce technical documentation from code or spec