design-playbook
Agent plugin: Design I/O for product UI (Claude Code / Codex).
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: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:ui-evaluator | Same eight skills as above |
/design-io · /ux-spec · /ui-review · /run-review · /run-status · /run-handoff · /doctor | Pipeline / spec-only / review / cross-run / status / handoff / health 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 (design-io, ux-spec, ui-review, run-review, run-status, run-handoff, doctor)
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.
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).
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: default "." in .mcp.json is the MCP process cwd, not the chat workspace — for a host-app dogfood, set an absolute path to .scratch/<run>/ (see 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.
