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.1.0",
"version": "3.0.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.1.0",
"version": "3.0.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.1.0",
"version": "3.0.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
13 changes: 11 additions & 2 deletions plugins/design-buddy/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,8 +92,9 @@ The config file is committable, so a team shares one setting; gitignore it if yo
## Governance

`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
**Floor rules** `DF-1..7` (never invent paths/symbols; no silent deviation; single orchestrator
writes; mediated debate; floor blocks approval; host hard rules are floor-equivalent; every
unilateral assumption is listed before each gate and persisted with its outcome) and
**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; right-sized design = YAGNI; sound structure = SOLID; and the
Expand All @@ -102,6 +103,14 @@ performance — heuristics, never dogma). Your repo's own absolute rules — "ne
in CLAUDE.md/CONTRIBUTING/docs — are discovered during recon, quoted verbatim, and enforced like
floor rules.

> **New in 3.0.0 — `DF-7`, assumptions before every gate.** Before any question it asks you, each
> skill prints an **Assumptions (unconfirmed)** block: every call it made on its own (inferred
> scope, recommended depth, resolved input file, demoted finding, …), with its basis, or "none".
> Your answer confirms or corrects each one, and the outcomes are recorded in `design.md` /
> `plan.md` under `## Assumptions` (plan-review records its own in `## Review Log`). Breaking:
> plan-review now fails a plan with no `## Assumptions` section — re-run impl-plan on plans
> written by 2.x.

## Development

**Script policy: Python only.** Any executable shipped in this plugin is Python 3, stdlib-only,
Expand Down
10 changes: 9 additions & 1 deletion plugins/design-buddy/skills/design-debate/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,11 @@ the state you synthesize and pass.
**Interactive gates.** Every user gate below uses a single structured multiple-choice prompt —
the `AskUserQuestion` tool in Claude Code. Where that tool isn't available (e.g. under Cursor),
ask the same question, with the same options, in plain chat and wait for the answer.
Immediately before every gate — the first-run interview, B3, and each debate round — print the
**Assumptions (unconfirmed)** block (**DF-7**): every unilateral assumption made so far that the
user has not confirmed (yours, plus the proposer's assumptions list), one line each with its
basis, or "none". Record each one's gate outcome; they all land in the design doc's
`## Assumptions`.

**Implicit invocation.** This skill may be triggered by the model when a user asks how to
approach a change, rather than by an explicit command. When that happens, restate the change you
Expand Down Expand Up @@ -94,7 +99,8 @@ panel included). A floor breach — a `DF-*` violation or a quoted host hard rul
blocks Approve at every depth; "proceed anyway" never clears it (**DF-5**).

On approval, write the design doc from `templates/design.md`: Chosen Approach (cited), Rejected
Alternatives, Open Risks, Principles & Host Rules Touched, Waivers.
Alternatives, Open Risks, Assumptions (with gate outcomes — **DF-7**), Principles & Host Rules
Touched, Waivers.

## COMPLETION

Expand All @@ -114,6 +120,8 @@ Alternatives, Open Risks, Principles & Host Rules Touched, Waivers.
- **Mediate every exchange (DF-4).** No participant sees another's raw output.
- **Never invent (DF-1); never guess past ambiguity (DF-2).**
- **A floor breach blocks approval at every depth (DF-5, DF-6).**
- **Declare assumptions before every gate (DF-7).** No gate is asked without the
**Assumptions (unconfirmed)** block — "none" is stated, never omitted.
- **Round bounds by depth.** Never approve below the mandate; never loop past the cap. The user
may opt into more rounds, never fewer.
- **Scratch mode writes no files anywhere** — inline artifacts only.
Original file line number Diff line number Diff line change
Expand Up @@ -45,12 +45,17 @@ depth). The user may always opt into *more* rounds, never fewer than the mandate
- **Floor status** — any unresolved `DF-*` breach or host hard-rule violation.

