Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion plugins/design-buddy/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
2 changes: 1 addition & 1 deletion plugins/design-buddy/.codex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
2 changes: 1 addition & 1 deletion plugins/design-buddy/.cursor-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
8 changes: 5 additions & 3 deletions plugins/design-buddy/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 7 additions & 0 deletions plugins/design-buddy/agents/adversary.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
6 changes: 6 additions & 0 deletions plugins/design-buddy/agents/proposer.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
22 changes: 21 additions & 1 deletion plugins/design-buddy/skills/impl-plan/reference/principles.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
10 changes: 10 additions & 0 deletions plugins/design-buddy/skills/impl-plan/reference/step-rules.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
22 changes: 21 additions & 1 deletion plugins/design-buddy/skills/plan-review/reference/principles.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
Loading