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](codex/AGENTS.md).

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

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>:

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.

Stack with other skills

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)
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.

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.

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](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.