4. **Gate (you, via `AskUserQuestion` — DN-3).** Present a tight synthesis (current approach, the
strongest surviving objection, floor status) and offer:
strongest surviving objection, floor status), preceded by the **Assumptions (unconfirmed)**
block (**DF-7**) — the proposer's assumptions list plus any you made while synthesizing, minus
those already confirmed at an earlier gate, or "none" — and offer:
- **Approve design** — selectable only when `R ≥ mandated` for the depth AND there is **no
unresolved floor breach**. Exit the loop.
- **Run another round** — feed your synthesis into round R+1.
- **Inject a constraint / steer** — record the user's note, then run round R+1 with it.

Choosing Approve or Run another round confirms the listed assumptions; a steer that contradicts
one marks it `corrected → <the note>` and turns it into a constraint for round R+1.

Below the mandated count, do not offer Approve — at least one more round is mandatory. At the
hard cap, present the state and ask the user to approve as-is, accept a documented open risk,
or stop — do not loop past the cap.
Expand All @@ -71,6 +76,8 @@ depth). The user may always opt into *more* rounds, never fewer than the mandate
- **Rejected Alternatives** — one line each, pulled from the adversary's trade-off analysis (and,
in deep mode, the losing panel proposals). This is the durable value of the debate.
- **Open Risks** — anything accepted-but-unresolved, each with where it must be addressed.
- **Assumptions** — every assumption declared at any gate of this run (boot included), each with
its basis and gate outcome (**DF-7**).
- **Principles & Host Rules Touched** — the DF-*/DN-* IDs and quoted host rules the approach
interacts with, and how each is honored.
- **Waivers** — any DN-* objections the user explicitly waived, with rationale.
Expand Down
10 changes: 10 additions & 0 deletions plugins/design-buddy/skills/design-debate/reference/principles.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,16 @@ clears a Floor item — the user may steer the work to *resolve* it, or stop.
absolute ("never …", "always …", "must not …" in its CLAUDE.md, CONTRIBUTING, or docs) is
treated exactly like a `DF-*` rule. Cite it by verbatim quote + `path:line` — never invent an
ID for it.
- **DF-7 — Assumptions are declared before every gate.** Immediately before every user gate,
the orchestrator lists every unilateral assumption made so far that the user has not yet
confirmed — its own and any a subagent reported: an inferred scope or interpretation, a
recommended or defaulted choice, a resolved input file, a filled gap, a severity demotion, a
judgment call between options. One line each, with its basis (`path:line` evidence, or "no
evidence — judgment"), under an **Assumptions (unconfirmed)** heading; when there are none, it
says "none" — never omits the block. Every assumption, with its gate outcome (`confirmed`, or
`corrected → <what the user said>`), is persisted in the artifact's `## Assumptions` section.
Listing an assumption never legalizes a `DF-1`/`DF-2` breach: an unfound path stays under
`## Not found`, and real ambiguity is still asked as a gate question, not assumed and listed.

## Norms (`DN-*`) — must be addressed or explicitly waived at a gate

Expand Down
8 changes: 8 additions & 0 deletions plugins/design-buddy/skills/design-debate/templates/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,14 @@ analysis; in deep mode, also the losing panel proposals.>
- [ ] <risk> — to be addressed at <plan step / follow-up>.
- ...

## Assumptions

<Every unilateral assumption declared before a gate in this run (DF-7) — boot, recon, and each
debate round — with its basis and the outcome the user gave. Write "None." if there were none.>
- <assumption> — basis: <path:line | "no evidence — judgment"> — gate: <B3 | round N> —
`confirmed` | `corrected → <what the user said>`.
- ...

## Principles & Host Rules Touched

<The DF-*/DN-* IDs this approach interacts with and how each is honored, plus any host-repo
Expand Down
11 changes: 10 additions & 1 deletion plugins/design-buddy/skills/impl-plan/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,14 @@ cannot find something, say so explicitly.

**Interactive gates.** Any user gate below uses a structured multiple-choice prompt — the
`AskUserQuestion` tool in Claude Code. Where that tool isn't available (e.g. under Cursor), ask
the same question, with the same options, in plain chat and wait for the answer.
the same question, with the same options, in plain chat and wait for the answer. Immediately
before every gate — the first-run interview, the no-design-doc warning, the implicit-invocation
confirmation, and any conflict surfaced under **DF-2** — print the **Assumptions (unconfirmed)**
block (**DF-7**): every unilateral assumption made so far that the user has not confirmed (the
resolved input, an inferred area list, a chosen step order, a defaulted harness), one line each
with its basis, or "none". If planning reaches step 6 with assumptions made after the last gate,
run one final confirmation gate for them before writing. All of them, with gate outcomes, land in
the plan's `## Assumptions`.

**Implicit invocation.** This skill may be triggered by the model when a user asks for an
implementation plan, rather than by an explicit command. When that happens, state which design
Expand Down Expand Up @@ -106,5 +113,7 @@ bodies stay immutable (deviations → Deviation Log).
- **The Chosen Approach is binding.** Conflicts are surfaced (**DF-2**), never silently resolved.
- **Detected, not assumed.** Test commands, lint commands, and coverage thresholds come from the
repo's own files, cited — or are omitted.
- **Declare assumptions before every gate (DF-7).** No gate is asked — and no plan is written —
with an unconfirmed assumption left unlisted; "none" is stated, never omitted.
- **You are the only writer (DF-3).** Subagents never write.
- **Scratch mode writes no files anywhere** — inline artifacts only.
10 changes: 10 additions & 0 deletions plugins/design-buddy/skills/impl-plan/reference/principles.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,16 @@ clears a Floor item — the user may steer the work to *resolve* it, or stop.
absolute ("never …", "always …", "must not …" in its CLAUDE.md, CONTRIBUTING, or docs) is
treated exactly like a `DF-*` rule. Cite it by verbatim quote + `path:line` — never invent an
ID for it.
- **DF-7 — Assumptions are declared before every gate.** Immediately before every user gate,
the orchestrator lists every unilateral assumption made so far that the user has not yet
confirmed — its own and any a subagent reported: an inferred scope or interpretation, a
recommended or defaulted choice, a resolved input file, a filled gap, a severity demotion, a
judgment call between options. One line each, with its basis (`path:line` evidence, or "no
evidence — judgment"), under an **Assumptions (unconfirmed)** heading; when there are none, it
says "none" — never omits the block. Every assumption, with its gate outcome (`confirmed`, or
`corrected → <what the user said>`), is persisted in the artifact's `## Assumptions` section.
Listing an assumption never legalizes a `DF-1`/`DF-2` breach: an unfound path stays under
`## Not found`, and real ambiguity is still asked as a gate question, not assumed and listed.

## Norms (`DN-*`) — must be addressed or explicitly waived at a gate

Expand Down
7 changes: 7 additions & 0 deletions plugins/design-buddy/skills/impl-plan/templates/plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,13 @@ only `**Status**` flips, and divergence lands in `## Deviation Log`.
- Step N requires Step M: <reason>
- (list all ordering constraints, or "none — steps are independent")

## Assumptions

<Every unilateral assumption declared before a gate while planning (DF-7), with its basis and the
outcome the user gave. Write "None." if there were none.>
- <assumption> — basis: <path:line | "no evidence — judgment"> — `confirmed` |
`corrected → <what the user said>`.

---

### Step N — <title>
Expand Down
16 changes: 13 additions & 3 deletions plugins/design-buddy/skills/plan-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,14 @@ advisory only — it assesses; you decide, edit, and record.

**Interactive gates.** Every user gate below uses a structured multiple-choice prompt — the
`AskUserQuestion` tool in Claude Code. Where that tool isn't available (e.g. under Cursor), ask
the same question, with the same options, in plain chat and wait for the answer.
the same question, with the same options, in plain chat and wait for the answer. Immediately
before every gate — the first-run interview, the implicit-invocation confirmation, the
execution-has-begun warning, and each step 4 gate — print the **Assumptions (unconfirmed)** block
(**DF-7**): every unilateral assumption made so far that the user has not confirmed (the resolved
plan, a BLOCKER demoted to WARNING, a reviewer finding you interpreted, an amendment you chose),
one line each with its basis, or "none". They are recorded, with gate outcomes, in the
`## Review Log` entry (step 5) — never in the plan's own `## Assumptions`, which belongs to the
**impl-plan** skill.

**Implicit invocation.** This skill may be triggered by the model when a user asks whether a plan
is ready, rather than by an explicit command. When that happens, name the plan file you resolved
Expand Down Expand Up @@ -66,14 +73,16 @@ keyed to criteria, blockers and warnings listed separately. Spot-check before ac
There is **no waive option for blockers** (**DN-6**).
- **PASS WITH WARNINGS.** Present each warning and ask: **address now** (amend + log, re-run
step 3 once) or **waive** (record the waiver + rationale in `## Review Log` — **DN-3**).
- **PASS.** Proceed to step 5.
- **PASS.** If assumptions are still unconfirmed, run one confirmation gate for them (**DF-7**);
then proceed to step 5.

### 5. Record the verdict

Edit the plan (scratch mode: re-emit inline):
- Header: set `**Review**: passed | passed-with-warnings | failed @ <ISO date>`.
- Append a `## Review Log` section (create if absent): date, verdict, blockers found/fixed,
warnings addressed/waived (with rationale), and any step amendments made in step 4.
warnings addressed/waived (with rationale), any step amendments made in step 4, and the
assumptions declared at this review's gates with their outcomes (**DF-7**).

### 6. Report

Expand All @@ -90,5 +99,6 @@ Blockers: <n found, n fixed | none>. Warnings: <n addressed, n waived | none>.
- **A BLOCKER must be floor-tied.** `DF-*` or a quoted host hard rule — otherwise demote it.
- **Every plan edit is logged** in `## Review Log`; after execution has begun, edit nothing but
the header and the log (**DN-5**).
- **Declare assumptions before every gate (DF-7).** "none" is stated, never omitted.
- **You are the only writer (DF-3).** The reviewer never edits the plan.
- **Bounded loop.** At most 2 fix-and-re-review cycles per invocation.
10 changes: 10 additions & 0 deletions plugins/design-buddy/skills/plan-review/reference/principles.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,16 @@ clears a Floor item — the user may steer the work to *resolve* it, or stop.
absolute ("never …", "always …", "must not …" in its CLAUDE.md, CONTRIBUTING, or docs) is
treated exactly like a `DF-*` rule. Cite it by verbatim quote + `path:line` — never invent an
ID for it.
- **DF-7 — Assumptions are declared before every gate.** Immediately before every user gate,
the orchestrator lists every unilateral assumption made so far that the user has not yet
confirmed — its own and any a subagent reported: an inferred scope or interpretation, a
recommended or defaulted choice, a resolved input file, a filled gap, a severity demotion, a
judgment call between options. One line each, with its basis (`path:line` evidence, or "no
evidence — judgment"), under an **Assumptions (unconfirmed)** heading; when there are none, it
says "none" — never omits the block. Every assumption, with its gate outcome (`confirmed`, or
`corrected → <what the user said>`), is persisted in the artifact's `## Assumptions` section.
Listing an assumption never legalizes a `DF-1`/`DF-2` breach: an unfound path stays under
`## Not found`, and real ambiguity is still asked as a gate question, not assumed and listed.

## Norms (`DN-*`) — must be addressed or explicitly waived at a gate

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,8 @@ fidelity checks could not run.
| Dependencies declared | `## Step Dependencies` says "none" but steps clearly have ordering constraints | WARNING |
| Tree stays consistent | Executing the steps in order would leave the tree broken between steps (consumer lands before its contract) | WARNING |
| Header complete | The plan header lacks `**Status**`, `**Test harness**`, `**Total Steps**`, or `**Review**` | WARNING |
| Assumptions declared | The plan has no `## Assumptions` section, or an entry in it lacks a gate outcome (`confirmed` / `corrected → …`) | BLOCKER (`DF-7`) |
| Assumptions honored | A step contradicts an assumption the user marked `corrected → …` (in the plan or the design doc's `## Assumptions`) | BLOCKER (`DF-2`) |

## Verdict shape the agent returns

Expand Down
Loading