design-playbook 0.7.0

package/LICENSE

@@ -0,0 +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.

package/NOTICE

@@ -0,0 +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.

package/README.md

@@ -0,0 +1,143 @@
+# 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 <owner>/<repo>
+/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 |
+
+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` | Pipeline / spec-only / review 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 only)
+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

@@ -0,0 +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

package/commands/ui-review.md

@@ -0,0 +1,8 @@
+---
+description: Declaration-backed UI review with point-back findings
+---
+
+Run skill **ui-evaluator** (pull craft-guard checks when AI slop/motion/loading is in scope). Output issue/source/fix/severity; blocking first.
+
+Scope:
+$ARGUMENTS

package/commands/ux-spec.md

@@ -0,0 +1,8 @@
+---
+description: Six-layer spec.md only (stop before UI shell/code)
+---
+
+Run skill **ux-spec** only. Emit complete `spec.md`. Do not pick templates or write UI.
+
+Request:
+$ARGUMENTS

package/mcp/_transport.py

@@ -0,0 +1,242 @@
+"""Shared stdio JSON-RPC framing + single-tool dispatch for the bundled MCP servers.
+
+Both the preview and evidence adapters speak the same wire format
+(Content-Length- or newline-delimited JSON-RPC over stdio) and run the same
+JSON-RPC dispatch (initialize / tools/list / tools/call / ping /
+method-not-found). This module owns both once so the two servers keep them in
+lockstep (ADR-0009 bundled layout). Each server runs in its own process, so
+the module-level framing state is per-process and never shared across servers.
+
+The one policy that is deliberately per-server is malformed-input recovery,
+expressed as the ``recover_from_malformed`` flag on :func:`serve_stdio`:
+``read_message`` always raises on a bad frame; preview re-raises it
+(fail-fast — the server ends), while evidence catches it, replies ``-32700``
+/ ``-32600``, and keeps serving (fail-soft — one bad client frame cannot abort
+a capture run).
+"""
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, Callable
+
+STDIO_FRAMING_CONTENT_LENGTH = "content-length"
+STDIO_FRAMING_NEWLINE = "newline"
+_stdio_framing: str | None = None
+
+
+class ToolError(Exception):
+    """Recoverable domain error with MCP structured error content."""
+
+    def __init__(self, message: str, structured_content: dict[str, Any]):
+        super().__init__(message)
+        self.structured_content = structured_content
+
+
+def read_message() -> dict[str, Any] | None:
+    """Read one Content-Length- or newline-delimited JSON-RPC message.
+
+    Returns None at EOF. Raises json/unicode/value/EOF errors on a bad
+    frame; the caller decides the recovery policy (see module docstring).
+    """
+    global _stdio_framing
+
+    while True:
+        first_line = sys.stdin.buffer.readline()
+        if not first_line:
+            return None
+        if first_line not in (b"\r\n", b"\n"):
+            break
+
+    if not first_line.lower().startswith(b"content-length:"):
+        _stdio_framing = STDIO_FRAMING_NEWLINE
+        return json.loads(first_line.decode("utf-8"))
+
+    _stdio_framing = STDIO_FRAMING_CONTENT_LENGTH
+    headers: dict[str, str] = {}
+    line = first_line
+    while line not in (b"\r\n", b"\n"):
+        key, separator, value = line.decode("utf-8").partition(":")
+        if not separator:
+            raise ValueError(f"invalid MCP stdio header: {line!r}")
+        headers[key.strip().lower()] = value.strip()
+        line = sys.stdin.buffer.readline()
+        if not line:
+            raise EOFError("MCP stdio headers ended before the blank line")
+    length = int(headers.get("content-length", "0"))
+    if length <= 0:
+        raise ValueError("MCP stdio Content-Length must be positive")
+    body = sys.stdin.buffer.read(length)
+    if len(body) != length:
+        raise EOFError(
+            f"MCP stdio body ended early: expected {length}, got {len(body)}"
+        )
+    return json.loads(body.decode("utf-8"))
+
+
+def write_message(payload: dict[str, Any]) -> None:
+    """Write one JSON-RPC message in the framing detected by read_message."""
+    raw = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+    if _stdio_framing == STDIO_FRAMING_NEWLINE:
+        sys.stdout.buffer.write(raw + b"\n")
+    else:
+        sys.stdout.buffer.write(
+            f"Content-Length: {len(raw)}\r\n\r\n".encode("ascii") + raw
+        )
+    sys.stdout.buffer.flush()
+
+
+def _result_text(payload: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "content": [
+            {
+                "type": "text",
+                "text": json.dumps(payload, ensure_ascii=False, indent=2),
+            }
+        ],
+        "structuredContent": payload,
+        "isError": False,
+    }
+
+
+def _error_result(
+        message: str, structured_content: dict[str, Any] | None = None
+) -> dict[str, Any]:
+    result: dict[str, Any] = {
+        "content": [{"type": "text", "text": message}],
+        "isError": True,
+    }
+    if structured_content is not None:
+        result["structuredContent"] = structured_content
+    return result
+
+
+def _exception_result(exc: Exception) -> dict[str, Any]:
+    structured = exc.structured_content if isinstance(exc, ToolError) else None
+    return _error_result(str(exc), structured)
+
+
+def serve_stdio(
+        server_name: str,
+        server_version: str,
+        tool_schema: dict[str, Any],
+        handle_tool: Callable[[dict[str, Any]], dict[str, Any]],
+        *,
+        recover_from_malformed: bool) -> None:
+    """Run the shared single-tool MCP stdio dispatch loop (ADR-0009).
+
+    Both bundled adapters speak the same JSON-RPC protocol; owning the
+    dispatch once here keeps initialize / tools/list / tools/call / ping /
+    method-not-found in lockstep instead of copy-pasted in each server.
+
+    ``tool_schema`` is the single advertised tool (its ``name`` is the
+    accepted ``tools/call`` name); ``handle_tool`` maps the call's
+    ``arguments`` to the payload returned to the client. A raised exception
+    becomes a tool-level error result (``isError: true``); a returned dict
+    is the structured success payload.
+
+    The one deliberately per-server policy is malformed-input recovery (see
+    module docstring):
+
+      * ``recover_from_malformed=False`` (preview): a bad frame or a
+        non-object request propagates and ends the server (fail-fast).
+      * ``recover_from_malformed=True`` (evidence): reply ``-32700`` (bad
+        frame) or ``-32600`` (non-object request) and keep serving, so one
+        bad client frame cannot abort a capture run.
+    """
+    print(f"{server_name} MCP server starting (stdio)",
+          file=sys.stderr, flush=True)
+    while True:
+        try:
+            msg = read_message()
+        except (json.JSONDecodeError, UnicodeDecodeError,
+                ValueError, EOFError) as exc:
+            if not recover_from_malformed:
+                raise
+            print(f"MCP parse error: {exc}", file=sys.stderr, flush=True)
+            write_message({
+                "jsonrpc": "2.0",
+                "id": None,
+                "error": {"code": -32700, "message": f"Parse error: {exc}"},
+            })
+            continue
+        if msg is None:
+            break
+        if recover_from_malformed and not isinstance(msg, dict):
+            write_message({
+                "jsonrpc": "2.0",
+                "id": None,
+                "error": {"code": -32600, "message": "Invalid Request"},
+            })
+            continue
+
+        method = msg.get("method")
+        msg_id = msg.get("id")
+        params = msg.get("params") or {}
+
+        if method == "initialize":
+            write_message({
+                "jsonrpc": "2.0",
+                "id": msg_id,
+                "result": {
+                    "protocolVersion": params.get(
+                        "protocolVersion", "2024-11-05"),
+                    "capabilities": {"tools": {}},
+                    "serverInfo": {
+                        "name": server_name,
+                        "version": server_version,
+                    },
+                },
+            })
+            continue
+
+        if method == "notifications/initialized":
+            continue
+
+        if method == "tools/list":
+            write_message({
+                "jsonrpc": "2.0",
+                "id": msg_id,
+                "result": {"tools": [tool_schema]},
+            })
+            continue
+
+        if method == "tools/call":
+            name = params.get("name")
+            arguments = params.get("arguments") or {}
+            if name != tool_schema["name"]:
+                write_message({
+                    "jsonrpc": "2.0",
+                    "id": msg_id,
+                    "result": _error_result(f"unknown tool: {name}"),
+                })
+                continue
+            try:
+                payload = handle_tool(arguments)
+                write_message({
+                    "jsonrpc": "2.0",
+                    "id": msg_id,
+                    "result": _result_text(payload),
+                })
+            except Exception as exc:  # noqa: BLE001 — return to client
+                print(f"tools/call error: {exc}", file=sys.stderr, flush=True)
+                write_message({
+                    "jsonrpc": "2.0",
+                    "id": msg_id,
+                    "result": _exception_result(exc),
+                })
+            continue
+
+        if method == "ping":
+            write_message({"jsonrpc": "2.0", "id": msg_id, "result": {}})
+            continue
+
+        if msg_id is not None:
+            write_message({
+                "jsonrpc": "2.0",
+                "id": msg_id,
+                "error": {
+                    "code": -32601,
+                    "message": f"Method not found: {method}",
+                },
+            })

package/mcp/evidence/README.md

@@ -0,0 +1,40 @@
+# Evidence MCP adapter (`execute_capture_plan`)
+
+Runtime for the optional **observe\*** step. Writes capture artifacts only — **never** `manifest.jsonl`, never judges L6.
+
+## `DESIGN_PLAYBOOK_RUN_ROOT`
+
+| Setting | Meaning |
+| --- | --- |
+| Unset | Artifact paths resolve under the **MCP process cwd** |
+| `"."` (default in package `.mcp.json`) | Same — relative to process cwd, **not** the chat workspace root |
+| Absolute path | Preferred for cross-repo dogfood: set to the run root (e.g. `D:/…/nmg_bup_h5/.scratch/playbook-smoke/<run>`) so `evidence/L6.*.png` lands next to `manifest.jsonl` |
+
+Relative values are resolved with `Path(value).resolve()` at process start semantics (cwd-relative). If captures appear under the plugin monorepo instead of the host run, check cwd and this env — the tool also returns **`written_path`** (absolute) so mis-roots are obvious without a filesystem search.
+
+Example (host run):
+
+```json
+"env": {
+  "DESIGN_PLAYBOOK_RUN_ROOT": "D:/code_space/app/.scratch/my-run"
+}
+```
+
+Plugin auto-load: [`../.mcp.json`](../.mcp.json) (under `packages/design-playbook/`).  
+Codex / manual: sibling [`mcp.example.toml`](../../../design-playbook-evidence/mcp.example.toml).
+
+## Return shape
+
+`artifact` (run-root-relative) · `observed_state` (from page `data-state`, else `unknown`) · `result` · `error` · **`written_path`** (absolute).
+
+Orchestrator bind rules (verbatim `observed_state`, per-capture append, mirror surface notes): `skills/design-playbook/SKILL.md` step 8.
+
+## Mirror pages and `data-state`
+
+When capture uses a semantic mirror (not the live Fill host), set a root marker the provider can read:
+
+```html
+<body data-state="error">…</body>
+```
+
+`observed_state` comes only from that probe (else `unknown`). Do not overwrite it in the manifest with the request's `state` field.