diff --git a/plugins/design-buddy/.claude-plugin/plugin.json b/plugins/design-buddy/.claude-plugin/plugin.json index 021af6b..c698e39 100644 --- a/plugins/design-buddy/.claude-plugin/plugin.json +++ b/plugins/design-buddy/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "design-buddy", "displayName": "Design Buddy", - "version": "2.0.0", + "version": "2.1.0", "description": "A repo-agnostic design partner: adversarially debated designs (recon + mediated proposer-vs-adversary rounds, depth-scaled from bug fix to rearchitecture), evidence-grounded implementation plans, and a strict plan-review gate.", "author": { "name": "David Castillo", diff --git a/plugins/design-buddy/.codex-plugin/plugin.json b/plugins/design-buddy/.codex-plugin/plugin.json index 452d476..e09315c 100644 --- a/plugins/design-buddy/.codex-plugin/plugin.json +++ b/plugins/design-buddy/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "design-buddy", - "version": "2.0.0", + "version": "2.1.0", "description": "A repo-agnostic design partner: adversarially debated designs (recon + mediated proposer-vs-adversary rounds, depth-scaled from bug fix to rearchitecture), evidence-grounded implementation plans, and a strict plan-review gate.", "author": { "name": "David Castillo", diff --git a/plugins/design-buddy/.cursor-plugin/plugin.json b/plugins/design-buddy/.cursor-plugin/plugin.json index 021af6b..c698e39 100644 --- a/plugins/design-buddy/.cursor-plugin/plugin.json +++ b/plugins/design-buddy/.cursor-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "design-buddy", "displayName": "Design Buddy", - "version": "2.0.0", + "version": "2.1.0", "description": "A repo-agnostic design partner: adversarially debated designs (recon + mediated proposer-vs-adversary rounds, depth-scaled from bug fix to rearchitecture), evidence-grounded implementation plans, and a strict plan-review gate.", "author": { "name": "David Castillo", diff --git a/plugins/design-buddy/README.md b/plugins/design-buddy/README.md index c1ffbd4..dc65e99 100644 --- a/plugins/design-buddy/README.md +++ b/plugins/design-buddy/README.md @@ -94,10 +94,12 @@ The config file is committable, so a team shares one setting; gitignore it if yo `skills/*/reference/principles.md` ships the portable rule seed the adversary and reviewer cite: **Floor rules** `DF-1..6` (never invent paths/symbols; no silent deviation; single orchestrator writes; mediated debate; floor blocks approval; host hard rules are floor-equivalent) and -**Norms** `DN-1..6` (evidence-cited claims; reuse over rebuild; recorded gates; depth scales +**Norms** `DN-1..9` (evidence-cited claims; reuse over rebuild = DRY; recorded gates; depth scales with the change; plan steps immutable during execution; plans reviewed before execution — a -failed review blocks it). Your repo's own absolute rules — "never …", "must not …" in -CLAUDE.md/CONTRIBUTING/docs — are discovered during recon, quoted verbatim, and enforced like +failed review blocks it; right-sized design = YAGNI; sound structure = SOLID; and the +staff-engineer check that keeps SOLID/DRY/YAGNI subordinate to scalability, maintainability, and +performance — heuristics, never dogma). Your repo's own absolute rules — "never …", "must not …" +in CLAUDE.md/CONTRIBUTING/docs — are discovered during recon, quoted verbatim, and enforced like floor rules. ## Development diff --git a/plugins/design-buddy/agents/adversary.md b/plugins/design-buddy/agents/adversary.md index 8259c32..5d0a21f 100644 --- a/plugins/design-buddy/agents/adversary.md +++ b/plugins/design-buddy/agents/adversary.md @@ -31,6 +31,13 @@ Be rigorous, not contrarian: every objection must be real and actionable. 6. **Offer the alternative.** For your strongest objections, name the alternative design and its trade-off. These become the "Rejected Alternatives" record — they have lasting value even when the original approach wins. +7. **Weigh design quality — without dogma (`DN-2`/`DN-7`/`DN-8`/`DN-9`).** Test the approach for + reuse (DRY, `DN-2`), right-sizing (YAGNI, `DN-7`), and sound structure (SOLID, `DN-8`): name the + specific speculative generality, the unit doing too much, or the duplicated concept, each with + the concrete maintenance cost it creates. But hold yourself to `DN-9` — these are subordinate to + scalability, maintainability, and performance; raise only what a staff engineer optimizing THIS + system's long-term health would actually change, never a pattern applied for its own sake. A + design-quality point is a Norm concern (addressed or waived at the gate), never a floor breach. ## What you receive diff --git a/plugins/design-buddy/agents/proposer.md b/plugins/design-buddy/agents/proposer.md index f0a46cc..c0dfa1a 100644 --- a/plugins/design-buddy/agents/proposer.md +++ b/plugins/design-buddy/agents/proposer.md @@ -22,6 +22,12 @@ adversary argues against it. You never see the adversary directly — the orches isn't in the recon, say so under assumptions — don't fabricate it. 4. **Reuse over rebuild (DN-2).** Prefer the recon's **Patterns to REUSE**. A proposal that re-creates an existing helper/type is a weak proposal. +4b. **Right-size the design (`DN-7`/`DN-8`/`DN-9`).** Propose the least mechanism the requirement + needs (YAGNI) with each new/changed unit carrying one clear responsibility at the seams the + change actually touches (SOLID) — no speculative abstraction, option, or indirection the change + does not demand. When honoring one of these heuristics would cost scalability, maintainability, + or performance, choose the system's health (`DN-9`) and record the trade-off under assumptions + rather than shipping a design that is "clean" but slower or harder to scale. 5. **Honor the rules.** Your design must respect the principles you were given and the host repo's own hard rules quoted in the recon (**DF-6**). If the requirement forces a tension with a rule, surface it rather than quietly violating it. diff --git a/plugins/design-buddy/skills/design-debate/reference/principles.md b/plugins/design-buddy/skills/design-debate/reference/principles.md index b0b2df2..9415991 100644 --- a/plugins/design-buddy/skills/design-debate/reference/principles.md +++ b/plugins/design-buddy/skills/design-debate/reference/principles.md @@ -35,7 +35,7 @@ the user at a gate. A waiver is recorded in the artifact, never implied. - **DN-1 — Evidence-cited claims.** Every load-bearing design claim cites `path:line` evidence from the recon dossier or the codebase. -- **DN-2 — Reuse over rebuild.** Prefer an existing pattern, helper, or type over a new one. A +- **DN-2 — Reuse over rebuild (DRY).** Prefer an existing pattern, helper, or type over a new one. A proposal that re-creates something the recon found is a weak proposal. - **DN-3 — Gates are recorded.** Every user decision at a gate (approve, waive, steer, accepted open risk) is recorded in the artifact it affects. @@ -50,3 +50,23 @@ the user at a gate. A waiver is recorded in the artifact, never implied. references, host hard-rule violations, contradiction of the approved design) is `failed` and must not be executed until fixed and re-reviewed; BLOCKERs cannot be waived. Warnings must be addressed or explicitly waived at a gate. +- **DN-7 — Right-sized design (YAGNI).** Solve the stated requirement with the least mechanism that + satisfies it. No speculative abstraction, extension point, configuration knob, or "while we're + here" generality the requirement does not demand — unbuilt flexibility is a carrying cost, not a + free asset. A proposal that adds structure for a future absent from the change description is a + weak proposal; the adversary names the specific speculative element and the proposer either cites + the concrete requirement that needs it or drops it. +- **DN-8 — Sound structure (SOLID).** Each unit the change adds or reshapes carries one clear + responsibility and one reason to change; callers depend on a stable seam, not on internals; new + behavior extends an existing seam rather than editing what already works, *where such a seam + already exists*. Applied to the real seams the change touches — never as a mandate to introduce + interfaces, layers, or indirection the change does not need (**DN-7** bounds this). +- **DN-9 — Design heuristics serve the system (the staff-engineer check).** **DN-2**, **DN-7**, and + **DN-8** are heuristics subordinate to the system's scalability, maintainability, and performance — + not ends in themselves. When a heuristic genuinely conflicts with one of those qualities, the + quality wins and the trade-off is recorded (design doc, or at the gate); the recorded trade-off is + compliance, not a waiver of it. The test for every design-quality point — raised or rebutted — is + *what would a staff engineer optimizing the long-term health of THIS system do?* An objection that + fails that test (dogmatic pattern-application, premature abstraction dressed up as SOLID, a DRY + merge that couples genuinely unrelated call-sites, or YAGNI invoked to starve a scalability need + the requirement states) is itself answerable or dismissable at the gate. diff --git a/plugins/design-buddy/skills/impl-plan/reference/principles.md b/plugins/design-buddy/skills/impl-plan/reference/principles.md index b0b2df2..9415991 100644 --- a/plugins/design-buddy/skills/impl-plan/reference/principles.md +++ b/plugins/design-buddy/skills/impl-plan/reference/principles.md @@ -35,7 +35,7 @@ the user at a gate. A waiver is recorded in the artifact, never implied. - **DN-1 — Evidence-cited claims.** Every load-bearing design claim cites `path:line` evidence from the recon dossier or the codebase. -- **DN-2 — Reuse over rebuild.** Prefer an existing pattern, helper, or type over a new one. A +- **DN-2 — Reuse over rebuild (DRY).** Prefer an existing pattern, helper, or type over a new one. A proposal that re-creates something the recon found is a weak proposal. - **DN-3 — Gates are recorded.** Every user decision at a gate (approve, waive, steer, accepted open risk) is recorded in the artifact it affects. @@ -50,3 +50,23 @@ the user at a gate. A waiver is recorded in the artifact, never implied. references, host hard-rule violations, contradiction of the approved design) is `failed` and must not be executed until fixed and re-reviewed; BLOCKERs cannot be waived. Warnings must be addressed or explicitly waived at a gate. +- **DN-7 — Right-sized design (YAGNI).** Solve the stated requirement with the least mechanism that + satisfies it. No speculative abstraction, extension point, configuration knob, or "while we're + here" generality the requirement does not demand — unbuilt flexibility is a carrying cost, not a + free asset. A proposal that adds structure for a future absent from the change description is a + weak proposal; the adversary names the specific speculative element and the proposer either cites + the concrete requirement that needs it or drops it. +- **DN-8 — Sound structure (SOLID).** Each unit the change adds or reshapes carries one clear + responsibility and one reason to change; callers depend on a stable seam, not on internals; new + behavior extends an existing seam rather than editing what already works, *where such a seam + already exists*. Applied to the real seams the change touches — never as a mandate to introduce + interfaces, layers, or indirection the change does not need (**DN-7** bounds this). +- **DN-9 — Design heuristics serve the system (the staff-engineer check).** **DN-2**, **DN-7**, and + **DN-8** are heuristics subordinate to the system's scalability, maintainability, and performance — + not ends in themselves. When a heuristic genuinely conflicts with one of those qualities, the + quality wins and the trade-off is recorded (design doc, or at the gate); the recorded trade-off is + compliance, not a waiver of it. The test for every design-quality point — raised or rebutted — is + *what would a staff engineer optimizing the long-term health of THIS system do?* An objection that + fails that test (dogmatic pattern-application, premature abstraction dressed up as SOLID, a DRY + merge that couples genuinely unrelated call-sites, or YAGNI invoked to starve a scalability need + the requirement states) is itself answerable or dismissable at the gate. diff --git a/plugins/design-buddy/skills/impl-plan/reference/step-rules.md b/plugins/design-buddy/skills/impl-plan/reference/step-rules.md index d6c47a7..e3f8d99 100644 --- a/plugins/design-buddy/skills/impl-plan/reference/step-rules.md +++ b/plugins/design-buddy/skills/impl-plan/reference/step-rules.md @@ -47,6 +47,16 @@ Use the Repo Profile's **Test & quality harness** finding: If the Repo Profile found a lint or format command, append it to the `**Verification**` of every step that edits code in its scope. If none was found, do not invent one. +## Right-sized steps (DN-7 / DN-8 / DN-9) + +A step implements what its design decision needs — no speculative abstraction, configuration knob, +or extension point the design doc / requirement did not call for (**DN-7**), and each new unit it +adds carries one clear responsibility at the seam it touches (**DN-8**). These are heuristics +subordinate to the system's scalability, maintainability, and performance (**DN-9**): where honoring +one would cost the system, note the trade-off in the step rather than gold-plating. Do not smuggle +"while we're here" generality into a step the design did not decide — that is scope the design gate +never approved, and it belongs back in a design round, not a plan step. + ## Step granularity and ordering - One step = one reviewable unit of change (a commit's worth). Split a step whose Files list diff --git a/plugins/design-buddy/skills/plan-review/reference/principles.md b/plugins/design-buddy/skills/plan-review/reference/principles.md index b0b2df2..9415991 100644 --- a/plugins/design-buddy/skills/plan-review/reference/principles.md +++ b/plugins/design-buddy/skills/plan-review/reference/principles.md @@ -35,7 +35,7 @@ the user at a gate. A waiver is recorded in the artifact, never implied. - **DN-1 — Evidence-cited claims.** Every load-bearing design claim cites `path:line` evidence from the recon dossier or the codebase. -- **DN-2 — Reuse over rebuild.** Prefer an existing pattern, helper, or type over a new one. A +- **DN-2 — Reuse over rebuild (DRY).** Prefer an existing pattern, helper, or type over a new one. A proposal that re-creates something the recon found is a weak proposal. - **DN-3 — Gates are recorded.** Every user decision at a gate (approve, waive, steer, accepted open risk) is recorded in the artifact it affects. @@ -50,3 +50,23 @@ the user at a gate. A waiver is recorded in the artifact, never implied. references, host hard-rule violations, contradiction of the approved design) is `failed` and must not be executed until fixed and re-reviewed; BLOCKERs cannot be waived. Warnings must be addressed or explicitly waived at a gate. +- **DN-7 — Right-sized design (YAGNI).** Solve the stated requirement with the least mechanism that + satisfies it. No speculative abstraction, extension point, configuration knob, or "while we're + here" generality the requirement does not demand — unbuilt flexibility is a carrying cost, not a + free asset. A proposal that adds structure for a future absent from the change description is a + weak proposal; the adversary names the specific speculative element and the proposer either cites + the concrete requirement that needs it or drops it. +- **DN-8 — Sound structure (SOLID).** Each unit the change adds or reshapes carries one clear + responsibility and one reason to change; callers depend on a stable seam, not on internals; new + behavior extends an existing seam rather than editing what already works, *where such a seam + already exists*. Applied to the real seams the change touches — never as a mandate to introduce + interfaces, layers, or indirection the change does not need (**DN-7** bounds this). +- **DN-9 — Design heuristics serve the system (the staff-engineer check).** **DN-2**, **DN-7**, and + **DN-8** are heuristics subordinate to the system's scalability, maintainability, and performance — + not ends in themselves. When a heuristic genuinely conflicts with one of those qualities, the + quality wins and the trade-off is recorded (design doc, or at the gate); the recorded trade-off is + compliance, not a waiver of it. The test for every design-quality point — raised or rebutted — is + *what would a staff engineer optimizing the long-term health of THIS system do?* An objection that + fails that test (dogmatic pattern-application, premature abstraction dressed up as SOLID, a DRY + merge that couples genuinely unrelated call-sites, or YAGNI invoked to starve a scalability need + the requirement states) is itself answerable or dismissable at the gate. diff --git a/plugins/design-buddy/skills/plan-review/reference/review-criteria.md b/plugins/design-buddy/skills/plan-review/reference/review-criteria.md index 7dc6ec0..a1b0cb4 100644 --- a/plugins/design-buddy/skills/plan-review/reference/review-criteria.md +++ b/plugins/design-buddy/skills/plan-review/reference/review-criteria.md @@ -25,8 +25,15 @@ Apply to each numbered step: | Schema/migration rollback | A step adds to a schema/migration chain that has rollback counterparts (down files) in the repo, but lists none | WARNING | | Contract identifiers stated | A step changes a public contract (API route, message schema, exported surface) without stating the identifiers that must not be reused or broken | WARNING | | Symmetry | A step implements one variant of an enumerated set found in the repo (one of several providers, states, platforms, order/kind values) without stating coverage of the others or explicitly scoping them out | WARNING | +| Right-sized (YAGNI) | A step introduces an abstraction, extension point, or configuration knob the design doc / requirement does not call for | WARNING (`DN-7`) | +| Single responsibility (SOLID) | A step's new unit takes on unrelated responsibilities, or one concern is split across many units when the change does not need it | WARNING (`DN-8`) | | Step size | `**Files**` lists more than ~5 files — consider splitting | NOTE | +Design-quality findings (`DN-2`/`DN-7`/`DN-8`) are `WARNING` at most, never a `BLOCKER` (**DN-9** — +they are subordinate to scalability, maintainability, and performance). Raise one only where a staff +engineer optimizing the system's long-term health would change the step; a design that consciously +trades a heuristic for a higher quality, with the trade-off recorded, is compliant — do not flag it. + ## B. Design fidelity (when a design doc exists) | Criterion | Fails when | Severity |