design-playbook 0.10.0 → 0.11.1

package/README.md

@@ -1,144 +1,144 @@
-# 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.
+
+**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`.

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/run-review.md

@@ -1,30 +1,30 @@
----
-description: Cross-run review of Design I/O runs — gate table + repeat blockers
----
-
-Cross-run **run review** over `.scratch/<run>/` dirs in the user project. Not a step of a single Design I/O run. Markdown only; report header **`run-review/v1`**.
-
-## Discover
-
-Scan user-side `.scratch/<run>/` (not monorepo `dogfood/*` globs). **Include** only dirs that have `point-back.md` (one table row each). List dirs without `point-back.md` as skipped + reason — they contribute **0** rows. If runs-with-point-back **< 2**, refuse and report that N.
-
-## Report (tables, in order)
-
-1. **Inclusion manifest** first: `path | status` (`included` / `skipped` + reason). Note: hash match ≠ honest transcription of `observed`.
-2. **Per-run table** — mandatory **run-path** column; other columns as needed; **gate** from real `validate_run.py` exit when the script is present (plugin install: `packages/design-playbook/scripts/validate_run.py` per run); else literal `not checked`. **Never** infer ok from "artifacts look complete".
-3. **Repeat blockers** — pure frequency table `count | runs | observed text` (verbatim first-seen text). A **repeat blocker** is the same normalized `observed` text recurring across runs (**counting, not judging**). Rows only where ledger `result != pass`. Grouping key = `observed` **casefold + whitespace-collapsed**, then **char-for-char** equality only; `count ≥ 2`. Literal differences stay separate; optional `similar:` pointer line, never merge counts. **`_none_` is normal** when nothing qualifies (do not loosen normalization to manufacture repeats).
-4. **Point-back** cites: path + verbatim `observed:` quote; no line numbers.
-5. Rollup numbers derived **row-by-row** from the tables above — no "overall it seems".
-
-Ledger row shape: **ui-evaluator** step 2 (do not restate).
-
-```
-禁止:
-- no new run ledger
-- no prose lessons / narrative "learning"
-- no auto-writeback to baseline
-- no semantic clustering of observed — verbatim grouping only
-```
-
-Scope:
-$ARGUMENTS
+---
+description: Cross-run review of Design I/O runs — gate table + repeat blockers
+---
+
+Cross-run **run review** over `.scratch/<run>/` dirs in the user project. Not a step of a single Design I/O run. Markdown only; report header **`run-review/v1`**.
+
+## Discover
+
+Scan user-side `.scratch/<run>/` (not monorepo `dogfood/*` globs). **Include** only dirs that have `point-back.md` (one table row each). List dirs without `point-back.md` as skipped + reason — they contribute **0** rows. If runs-with-point-back **< 2**, refuse and report that N.
+
+## Report (tables, in order)
+
+1. **Inclusion manifest** first: `path | status` (`included` / `skipped` + reason). Note: hash match ≠ honest transcription of `observed`.
+2. **Per-run table** — mandatory **run-path** column; other columns as needed; **gate** from real `validate_run.py` exit when the script is present (plugin install: `packages/design-playbook/scripts/validate_run.py` per run); else literal `not checked`. **Never** infer ok from "artifacts look complete".
+3. **Repeat blockers** — pure frequency table `count | runs | observed text` (verbatim first-seen text). A **repeat blocker** is the same normalized `observed` text recurring across runs (**counting, not judging**). Rows only where ledger `result != pass`. Grouping key = `observed` **casefold + whitespace-collapsed**, then **char-for-char** equality only; `count ≥ 2`. Literal differences stay separate; optional `similar:` pointer line, never merge counts. **`_none_` is normal** when nothing qualifies (do not loosen normalization to manufacture repeats).
+4. **Point-back** cites: path + verbatim `observed:` quote; no line numbers.
+5. Rollup numbers derived **row-by-row** from the tables above — no "overall it seems".
+
+Ledger row shape: **ui-evaluator** step 2 (do not restate).
+
+```
+禁止:
+- no new run ledger
+- no prose lessons / narrative "learning"
+- no auto-writeback to baseline
+- no semantic clustering of observed — verbatim grouping only
+```
+
+Scope:
+$ARGUMENTS