@brunosps00/dev-workflow 1.6.0 → 1.7.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "dev-workflow",
   "description": "Standalone, à-la-carte skills from the dev-workflow pipeline: minimalism, search-first, simplification, verification, security review, and more.",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "author": {
     "name": "Bruno Santos"
   },

package/README.md

@@ -42,7 +42,7 @@ Exportable skills (no `.dw/` pipeline required): `dw-minimalism`, `dw-search-fir
 
 ## Commands
 
-dev-workflow v1.6.0 ships **37 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
+dev-workflow v1.7.0 ships **38 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
 
 ### Tier 1 — Gateway (3)
 

package/lib/constants.js

@@ -22,6 +22,7 @@ const COMMANDS = {
     { name: 'dw-intel', description: 'Codebase intelligence: query mode (default) answers questions citing .dw/intel/ + .dw/rules/; --build mode (re)builds the index.' },
     { name: 'dw-learn', description: 'Synthesizes durable decisions, bugfixes, deviations, and git history into atomic confidence-weighted instincts you approve; can propose constitution principles. On-demand and human-in-the-loop — no always-on observer.' },
     { name: 'dw-new-project', description: 'Interviews you about stack and infra, then scaffolds a working monorepo with docker-compose for dev, .env, scripts, CI, and seeded rules.' },
+    { name: 'dw-open-design', userInvoked: true, description: 'Trigger when user asks to generate, iterate, or refactor/redesign headless Open Design HTML prototypes via the od CLI. Imports a target folder with isolated OD_DATA_DIR, refines briefs before dispatch, supports --refactor screenshots via --url/--viewports or --screenshot, runs web-prototype briefs with explicit --agent codex|claude, verifies files, captures JSONL audit logs, and stops for a dual >=9 visual gate.' },
     { name: 'dw-opportunities', description: 'Scans the installed project for product, UX, automation, refactor, and security opportunities, then routes each idea to the right next dw-* command.' },
     { name: 'dw-pause', description: 'Trigger when user says "pause work", "end session", or "save where we are". Consolidates open loops, decisions, blockers, and todos into .dw/STATE.md so the next session can resume.' },
     { name: 'dw-plan', description: 'Trigger when user has a feature idea and needs spec + architecture + tasks. Runs PRD → TechSpec → Tasks sequentially. Stages: prd / techspec / tasks; --from techspec; --council.' },
@@ -61,6 +62,7 @@ const COMMANDS = {
     { name: 'dw-intel', description: 'Inteligencia do codebase: modo query (default) responde citando .dw/intel/ + .dw/rules/; modo --build (re)constroi indice.' },
     { name: 'dw-learn', description: 'Sintetiza decisoes duraveis, bugfixes, deviations e historico git em instincts atomicos ponderados por confianca que voce aprova; pode propor principios de constitution. On-demand e human-in-the-loop — sem observador sempre-ligado.' },
     { name: 'dw-new-project', description: 'Entrevista voce sobre stack e infra, depois faz scaffold de um monorepo com docker-compose para dev, .env, scripts, CI e rules seed.' },
+    { name: 'dw-open-design', userInvoked: true, description: 'Trigger quando usuario pede para gerar, iterar ou refatorar/redesenhar prototipos HTML headless do Open Design via od CLI. Importa pasta alvo com OD_DATA_DIR isolado, refina briefs antes de despachar, suporta prints --refactor via --url/--viewports ou --screenshot, roda briefs web-prototype com --agent codex|claude explicito, verifica arquivos, captura logs JSONL e para para gate visual dual >=9.' },
     { name: 'dw-opportunities', description: 'Escaneia o projeto instalado por oportunidades de produto, UX, automacao, refactor e seguranca, e roteia cada ideia para o proximo comando dw-* correto.' },
     { name: 'dw-pause', description: 'Trigger quando usuario diz "pausa o trabalho", "encerra a sessao" ou "salva onde paramos". Consolida pontas soltas, decisoes, bloqueios e todos em .dw/STATE.md para a proxima sessao retomar.' },
     { name: 'dw-plan', description: 'Trigger quando usuario tem ideia de feature e precisa spec + arquitetura + tasks. Roda PRD → TechSpec → Tasks sequencial. Stages: prd / techspec / tasks; --from techspec; --council.' },

package/lib/install-deps.js

@@ -1,4 +1,5 @@
 const { execSync } = require('child_process');
+const openDesign = require('./install-open-design');
 
 function run() {
   console.log('\n  dev-workflow install-deps');
@@ -84,6 +85,12 @@ function run() {
         'Verify after install:  docker --version && docker compose version',
       ],
     },
+    {
+      name: 'Open Design CLI (od)',
+      check: openDesign.check,
+      install: openDesign.install,
+      instructions: openDesign.instructions(),
+    },
   ];
 
   let installed = 0;
@@ -113,12 +120,26 @@ function run() {
 
     process.stdout.write(`  Installing ${dep.name}...`);
     try {
-      execSync(dep.install, { stdio: 'pipe', timeout: 300000 });
+      if (typeof dep.check === 'function' && dep.check()) {
+        console.log(' \x1b[32m✓ already installed\x1b[0m');
+        installed++;
+        continue;
+      }
+      if (typeof dep.install === 'function') {
+        dep.install();
+      } else {
+        execSync(dep.install, { stdio: 'pipe', timeout: 300000 });
+      }
       console.log(' \x1b[32m✓\x1b[0m');
       installed++;
     } catch (err) {
       console.log(' \x1b[31m✗\x1b[0m');
       console.log(`    Error: ${err.message.split('\n')[0]}`);
+      if (Array.isArray(dep.instructions)) {
+        for (const line of dep.instructions) {
+          console.log(`    ${line}`);
+        }
+      }
       failed++;
     }
   }

package/lib/install-open-design.js

@@ -0,0 +1,89 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const OPEN_DESIGN_REPO = 'https://github.com/nexu-io/open-design';
+const OPEN_DESIGN_REF = '1cb7eae';
+const OPEN_DESIGN_VENDOR_DIR = path.join(os.homedir(), '.dw', 'vendor', 'open-design');
+
+function odBin(dir = OPEN_DESIGN_VENDOR_DIR) {
+  return path.join(dir, 'apps', 'daemon', 'bin', 'od.mjs');
+}
+
+function check() {
+  return fs.existsSync(odBin());
+}
+
+function install() {
+  checkPrerequisites();
+
+  fs.mkdirSync(path.dirname(OPEN_DESIGN_VENDOR_DIR), { recursive: true });
+  if (!fs.existsSync(path.join(OPEN_DESIGN_VENDOR_DIR, '.git'))) {
+    if (fs.existsSync(OPEN_DESIGN_VENDOR_DIR)) {
+      throw new Error(`${OPEN_DESIGN_VENDOR_DIR} exists but is not a git checkout; move it aside and retry.`);
+    }
+    execFileSync('git', ['clone', OPEN_DESIGN_REPO, OPEN_DESIGN_VENDOR_DIR], { stdio: 'pipe', timeout: 600000 });
+  }
+
+  execFileSync('git', ['fetch', '--tags', '--force', 'origin'], { cwd: OPEN_DESIGN_VENDOR_DIR, stdio: 'pipe', timeout: 600000 });
+  execFileSync('git', ['checkout', OPEN_DESIGN_REF], { cwd: OPEN_DESIGN_VENDOR_DIR, stdio: 'pipe', timeout: 120000 });
+  execFileSync('pnpm', ['install', '--frozen-lockfile'], { cwd: OPEN_DESIGN_VENDOR_DIR, stdio: 'pipe', timeout: 1200000 });
+
+  if (!check()) {
+    throw new Error(`Open Design install finished but ${odBin()} was not found.`);
+  }
+}
+
+function instructions() {
+  return [
+    'Open Design CLI is provisioned by dev-workflow into a managed checkout:',
+    `  ${OPEN_DESIGN_VENDOR_DIR}`,
+    `  repo: ${OPEN_DESIGN_REPO}`,
+    `  pinned ref: ${OPEN_DESIGN_REF}`,
+    '',
+    'Prerequisites:',
+    '  Node.js ~24: install with fnm/nvm/asdf, then verify: node -v',
+    '  pnpm >=10.33: corepack enable && corepack prepare pnpm@10.33.2 --activate',
+    '  git: required to clone the upstream monorepo',
+    '',
+    'Then run: dev-workflow install-deps',
+    'To use your own checkout instead of the managed one, set OD_CLI_DIR=/path/to/open-design.',
+  ];
+}
+
+function checkPrerequisites() {
+  const nodeVersion = process.versions.node;
+  const nodeMajor = Number(nodeVersion.split('.')[0]);
+  if (nodeMajor !== 24) {
+    throw new Error(`Open Design requires Node.js ~24; detected ${nodeVersion}.`);
+  }
+
+  const pnpmRaw = execFileSync('pnpm', ['-v'], { stdio: 'pipe', timeout: 10000 }).toString().trim();
+  if (!isAtLeast(pnpmRaw, '10.33.0')) {
+    throw new Error(`Open Design requires pnpm >=10.33; detected ${pnpmRaw}.`);
+  }
+
+  execFileSync('git', ['--version'], { stdio: 'pipe', timeout: 10000 });
+}
+
+function isAtLeast(actual, minimum) {
+  const a = actual.split('.').map((part) => Number(part));
+  const b = minimum.split('.').map((part) => Number(part));
+  for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+    const av = a[index] || 0;
+    const bv = b[index] || 0;
+    if (av > bv) return true;
+    if (av < bv) return false;
+  }
+  return true;
+}
+
+module.exports = {
+  OPEN_DESIGN_REF,
+  OPEN_DESIGN_VENDOR_DIR,
+  check,
+  install,
+  instructions,
+  odBin,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosps00/dev-workflow",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "AI-driven development workflow commands for any project. Scaffolds a complete PRD-to-PR pipeline with multi-platform AI assistant support.",
   "bin": {
     "dev-workflow": "./bin/dev-workflow.js"

package/scaffold/en/commands/dw-help.md

@@ -38,12 +38,13 @@ Use `/dw-autopilot "wish"` as the gateway for most feature work. The granular co
 | `/dw-commit` | Atomic Conventional Commits for pending work. |
 | `/dw-generate-pr [target]` | Push branch, draft PR body, open browser. |
 
-## Tier 3 — Specialty (11)
+## Tier 3 — Specialty (12)
 
 | Command | What |
 |---------|------|
 | `/dw-analyze-project` | Scan the repo, write `.dw/rules/`, offer `.dw/constitution.md`, generate `.dw/rules/concerns.md`, and synthesize frontend `DESIGN.md` when tokens exist. |
 | `/dw-redesign-ui "target"` | Audit, propose 2-3 design directions, ship. Enforces UI grounding + WCAG; can run the deterministic impeccable slop detector. |
+| `/dw-open-design --brief <file>` | Generate, iterate, or `--refactor` headless Open Design HTML prototypes via `od`; refines briefs first, can capture current screenshots with `--url --viewports` or `--screenshot`, then verifies file + visual gate. |
 | `/dw-refactor "target"` | Audit code-health and tech debt with Fowler smells, deep-modules analysis, and behavior-preserving test gates. |
 | `/dw-functional-doc` | Map screens + flows into a functional doc validated with Playwright; uses WSL-resilient browser resolution. |
 | `/dw-context-budget` | Audit context overhead from commands, skills, agents, instructions, and MCPs. |
@@ -112,6 +113,7 @@ Match the keyword and suggest:
 | `research`, `compare`, `state of the art` | `/dw-brainstorm --research` |
 | `refactor`, `smell`, `code health`, `tech debt` | `/dw-refactor` |
 | `ui`, `design`, `redesign` | `/dw-redesign-ui` |
+| `open design`, `prototype`, `prototipo`, `od cli`, `html prototype` | `/dw-open-design --brief <file>`, `/dw-open-design --brief-glob "<glob>" --agent claude`, or `/dw-open-design --refactor --url <url> --viewports "1440x900,375x812"` |
 | `intel`, `where is`, `what uses` | `/dw-intel` (or `--build` to (re)create the index) |
 | `context`, `tokens`, `slow agent` | `/dw-context-budget` |
 | `harness`, `install`, `wrappers`, `agents` | `/dw-harness-audit` |

package/scaffold/en/commands/dw-open-design.md

@@ -0,0 +1,324 @@
+<system_instructions>
+You are the **headless Open Design (`od`) runner** for generating and iterating HTML prototypes in a project
+folder, without Electron and without depending on the user's GUI state. Start the `nexu-io/open-design` daemon in
+`--headless`, import the target folder once, run single briefs or serial batches, verify the output file, run the
+Playwright/Firefox visual gate, and **STOP for the owner's gate** before any commit.
+
+<critical>NEVER use the user's GUI state. Always run with an isolated per-project `OD_DATA_DIR`, for example `.dw/.open-design/data/`.</critical>
+<critical>NEVER commit a rejected prototype. The gate is dual >=9: automated gate + your own visual score >=9, then owner gate.</critical>
+<critical>The agent (`codex` or `claude`) must always be explicit in `od run start --agent <agent>`. If the user does not pass one, resolve from project config/state; fallback `codex`.</critical>
+<critical>NEVER dispatch the user's raw request to `od`. This command's value is refining the prompt first: ground it in real code, structure the brief, qualify states/themes/a11y/deep-link, persist the reviewable brief, and only then append the headless appendix.</critical>
+
+## Inputs
+
+| Flag/argument | Default | Description |
+|---|---:|---|
+| `--target <dir>` | `open-design/` | Folder imported as the external project and where HTML files are written. |
+| `--brief <file>` | none | One markdown brief for a single run. |
+| `--brief-glob <glob>` | none | Serial batch. Expand to a stable list and run one prompt at a time. |
+| `--output <file>` | required in the brief/appendix | Expected HTML file; verify it on disk after the run. |
+| `--agent <codex|claude>` | state/config -> `codex` | Agent forwarded to `od run start --agent`. |
+| `--platform <text>` | `Responsive web, desktop-first and mobile-safe` | Pre-filled discovery answer for the `web-prototype` skill. |
+| `--deep-link-id <id>` | none | Value used by the behavioral gate for `?aberto=<id>` + Esc. |
+| `--refactor` | false | Existing-screen redesign/refactor mode; captures current screenshots and grounds the brief in visible state + real code. |
+| `--url <url>` | none | Running app URL for current screenshot capture via Playwright Firefox. |
+| `--viewports <list>` | `1440x900,375x812` | Comma-separated viewports for `--refactor --url`; expand as the pain requires (for example `1920x1080` for a wide table). |
+| `--screenshot <path>` | repeatable | Already-captured current screenshot when there is no `--url`; copy it into `_refs/<slug>/`. |
+
+## 0. Refine The Brief
+
+Before any daemon pre-flight or `od` call, turn the user's intent into a qualified brief. Do not send the user's raw
+sentence to the runner.
+
+Required contract:
+
+| Step | Requirement |
+|---|---|
+| Ground in reality | If the screen exists, read its real code: columns, enums, actions, states, permissions, contracts, and domain. Also read the project's design system, sibling prototypes, and design guides. Inventing a field, status, or action is forbidden. |
+| Structure | Rewrite the request into the standard skeleton below, filling real paths and the exact output file. |
+| Qualify | Cover loading/skeleton, empty, error/failure, light + dark, a11y, local design-system limits (for example <=6 cards/filters), responsiveness, and deep-link. |
+| Persist | Save the refined brief inside the project, for example `<target>/PROMPT-<slug>.md`. It is a reviewable owner deliverable, not a disposable scratch file. |
+| Review if already ready | If the user already provides a qualified brief, do a quick checklist review, patch only gaps, and persist the final version. |
+
+Standard refined brief skeleton:
+
+```markdown
+# <screen/prototype title>
+
+Paste this brief into Open Design. Exact output file: `<OUTPUT_FILE>`.
+
+## 1. Why
+<real user/product pain; observable problem this prototype must solve>
+
+## 2. Interaction Decision
+<navigation, opening, selection, filters, sorting, editing, and confirmation pattern>
+
+## 3. Layout/List
+Table/list based only on REAL columns:
+
+| Real column | Source/contract | Presentation | State/limit |
+|---|---|---|---|
+| <name> | <file/API/schema> | <text, badge, action> | <truncate, empty, error> |
+
+## 4. Detail/Actions
+<drawer/modal/detail page; contextual actions allowed by real state/permission>
+
+## 5. Domain Fidelity
+So the mock does not lie: use real enums/statuses, realistic sample data in the project's language, and include rare/broken states that exist in the domain.
+
+## 6. Visual Direction
+<tokens, components, density, inherited references, sibling prototypes, and design-system limits>
+
+## Deliver
+- `<OUTPUT_FILE>`
+- `<OUTPUT_FILE>.artifact.json` when there is a sidecar
+```
+
+Only after persisting this file should you append the headless appendix under `.dw/.open-design/runs/` and dispatch
+the run.
+
+### 0R. Refactor/Redesign Mode
+
+When `--refactor` is present, phase 0 remains mandatory. Screenshots complement grounding in code; they do not
+replace reading contracts, enums, permissions, states, the design system, and sibling prototypes.
+
+Capture or copy current screenshots into the imported folder, under `_refs/<slug>/`, before persisting the brief:
+
+```bash
+node .dw/scripts/open-design/capture-current.mjs \
+  --target "$TARGET_DIR" \
+  --slug "<slug>" \
+  --url "<url>" \
+  --viewports "1440x900,375x812"
+```
+
+Without a running app URL, accept existing screenshots by repeating `--screenshot`:
+
+```bash
+node .dw/scripts/open-design/capture-current.mjs \
+  --target "$TARGET_DIR" \
+  --slug "<slug>" \
+  --screenshot "./before-1440-light.png" \
+  --screenshot "./before-375-dark.png"
+```
+
+Capture rules:
+
+| Case | Requirement |
+|---|---|
+| Viewports | Sensible default: desktop `1440x900` + mobile `375x812`. The agent chooses/expands as the pain requires: mobile bug includes `375x812`; wide table includes `1920x1080`; tablet/console includes `768x1024`. |
+| Themes | Capture light and dark when applicable. The helper uses `light,dark` by default and writes names like `_refs/<slug>/atual-1440-light.png` and `_refs/<slug>/atual-375-dark.png`. |
+| Robust path | The `od` agent reads images from the project filesystem. Reference relative paths inside the target; do not depend on an image flag in `run start`. |
+| Hygiene | `_refs/` and reference material must not become prototypes. If the target project tracks final prototypes, document cleanup or add `<target>/_refs/` to `.gitignore` according to local convention. |
+
+The refined refactor brief must add this block:
+
+```markdown
+## Current Screen References
+Open and ANALYZE the screenshots before writing:
+- `_refs/<slug>/atual-1440-light.png`
+- `_refs/<slug>/atual-375-dark.png`
+
+## What Is Wrong Today
+<pain pointing to visible elements in the screenshots: density, hierarchy, table, filters, states, contrast, mobile, etc.>
+
+## The Change Idea
+<what changes and why; interaction/visual decision proposed by the user or by the agent after reading code and screenshots>
+
+## Preserve
+<flows, fields, permissions, states, copy, affordances, and integrations that must not change>
+```
+
+## Pre-flight
+
+| Check | Action |
+|---|---|
+| Resolve `od` | `OD_CLI_DIR` wins. Otherwise use `~/.dw/vendor/open-design`. If `apps/daemon/bin/od.mjs` is missing, stop and tell the user to run `dev-workflow install-deps`. |
+| Prerequisites | The Open Design checkout requires Node `~24` and pnpm `>=10.33`. If missing, stop with concrete instructions. |
+| Isolated state | Create `.dw/.open-design/`, `.dw/.open-design/data/`, `.dw/.open-design/runs/`, and `.dw/.open-design/state.json`. |
+| Port | Pick a free port on `127.0.0.1`; persist `daemonUrl` and `port` in state. |
+| Live daemon | If `od daemon status --daemon-url <url> --json` returns `ok: true`, reuse it. Otherwise start a new daemon. |
+
+Daemon command shape:
+
+```bash
+OD_DATA_DIR="$PWD/.dw/.open-design/data" \
+OD_CHAT_RUN_INACTIVITY_TIMEOUT_MS=1800000 \
+node "$OD_DIR/apps/daemon/bin/od.mjs" daemon start \
+  --headless \
+  --host 127.0.0.1 \
+  --port "$PORT"
+```
+
+Known noise: `codex_core::shell_snapshot` may log a syntax `ERROR`. Treat it as benign when the run continues and
+the target file is created.
+
+## Idempotent Import
+
+Use `project import-folder` on the resolved absolute target folder. Default: `<repo>/open-design/`.
+
+Persist in `.dw/.open-design/state.json`:
+
+```json
+{
+  "schema_version": "1.0",
+  "targetDir": "/abs/repo/open-design",
+  "projectId": "<project.id>",
+  "conversationId": "<conversationId>",
+  "daemonUrl": "http://127.0.0.1:<port>",
+  "port": 17556,
+  "agent": "codex"
+}
+```
+
+If `projectId` exists in state and `od project info <id> --daemon-url <url> --json` works for the same `targetDir`,
+reuse it. Otherwise, reimport:
+
+```bash
+node "$OD_DIR/apps/daemon/bin/od.mjs" project import-folder "$TARGET_DIR" \
+  --daemon-url "$OD_URL" \
+  --name "$(basename "$TARGET_DIR")" \
+  --skill web-prototype \
+  --design-system default \
+  --json
+```
+
+Capture `project.id` and `conversationId`; do not depend on global app state.
+
+## Required Headless Appendix
+
+Append this block to every brief in a temporary file under `.dw/.open-design/runs/`.
+Fill `<PLATFORM>`, `<OUTPUT_FILE>`, and sibling references when applicable.
+
+```markdown
+---
+
+## Headless appendix for Open Design
+
+Target platform: <PLATFORM>.
+
+Do not run discovery and do not ask questions. Do not emit `<question-form>`. Follow this brief with the answers
+above and deliver file-first.
+
+Required output file: `<OUTPUT_FILE>`.
+
+File-first contract:
+- Write the HTML directly to the project filesystem, exactly at `<OUTPUT_FILE>`.
+- Do not alter existing files, except when this prompt is explicitly a surgical iteration on a target file.
+- If you need to create a sidecar, keep `<OUTPUT_FILE>.artifact.json` coherent.
+- Do not answer only with a textual `<artifact>` block; run `succeeded` without the file is a failure.
+
+To avoid headless timeout:
+- Write large files in parts, with edits of about 150 lines per call.
+- Keep visible progress until the HTML is complete.
+
+Consistency context:
+- Read sibling prototypes in `prototipos/` or the folder named by the brief before defining visual patterns.
+- Preserve the local visual system when a nearby reference exists.
+
+Required deep link:
+- Implement `?aberto=<id>` to open the correct item's drawer/modal.
+- On Esc or close action, clear the parameter with `history.replaceState`.
+- The drawer/modal must use `role="dialog"` and appropriate ARIA attributes.
+- Include skeleton/loading, empty, and error states.
+```
+
+## Single Run
+
+Always pass `--agent` explicitly:
+
+```bash
+node "$OD_DIR/apps/daemon/bin/od.mjs" run start \
+  --daemon-url "$OD_URL" \
+  --project "$PROJECT_ID" \
+  --conversation "$CONVERSATION_ID" \
+  --agent "$AGENT" \
+  --skill web-prototype \
+  --design-system default \
+  --prompt-file "$PROMPT_WITH_APPENDIX" \
+  --follow \
+  --json | tee ".dw/.open-design/runs/<slug>.jsonl"
+```
+
+After the run, check the file. **Do not accept only `succeeded`:**
+
+```bash
+test -s "$TARGET_DIR/<OUTPUT_FILE>"
+```
+
+Record in JSONL or an audit sidecar: brief, prompt with appendix, agent, daemonUrl, projectId, conversationId,
+expected output, final status, and file verification result.
+
+## Batch
+
+For `--brief-glob`, expand the briefs, sort by name, and run serially. Stop at the first case where:
+
+| Condition | Result |
+|---|---|
+| run fails | `BLOCKED` with JSONL log |
+| run says success but file is missing or empty | `FINDINGS` and surgical follow-up or `BLOCKED` |
+| visual gate <9 | `FINDINGS`; iterate before continuing |
+
+Do not run prompts in parallel in the same `od` project; preserve auditability and context.
+
+## Surgical Iteration
+
+Use a follow-up run on the same `projectId`/`conversationId`, with a short prompt and explicit target file:
+
+```bash
+node "$OD_DIR/apps/daemon/bin/od.mjs" run start \
+  --daemon-url "$OD_URL" \
+  --project "$PROJECT_ID" \
+  --conversation "$CONVERSATION_ID" \
+  --agent "$AGENT" \
+  --skill web-prototype \
+  --design-system default \
+  --prompt-file ".dw/.open-design/runs/<slug>.followup.md" \
+  --follow \
+  --json | tee -a ".dw/.open-design/runs/<slug>.jsonl"
+```
+
+The follow-up must say: single file, exact change, do not touch sibling prototypes, preserve deep-link and states.
+
+## Required Visual Gate
+
+Run the automated gate:
+
+```bash
+node .dw/scripts/open-design/gate-prototype.mjs \
+  --file "$TARGET_DIR/<OUTPUT_FILE>" \
+  --deep-link-id "<real-id>" \
+  --expected-text "<item-text>" \
+  --out ".dw/.open-design/gate/<slug>"
+```
+
+The gate covers:
+
+| Layer | Requirement |
+|---|---|
+| Structural | `<title>`, `aberto`, `replaceState`, `role=dialog`/ARIA, skeleton/loading, empty, error. |
+| Screenshot | Headless Firefox in light and dark, with `colorScheme` and `data-theme`. |
+| Behavioral | `?aberto=<id>` opens the correct item; Esc closes and clears the parameter. |
+| Evaluation | Automated PASS + your visual score >=9. If below 9, run a surgical follow-up. |
+
+After it passes, **stop for the owner's gate**. Do not commit until the owner approves.
+
+## Validated Pitfalls
+
+| Pitfall | Symptom | Required workaround |
+|---|---|---|
+| `web-prototype` discovery | Opens with `<question-form>` and ends the turn; headless does not create GenUI (`od ui list` empty). | Append the headless appendix answering platform and forbidding questions/discovery. |
+| Inactivity timeout | Large HTML goes silent and the run dies near 10 minutes. | `OD_CHAT_RUN_INACTIVITY_TIMEOUT_MS=1800000` on the daemon + instruct ~150-line chunked writes. |
+| `codex_core::shell_snapshot` | Logs a syntax `ERROR` in the stream. | Treat as noise if the run continues and the final file exists. |
+| GUI state | App config/agent/projects leak from the user's GUI. | Isolated `OD_DATA_DIR` always; explicit `--agent`, `--skill`, and `--design-system`. |
+
+## Structured Return
+
+**Status:** `PASS` | `FINDINGS` | `BLOCKED` | `NOT_APPLICABLE`  
+**Scope:** target folder, briefs run, agent used, projectId/conversationId.  
+**Evidence:** JSONL logs, verified HTML file(s), gate JSON, light/dark screenshots.  
+**Artifacts:** prototype and sidecar paths.  
+**Decisions:** defaults/overrides applied (`agent`, `target`, platform, port).  
+**Risks:** any gate below 9, missing file despite run succeeded, missing dependency.  
+**Next Step:** owner gate, required surgical follow-up, or exact resume command.
+</system_instructions>

package/scaffold/pt-br/commands/dw-help.md

@@ -36,12 +36,13 @@ Use `/dw-autopilot "desejo"` como gateway pra maior parte do trabalho. Comandos
 | `/dw-commit` | Commits atômicos Conventional pra trabalho pendente. |
 | `/dw-generate-pr [target]` | Push branch, draft do PR body, abre browser. |
 
-## Tier 3 — Especialidade (11)
+## Tier 3 — Especialidade (12)
 
 | Comando | O que |
 |---------|-------|
 | `/dw-analyze-project` | Scan do repo, escreve `.dw/rules/`, oferece `.dw/constitution.md`, gera `.dw/rules/concerns.md` e sintetiza `DESIGN.md` em frontend quando há tokens. |
 | `/dw-redesign-ui "target"` | Audit, propõe 2-3 direções, entrega. Enforça UI grounding + WCAG; pode rodar o detector determinístico do impeccable. |
+| `/dw-open-design --brief <file>` | Gera, itera ou faz `--refactor` de prototipos HTML headless via Open Design `od`; refina briefs primeiro, pode capturar prints atuais com `--url --viewports` ou `--screenshot`, depois verifica arquivo + gate visual. |
 | `/dw-refactor "target"` | Audita code health e tech debt com smells Fowler, deep-modules e gates de teste preservando comportamento. |
 | `/dw-functional-doc` | Mapeia screens + flows em doc funcional validado com Playwright; usa resolução de browser resiliente no WSL. |
 | `/dw-context-budget` | Audita contexto de commands, skills, agentes, instrucoes e MCPs. |
@@ -108,6 +109,7 @@ Auto-invocados por comandos primários mas disponíveis standalone.
 | `research`, `compara`, `estado da arte` | `/dw-brainstorm --research` |
 | `refactor`, `smell`, `code health`, `tech debt` | `/dw-refactor` |
 | `ui`, `design`, `redesign` | `/dw-redesign-ui` |
+| `open design`, `prototype`, `prototipo`, `od cli`, `html prototype` | `/dw-open-design --brief <file>`, `/dw-open-design --brief-glob "<glob>" --agent claude` ou `/dw-open-design --refactor --url <url> --viewports "1440x900,375x812"` |
 | `intel`, `onde está`, `o que usa` | `/dw-intel` (ou `--build`) |
 | `contexto`, `tokens`, `agente lento` | `/dw-context-budget` |
 | `harness`, `install`, `wrappers`, `agentes` | `/dw-harness-audit` |

package/scaffold/pt-br/commands/dw-open-design.md

@@ -0,0 +1,323 @@
+<system_instructions>
+Voce e o **runner headless do Open Design (`od`)** para gerar e iterar prototipos HTML em uma pasta de projeto,
+sem abrir Electron e sem depender do estado da GUI do usuario. Use o daemon do `nexu-io/open-design` em
+`--headless`, importe a pasta alvo uma vez, rode briefs single ou batch em serie, verifique o arquivo produzido,
+rode gate visual Playwright/Firefox e **PARE para o gate do dono** antes de qualquer commit.
+
+<critical>NUNCA use o estado da GUI do usuario. Sempre rode com `OD_DATA_DIR` isolado por projeto, por exemplo `.dw/.open-design/data/`.</critical>
+<critical>NUNCA commite prototipo reprovado. O gate e dual >=9: gate automatico + avaliacao visual propria >=9, depois gate do dono.</critical>
+<critical>O agente (`codex` ou `claude`) deve ser sempre explicito em `od run start --agent <agent>`. Se o usuario nao passar, resolva de config/estado do projeto; fallback `codex`.</critical>
+<critical>NUNCA despache o pedido cru do usuario para o `od`. O valor deste comando e refinar o prompt primeiro: ancore no codigo real, estruture o brief, qualifique estados/temas/a11y/deep-link, persista o brief revisavel e so entao anexe o apendice headless.</critical>
+
+## Inputs
+
+| Flag/argumento | Default | Descricao |
+|---|---:|---|
+| `--target <dir>` | `open-design/` | Pasta importada como projeto externo e onde os HTMLs serao escritos. |
+| `--brief <file>` | nenhum | Um brief markdown para uma run single. |
+| `--brief-glob <glob>` | nenhum | Batch em serie. Expanda para lista estavel e rode um prompt por vez. |
+| `--output <file>` | obrigatorio no brief/apendice | HTML esperado; verifique no filesystem depois da run. |
+| `--agent <codex|claude>` | estado/config -> `codex` | Agente repassado ao `od run start --agent`. |
+| `--platform <text>` | `Web responsivo desktop-first e mobile-safe` | Resposta pre-preenchida para o discovery da skill `web-prototype`. |
+| `--deep-link-id <id>` | nenhum | Valor usado no gate comportamental `?aberto=<id>` + Esc. |
+| `--refactor` | falso | Modo redesign/refactor de tela existente; captura prints atuais e ancora o brief no estado visivel + codigo real. |
+| `--url <url>` | nenhum | URL de app rodando para capturar prints atuais via Playwright Firefox. |
+| `--viewports <lista>` | `1440x900,375x812` | Viewports separados por virgula para `--refactor --url`; expanda conforme a dor (ex.: `1920x1080` para tabela larga). |
+| `--screenshot <path>` | repetivel | Print atual ja capturado quando nao houver `--url`; copie para `_refs/<slug>/`. |
+
+## 0. Refinar o brief
+
+Antes de qualquer pre-flight de daemon ou chamada ao `od`, transforme a intencao do usuario em um brief qualificado.
+Nao envie a frase crua do usuario para o runner.
+
+Contrato obrigatorio:
+
+| Etapa | Exigencia |
+|---|---|
+| Ancorar na realidade | Se a tela existe, leia o codigo real dela: colunas, enums, acoes, estados, permissoes, contracts e dominio. Leia tambem design system, prototipos irmaos e guias de design do projeto. E proibido inventar campo, status ou acao. |
+| Estruturar | Reescreva o pedido no esqueleto padrao abaixo, preenchendo paths reais e arquivo de saida exato. |
+| Qualificar | Cubra loading/skeleton, empty/vazio, erro/falha, light + dark, a11y, limites do design system local (ex.: <=6 cards/filtros), responsividade e deep-link. |
+| Persistir | Salve o brief refinado dentro do projeto, por exemplo `<target>/PROMPT-<slug>.md`. Ele e entregavel revisavel pelo dono, nao arquivo descartavel. |
+| Revisar se ja vier pronto | Se o usuario trouxer um brief ja qualificado, faca uma revisao rapida por checklist, ajuste apenas lacunas e persista a versao final. |
+
+Esqueleto padrao do brief refinado:
+
+```markdown
+# <titulo da tela/prototipo>
+
+Cole este brief no Open Design. Arquivo de saida exato: `<OUTPUT_FILE>`.
+
+## 1. Por que
+<dor real do usuario/produto; problema observavel que este prototipo precisa resolver>
+
+## 2. Decisao de interacao
+<padrao de navegacao, abertura, selecao, filtros, ordenacao, edicao e confirmacoes>
+
+## 3. Layout/lista
+Tabela/lista baseada apenas em colunas REAIS:
+
+| Coluna real | Origem/contract | Como aparece | Estado/limite |
+|---|---|---|---|
+| <nome> | <arquivo/API/schema> | <texto, badge, acao> | <truncate, vazio, erro> |
+
+## 4. Detalhe/acoes
+<drawer/modal/pagina de detalhe; acoes contextuais permitidas por estado/permissao real>
+
+## 5. Fidelidade de dominio
+Para o mock nao mentir: usar enums/status reais, dados de exemplo realistas no idioma do projeto e incluir estados raros/quebrados que existem no dominio.
+
+## 6. Direcao visual
+<tokens, componentes, densidade, referencias herdadas, prototipos irmaos e limites do design system>
+
+## Entregar
+- `<OUTPUT_FILE>`
+- `<OUTPUT_FILE>.artifact.json` se houver sidecar
+```
+
+So depois de persistir esse arquivo anexe o apendice headless em `.dw/.open-design/runs/` e despache a run.
+
+### 0R. Modo refactor/redesign
+
+Quando `--refactor` estiver presente, a fase 0 continua obrigatoria. Prints complementam a ancoragem no codigo; eles
+nao substituem leitura de contracts, enums, permissoes, estados, design system e prototipos irmaos.
+
+Capture ou copie os prints atuais para dentro da pasta importada, em `_refs/<slug>/`, antes de persistir o brief:
+
+```bash
+node .dw/scripts/open-design/capture-current.mjs \
+  --target "$TARGET_DIR" \
+  --slug "<slug>" \
+  --url "<url>" \
+  --viewports "1440x900,375x812"
+```
+
+Sem URL de app rodando, aceite prints prontos repetindo `--screenshot`:
+
+```bash
+node .dw/scripts/open-design/capture-current.mjs \
+  --target "$TARGET_DIR" \
+  --slug "<slug>" \
+  --screenshot "./antes-1440-light.png" \
+  --screenshot "./antes-375-dark.png"
+```
+
+Regras de captura:
+
+| Caso | Exigencia |
+|---|---|
+| Viewports | Default sensato: desktop `1440x900` + mobile `375x812`. O agente escolhe/expande conforme a dor: bug mobile inclui `375x812`; tabela larga inclui `1920x1080`; tablet/console inclui `768x1024`. |
+| Temas | Capture light e dark quando aplicavel. O helper usa `light,dark` por default e grava nomes como `_refs/<slug>/atual-1440-light.png` e `_refs/<slug>/atual-375-dark.png`. |
+| Caminho robusto | O agente do `od` le imagens do filesystem do projeto. Referencie caminhos relativos dentro do target; nao dependa de flag de imagem no `run start`. |
+| Higiene | `_refs/` e material de referencia nao devem virar prototipo. Se o projeto-alvo versiona prototipos finais, documente limpeza ou adicione `<target>/_refs/` ao `.gitignore` conforme a convencao local. |
+
+O brief refinado do modo refactor deve adicionar este bloco:
+
+```markdown
+## Referencias da tela atual
+Abra e ANALISE os prints antes de escrever:
+- `_refs/<slug>/atual-1440-light.png`
+- `_refs/<slug>/atual-375-dark.png`
+
+## O que esta errado hoje
+<dor apontando elementos visiveis nos prints: densidade, hierarquia, tabela, filtros, estados, contraste, mobile, etc.>
+
+## A ideia da mudanca
+<o que muda e por que; decisao de interacao/visual proposta pelo usuario ou pelo agente apos ler codigo e prints>
+
+## Preservar
+<fluxos, campos, permissoes, estados, copys, affordances e integracoes que nao podem mudar>
+```
+
+## Pre-flight
+
+| Checagem | Acao |
+|---|---|
+| Resolver `od` | `OD_CLI_DIR` vence. Senao use `~/.dw/vendor/open-design`. Se `apps/daemon/bin/od.mjs` nao existir, pare e mande rodar `dev-workflow install-deps`. |
+| Prerequisitos | O checkout do Open Design exige Node `~24` e pnpm `>=10.33`. Se faltarem, pare com instrucoes objetivas. |
+| Estado isolado | Crie `.dw/.open-design/`, `.dw/.open-design/data/`, `.dw/.open-design/runs/` e `.dw/.open-design/state.json`. |
+| Porta | Escolha porta livre em `127.0.0.1`; persista `daemonUrl` e `port` no state. |
+| Daemon vivo | Se `od daemon status --daemon-url <url> --json` retornar `ok: true`, reuse. Senao inicie novo daemon. |
+
+Comando base do daemon:
+
+```bash
+OD_DATA_DIR="$PWD/.dw/.open-design/data" \
+OD_CHAT_RUN_INACTIVITY_TIMEOUT_MS=1800000 \
+node "$OD_DIR/apps/daemon/bin/od.mjs" daemon start \
+  --headless \
+  --host 127.0.0.1 \
+  --port "$PORT"
+```
+
+Ruido conhecido: `codex_core::shell_snapshot` pode logar `ERROR` de sintaxe. Isso e benigno; nao aborte se a run
+continua e o arquivo alvo e criado.
+
+## Import idempotente
+
+Use `project import-folder` na pasta alvo resolvida absoluta. Default: `<repo>/open-design/`.
+
+Persistir em `.dw/.open-design/state.json`:
+
+```json
+{
+  "schema_version": "1.0",
+  "targetDir": "/abs/repo/open-design",
+  "projectId": "<project.id>",
+  "conversationId": "<conversationId>",
+  "daemonUrl": "http://127.0.0.1:<port>",
+  "port": 17556,
+  "agent": "codex"
+}
+```
+
+Se `projectId` existe no state e `od project info <id> --daemon-url <url> --json` funciona para o mesmo
+`targetDir`, reuse. Caso contrario, reimporte:
+
+```bash
+node "$OD_DIR/apps/daemon/bin/od.mjs" project import-folder "$TARGET_DIR" \
+  --daemon-url "$OD_URL" \
+  --name "$(basename "$TARGET_DIR")" \
+  --skill web-prototype \
+  --design-system default \
+  --json
+```
+
+Capture `project.id` e `conversationId`; nao dependa de estado global do app.
+
+## Apendice headless obrigatorio
+
+Anexe este bloco ao final de cada brief em um arquivo temporario dentro de `.dw/.open-design/runs/`.
+Preencha `<PLATFORM>`, `<OUTPUT_FILE>` e referencias irma se houver.
+
+```markdown
+---
+
+## Apendice headless para Open Design
+
+Plataforma-alvo: <PLATFORM>.
+
+Nao faca discovery e nao faca perguntas. Nao emita `<question-form>`. Siga este brief com as respostas acima e
+entregue arquivo primeiro.
+
+Arquivo de saida obrigatorio: `<OUTPUT_FILE>`.
+
+Contrato file-first:
+- Escreva o HTML diretamente no filesystem do projeto, exatamente em `<OUTPUT_FILE>`.
+- Nao altere arquivos existentes, exceto quando este prompt for explicitamente uma iteracao cirurgica sobre um arquivo alvo.
+- Se precisar criar sidecar, mantenha `<OUTPUT_FILE>.artifact.json` coerente.
+- Nao responda apenas com bloco `<artifact>` textual; run `succeeded` sem arquivo e falha.
+
+Para evitar timeout headless:
+- Escreva arquivos grandes em partes, com edicoes de aproximadamente 150 linhas por chamada.
+- Mantenha progresso visivel ate finalizar o HTML.
+
+Contexto de consistencia:
+- Leia prototipos irmaos em `prototipos/` ou na pasta indicada no brief antes de definir padroes visuais.
+- Preserve o sistema visual local quando houver referencia proxima.
+
+Deep-link obrigatorio:
+- Implemente `?aberto=<id>` para abrir o drawer/modal do item correto.
+- Ao fechar com Esc ou acao de fechar, limpe o parametro com `history.replaceState`.
+- O drawer/modal deve usar `role="dialog"` e atributos ARIA adequados.
+- Inclua estados skeleton/loading, empty/vazio e erro/falha.
+```
+
+## Run single
+
+Sempre passe `--agent` explicitamente:
+
+```bash
+node "$OD_DIR/apps/daemon/bin/od.mjs" run start \
+  --daemon-url "$OD_URL" \
+  --project "$PROJECT_ID" \
+  --conversation "$CONVERSATION_ID" \
+  --agent "$AGENT" \
+  --skill web-prototype \
+  --design-system default \
+  --prompt-file "$PROMPT_WITH_APPENDIX" \
+  --follow \
+  --json | tee ".dw/.open-design/runs/<slug>.jsonl"
+```
+
+Depois da run, confira o arquivo. **Nao aceite apenas status `succeeded`:**
+
+```bash
+test -s "$TARGET_DIR/<OUTPUT_FILE>"
+```
+
+Registre no JSONL ou em sidecar de auditoria: brief, prompt com apendice, agente, daemonUrl, projectId,
+conversationId, output esperado, status final e resultado da verificacao do arquivo.
+
+## Batch
+
+Para `--brief-glob`, expanda os briefs, ordene por nome e rode em serie. Pare no primeiro caso em que:
+
+| Condicao | Resultado |
+|---|---|
+| run falha | `BLOCKED` com log JSONL |
+| run diz sucesso mas arquivo nao existe ou esta vazio | `FINDINGS` e follow-up cirurgico ou `BLOCKED` |
+| gate visual <9 | `FINDINGS`; iterar antes de continuar |
+
+Nao rode prompts em paralelo no mesmo projeto `od`; preserve auditabilidade e contexto.
+
+## Iteracao cirurgica
+
+Use follow-up run no mesmo `projectId`/`conversationId`, com prompt curto e arquivo alvo explicito:
+
+```bash
+node "$OD_DIR/apps/daemon/bin/od.mjs" run start \
+  --daemon-url "$OD_URL" \
+  --project "$PROJECT_ID" \
+  --conversation "$CONVERSATION_ID" \
+  --agent "$AGENT" \
+  --skill web-prototype \
+  --design-system default \
+  --prompt-file ".dw/.open-design/runs/<slug>.followup.md" \
+  --follow \
+  --json | tee -a ".dw/.open-design/runs/<slug>.jsonl"
+```
+
+O follow-up deve dizer: arquivo unico, mudanca exata, nao tocar prototipos irmaos, manter deep-link e estados.
+
+## Gate visual obrigatorio
+
+Execute o gate automatico:
+
+```bash
+node .dw/scripts/open-design/gate-prototype.mjs \
+  --file "$TARGET_DIR/<OUTPUT_FILE>" \
+  --deep-link-id "<id-real>" \
+  --expected-text "<texto-do-item>" \
+  --out ".dw/.open-design/gate/<slug>"
+```
+
+O gate cobre:
+
+| Camada | Exigencia |
+|---|---|
+| Estrutural | `<title>`, `aberto`, `replaceState`, `role=dialog`/ARIA, skeleton/loading, empty/vazio, erro/falha. |
+| Screenshot | Firefox headless em light e dark, com `colorScheme` e `data-theme`. |
+| Comportamental | `?aberto=<id>` abre o item certo; Esc fecha e limpa o parametro. |
+| Avaliacao | Automatico PASS + sua nota visual >=9. Se abaixo de 9, faca follow-up cirurgico. |
+
+Depois de passar, **pare para o gate do dono**. Nao commite ate o dono aprovar.
+
+## Armadilhas validadas
+
+| Armadilha | Sintoma | Contorno obrigatorio |
+|---|---|---|
+| Discovery da `web-prototype` | Abre com `<question-form>` e encerra o turno; headless nao gera GenUI (`od ui list` vazio). | Anexar o apendice headless respondendo plataforma e proibindo perguntas/discovery. |
+| Timeout de inatividade | HTML grande fica silencioso e o run morre perto de 10min. | `OD_CHAT_RUN_INACTIVITY_TIMEOUT_MS=1800000` no daemon + instruir escrita em partes de ~150 linhas. |
+| `codex_core::shell_snapshot` | Loga `ERROR` de sintaxe no stream. | Tratar como ruido se a run prossegue e o arquivo final existe. |
+| Estado da GUI | Config/agente/projetos vazam do app do usuario. | `OD_DATA_DIR` isolado sempre; `--agent`, `--skill` e `--design-system` explicitos. |
+
+## Structured Return
+
+**Status:** `PASS` | `FINDINGS` | `BLOCKED` | `NOT_APPLICABLE`  
+**Scope:** pasta alvo, briefs executados, agente usado, projectId/conversationId.  
+**Evidence:** logs JSONL, arquivo(s) HTML verificados, gate JSON, screenshots light/dark.  
+**Artifacts:** paths dos prototipos e sidecars.  
+**Decisions:** defaults/overrides aplicados (`agent`, `target`, plataforma, porta).  
+**Risks:** qualquer gate abaixo de 9, arquivo nao gerado apesar de run succeeded, dependencia ausente.  
+**Next Step:** gate do dono, follow-up cirurgico necessario, ou comando de resume exato.
+</system_instructions>

package/scaffold/scripts/open-design/capture-current.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+
+function parseArgs(argv) {
+  const result = { screenshot: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) continue;
+    const [rawKey, inlineValue] = token.slice(2).split("=", 2);
+    const key = rawKey.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    if (inlineValue !== undefined) {
+      if (key === "screenshot") result.screenshot.push(inlineValue);
+      else result[key] = inlineValue;
+      continue;
+    }
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      if (key === "screenshot") {
+        throw new Error("Missing value for --screenshot <path>.");
+      }
+      result[key] = true;
+      continue;
+    }
+    if (key === "screenshot") result.screenshot.push(next);
+    else result[key] = next;
+    index += 1;
+  }
+  return result;
+}
+
+async function importFirefox() {
+  try {
+    return (await import("@playwright/test")).firefox;
+  } catch {
+    try {
+      return (await import("playwright")).firefox;
+    } catch {
+      return null;
+    }
+  }
+}
+
+function slugify(value) {
+  return (
+    String(value)
+      .toLowerCase()
+      .replace(/^https?:\/\//, "")
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 70) || "screen"
+  );
+}
+
+function parseViewports(value) {
+  return String(value || "1440x900,375x812")
+    .split(",")
+    .map((entry) => {
+      const match = entry.trim().match(/^(\d{2,5})x(\d{2,5})$/);
+      if (!match) return null;
+      return { width: Number(match[1]), height: Number(match[2]) };
+    })
+    .filter(Boolean);
+}
+
+function parseThemes(value) {
+  return String(value || "light,dark")
+    .split(",")
+    .map((entry) => entry.trim().toLowerCase())
+    .filter((entry) => entry === "light" || entry === "dark");
+}
+
+function inferProvidedName(source, index) {
+  const base = path.basename(source, path.extname(source)).toLowerCase();
+  const width = base.match(/(?:^|[^0-9])(\d{3,5})(?:x\d{3,5})?(?:[^0-9]|$)/)?.[1];
+  const theme = base.includes("dark") ? "dark" : base.includes("light") ? "light" : "";
+  if (width && theme) return `atual-${width}-${theme}.png`;
+  if (width) return `atual-${width}-${String(index + 1).padStart(2, "0")}.png`;
+  return `atual-ref-${String(index + 1).padStart(2, "0")}.png`;
+}
+
+async function captureFromUrl(args, outDir) {
+  if (!args.url) return [];
+  const firefox = await importFirefox();
+  if (!firefox) {
+    throw new Error("Playwright is not installed. Run: npm i -D @playwright/test && npx playwright install firefox");
+  }
+
+  const viewports = parseViewports(args.viewports);
+  if (viewports.length === 0) {
+    throw new Error("No valid --viewports entries. Use comma-separated WIDTHxHEIGHT values, for example 1440x900,375x812.");
+  }
+  const themes = parseThemes(args.themes);
+  if (themes.length === 0) {
+    throw new Error("No valid --themes entries. Use light,dark or one of them.");
+  }
+
+  const browser = await firefox.launch({ headless: true });
+  const shots = [];
+  try {
+    for (const viewport of viewports) {
+      for (const theme of themes) {
+        const context = await browser.newContext({
+          colorScheme: theme,
+          viewport,
+        });
+        const page = await context.newPage();
+        await page.goto(String(args.url), { waitUntil: "networkidle" }).catch(() => page.goto(String(args.url)));
+        await page.evaluate((value) => {
+          document.documentElement.setAttribute("data-theme", value);
+        }, theme);
+        await page.waitForTimeout(300);
+        const target = path.join(outDir, `atual-${viewport.width}-${theme}.png`);
+        await page.screenshot({ path: target, fullPage: true });
+        shots.push({ source: String(args.url), viewport, theme, path: target });
+        await context.close();
+      }
+    }
+  } finally {
+    await browser.close();
+  }
+  return shots;
+}
+
+function copyProvidedScreenshots(args, outDir) {
+  return args.screenshot.map((source, index) => {
+    const resolved = path.resolve(String(source));
+    if (!fs.existsSync(resolved)) {
+      throw new Error(`Screenshot not found: ${resolved}`);
+    }
+    const target = path.join(outDir, inferProvidedName(resolved, index));
+    fs.copyFileSync(resolved, target);
+    return { source: resolved, path: target };
+  });
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.url && args.screenshot.length === 0) {
+    throw new Error("Pass --url <app-url> or one or more --screenshot <path> values.");
+  }
+
+  const targetDir = path.resolve(String(args.target || "open-design"));
+  const slug = slugify(args.slug || args.url || "screen");
+  const outDir = path.resolve(String(args.out || path.join(targetDir, "_refs", slug)));
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const copied = copyProvidedScreenshots(args, outDir);
+  const captured = await captureFromUrl(args, outDir);
+  const shots = [...copied, ...captured];
+
+  process.stdout.write(
+    `${JSON.stringify(
+      {
+        targetDir,
+        refsDir: outDir,
+        relativeRefs: shots.map((shot) => path.relative(targetDir, shot.path).split(path.sep).join("/")),
+        shots,
+      },
+      null,
+      2,
+    )}\n`,
+  );
+}
+
+main().catch((error) => {
+  process.stderr.write(`capture-current: ${error.message}\n`);
+  process.exit(1);
+});

package/scaffold/scripts/open-design/gate-prototype.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+function parseArgs(argv) {
+  const result = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) continue;
+    const [rawKey, inlineValue] = token.slice(2).split("=", 2);
+    const key = rawKey.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    if (inlineValue !== undefined) {
+      result[key] = inlineValue;
+      continue;
+    }
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      result[key] = true;
+      continue;
+    }
+    result[key] = next;
+    index += 1;
+  }
+  return result;
+}
+
+async function importFirefox() {
+  try {
+    return (await import("@playwright/test")).firefox;
+  } catch {
+    try {
+      return (await import("playwright")).firefox;
+    } catch {
+      return null;
+    }
+  }
+}
+
+function slugify(value) {
+  return (
+    String(value)
+      .toLowerCase()
+      .replace(/\.html?$/, "")
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 70) || "prototype"
+  );
+}
+
+function addResult(results, name, pass, details = "") {
+  results.push({ name, pass: Boolean(pass), details });
+}
+
+async function structuralChecks(page, html, results) {
+  const data = await page.evaluate(() => {
+    const visibleText = document.body ? document.body.innerText : "";
+    const hasDialogRole = Boolean(document.querySelector('[role="dialog"], [aria-modal="true"], [aria-labelledby]'));
+    const title = document.title.trim();
+    return { visibleText, hasDialogRole, title };
+  });
+
+  addResult(results, "title", data.title.length > 0, data.title || "missing document title");
+  addResult(results, "aberto-param", /\baberto\b/.test(html), "source contains aberto");
+  addResult(results, "replace-state", /replaceState/.test(html), "source contains replaceState");
+  addResult(results, "dialog-aria", data.hasDialogRole, "role=dialog, aria-modal, or aria-labelledby present");
+  addResult(results, "skeleton-state", /skeleton|carregando|loading/i.test(html + "\n" + data.visibleText));
+  addResult(results, "empty-state", /empty|vazio|sem\s+(resultado|dados|itens|registros)/i.test(html + "\n" + data.visibleText));
+  addResult(results, "error-state", /error|erro|falha|failed|retry|tentar novamente/i.test(html + "\n" + data.visibleText));
+}
+
+async function visibleDialog(page, selector) {
+  const selected = selector ? page.locator(selector).first() : page.locator('[role="dialog"], [aria-modal="true"]').first();
+  try {
+    return (await selected.count()) > 0 && (await selected.isVisible());
+  } catch {
+    return false;
+  }
+}
+
+async function clickFirstOpenable(page, rowSelector) {
+  const selector =
+    rowSelector ||
+    '[data-open], [data-id], tbody tr, [role="row"], [role="button"], article, li button, li, button';
+  const candidates = page.locator(selector);
+  const count = Math.min(await candidates.count(), 20);
+  for (let index = 0; index < count; index += 1) {
+    const candidate = candidates.nth(index);
+    try {
+      if (!(await candidate.isVisible())) continue;
+      await candidate.click({ timeout: 1500 });
+      return true;
+    } catch {
+      // Try the next plausible opener.
+    }
+  }
+  return false;
+}
+
+async function behavioralChecks(page, baseUrl, args, results) {
+  const dialogSelector = args.dialogSelector ? String(args.dialogSelector) : "";
+  if (!(await visibleDialog(page, dialogSelector))) {
+    const clicked = await clickFirstOpenable(page, args.rowSelector ? String(args.rowSelector) : "");
+    await page.waitForTimeout(300);
+    addResult(results, "open-drawer-click", clicked && (await visibleDialog(page, dialogSelector)), "first row/openable opens dialog or drawer");
+  } else {
+    addResult(results, "open-drawer-click", true, "dialog already visible");
+  }
+
+  const deepLinkId = args.deepLinkId ? String(args.deepLinkId) : "";
+  if (!deepLinkId) {
+    addResult(results, "deep-link-opens", false, "missing --deep-link-id");
+    addResult(results, "esc-clears-param", false, "missing --deep-link-id");
+    return;
+  }
+
+  const url = new URL(baseUrl);
+  url.searchParams.set("aberto", deepLinkId);
+  await page.goto(url.toString(), { waitUntil: "load" });
+  await page.waitForTimeout(500);
+
+  const expectedText = String(args.expectedText || deepLinkId);
+  const deepLinkData = await page.evaluate((text) => {
+    const bodyText = document.body ? document.body.innerText : "";
+    const hasDialog = Boolean(document.querySelector('[role="dialog"], [aria-modal="true"]'));
+    return {
+      hasDialog,
+      hasText: bodyText.toLowerCase().includes(text.toLowerCase()),
+      search: window.location.search,
+    };
+  }, expectedText);
+  addResult(
+    results,
+    "deep-link-opens",
+    deepLinkData.search.includes(`aberto=${encodeURIComponent(deepLinkId)}`) && deepLinkData.hasDialog && deepLinkData.hasText,
+    `expected visible text: ${expectedText}`,
+  );
+
+  await page.keyboard.press("Escape");
+  await page.waitForTimeout(500);
+  const searchAfterEsc = await page.evaluate(() => window.location.search);
+  addResult(results, "esc-clears-param", !new URLSearchParams(searchAfterEsc).has("aberto"), searchAfterEsc || "empty search");
+}
+
+async function captureScreenshots(browser, fileUrl, outDir, slug) {
+  const shots = [];
+  for (const scheme of ["light", "dark"]) {
+    const context = await browser.newContext({
+      colorScheme: scheme,
+      viewport: { width: 1440, height: 1000 },
+    });
+    const page = await context.newPage();
+    await page.goto(fileUrl, { waitUntil: "load" });
+    await page.evaluate((theme) => {
+      document.documentElement.setAttribute("data-theme", theme);
+    }, scheme);
+    await page.waitForTimeout(300);
+    const shotPath = path.join(outDir, `${slug}-${scheme}.png`);
+    await page.screenshot({ path: shotPath, fullPage: true });
+    shots.push({ colorScheme: scheme, path: shotPath });
+    await context.close();
+  }
+  return shots;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.file) {
+    throw new Error("Missing required argument: --file <prototype.html>");
+  }
+
+  const filePath = path.resolve(String(args.file));
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Prototype file not found: ${filePath}`);
+  }
+
+  const firefox = await importFirefox();
+  if (!firefox) {
+    throw new Error("Playwright is not installed. Run: npm i -D @playwright/test && npx playwright install firefox");
+  }
+
+  const html = fs.readFileSync(filePath, "utf8");
+  const outDir = path.resolve(String(args.out || path.join(".dw", ".open-design", "gate", slugify(path.basename(filePath)))));
+  fs.mkdirSync(outDir, { recursive: true });
+  const baseUrl = pathToFileURL(filePath).toString();
+  const slug = slugify(path.basename(filePath));
+
+  const browser = await firefox.launch({ headless: true });
+  const results = [];
+  let screenshots = [];
+  try {
+    const context = await browser.newContext({ colorScheme: "light", viewport: { width: 1440, height: 1000 } });
+    const page = await context.newPage();
+    await page.goto(baseUrl, { waitUntil: "load" });
+    await structuralChecks(page, html, results);
+    await behavioralChecks(page, baseUrl, args, results);
+    await context.close();
+    screenshots = await captureScreenshots(browser, baseUrl, outDir, slug);
+  } finally {
+    await browser.close();
+  }
+
+  const failed = results.filter((result) => !result.pass);
+  const summary = {
+    file: filePath,
+    score: Number(((results.length - failed.length) / results.length * 10).toFixed(1)),
+    pass: failed.length === 0,
+    results,
+    screenshots,
+  };
+  fs.writeFileSync(path.join(outDir, `${slug}-gate.json`), JSON.stringify(summary, null, 2) + "\n", "utf8");
+  process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+
+  if (failed.length > 0) {
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  process.stderr.write(`gate-prototype: ${error.message}\n`);
+  process.exit(1);
+});