design-playbook 0.11.0 → 0.12.0

package/LICENSE

@@ -1,28 +1,28 @@
-MIT License
-
-Copyright (c) 2026 Bandersnatch0x and contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
----
-
-This LICENSE covers only the authored materials in this package (skills,
-commands, plugin metadata, and self-written examples). It does not grant
-rights to any third-party playbook manuscript, figures, or trademarks that may
-exist elsewhere in a parent monorepo for learning purposes.
+MIT License
+
+Copyright (c) 2026 Bandersnatch0x and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This LICENSE covers only the authored materials in this package (skills,
+commands, plugin metadata, and self-written examples). It does not grant
+rights to any third-party playbook manuscript, figures, or trademarks that may
+exist elsewhere in a parent monorepo for learning purposes.

package/NOTICE

@@ -1,37 +1,37 @@
-# NOTICE
-
-design-playbook is an original agent plugin (skills, commands, plugin metadata,
-workflow docs, and self-authored examples), licensed under MIT (see `LICENSE`).
-
-It is **not** a port, overlay, or redistribution of any third-party design
-playbook's manuscript, figures, brand marks, or demo site. No rights to such
-materials are claimed or granted here.
-
-The `native-craft` skill is a derivative of yetone/native-feel-skill (MIT). We
-authored our own Design I/O leaf and condensed its decision gate and native
-conventions audit in our own voice; the full depth (WebView survival, IPC
-contract, memory truths, Raycast evidence) remains in the original skill, which
-users may install separately. The MIT License of the original is reproduced
-below in full, as required for derivative works:
-
-  The MIT License (MIT)
-
-  Copyright (c) 2026 yetone
-
-  Permission is hereby granted, free of charge, to any person obtaining a copy
-  of this software and associated documentation files (the "Software"), to deal
-  in the Software without restriction, including without limitation the rights
-  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-  copies of the Software, and to permit persons to whom the Software is
-  furnished to do so, subject to the following conditions:
-
-  The above copyright notice and this permission notice shall be included in all
-  copies or substantial portions of the Software.
-
-  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-  SOFTWARE.
+# NOTICE
+
+design-playbook is an original agent plugin (skills, commands, plugin metadata,
+workflow docs, and self-authored examples), licensed under MIT (see `LICENSE`).
+
+It is **not** a port, overlay, or redistribution of any third-party design
+playbook's manuscript, figures, brand marks, or demo site. No rights to such
+materials are claimed or granted here.
+
+The `native-craft` skill is a derivative of yetone/native-feel-skill (MIT). We
+authored our own Design I/O leaf and condensed its decision gate and native
+conventions audit in our own voice; the full depth (WebView survival, IPC
+contract, memory truths, Raycast evidence) remains in the original skill, which
+users may install separately. The MIT License of the original is reproduced
+below in full, as required for derivative works:
+
+  The MIT License (MIT)
+
+  Copyright (c) 2026 yetone
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy
+  of this software and associated documentation files (the "Software"), to deal
+  in the Software without restriction, including without limitation the rights
+  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+  copies of the Software, and to permit persons to whom the Software is
+  furnished to do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in all
+  copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+  SOFTWARE.

package/README.md

