design-playbook

design-playbook

Agent plugin for evidence-backed UI delivery in existing Web products (Claude Code / Codex). Design I/O is the declaration and contract mechanism.

The project is in maintainer self-use and maintenance. Catalog submissions and recruitment are paused; installed paths remain available. Missing required proof stays blocked; an explicitly skipped evaluator records audited: false, not an audited Pass. Evaluator review does not replace human semantic approval.

Declarations + contracts — not a style CSV pack. Compose with ui-ux-pro-max and Anthropic frontend-design for aesthetics; this package owns pipeline and acceptance.

Install (Claude Code)

Path of record (published) - the marketplace catalog lives at the repo root, not in this package:

/plugin marketplace add https://github.com/Bandersnatch0x/design-playbook.git
/plugin install design-playbook@design-playbook

Local dev / self-test:

claude --plugin-dir <abs-path>/packages/design-playbook      # dev load, no install
# or local marketplace (point at the repo root, where the catalog lives)
/plugin marketplace add <abs-path-to-repo-root>
/plugin install design-playbook@design-playbook

Install (Codex)

Same GitHub repo / monorepo root catalog. Codex-native manifest lives at .codex-plugin/ (MCP uses relative paths).

codex plugin marketplace add Bandersnatch0x/design-playbook
codex plugin add design-playbook@design-playbook

Local monorepo:

codex plugin marketplace add <abs-path-to-repo-root>
codex plugin add design-playbook@design-playbook

Details + skills-only fallback: codex/AGENTS.md.

After install, skills and commands are namespaced by the plugin name:

Invoke	Role
/design-playbook:design-playbook	Orchestrator skill (model-invoked)
/design-playbook:design-baseline	Discover/validate/draft the project DESIGN.md baseline
/design-playbook:reference-intake	Reference contract skill (screenshot/URL/analogy)
/design-playbook:ux-spec	Six-layer spec skill
/design-playbook:ui-picker	Shell + components skill
/design-playbook:craft-guard	Craft / anti-slop skill
/design-playbook:native-craft	Native-feel desktop declaration skill
/design-playbook:ui-evaluator	Point-back acceptance skill
/design-playbook:component-distill	Cross-run component/token proposal skill and command; report-only, promotion requires a user decision
/design-playbook:design-io	Full pipeline command
/design-playbook:ux-spec	Spec-only command
/design-playbook:ui-review	Review command
/design-playbook:run-review	Cross-run review command
/design-playbook:run-status	Run phase, blocker, and resume/continuation narration
/design-playbook:run-handoff	Static delivery package for one reviewed run
/design-playbook:doctor	Install health diagnosis

Bare /design-io is not the installed name — always use the design-playbook: prefix.

Install (pi)

Published to npm, listed in the pi package gallery.

pi install npm:design-playbook

pi has no plugin namespace — skills are /skill:<name>, commands are bare /<name>:

Invoke	Role
/skill:design-playbook	Orchestrator skill (model-invoked)
/skill:ux-spec … /skill:component-distill	Same nine skills as above
/design-io · /ux-spec · /ui-review · /run-review · /run-status · /run-handoff · /doctor · /component-distill	Pipeline / spec-only / review / cross-run / status / handoff / health / proposal commands

pi ships no built-in MCP, so preview* and observe* skip by default (ADR-0009 absent→skip; the pipeline still runs spec → picker → fill → craft → accept). To enable both gates, install an MCP adapter and register the bundled servers in your project .mcp.json:

pi install npm:pi-mcp-adapter

{
  "mcpServers": {
    "design-playbook-preview": {
      "command": "python",
      "args": ["<pkg>/mcp/preview/server.py"],
      "timeout": 3600000
    },
    "design-playbook-evidence": {
      "command": "python",
      "args": ["<pkg>/mcp/evidence/server.py"],
      "env": { "DESIGN_PLAYBOOK_RUN_ROOT": "." },
      "timeout": 3600000
    }
  }
}

