diff --git a/plugins/bin/.apm/skills/grill-with-docs/README.md b/plugins/bin/.apm/skills/grill-with-docs/README.md index 11b544b..1ea62ce 100644 --- a/plugins/bin/.apm/skills/grill-with-docs/README.md +++ b/plugins/bin/.apm/skills/grill-with-docs/README.md @@ -4,10 +4,11 @@ The grilling interview, run against the project's domain model — and writing d ## 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: +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 five 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?"). +- **Stress-tests domain relationships with concrete scenarios**, inventing edge cases that force the user to be precise about where one concept ends and the next begins. - **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. @@ -31,6 +32,6 @@ Describe the plan or design. Expect questions one at a time, each with a recomme | 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 | +| `SKILL.md` | The interview instruction plus the domain-awareness rules: file layout discovery, the five 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 | diff --git a/plugins/bin/.apm/skills/improve-codebase-architecture/SKILL.md b/plugins/bin/.apm/skills/improve-codebase-architecture/SKILL.md index 6ec346b..750876a 100644 --- a/plugins/bin/.apm/skills/improve-codebase-architecture/SKILL.md +++ b/plugins/bin/.apm/skills/improve-codebase-architecture/SKILL.md @@ -1,10 +1,11 @@ --- name: improve-codebase-architecture 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`. + Use when the user wants to improve architecture, find refactoring + opportunities, consolidate tightly-coupled modules, or make a codebase more + testable and AI-navigable — deepening opportunities that turn shallow modules + into deep ones, informed by `CONTEXT.md` and `docs/adr/`. Not debugging a + failure -> `diagnose`. --- # Improve Codebase Architecture @@ -13,7 +14,7 @@ Surface architectural friction and propose **deepening opportunities** — refac ## Glossary -Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." Full definitions in [LANGUAGE.md](LANGUAGE.md). +Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." - **Module** — anything with an interface and an implementation (function, class, package, slice). - **Interface** — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature. @@ -24,12 +25,14 @@ Use these terms exactly in every suggestion. Consistent language is the point - **Leverage** — what callers get from depth. - **Locality** — what maintainers get from depth: change, bugs, knowledge concentrated in one place. -Key principles (see [LANGUAGE.md](LANGUAGE.md) for the full list): +Key principles: - **Deletion test**: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep. - **The interface is the test surface.** - **One adapter = hypothetical seam. Two adapters = real seam.** +If a term or principle above is ambiguous in the case in front of you, or you need the definitions and the principles the two lists leave out, read `LANGUAGE.md`. + This skill is _informed_ by the project's domain model. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate. ## Process @@ -57,7 +60,7 @@ Present a numbered list of deepening opportunities. For each candidate: - **Solution** — plain English description of what would change - **Benefits** — explained in terms of locality and leverage, and also in how tests would improve -**Use CONTEXT.md vocabulary for the domain, and [LANGUAGE.md](LANGUAGE.md) vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service." +**Use CONTEXT.md vocabulary for the domain, and the architecture glossary above for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service." **ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly (e.g. _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids. @@ -72,4 +75,4 @@ Side effects happen inline as decisions crystallize: - **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `grill-with-docs`, in the format `grill-with-docs`'s `CONTEXT-FORMAT.md` defines. Create the file lazily if it doesn't exist. - **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there. - **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See `grill-with-docs`'s `ADR-FORMAT.md`. -- **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md). +- **Want to explore alternative interfaces for the deepened module?** Read `INTERFACE-DESIGN.md`. diff --git a/plugins/bin/.apm/skills/prototype/references/logic.md b/plugins/bin/.apm/skills/prototype/references/logic.md index 2945853..2376fd1 100644 --- a/plugins/bin/.apm/skills/prototype/references/logic.md +++ b/plugins/bin/.apm/skills/prototype/references/logic.md @@ -72,5 +72,8 @@ When the prototype has done its job, the answer to the question is the only thin ## Anti-patterns +- **Don't add tests.** A prototype that needs tests is no longer a prototype. +- **Don't wire it to the real database.** Use an in-memory store unless the question is specifically about persistence. +- **Don't generalise.** No "what if we wanted to support X later." The prototype answers one question. - **Don't blur the logic and the TUI together.** If the reducer / state machine references `console.log`, prompts, or terminal escape codes, it's no longer portable. Keep the TUI as a thin shell over a pure module. - **Don't ship the TUI shell into production.** The shell is optimised for being driven by hand from a terminal. The logic module behind it is the bit worth keeping. diff --git a/plugins/bin/.apm/skills/tdd/SKILL.md b/plugins/bin/.apm/skills/tdd/SKILL.md index d4a97f6..ad3be57 100644 --- a/plugins/bin/.apm/skills/tdd/SKILL.md +++ b/plugins/bin/.apm/skills/tdd/SKILL.md @@ -16,7 +16,7 @@ description: > **Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior. -See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines. +If you need worked examples of the difference — a behaviour-level test beside the implementation-coupled version of the same check — read `tests.md`. If a test needs a collaborator faked, read `mocking.md` before reaching for a mock. ## Anti-Pattern: Horizontal Slices diff --git a/plugins/bin/.apm/skills/triage/README.md b/plugins/bin/.apm/skills/triage/README.md index 3f21e51..d9f5da2 100644 --- a/plugins/bin/.apm/skills/triage/README.md +++ b/plugins/bin/.apm/skills/triage/README.md @@ -12,7 +12,7 @@ A run does one of three things depending on what the maintainer asks for: - **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. +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 — each is resolved against the tracker's live label set before it is applied, and a name with no counterpart there is reported to the maintainer as a gap rather than guessed at. ## Composition diff --git a/plugins/bin/.apm/skills/write-docs/SKILL.md b/plugins/bin/.apm/skills/write-docs/SKILL.md index 309ec6c..30ea51d 100644 --- a/plugins/bin/.apm/skills/write-docs/SKILL.md +++ b/plugins/bin/.apm/skills/write-docs/SKILL.md @@ -2,8 +2,10 @@ name: write-docs 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`. + or spec, every claim traced to a source — "write docs for X", "document this + module", "create docs for this feature", "write a README for this". Not an ADR + or other decision record -> `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 @@ -38,7 +40,8 @@ You are a technical writer that produces documentation by reading code and spec - User says "write docs for X", "document this", "create docs for this feature", "write a README for this" **Do not use when:** -- User wants a PRD, decision doc, or architecture proposal → `grill-me` or `grill-with-docs` +- User wants an ADR, decision doc, or architecture proposal → `grill-with-docs`, which writes ADRs +- User wants a PRD → no skill in this set produces one; say so rather than redirecting - User wants to document a skill file (skill files are self-describing) - User wants marketing or blog copy - Documentation requires tacit organisational knowledge that cannot be read from code or spec @@ -91,7 +94,7 @@ You are a technical writer that produces documentation by reading code and spec - Stage skipped without a logged reason → flag and require the one-sentence log before continuing - Code behaviour is undocumentable (internal implementation detail, no public spec) → note as out-of-scope in the doc; do not invent an explanation - Reader Testing sub-agent fails on multiple questions → surface the failures, return to step 4; do not mark complete -- Requested output is a PRD, decision doc, or architecture proposal → redirect to `grill-me` or `grill-with-docs` +- Requested output is an ADR, decision doc, or architecture proposal → redirect to `grill-with-docs`; for a PRD, say no skill here produces one instead of redirecting ## Self-check diff --git a/plugins/bin/skills/grill-with-docs/README.md b/plugins/bin/skills/grill-with-docs/README.md index 11b544b..1ea62ce 100644 --- a/plugins/bin/skills/grill-with-docs/README.md +++ b/plugins/bin/skills/grill-with-docs/README.md @@ -4,10 +4,11 @@ The grilling interview, run against the project's domain model — and writing d ## 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: +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 five 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?"). +- **Stress-tests domain relationships with concrete scenarios**, inventing edge cases that force the user to be precise about where one concept ends and the next begins. - **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. @@ -31,6 +32,6 @@ Describe the plan or design. Expect questions one at a time, each with a recomme | 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 | +| `SKILL.md` | The interview instruction plus the domain-awareness rules: file layout discovery, the five 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 | diff --git a/plugins/bin/skills/improve-codebase-architecture/SKILL.md b/plugins/bin/skills/improve-codebase-architecture/SKILL.md index 6ec346b..750876a 100644 --- a/plugins/bin/skills/improve-codebase-architecture/SKILL.md +++ b/plugins/bin/skills/improve-codebase-architecture/SKILL.md @@ -1,10 +1,11 @@ --- name: improve-codebase-architecture 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`. + Use when the user wants to improve architecture, find refactoring + opportunities, consolidate tightly-coupled modules, or make a codebase more + testable and AI-navigable — deepening opportunities that turn shallow modules + into deep ones, informed by `CONTEXT.md` and `docs/adr/`. Not debugging a + failure -> `diagnose`. --- # Improve Codebase Architecture @@ -13,7 +14,7 @@ Surface architectural friction and propose **deepening opportunities** — refac ## Glossary -Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." Full definitions in [LANGUAGE.md](LANGUAGE.md). +Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." - **Module** — anything with an interface and an implementation (function, class, package, slice). - **Interface** — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature. @@ -24,12 +25,14 @@ Use these terms exactly in every suggestion. Consistent language is the point - **Leverage** — what callers get from depth. - **Locality** — what maintainers get from depth: change, bugs, knowledge concentrated in one place. -Key principles (see [LANGUAGE.md](LANGUAGE.md) for the full list): +Key principles: - **Deletion test**: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep. - **The interface is the test surface.** - **One adapter = hypothetical seam. Two adapters = real seam.** +If a term or principle above is ambiguous in the case in front of you, or you need the definitions and the principles the two lists leave out, read `LANGUAGE.md`. + This skill is _informed_ by the project's domain model. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate. ## Process @@ -57,7 +60,7 @@ Present a numbered list of deepening opportunities. For each candidate: - **Solution** — plain English description of what would change - **Benefits** — explained in terms of locality and leverage, and also in how tests would improve -**Use CONTEXT.md vocabulary for the domain, and [LANGUAGE.md](LANGUAGE.md) vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service." +**Use CONTEXT.md vocabulary for the domain, and the architecture glossary above for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service." **ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly (e.g. _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids. @@ -72,4 +75,4 @@ Side effects happen inline as decisions crystallize: - **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `grill-with-docs`, in the format `grill-with-docs`'s `CONTEXT-FORMAT.md` defines. Create the file lazily if it doesn't exist. - **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there. - **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See `grill-with-docs`'s `ADR-FORMAT.md`. -- **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md). +- **Want to explore alternative interfaces for the deepened module?** Read `INTERFACE-DESIGN.md`. diff --git a/plugins/bin/skills/prototype/references/logic.md b/plugins/bin/skills/prototype/references/logic.md index 2945853..2376fd1 100644 --- a/plugins/bin/skills/prototype/references/logic.md +++ b/plugins/bin/skills/prototype/references/logic.md @@ -72,5 +72,8 @@ When the prototype has done its job, the answer to the question is the only thin ## Anti-patterns +- **Don't add tests.** A prototype that needs tests is no longer a prototype. +- **Don't wire it to the real database.** Use an in-memory store unless the question is specifically about persistence. +- **Don't generalise.** No "what if we wanted to support X later." The prototype answers one question. - **Don't blur the logic and the TUI together.** If the reducer / state machine references `console.log`, prompts, or terminal escape codes, it's no longer portable. Keep the TUI as a thin shell over a pure module. - **Don't ship the TUI shell into production.** The shell is optimised for being driven by hand from a terminal. The logic module behind it is the bit worth keeping. diff --git a/plugins/bin/skills/tdd/SKILL.md b/plugins/bin/skills/tdd/SKILL.md index d4a97f6..ad3be57 100644 --- a/plugins/bin/skills/tdd/SKILL.md +++ b/plugins/bin/skills/tdd/SKILL.md @@ -16,7 +16,7 @@ description: > **Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior. -See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines. +If you need worked examples of the difference — a behaviour-level test beside the implementation-coupled version of the same check — read `tests.md`. If a test needs a collaborator faked, read `mocking.md` before reaching for a mock. ## Anti-Pattern: Horizontal Slices diff --git a/plugins/bin/skills/triage/README.md b/plugins/bin/skills/triage/README.md index 3f21e51..d9f5da2 100644 --- a/plugins/bin/skills/triage/README.md +++ b/plugins/bin/skills/triage/README.md @@ -12,7 +12,7 @@ A run does one of three things depending on what the maintainer asks for: - **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. +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 — each is resolved against the tracker's live label set before it is applied, and a name with no counterpart there is reported to the maintainer as a gap rather than guessed at. ## Composition diff --git a/plugins/bin/skills/write-docs/SKILL.md b/plugins/bin/skills/write-docs/SKILL.md index 309ec6c..30ea51d 100644 --- a/plugins/bin/skills/write-docs/SKILL.md +++ b/plugins/bin/skills/write-docs/SKILL.md @@ -2,8 +2,10 @@ name: write-docs 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`. + or spec, every claim traced to a source — "write docs for X", "document this + module", "create docs for this feature", "write a README for this". Not an ADR + or other decision record -> `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 @@ -38,7 +40,8 @@ You are a technical writer that produces documentation by reading code and spec - User says "write docs for X", "document this", "create docs for this feature", "write a README for this" **Do not use when:** -- User wants a PRD, decision doc, or architecture proposal → `grill-me` or `grill-with-docs` +- User wants an ADR, decision doc, or architecture proposal → `grill-with-docs`, which writes ADRs +- User wants a PRD → no skill in this set produces one; say so rather than redirecting - User wants to document a skill file (skill files are self-describing) - User wants marketing or blog copy - Documentation requires tacit organisational knowledge that cannot be read from code or spec @@ -91,7 +94,7 @@ You are a technical writer that produces documentation by reading code and spec - Stage skipped without a logged reason → flag and require the one-sentence log before continuing - Code behaviour is undocumentable (internal implementation detail, no public spec) → note as out-of-scope in the doc; do not invent an explanation - Reader Testing sub-agent fails on multiple questions → surface the failures, return to step 4; do not mark complete -- Requested output is a PRD, decision doc, or architecture proposal → redirect to `grill-me` or `grill-with-docs` +- Requested output is an ADR, decision doc, or architecture proposal → redirect to `grill-with-docs`; for a PRD, say no skill here produces one instead of redirecting ## Self-check