diff --git a/plugins/design-buddy/.claude-plugin/plugin.json b/plugins/design-buddy/.claude-plugin/plugin.json index c698e39..6c82300 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.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", diff --git a/plugins/design-buddy/.codex-plugin/plugin.json b/plugins/design-buddy/.codex-plugin/plugin.json index e09315c..3462b8c 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.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", diff --git a/plugins/design-buddy/.cursor-plugin/plugin.json b/plugins/design-buddy/.cursor-plugin/plugin.json index c698e39..6c82300 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.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", diff --git a/plugins/design-buddy/README.md b/plugins/design-buddy/README.md index dc65e99..3804c09 100644 --- a/plugins/design-buddy/README.md +++ b/plugins/design-buddy/README.md @@ -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 @@ -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, diff --git a/plugins/design-buddy/skills/design-debate/SKILL.md b/plugins/design-buddy/skills/design-debate/SKILL.md index 5385615..fd82eec 100644 --- a/plugins/design-buddy/skills/design-debate/SKILL.md +++ b/plugins/design-buddy/skills/design-debate/SKILL.md @@ -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 @@ -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 @@ -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. diff --git a/plugins/design-buddy/skills/design-debate/reference/debate-protocol.md b/plugins/design-buddy/skills/design-debate/reference/debate-protocol.md index 508b47b..b6ac2a2 100644 --- a/plugins/design-buddy/skills/design-debate/reference/debate-protocol.md +++ b/plugins/design-buddy/skills/design-debate/reference/debate-protocol.md @@ -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 → ` 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. @@ -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. diff --git a/plugins/design-buddy/skills/design-debate/reference/principles.md b/plugins/design-buddy/skills/design-debate/reference/principles.md index 9415991..9e507e0 100644 --- a/plugins/design-buddy/skills/design-debate/reference/principles.md +++ b/plugins/design-buddy/skills/design-debate/reference/principles.md @@ -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 → `), 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 diff --git a/plugins/design-buddy/skills/design-debate/templates/design.md b/plugins/design-buddy/skills/design-debate/templates/design.md index c83bbb1..41f2ff6 100644 --- a/plugins/design-buddy/skills/design-debate/templates/design.md +++ b/plugins/design-buddy/skills/design-debate/templates/design.md @@ -32,6 +32,14 @@ analysis; in deep mode, also the losing panel proposals.> - [ ] — to be addressed at . - ... +## Assumptions + + +- — basis: — gate: — + `confirmed` | `corrected → `. +- ... + ## Principles & Host Rules Touched `), 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 diff --git a/plugins/design-buddy/skills/impl-plan/templates/plan.md b/plugins/design-buddy/skills/impl-plan/templates/plan.md index 16059a8..2f68622 100644 --- a/plugins/design-buddy/skills/impl-plan/templates/plan.md +++ b/plugins/design-buddy/skills/impl-plan/templates/plan.md @@ -25,6 +25,13 @@ only `**Status**` flips, and divergence lands in `## Deviation Log`. - Step N requires Step M: - (list all ordering constraints, or "none — steps are independent") +## Assumptions + + +- — basis: — `confirmed` | + `corrected → `. + --- ### Step N — diff --git a/plugins/design-buddy/skills/plan-review/SKILL.md b/plugins/design-buddy/skills/plan-review/SKILL.md index 56d7205..0e2371e 100644 --- a/plugins/design-buddy/skills/plan-review/SKILL.md +++ b/plugins/design-buddy/skills/plan-review/SKILL.md @@ -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 @@ -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 @@ -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. diff --git a/plugins/design-buddy/skills/plan-review/reference/principles.md b/plugins/design-buddy/skills/plan-review/reference/principles.md index 9415991..9e507e0 100644 --- a/plugins/design-buddy/skills/plan-review/reference/principles.md +++ b/plugins/design-buddy/skills/plan-review/reference/principles.md @@ -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 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 a1b0cb4..5d563b1 100644 --- a/plugins/design-buddy/skills/plan-review/reference/review-criteria.md +++ b/plugins/design-buddy/skills/plan-review/reference/review-criteria.md @@ -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