<pkg> is the installed package root — ~/.pi/agent/npm/node_modules/design-playbook for a user install, .pi/npm/node_modules/design-playbook for a project install. Evidence also needs pip install playwright && playwright install chromium.

Install on other agents

Generate adapter files for Cursor, Gemini CLI, OpenCode, Windsurf, GitHub Copilot, Zed, or any of 22 Tier-3 agents:

npx design-playbook init <agent>   # e.g. cursor, gemini-cli, windsurf
npx design-playbook --list         # all 30 agents, shows which have renderers

See the root README for the tier table and capability notes.

Stack with other skills

Package	Use for
design-playbook	Baseline? → Reference? → Spec? → plan? → shell → optional preview* → fill → craft → optional observe* → evaluate / recirculate
ui-ux-pro-max	Style / palette / type search
frontend-design	Anti-template visual direction

Layout

.claude-plugin/
  plugin.json          ← plugin manifest (the marketplace catalog lives at the repo root)
.mcp.json              ← bundled MCP servers, launched via ${CLAUDE_PLUGIN_ROOT} (ADR-0009)
mcp/{preview,evidence}/← MCP adapter runtimes (preview_prototype / execute_capture_plan)
skills/<name>/SKILL.md ← model-invoked skills
commands/<name>.md     ← slash commands; see invocation tables above
codex/AGENTS.md        ← Codex bridge notes
examples/              ← self-authored onboarding samples
LICENSE · NOTICE       ← authored-only scope

What ships

Only authored content in this package (skills, pipeline commands, metadata, self-written examples, self-authored bundled MCP adapters). See NOTICE and repo ADRs 0003–0006, 0009. Repo-maintainer polish commands live in the monorepo root .claude/commands/, not in this package.

Runtime behavior & data

Everything this plugin runs is local and disclosed here (directory-submission review):

• MCP servers (stdio, launched from ${CLAUDE_PLUGIN_ROOT} in .mcp.json):
  • design-playbook-preview — python mcp/preview/server.py. Renders a caller-supplied HTML prototype in a local window and collects a confirm/revise decision. No third-party dependencies.
  • design-playbook-evidence — python mcp/evidence/server.py. Drives a local browser (Playwright + Chromium, user-installed) to the URL named in each capture call and writes screenshot / a11y-tree / trace artifacts under <run_root>/evidence/. It never uploads artifacts (no HTTP delivery endpoint exists).
• Network: the plugin makes no outbound request of its own — no telemetry, analytics, or reporting. The only fetch is the browser navigating to the target URL you pass to a capture call (and whatever that page loads).
• Environment: DESIGN_PLAYBOOK_RUN_ROOT is forwarded to the evidence server via env interpolation to locate the run tree; no credentials or tokens are read. Unset → artifacts resolve under the MCP process cwd.
• Interpreter: servers run under python (Python 3); the evidence path also needs playwright + a Chromium install. Hosts without these skip preview* / observe* (absent→skip, ADR-0009).

Contract vs enforcement

Evidence exists only to satisfy a declared criterion — an observation without a binding to an L6 acceptance item is telemetry, not evidence. Runtime capture is done by external providers; design-playbook owns the binding (manifest) and the verdict (ledger), never the runtime.

The Design I/O run is a declared, host-neutral contract over plain-Markdown artifacts (DESIGN.md, spec, decision report, point-back ledger). Any coding agent that emits that shape can be checked; Claude Code and Codex are adapters over the same artifacts. Generators and bridges remain optional; existing-product UI work must bind a valid/accepted project baseline or record an explicit waiver.

Run artifacts land under .scratch/<run>/ (design-baseline/, plan.md, preview/, evidence/manifest.jsonl, point-back.md); see the orchestrator skill for what lands when. That is where to look — and manually intervene — when a run stalls.

Stuck / resume

