Skip to content

Latest commit

 

History

History

design-buddy

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

Design Buddy

A repo-agnostic plugin — for Claude Code, Cursor, and Codex — that turns the agent into a design partner for any source-code change — bug fix through large rearchitecture or migration — and then into an implementation planner whose every step is grounded in evidence from the target codebase. One shared skills/ + agents/ tree serves all three tools.

It is a portable export of a spec-driven-development methodology: a read-only recon pass builds a grounded dossier of the repo, a mediated proposer-vs-adversary debate pressure-tests one design (recording the rejected alternatives), and a zero-assumption planning pass turns the approved design into numbered, verifiable, statused steps a future session can execute.

Install

Claude Code

/plugin marketplace add davcs86/agent-plugins
/plugin install design-buddy@davcs86-agent-plugins

Cursor

Add this repository as a plugin marketplace source, then install design-buddy from it — see the Cursor plugins docs. Cursor discovers the plugin's skills/ and agents/ directly, and its subagents run through the same Task tool.

Codex

/plugin marketplace add davcs86/agent-plugins
/plugin install design-buddy@davcs86-agent-plugins

Skills

Invoke each as a slash command: /design-buddy:design-debate in Claude Code (plugin-namespaced), or /design-debate in Cursor and Codex (flat, un-namespaced command names — so /design-debate, /impl-plan, /plan-review).

Skill What it does
design-debate <change description or issue ref> [quick|full|deep] Recon (repo scout + parallel area discovery → recon.md) then a depth-scaled adversarial debate → design.md with the chosen approach, rejected alternatives, and open risks.
impl-plan <design.md path | slug | change description> Consumes the design doc (or warns and discovers from scratch) and writes plan.md: numbered steps, each with Files / Evidence / Instructions / Verification / Test, executable step-by-step by a later session.
plan-review <plan.md path | slug> Review gate for the plan — stricter than advisory. A reviewer subagent checks every step (evidence resolves, design fidelity, host hard rules, ordering); the verdict is recorded in the plan header. Any floor-tied BLOCKER fails the review and blocks execution readiness — BLOCKERs cannot be waived; warnings are addressed or explicitly waived, with everything logged in ## Review Log.

Renamed in 2.0.0. These skills were design / plan / review through 1.x. The old names collided with built-in agent commands (Claude Code ships its own /review, and plan shadows plan mode), which mattered most under Cursor, where commands are invoked flat with no plugin: namespace to disambiguate. Update any saved command or script that used the old names.

Debate depths

Depth For Rounds (mandated / cap) Round 1
quick bug fixes, small localized changes 1 / 3 single proposer
full typical features, multi-module changes 2 / 5 single proposer
deep rearchitectures, migrations, framework swaps 2 / 6 a panel of 2–3 proposers with assigned angles (minimal-delta, target-state, operational-safety), judged and merged before the adversary attacks

If you omit the depth, the skill recommends one from the change's blast radius, reversibility, and novelty, and asks you to confirm. At every depth, approval is gated: you approve the design explicitly, and an unresolved floor breach (a DF-* principle or a hard rule your own repo states about itself) blocks approval outright.

Subagents

Five read-only agents do the heavy lifting so the orchestrating session stays lean: repo-scout (once-per-run repo orientation), area-discovery (per-area evidence digests), proposer (one cited design per round), adversary (attacks it, citing rules by ID), and reviewer (verdicts the finished plan against the review criteria). Proposer and adversary never see each other's raw output — the skill mediates every round. Each agent declares its read-only contract for the tools that read it: tools: Glob, Grep, Read (Claude Code) and readonly: true (Cursor); Codex discovers the same agents/*.md files but has no matching frontmatter key yet. Only the orchestrating skill ever writes.

First run & configuration

On first use in a repo, the skill asks where to store artifacts and writes .agents/design-buddy.json (a tool-neutral location Claude Code, Cursor, and Codex all recognize):

{ "version": 1, "artifactsDir": "docs/design", "ledger": true, "created": "2026-07-13" }
  • Each change gets <artifactsDir>/<date>-<slug>/ containing recon.md, design.md, plan.md.
  • "artifactsDir": null = scratch mode — no files at all; artifacts are emitted inline in chat.
  • "ledger": true seeds an append-only <artifactsDir>/ledger.md of one-line lessons that future runs feed to the adversary.

The config file is committable, so a team shares one setting; gitignore it if you prefer.

Governance

skills/*/reference/principles.md ships the portable rule seed the adversary and reviewer cite: 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 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.

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, invoked as python3 <script>.py — never Bash (shell scripts are not portable across the infrastructures host repos run on). The plugin currently ships exactly one script:

python3 plugins/design-buddy/scripts/validate.py              # validate the plugin tree
python3 plugins/design-buddy/scripts/validate.py --self-test  # run its negative-fixture tests

The bundled validator is the fast, dependency-free local check. For the authoritative pass — real YAML frontmatter parsing, marketplace schema, duplicate/kebab-case checks — also run Claude Code's official validator:

claude plugin validate .                        # the marketplace catalog
claude plugin validate plugins/design-buddy     # the plugin (manifest + skill/agent frontmatter)

validate.py checks both plugin manifests (.claude-plugin/plugin.json and .cursor-plugin/plugin.json) parse and carry required fields, every skill/agent has frontmatter (agents carry readonly for the Cursor read-only contract), every reference//templates/ path named in a SKILL.md resolves, and no host-repo-specific strings leak into the plugin.