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, or any of 22 Tier-3 agents:

npx design-playbook init <agent>   # e.g. cursor, gemini-cli, windsurf
npx design-playbook --list         # all 29 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.