@@ -1,144 +1,163 @@
-# 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](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) 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:
-
-```text
-/plugin marketplace add https://github.com/Bandersnatch0x/design-playbook.git
-/plugin install design-playbook@design-playbook
-```
-
-Local dev / self-test:
-
-```bash
-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).
-
-```bash
-codex plugin marketplace add Bandersnatch0x/design-playbook
-codex plugin add design-playbook@design-playbook
-```
-
-Local monorepo:
-
-```bash
-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:
-
-| 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 |
-
-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](https://pi.dev/packages).
-
-```bash
-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` | Pipeline / spec-only / review / cross-run 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`:
-
-```bash
-pi install npm:pi-mcp-adapter
-```
-
-```json
-{
-  "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
-
-| 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
-
-```text
-.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.
-
-**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: plugin install/structure (`scripts/validate.py`) 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`.
+# 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](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) 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:
+
+```text
+/plugin marketplace add https://github.com/Bandersnatch0x/design-playbook.git
+/plugin install design-playbook@design-playbook
+```
+
+Local dev / self-test:
+
+```bash
+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).
+
+```bash
+codex plugin marketplace add Bandersnatch0x/design-playbook
+codex plugin add design-playbook@design-playbook
+```
+
+Local monorepo:
+
+```bash
+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:
+
+| 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 |
+
+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](https://pi.dev/packages).
+
+```bash
+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` | Pipeline / spec-only / review / cross-run 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`:
+
+```bash
+pi install npm:pi-mcp-adapter
+```
+
+```json
+{
+  "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
+
+| 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
+
+```text
+.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
+
+```text
+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
+
+```text
+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`.

package/codex/AGENTS.md

@@ -0,0 +1,70 @@
+# design-playbook for Codex
+
+## Install (path of record)
+
+Marketplace catalog lives at the **repo root** (same GitHub repo as Claude Code).
+
+```bash
+# published
+codex plugin marketplace add Bandersnatch0x/design-playbook
+codex plugin add design-playbook@design-playbook
+
+# local monorepo (dev)
+codex plugin marketplace add <abs-path-to-repo-root>
+codex plugin add design-playbook@design-playbook
+```
+
+Verify:
+
+```bash
+codex plugin list -m design-playbook --available --json
+# expect: design-playbook@design-playbook, enabled=true after add
+```
+
+Codex-native manifest: `packages/design-playbook/.codex-plugin/plugin.json`  
+Codex MCP (relative paths, no `CLAUDE_PLUGIN_ROOT`): `.codex-plugin/mcp.json`  
+Skills: `packages/design-playbook/skills/*`
+
+## Fallback: skills-only install
+
+If you only want skills under `~/.codex/skills` (no plugin marketplace):
+
+```bash
+# from repo root — copies/symlinks skill trees into ~/.codex/skills
+python packages/design-playbook/codex/install_skills.py --force
+# or @-reference a single skill:
+#   @packages/design-playbook/skills/design-playbook/SKILL.md
+```
+
+Manual MCP (only if not using `codex plugin add`):
+
+```toml
+# ~/.codex/config.toml
+[mcp_servers.design-playbook-preview]
+command = "python"
+args = ["<abs>/packages/design-playbook/mcp/preview/server.py"]
+
+[mcp_servers.design-playbook-evidence]
+command = "python"
+args = ["<abs>/packages/design-playbook/mcp/evidence/server.py"]
+# evidence also needs: pip install playwright && playwright install chromium
+```
+
+## Load order
+
+1. `skills/design-playbook/SKILL.md`
+2. Standard order: `design-baseline?` → `ux-spec` → `ui-picker` → `fill` → `craft-guard` → `ui-evaluator`.
+
+Native desktop order: `ux-spec` → `native-craft` → `ui-picker` → `fill` → `craft-guard` → `ui-evaluator`.
+
+Conditional entry `reference-intake?` (screenshot/URL/design/product analogy, ADR-0011) runs **before** `ux-spec?` when reference materials are present — fixed orchestrator order, not reorderable. Run `native-craft` only for an explicit native-desktop/native-feel target. Web and mobile Web skip `native-craft`; if the platform is unclear, ask before choosing the order. The orchestrator owns the decision gate, render-surface seam handoff, and fail-closed behavior.
+
+Conditional entry `design-baseline?` (ADR-0012) runs before `reference-intake?` for UI builds/fixes in repositories with meaningful existing first-party UI. Existing-product Fill requires a valid existing baseline, an accepted generated baseline, or an explicit user waiver.
+
+Mirror the orchestrator's skip narration (SKILL.md Steps preamble): when a step is skipped, output one line — step name + reason + how to enable, with the gate label when one applies, e.g. `-> preview*: adapter absent, skipped (G5 not triggered; enable via packages/design-playbook/mcp/preview/ or host MCP)`.
+
+## Compose
+
+- Style DB → ui-ux-pro-max
+- Visual risk → frontend-design
+- Pipeline + acceptance → design-playbook

package/codex/install_skills.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Cross-platform Codex skill installer for design-playbook.
+
+Creates (or refreshes) symlinks under ``~/.codex/skills/<name>`` pointing at
+this package's ``skills/*`` directories. Falls back to directory copy when
+symlinks are unavailable (common on Windows without Developer Mode).
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import sys
+from pathlib import Path
+
+PACKAGE = Path(__file__).resolve().parents[1]
+SKILLS_SRC = PACKAGE / "skills"
+DEFAULT_DEST = Path.home() / ".codex" / "skills"
+
+
+def install_one(src: Path, dest: Path, *, force: bool) -> str:
+    if not src.is_dir():
+        return f"skip {src.name}: source missing"
+    if dest.exists() or dest.is_symlink():
+        if not force:
+            return f"skip {src.name}: {dest} exists (pass --force)"
+        if dest.is_symlink() or dest.is_file():
+            dest.unlink()
+        else:
+            shutil.rmtree(dest)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        os.symlink(src, dest, target_is_directory=True)
+        return f"link {src.name} -> {dest}"
+    except OSError:
+        shutil.copytree(src, dest)
+        return f"copy {src.name} -> {dest}"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Install design-playbook skills for Codex")
+    parser.add_argument(
+        "--dest",
+        type=Path,
+        default=DEFAULT_DEST,
+        help=f"skills directory (default: {DEFAULT_DEST})",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="replace existing skill directories/links",
+    )
+    args = parser.parse_args(argv)
+
+    if not SKILLS_SRC.is_dir():
+        print(f"skills source missing: {SKILLS_SRC}", file=sys.stderr)
+        return 2
+
+    print(f"source: {SKILLS_SRC}")
+    print(f"dest:   {args.dest}")
+    for skill in sorted(p for p in SKILLS_SRC.iterdir() if p.is_dir()):
+        print(" ", install_one(skill, args.dest / skill.name, force=args.force))
+    print("done. Load design-playbook via Codex skills or @ references.")
+    print("MCP: see packages/design-playbook/codex/AGENTS.md")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/commands/design-io.md

@@ -1,8 +1,8 @@
----
-description: Run Design I/O end-to-end (reference-intake? → spec? → plan? → shell → preview* → fill → craft → accept)
----
-
-Run skill **design-playbook** in full. Honor each step’s completion criterion before the next. Recirculate blocking evaluator findings to the owning declaration. Entry routing and plan/preview orchestration live in that skill (not here).
-
-User request:
-$ARGUMENTS
+---
+description: Run Design I/O end-to-end (reference-intake? → spec? → plan? → shell → preview* → fill → craft → accept)
+---
+
+Run skill **design-playbook** in full. Honor each step’s completion criterion before the next. Recirculate blocking evaluator findings to the owning declaration. Entry routing and plan/preview orchestration live in that skill (not here).
+
+User request:
+$ARGUMENTS

package/commands/doctor.md

@@ -0,0 +1,15 @@
+---
+description: Diagnose installed design-playbook capability and repairs
+---
+
+# doctor
+
+One packaged diagnosis entry for install/runtime capability.
+
+```text
+python <plugin>/scripts/doctor.py
+python <plugin>/scripts/doctor.py --json
+python <plugin>/scripts/doctor.py --run-root .scratch/<run>
+```
+
+Reports `ok` / `degraded` / `broken`. Failed checks include a concrete repair. Optional adapters (Playwright, run-root env) degrade rather than hard-fail the install.