From 4f49b2a24994e478374697e7e79d2804d9c7f12e Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Wed, 9 Sep 2026 19:59:02 +0000 Subject: [PATCH 1/2] refactor(bin): move non-spec root files into references/ across four skills grill-with-docs, improve-codebase-architecture, tdd, and triage kept non-spec markdown files at their skill root, in violation of skill-audit's file-structure.md rule (only SKILL.md/README.md belong at the root; everything else lives in scripts/, references/, assets/ or tests/). A root-level file is invisible to the ADR-0020 dangling-reference gate, which only resolves unqualified `references/...` pointers. - Moved and renamed to lowercase-kebab-case under references/: grill-with-docs (ADR-FORMAT.md, CONTEXT-FORMAT.md), improve-codebase-architecture (DEEPENING.md, INTERFACE-DESIGN.md, LANGUAGE.md), tdd (five files, casing was already fine), triage (AGENT-BRIEF.md, OUT-OF-SCOPE.md). - Updated every in-skill link to the new references/ paths, including link text that still showed the old uppercase filenames. - Fixed improve-codebase-architecture/SKILL.md's cross-skill citation of grill-with-docs's two files to the sanctioned possessive form with the references/ segment included. - Updated all four skills' README.md file tables to match. - Regenerated the flat content mirror via scripts/sync-plugin-content.sh --all. Fixes #122. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01PDj6F7SPXzh3FtPN78dZ88 --- plugins/bin/.apm/skills/grill-with-docs/README.md | 4 ++-- plugins/bin/.apm/skills/grill-with-docs/SKILL.md | 4 ++-- .../{ADR-FORMAT.md => references/adr-format.md} | 0 .../context-format.md} | 0 .../skills/improve-codebase-architecture/README.md | 6 +++--- .../.apm/skills/improve-codebase-architecture/SKILL.md | 8 ++++---- .../{DEEPENING.md => references/deepening.md} | 2 +- .../interface-design.md} | 10 +++++----- .../{LANGUAGE.md => references/language.md} | 0 plugins/bin/.apm/skills/tdd/README.md | 10 +++++----- plugins/bin/.apm/skills/tdd/SKILL.md | 8 ++++---- .../.apm/skills/tdd/{ => references}/deep-modules.md | 0 .../skills/tdd/{ => references}/interface-design.md | 0 .../bin/.apm/skills/tdd/{ => references}/mocking.md | 0 .../.apm/skills/tdd/{ => references}/refactoring.md | 0 plugins/bin/.apm/skills/tdd/{ => references}/tests.md | 0 plugins/bin/.apm/skills/triage/README.md | 4 ++-- plugins/bin/.apm/skills/triage/SKILL.md | 8 ++++---- .../{AGENT-BRIEF.md => references/agent-brief.md} | 0 .../{OUT-OF-SCOPE.md => references/out-of-scope.md} | 0 plugins/bin/skills/grill-with-docs/README.md | 4 ++-- plugins/bin/skills/grill-with-docs/SKILL.md | 4 ++-- .../{ADR-FORMAT.md => references/adr-format.md} | 0 .../context-format.md} | 0 .../bin/skills/improve-codebase-architecture/README.md | 6 +++--- .../bin/skills/improve-codebase-architecture/SKILL.md | 8 ++++---- .../{DEEPENING.md => references/deepening.md} | 2 +- .../interface-design.md} | 10 +++++----- .../{LANGUAGE.md => references/language.md} | 0 plugins/bin/skills/tdd/README.md | 10 +++++----- plugins/bin/skills/tdd/SKILL.md | 8 ++++---- .../bin/skills/tdd/{ => references}/deep-modules.md | 0 .../skills/tdd/{ => references}/interface-design.md | 0 plugins/bin/skills/tdd/{ => references}/mocking.md | 0 plugins/bin/skills/tdd/{ => references}/refactoring.md | 0 plugins/bin/skills/tdd/{ => references}/tests.md | 0 plugins/bin/skills/triage/README.md | 4 ++-- plugins/bin/skills/triage/SKILL.md | 8 ++++---- .../{AGENT-BRIEF.md => references/agent-brief.md} | 0 .../{OUT-OF-SCOPE.md => references/out-of-scope.md} | 0 40 files changed, 64 insertions(+), 64 deletions(-) rename plugins/bin/.apm/skills/grill-with-docs/{ADR-FORMAT.md => references/adr-format.md} (100%) rename plugins/bin/.apm/skills/grill-with-docs/{CONTEXT-FORMAT.md => references/context-format.md} (100%) rename plugins/bin/.apm/skills/improve-codebase-architecture/{DEEPENING.md => references/deepening.md} (97%) rename plugins/bin/.apm/skills/improve-codebase-architecture/{INTERFACE-DESIGN.md => references/interface-design.md} (86%) rename plugins/bin/.apm/skills/improve-codebase-architecture/{LANGUAGE.md => references/language.md} (100%) rename plugins/bin/.apm/skills/tdd/{ => references}/deep-modules.md (100%) rename plugins/bin/.apm/skills/tdd/{ => references}/interface-design.md (100%) rename plugins/bin/.apm/skills/tdd/{ => references}/mocking.md (100%) rename plugins/bin/.apm/skills/tdd/{ => references}/refactoring.md (100%) rename plugins/bin/.apm/skills/tdd/{ => references}/tests.md (100%) rename plugins/bin/.apm/skills/triage/{AGENT-BRIEF.md => references/agent-brief.md} (100%) rename plugins/bin/.apm/skills/triage/{OUT-OF-SCOPE.md => references/out-of-scope.md} (100%) rename plugins/bin/skills/grill-with-docs/{ADR-FORMAT.md => references/adr-format.md} (100%) rename plugins/bin/skills/grill-with-docs/{CONTEXT-FORMAT.md => references/context-format.md} (100%) rename plugins/bin/skills/improve-codebase-architecture/{DEEPENING.md => references/deepening.md} (97%) rename plugins/bin/skills/improve-codebase-architecture/{INTERFACE-DESIGN.md => references/interface-design.md} (86%) rename plugins/bin/skills/improve-codebase-architecture/{LANGUAGE.md => references/language.md} (100%) rename plugins/bin/skills/tdd/{ => references}/deep-modules.md (100%) rename plugins/bin/skills/tdd/{ => references}/interface-design.md (100%) rename plugins/bin/skills/tdd/{ => references}/mocking.md (100%) rename plugins/bin/skills/tdd/{ => references}/refactoring.md (100%) rename plugins/bin/skills/tdd/{ => references}/tests.md (100%) rename plugins/bin/skills/triage/{AGENT-BRIEF.md => references/agent-brief.md} (100%) rename plugins/bin/skills/triage/{OUT-OF-SCOPE.md => references/out-of-scope.md} (100%) diff --git a/plugins/bin/.apm/skills/grill-with-docs/README.md b/plugins/bin/.apm/skills/grill-with-docs/README.md index 1ea62ce..679eecb 100644 --- a/plugins/bin/.apm/skills/grill-with-docs/README.md +++ b/plugins/bin/.apm/skills/grill-with-docs/README.md @@ -33,5 +33,5 @@ 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 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 | +| `references/context-format.md` | Cited when a term is resolved: the structure of a `CONTEXT.md` and how to write a Language entry | +| `references/adr-format.md` | Cited when an ADR is offered: `docs/adr/` naming, sequential numbering, and the ADR template | diff --git a/plugins/bin/.apm/skills/grill-with-docs/SKILL.md b/plugins/bin/.apm/skills/grill-with-docs/SKILL.md index cc93aef..30df96e 100644 --- a/plugins/bin/.apm/skills/grill-with-docs/SKILL.md +++ b/plugins/bin/.apm/skills/grill-with-docs/SKILL.md @@ -76,7 +76,7 @@ When the user states how something works, check whether the code agrees. If you ### Update CONTEXT.md inline -When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md). +When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [context-format.md](references/context-format.md). Don't couple `CONTEXT.md` to implementation details. Only include terms that are meaningful to domain experts. @@ -88,6 +88,6 @@ Only offer to create an ADR when all three are true: 2. **Surprising without context** — a future reader will wonder "why did they do it this way?" 3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons -If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md). +If any of the three is missing, skip the ADR. Use the format in [adr-format.md](references/adr-format.md). diff --git a/plugins/bin/.apm/skills/grill-with-docs/ADR-FORMAT.md b/plugins/bin/.apm/skills/grill-with-docs/references/adr-format.md similarity index 100% rename from plugins/bin/.apm/skills/grill-with-docs/ADR-FORMAT.md rename to plugins/bin/.apm/skills/grill-with-docs/references/adr-format.md diff --git a/plugins/bin/.apm/skills/grill-with-docs/CONTEXT-FORMAT.md b/plugins/bin/.apm/skills/grill-with-docs/references/context-format.md similarity index 100% rename from plugins/bin/.apm/skills/grill-with-docs/CONTEXT-FORMAT.md rename to plugins/bin/.apm/skills/grill-with-docs/references/context-format.md diff --git a/plugins/bin/.apm/skills/improve-codebase-architecture/README.md b/plugins/bin/.apm/skills/improve-codebase-architecture/README.md index 509cad7..26966ea 100644 --- a/plugins/bin/.apm/skills/improve-codebase-architecture/README.md +++ b/plugins/bin/.apm/skills/improve-codebase-architecture/README.md @@ -31,6 +31,6 @@ Point at a codebase or an area of one. Expect a numbered candidate list and a "w | 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 | +| `references/language.md` | Cited throughout `SKILL.md`: full definitions of every term, the words each one replaces, and the full principle list | +| `references/interface-design.md` | 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 | +| `references/deepening.md` | Cited from `references/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 | diff --git a/plugins/bin/.apm/skills/improve-codebase-architecture/SKILL.md b/plugins/bin/.apm/skills/improve-codebase-architecture/SKILL.md index 48803ca..00793b8 100644 --- a/plugins/bin/.apm/skills/improve-codebase-architecture/SKILL.md +++ b/plugins/bin/.apm/skills/improve-codebase-architecture/SKILL.md @@ -33,7 +33,7 @@ Key principles: - **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`. +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 `references/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. @@ -74,7 +74,7 @@ Once the user picks a candidate, drop into a grilling conversation. Walk the des 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. +- **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 `references/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?** Read `INTERFACE-DESIGN.md`. +- **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 `references/adr-format.md`. +- **Want to explore alternative interfaces for the deepened module?** Read `references/interface-design.md`. diff --git a/plugins/bin/.apm/skills/improve-codebase-architecture/DEEPENING.md b/plugins/bin/.apm/skills/improve-codebase-architecture/references/deepening.md similarity index 97% rename from plugins/bin/.apm/skills/improve-codebase-architecture/DEEPENING.md rename to plugins/bin/.apm/skills/improve-codebase-architecture/references/deepening.md index ecaf5d7..d230fb3 100644 --- a/plugins/bin/.apm/skills/improve-codebase-architecture/DEEPENING.md +++ b/plugins/bin/.apm/skills/improve-codebase-architecture/references/deepening.md @@ -1,6 +1,6 @@ # Deepening -How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**. +How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [language.md](language.md) — **module**, **interface**, **seam**, **adapter**. ## Dependency categories diff --git a/plugins/bin/.apm/skills/improve-codebase-architecture/INTERFACE-DESIGN.md b/plugins/bin/.apm/skills/improve-codebase-architecture/references/interface-design.md similarity index 86% rename from plugins/bin/.apm/skills/improve-codebase-architecture/INTERFACE-DESIGN.md rename to plugins/bin/.apm/skills/improve-codebase-architecture/references/interface-design.md index 3197723..da04831 100644 --- a/plugins/bin/.apm/skills/improve-codebase-architecture/INTERFACE-DESIGN.md +++ b/plugins/bin/.apm/skills/improve-codebase-architecture/references/interface-design.md @@ -2,7 +2,7 @@ When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best. -Uses the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**, **leverage**. +Uses the vocabulary in [language.md](language.md) — **module**, **interface**, **seam**, **adapter**, **leverage**. ## Process @@ -11,7 +11,7 @@ Uses the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate: - The constraints any new interface would need to satisfy -- The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](DEEPENING.md)) +- The dependencies it would rely on, and which category they fall into (see [deepening.md](deepening.md)) - A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel. @@ -20,21 +20,21 @@ Show this to the user, then immediately proceed to Step 2. The user reads and th Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module. -Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint: +Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [deepening.md](deepening.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint: - Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point." - Agent 2: "Maximise flexibility — support many use cases and extension." - Agent 3: "Optimise for the most common caller — make the default case trivial." - Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies." -Include both [LANGUAGE.md](LANGUAGE.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language. +Include both [language.md](language.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language. Each sub-agent outputs: 1. Interface (types, methods, params — plus invariants, ordering, error modes) 2. Usage example showing how callers use it 3. What the implementation hides behind the seam -4. Dependency strategy and adapters (see [DEEPENING.md](DEEPENING.md)) +4. Dependency strategy and adapters (see [deepening.md](deepening.md)) 5. Trade-offs — where leverage is high, where it's thin ### 3. Present and compare diff --git a/plugins/bin/.apm/skills/improve-codebase-architecture/LANGUAGE.md b/plugins/bin/.apm/skills/improve-codebase-architecture/references/language.md similarity index 100% rename from plugins/bin/.apm/skills/improve-codebase-architecture/LANGUAGE.md rename to plugins/bin/.apm/skills/improve-codebase-architecture/references/language.md diff --git a/plugins/bin/.apm/skills/tdd/README.md b/plugins/bin/.apm/skills/tdd/README.md index d3b62e6..09f7291 100644 --- a/plugins/bin/.apm/skills/tdd/README.md +++ b/plugins/bin/.apm/skills/tdd/README.md @@ -25,8 +25,8 @@ Describe the feature or bug. Expect the skill to ask what the public interface s | 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 | +| `references/tests.md` | Cited from Philosophy: worked good and bad test examples | +| `references/mocking.md` | Cited from Philosophy: mock at system boundaries only, and what not to mock | +| `references/deep-modules.md` | Cited from stage 1: what a deep module is (small interface, large implementation) and why it is the design to aim for | +| `references/interface-design.md` | Cited from stage 1: designing interfaces for testability, starting with accepting dependencies rather than creating them | +| `references/refactoring.md` | Cited from stage 4: the refactor-candidate checklist — duplication, long methods, shallow modules, feature envy, primitive obsession | diff --git a/plugins/bin/.apm/skills/tdd/SKILL.md b/plugins/bin/.apm/skills/tdd/SKILL.md index 736773a..e76a480 100644 --- a/plugins/bin/.apm/skills/tdd/SKILL.md +++ b/plugins/bin/.apm/skills/tdd/SKILL.md @@ -18,7 +18,7 @@ metadata: **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. -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. +If you need worked examples of the difference — a behaviour-level test beside the implementation-coupled version of the same check — read `references/tests.md`. If a test needs a collaborator faked, read `references/mocking.md` before reaching for a mock. ## Anti-Pattern: Horizontal Slices @@ -55,8 +55,8 @@ Before writing any code: - [ ] Confirm with user what interface changes are needed - [ ] Confirm with user which behaviors to test (prioritize) -- [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation) -- [ ] Design interfaces for [testability](interface-design.md) +- [ ] Identify opportunities for [deep modules](references/deep-modules.md) (small interface, deep implementation) +- [ ] Design interfaces for [testability](references/interface-design.md) - [ ] List the behaviors to test (not implementation steps) - [ ] Get user approval on the plan @@ -93,7 +93,7 @@ Rules: ### 4. Refactor -After all tests pass, look for [refactor candidates](refactoring.md): +After all tests pass, look for [refactor candidates](references/refactoring.md): - [ ] Extract duplication - [ ] Deepen modules (move complexity behind simple interfaces) diff --git a/plugins/bin/.apm/skills/tdd/deep-modules.md b/plugins/bin/.apm/skills/tdd/references/deep-modules.md similarity index 100% rename from plugins/bin/.apm/skills/tdd/deep-modules.md rename to plugins/bin/.apm/skills/tdd/references/deep-modules.md diff --git a/plugins/bin/.apm/skills/tdd/interface-design.md b/plugins/bin/.apm/skills/tdd/references/interface-design.md similarity index 100% rename from plugins/bin/.apm/skills/tdd/interface-design.md rename to plugins/bin/.apm/skills/tdd/references/interface-design.md diff --git a/plugins/bin/.apm/skills/tdd/mocking.md b/plugins/bin/.apm/skills/tdd/references/mocking.md similarity index 100% rename from plugins/bin/.apm/skills/tdd/mocking.md rename to plugins/bin/.apm/skills/tdd/references/mocking.md diff --git a/plugins/bin/.apm/skills/tdd/refactoring.md b/plugins/bin/.apm/skills/tdd/references/refactoring.md similarity index 100% rename from plugins/bin/.apm/skills/tdd/refactoring.md rename to plugins/bin/.apm/skills/tdd/references/refactoring.md diff --git a/plugins/bin/.apm/skills/tdd/tests.md b/plugins/bin/.apm/skills/tdd/references/tests.md similarity index 100% rename from plugins/bin/.apm/skills/tdd/tests.md rename to plugins/bin/.apm/skills/tdd/references/tests.md diff --git a/plugins/bin/.apm/skills/triage/README.md b/plugins/bin/.apm/skills/triage/README.md index d9f5da2..8c27ebb 100644 --- a/plugins/bin/.apm/skills/triage/README.md +++ b/plugins/bin/.apm/skills/triage/README.md @@ -31,5 +31,5 @@ Then describe what you want in natural language — "show me anything that needs | 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 | +| `references/agent-brief.md` | 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 | +| `references/out-of-scope.md` | 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 | diff --git a/plugins/bin/.apm/skills/triage/SKILL.md b/plugins/bin/.apm/skills/triage/SKILL.md index 548026e..7dc8f0e 100644 --- a/plugins/bin/.apm/skills/triage/SKILL.md +++ b/plugins/bin/.apm/skills/triage/SKILL.md @@ -20,8 +20,8 @@ Every comment or issue posted to the issue tracker during triage **must** start ## Reference docs -- [AGENT-BRIEF.md](AGENT-BRIEF.md) — how to write durable agent briefs -- [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md) — how the `.out-of-scope/` knowledge base works +- [agent-brief.md](references/agent-brief.md) — how to write durable agent briefs +- [out-of-scope.md](references/out-of-scope.md) — how the `.out-of-scope/` knowledge base works ## Roles @@ -74,11 +74,11 @@ Show counts and a one-line summary per issue. Let the maintainer pick. 4. **Grill (if needed).** If the issue needs fleshing out, run a `/grill-with-docs` session. 5. **Apply the outcome:** - - `ready-for-agent` — post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)). + - `ready-for-agent` — post an agent brief comment ([agent-brief.md](references/agent-brief.md)). - `ready-for-human` — same structure as an agent brief, but note why it can't be delegated (judgment calls, external access, design decisions, manual testing). - `needs-info` — post triage notes (template below). - `wontfix` (bug) — polite explanation, then close. - - `wontfix` (enhancement) — write to `.out-of-scope/`, link to it from a comment, then close ([OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)). + - `wontfix` (enhancement) — write to `.out-of-scope/`, link to it from a comment, then close ([out-of-scope.md](references/out-of-scope.md)). - `needs-triage` — apply the role. Optional comment if there's partial progress. ## Quick state override diff --git a/plugins/bin/.apm/skills/triage/AGENT-BRIEF.md b/plugins/bin/.apm/skills/triage/references/agent-brief.md similarity index 100% rename from plugins/bin/.apm/skills/triage/AGENT-BRIEF.md rename to plugins/bin/.apm/skills/triage/references/agent-brief.md diff --git a/plugins/bin/.apm/skills/triage/OUT-OF-SCOPE.md b/plugins/bin/.apm/skills/triage/references/out-of-scope.md similarity index 100% rename from plugins/bin/.apm/skills/triage/OUT-OF-SCOPE.md rename to plugins/bin/.apm/skills/triage/references/out-of-scope.md diff --git a/plugins/bin/skills/grill-with-docs/README.md b/plugins/bin/skills/grill-with-docs/README.md index 1ea62ce..679eecb 100644 --- a/plugins/bin/skills/grill-with-docs/README.md +++ b/plugins/bin/skills/grill-with-docs/README.md @@ -33,5 +33,5 @@ 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 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 | +| `references/context-format.md` | Cited when a term is resolved: the structure of a `CONTEXT.md` and how to write a Language entry | +| `references/adr-format.md` | Cited when an ADR is offered: `docs/adr/` naming, sequential numbering, and the ADR template | diff --git a/plugins/bin/skills/grill-with-docs/SKILL.md b/plugins/bin/skills/grill-with-docs/SKILL.md index cc93aef..30df96e 100644 --- a/plugins/bin/skills/grill-with-docs/SKILL.md +++ b/plugins/bin/skills/grill-with-docs/SKILL.md @@ -76,7 +76,7 @@ When the user states how something works, check whether the code agrees. If you ### Update CONTEXT.md inline -When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md). +When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [context-format.md](references/context-format.md). Don't couple `CONTEXT.md` to implementation details. Only include terms that are meaningful to domain experts. @@ -88,6 +88,6 @@ Only offer to create an ADR when all three are true: 2. **Surprising without context** — a future reader will wonder "why did they do it this way?" 3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons -If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md). +If any of the three is missing, skip the ADR. Use the format in [adr-format.md](references/adr-format.md). diff --git a/plugins/bin/skills/grill-with-docs/ADR-FORMAT.md b/plugins/bin/skills/grill-with-docs/references/adr-format.md similarity index 100% rename from plugins/bin/skills/grill-with-docs/ADR-FORMAT.md rename to plugins/bin/skills/grill-with-docs/references/adr-format.md diff --git a/plugins/bin/skills/grill-with-docs/CONTEXT-FORMAT.md b/plugins/bin/skills/grill-with-docs/references/context-format.md similarity index 100% rename from plugins/bin/skills/grill-with-docs/CONTEXT-FORMAT.md rename to plugins/bin/skills/grill-with-docs/references/context-format.md diff --git a/plugins/bin/skills/improve-codebase-architecture/README.md b/plugins/bin/skills/improve-codebase-architecture/README.md index 509cad7..26966ea 100644 --- a/plugins/bin/skills/improve-codebase-architecture/README.md +++ b/plugins/bin/skills/improve-codebase-architecture/README.md @@ -31,6 +31,6 @@ Point at a codebase or an area of one. Expect a numbered candidate list and a "w | 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 | +| `references/language.md` | Cited throughout `SKILL.md`: full definitions of every term, the words each one replaces, and the full principle list | +| `references/interface-design.md` | 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 | +| `references/deepening.md` | Cited from `references/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 | diff --git a/plugins/bin/skills/improve-codebase-architecture/SKILL.md b/plugins/bin/skills/improve-codebase-architecture/SKILL.md index 48803ca..00793b8 100644 --- a/plugins/bin/skills/improve-codebase-architecture/SKILL.md +++ b/plugins/bin/skills/improve-codebase-architecture/SKILL.md @@ -33,7 +33,7 @@ Key principles: - **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`. +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 `references/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. @@ -74,7 +74,7 @@ Once the user picks a candidate, drop into a grilling conversation. Walk the des 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. +- **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 `references/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?** Read `INTERFACE-DESIGN.md`. +- **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 `references/adr-format.md`. +- **Want to explore alternative interfaces for the deepened module?** Read `references/interface-design.md`. diff --git a/plugins/bin/skills/improve-codebase-architecture/DEEPENING.md b/plugins/bin/skills/improve-codebase-architecture/references/deepening.md similarity index 97% rename from plugins/bin/skills/improve-codebase-architecture/DEEPENING.md rename to plugins/bin/skills/improve-codebase-architecture/references/deepening.md index ecaf5d7..d230fb3 100644 --- a/plugins/bin/skills/improve-codebase-architecture/DEEPENING.md +++ b/plugins/bin/skills/improve-codebase-architecture/references/deepening.md @@ -1,6 +1,6 @@ # Deepening -How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**. +How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [language.md](language.md) — **module**, **interface**, **seam**, **adapter**. ## Dependency categories diff --git a/plugins/bin/skills/improve-codebase-architecture/INTERFACE-DESIGN.md b/plugins/bin/skills/improve-codebase-architecture/references/interface-design.md similarity index 86% rename from plugins/bin/skills/improve-codebase-architecture/INTERFACE-DESIGN.md rename to plugins/bin/skills/improve-codebase-architecture/references/interface-design.md index 3197723..da04831 100644 --- a/plugins/bin/skills/improve-codebase-architecture/INTERFACE-DESIGN.md +++ b/plugins/bin/skills/improve-codebase-architecture/references/interface-design.md @@ -2,7 +2,7 @@ When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best. -Uses the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**, **leverage**. +Uses the vocabulary in [language.md](language.md) — **module**, **interface**, **seam**, **adapter**, **leverage**. ## Process @@ -11,7 +11,7 @@ Uses the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate: - The constraints any new interface would need to satisfy -- The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](DEEPENING.md)) +- The dependencies it would rely on, and which category they fall into (see [deepening.md](deepening.md)) - A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel. @@ -20,21 +20,21 @@ Show this to the user, then immediately proceed to Step 2. The user reads and th Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module. -Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint: +Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [deepening.md](deepening.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint: - Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point." - Agent 2: "Maximise flexibility — support many use cases and extension." - Agent 3: "Optimise for the most common caller — make the default case trivial." - Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies." -Include both [LANGUAGE.md](LANGUAGE.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language. +Include both [language.md](language.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language. Each sub-agent outputs: 1. Interface (types, methods, params — plus invariants, ordering, error modes) 2. Usage example showing how callers use it 3. What the implementation hides behind the seam -4. Dependency strategy and adapters (see [DEEPENING.md](DEEPENING.md)) +4. Dependency strategy and adapters (see [deepening.md](deepening.md)) 5. Trade-offs — where leverage is high, where it's thin ### 3. Present and compare diff --git a/plugins/bin/skills/improve-codebase-architecture/LANGUAGE.md b/plugins/bin/skills/improve-codebase-architecture/references/language.md similarity index 100% rename from plugins/bin/skills/improve-codebase-architecture/LANGUAGE.md rename to plugins/bin/skills/improve-codebase-architecture/references/language.md diff --git a/plugins/bin/skills/tdd/README.md b/plugins/bin/skills/tdd/README.md index d3b62e6..09f7291 100644 --- a/plugins/bin/skills/tdd/README.md +++ b/plugins/bin/skills/tdd/README.md @@ -25,8 +25,8 @@ Describe the feature or bug. Expect the skill to ask what the public interface s | 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 | +| `references/tests.md` | Cited from Philosophy: worked good and bad test examples | +| `references/mocking.md` | Cited from Philosophy: mock at system boundaries only, and what not to mock | +| `references/deep-modules.md` | Cited from stage 1: what a deep module is (small interface, large implementation) and why it is the design to aim for | +| `references/interface-design.md` | Cited from stage 1: designing interfaces for testability, starting with accepting dependencies rather than creating them | +| `references/refactoring.md` | Cited from stage 4: the refactor-candidate checklist — duplication, long methods, shallow modules, feature envy, primitive obsession | diff --git a/plugins/bin/skills/tdd/SKILL.md b/plugins/bin/skills/tdd/SKILL.md index 736773a..e76a480 100644 --- a/plugins/bin/skills/tdd/SKILL.md +++ b/plugins/bin/skills/tdd/SKILL.md @@ -18,7 +18,7 @@ metadata: **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. -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. +If you need worked examples of the difference — a behaviour-level test beside the implementation-coupled version of the same check — read `references/tests.md`. If a test needs a collaborator faked, read `references/mocking.md` before reaching for a mock. ## Anti-Pattern: Horizontal Slices @@ -55,8 +55,8 @@ Before writing any code: - [ ] Confirm with user what interface changes are needed - [ ] Confirm with user which behaviors to test (prioritize) -- [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation) -- [ ] Design interfaces for [testability](interface-design.md) +- [ ] Identify opportunities for [deep modules](references/deep-modules.md) (small interface, deep implementation) +- [ ] Design interfaces for [testability](references/interface-design.md) - [ ] List the behaviors to test (not implementation steps) - [ ] Get user approval on the plan @@ -93,7 +93,7 @@ Rules: ### 4. Refactor -After all tests pass, look for [refactor candidates](refactoring.md): +After all tests pass, look for [refactor candidates](references/refactoring.md): - [ ] Extract duplication - [ ] Deepen modules (move complexity behind simple interfaces) diff --git a/plugins/bin/skills/tdd/deep-modules.md b/plugins/bin/skills/tdd/references/deep-modules.md similarity index 100% rename from plugins/bin/skills/tdd/deep-modules.md rename to plugins/bin/skills/tdd/references/deep-modules.md diff --git a/plugins/bin/skills/tdd/interface-design.md b/plugins/bin/skills/tdd/references/interface-design.md similarity index 100% rename from plugins/bin/skills/tdd/interface-design.md rename to plugins/bin/skills/tdd/references/interface-design.md diff --git a/plugins/bin/skills/tdd/mocking.md b/plugins/bin/skills/tdd/references/mocking.md similarity index 100% rename from plugins/bin/skills/tdd/mocking.md rename to plugins/bin/skills/tdd/references/mocking.md diff --git a/plugins/bin/skills/tdd/refactoring.md b/plugins/bin/skills/tdd/references/refactoring.md similarity index 100% rename from plugins/bin/skills/tdd/refactoring.md rename to plugins/bin/skills/tdd/references/refactoring.md diff --git a/plugins/bin/skills/tdd/tests.md b/plugins/bin/skills/tdd/references/tests.md similarity index 100% rename from plugins/bin/skills/tdd/tests.md rename to plugins/bin/skills/tdd/references/tests.md diff --git a/plugins/bin/skills/triage/README.md b/plugins/bin/skills/triage/README.md index d9f5da2..8c27ebb 100644 --- a/plugins/bin/skills/triage/README.md +++ b/plugins/bin/skills/triage/README.md @@ -31,5 +31,5 @@ Then describe what you want in natural language — "show me anything that needs | 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 | +| `references/agent-brief.md` | 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 | +| `references/out-of-scope.md` | 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 | diff --git a/plugins/bin/skills/triage/SKILL.md b/plugins/bin/skills/triage/SKILL.md index 548026e..7dc8f0e 100644 --- a/plugins/bin/skills/triage/SKILL.md +++ b/plugins/bin/skills/triage/SKILL.md @@ -20,8 +20,8 @@ Every comment or issue posted to the issue tracker during triage **must** start ## Reference docs -- [AGENT-BRIEF.md](AGENT-BRIEF.md) — how to write durable agent briefs -- [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md) — how the `.out-of-scope/` knowledge base works +- [agent-brief.md](references/agent-brief.md) — how to write durable agent briefs +- [out-of-scope.md](references/out-of-scope.md) — how the `.out-of-scope/` knowledge base works ## Roles @@ -74,11 +74,11 @@ Show counts and a one-line summary per issue. Let the maintainer pick. 4. **Grill (if needed).** If the issue needs fleshing out, run a `/grill-with-docs` session. 5. **Apply the outcome:** - - `ready-for-agent` — post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)). + - `ready-for-agent` — post an agent brief comment ([agent-brief.md](references/agent-brief.md)). - `ready-for-human` — same structure as an agent brief, but note why it can't be delegated (judgment calls, external access, design decisions, manual testing). - `needs-info` — post triage notes (template below). - `wontfix` (bug) — polite explanation, then close. - - `wontfix` (enhancement) — write to `.out-of-scope/`, link to it from a comment, then close ([OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)). + - `wontfix` (enhancement) — write to `.out-of-scope/`, link to it from a comment, then close ([out-of-scope.md](references/out-of-scope.md)). - `needs-triage` — apply the role. Optional comment if there's partial progress. ## Quick state override diff --git a/plugins/bin/skills/triage/AGENT-BRIEF.md b/plugins/bin/skills/triage/references/agent-brief.md similarity index 100% rename from plugins/bin/skills/triage/AGENT-BRIEF.md rename to plugins/bin/skills/triage/references/agent-brief.md diff --git a/plugins/bin/skills/triage/OUT-OF-SCOPE.md b/plugins/bin/skills/triage/references/out-of-scope.md similarity index 100% rename from plugins/bin/skills/triage/OUT-OF-SCOPE.md rename to plugins/bin/skills/triage/references/out-of-scope.md -- 2.43.0 From c75e4ef4f31aee313b00f608454803cb0dd2b84f Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Thu, 10 Sep 2026 19:12:16 +0000 Subject: [PATCH 2/2] fix(bin): repoint improve-codebase-architecture README's LANGUAGE.md mention PR #133 renamed the skill's root-level LANGUAGE.md to references/language.md but missed a prose mention (not a markdown link) in the overview paragraph. Fix both the .apm/ source and its generated flat mirror. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01PDj6F7SPXzh3FtPN78dZ88 --- plugins/bin/.apm/skills/improve-codebase-architecture/README.md | 2 +- plugins/bin/skills/improve-codebase-architecture/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/bin/.apm/skills/improve-codebase-architecture/README.md b/plugins/bin/.apm/skills/improve-codebase-architecture/README.md index 26966ea..93b6c05 100644 --- a/plugins/bin/.apm/skills/improve-codebase-architecture/README.md +++ b/plugins/bin/.apm/skills/improve-codebase-architecture/README.md @@ -10,7 +10,7 @@ Looks for places where a codebase is hard to understand, hard to test, or hard f 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". +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 `references/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. diff --git a/plugins/bin/skills/improve-codebase-architecture/README.md b/plugins/bin/skills/improve-codebase-architecture/README.md index 26966ea..93b6c05 100644 --- a/plugins/bin/skills/improve-codebase-architecture/README.md +++ b/plugins/bin/skills/improve-codebase-architecture/README.md @@ -10,7 +10,7 @@ Looks for places where a codebase is hard to understand, hard to test, or hard f 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". +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 `references/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. -- 2.43.0