python <pkg>/scripts/run_status.py .scratch/<run>          # text phases + next action
python <pkg>/scripts/run_status.py .scratch/<run> --json   # machine-readable
python <pkg>/scripts/run_status.py --list                  # newest runs under .scratch/

The status command reuses the packaged validator’s G5 confirm rules. It is part of the installed package — not monorepo-only tooling. For an eligible run it also reports an explicit open-console continuation command for the local Run Console (it never starts a server itself), with the blocking reason and a safe fallback when the run or Console prerequisites are ineligible. The Console’s current claim is local, experimental, and trial-gated — run-status --json reports the same capability receipt (publicClaim: experimental) — and no authorized external trial or public release is claimed until the separately authorized read-only trial gate passes (ADR-0043).

The source checkout adds a bounded self-use report: python <pkg>/scripts/run_status.py <run> --scope path:P1 --json. It links explicit declarations, summarizes evidence gaps, and retains the original owner's re-verification requirements. Unknown impact cannot safely narrow that scope. See scope inputs, source refresh, and limits. This is not a release or measured productivity claim.

Static handoff

python <pkg>/scripts/run_handoff.py <run> [--fill <declared-path>] [--round N] [--json]

Builds the existing static delivery package for one explicit run from its declared fill: path. Multiple declarations need an explicit --fill; a missing declaration fails with repair guidance instead of guessing. verdict / authority / confirmationSource are reported verbatim — a Pending handoff stays Pending and never becomes acceptance.

Doctor

python <pkg>/scripts/doctor.py
python <pkg>/scripts/doctor.py --json

One packaged diagnosis for interpreter, package surface, optional Playwright, and run-root configuration. Distinguishes ok / degraded / broken with repair actions. Those three states describe install and runtime health of what is present locally — they are not a public capability-maturity verdict; maturity vocabulary (stable / experimental / blocked-by-gate / not-shipped) stays with the run-status capability receipt, and doctor reads existing facts rather than adding a new health or capability-state authority.

Bundled MCP (v0.3+): Preview (mcp/preview/) and Evidence (mcp/evidence/) runtimes ship inside this package and are registered by .mcp.json (${CLAUDE_PLUGIN_ROOT}). Sibling monorepo dirs remain compatibility launchers/docs. The orchestrator still probes MCP tools/list and skips preview* / observe* when tools are absent. Evidence provider writes artifacts only — never the manifest. DESIGN_PLAYBOOK_RUN_ROOT: .mcp.json forwards this variable via a standard env interpolation (${DESIGN_PLAYBOOK_RUN_ROOT:-}), without pinning a default. With no explicit root, artifacts resolve under the MCP process cwd, not necessarily the chat workspace. For a host-app run, use an absolute .scratch/<run>/ root; per-call overrides and marker requirements are documented in mcp/evidence/README.md. Capture responses include written_path (absolute) so mis-rooted writes are visible without a filesystem search.

What is deterministically enforced today: repository install/structure CI checks and the run-artifact shape (scripts/validate_run.py — L1–L6 present; every top-level L6 item ordered Given -> When -> Then; one non-empty four-field evidence ledger row per L6.<n> with allowed results; four non-empty finding fields with non-empty source; exactly one explicit ## Verdict of Pass or Recirculate; Pass requires every evidence result to be pass and exactly one issue-linked 0 blocking closure per blocking finding; exit 0/RUN OK, exit 1/RUN INVALID, exit 2/RUN ERROR; regression-tested by tests/test_validate_run.py, which also validates the showcase artifacts directly; G5 is a conditional preview-confirm gate — enforced only when preview artifacts exist / --preview-dir is used; G6 is a conditional evidence-binding gate — enforced only when a ledger observed references an evidence/ artifact / --evidence-dir is used; opt-in strict mode via --require-preview / --require-evidence / --strict). The observe* step probes MCP tool execute_capture_plan and is skipped when absent. Everything else in the pipeline is agent-executed craft judgment, not a machine gate.

Codex

See codex/AGENTS.md.