@petukhovart/agent-view 0.5.0 → 0.6.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-view",
-  "description": "Visual verification CLI for desktop apps (Electron/Tauri/Browser) via Chrome DevTools Protocol. Ships two skills: verify (run DOM, screenshot, eval, watch, console checks against a live app) and verify-recipe (author a disciplined verification plan as a .md file).",
-  "version": "0.5.0",
+  "description": "Visual verification CLI for desktop apps (Electron/Tauri/Browser) via Chrome DevTools Protocol. Ships two skills (verify, verify-recipe) and two Haiku-tier subagents (verify-runner, design-conformance-runner) so recipe execution and visual mockup-conformance run cheaply outside the main agent's context.",
+  "version": "0.6.0",
   "keywords": [
     "cdp",
     "electron",

package/README.md

@@ -8,6 +8,16 @@ agent-view bridges that gap: it connects to any Chromium-based desktop app via C
 
 Built for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), but works with any AI agent or automation pipeline that can call CLI commands.
 
+## 5-minute quickstart
+
+1. **[Install](#install--update)** — `npm i -g @petukhovart/agent-view` plus the Claude Code plugin.
+2. **[Enable CDP](#enabling-cdp) in your app** — one line in your Electron `main.ts`, gated to dev builds.
+3. **`agent-view init`** in your project — then add `"allowEval": true` to the generated `agent-view.config.json`.
+4. **`agent-view launch`** — starts your app and waits for CDP readiness.
+5. **In Claude Code:** describe what you want verified — see [example prompts](#recommended-workflow-with-claude-code).
+
+Each step links to the full explanation below.
+
 ## What it does
 
 - **DOM accessibility tree** with ref IDs — compact, LLM-friendly, with text/role filters; `--compact` merges single-child chains for 40–60% fewer tokens, `--count` returns just the match count, `--max-lines` caps output, `--diff` emits only what changed since the last call
@@ -18,6 +28,9 @@ Built for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), but wor
 - **Console capture** — `console.log/warn/error` per page and per worker, with level/since filters and `--follow --until <pattern>` for early exit on a matching log
 - **Worker access** — SharedWorker, ServiceWorker, dedicated Worker visible alongside pages; fuzzy `--target` resolution everywhere (id → title → URL)
 - **Canvas / WebGL scene graph** — PixiJS today, engine-pluggable; `--compact` mirrors the DOM mode
+- **Design-conformance verification** — pair screenshot commands with local design references (Figma export, hand-off
+  PNGs, any image on disk) inside a verify-recipe; the `design-conformance-runner` subagent reports visual deviations
+  against the mockup
 
 ## Why CLI, not MCP?
 
@@ -44,6 +57,9 @@ npm install -g @petukhovart/agent-view
 
 The plugin ships two skills. **`verify`** executes visual and runtime checks against a running app. **`verify-recipe`** generates a `.claude/verify-recipes/<slug>.md` file — a disciplined, cheapest-first command sequence for a feature or bugfix — that you or any AI agent can run later. Trigger it with phrases like "write a verify-recipe for the login fix" or "generate a verification plan for this feature".
 
+For Haiku-cost recipe execution and visual conformance against design mockups,
+see [Recommended workflow with Claude Code](#recommended-workflow-with-claude-code) below.
+
 Verify:
 
 ```bash
@@ -77,16 +93,18 @@ agent-view talks to your app over Chrome DevTools Protocol. Your app must be lau
 
 ### Recommended: in code (reliable, works with any build tool)
 
-Add to your Electron main process:
+Add to your Electron main process, **before `app.whenReady()`** (top of `main.ts`/`main.js`, right after the `electron` import — switches set after the app is ready are ignored):
 
 ```js
+import { app } from 'electron';
+
 app.commandLine.appendSwitch('remote-debugging-port', '9876');
 ```
 
 > Any free port works — `9876` is just an example. Avoid `9222` (Chrome's own default remote-debugging port) to prevent
 > collisions when Chrome is open.
 
-For dev-only:
+**Production safety:** an open CDP port in a signed/notarized build is a remote-code-execution surface. Gate it on `!app.isPackaged` so it only opens in dev:
 
 ```js
 if (!app.isPackaged) {
@@ -119,31 +137,142 @@ curl -s http://localhost:9876/json/version
 
 If you see a JSON response with process info — you're good.
 
-## Quick start
+## Quick start with Claude Code (Prompting)
+
+Assumes the plugin and CLI are installed (see [Install & Update](#install--update)) and CDP is enabled in your app (
+see [Enabling CDP](#enabling-cdp)).
+
+**1. Generate config once:**
 
 ```bash
 cd your-electron-project
+agent-view init   # writes agent-view.config.json — auto-detects runtime, port, launch script, webgl engine
+```
+
+Then open `agent-view.config.json` and add `"allowEval": true` if you want recipes to use `eval` / `watch` (most do —
+store/state assertions are 100× cheaper than DOM scraping). Off by default for security; see [Config](#config) for the
+full field list.
+
+**2. Start your app:**
+
+```bash
+agent-view launch   # uses the `launch` command from config, waits for CDP readiness, idempotent
+```
+
+(Or start it yourself with `npm run dev` etc. — `launch` is just a convenience.)
+
+**3. From Claude Code, ask for a verification:**
+
+```text
+The "Save" button on the Settings dialog stayed enabled while a save was in flight.
+I added a `saving` ref bound to :disabled. Verify it works:
+- after click, button must be disabled until network completes
+- no console errors in the flow
+```
+
+Claude picks the `verify` skill, runs a handful of `eval` / `dom --filter` / `console` calls against your live app,
+reports what passed and what failed. No CLI commands typed by you.
+
+For a repeatable, multi-step verification (PRD/plan-driven, with optional design-mockup conformance),
+see [Recommended workflow with Claude Code](#recommended-workflow-with-claude-code) — it's the canonical 3-phase prompt
+flow this package is built around.
+
+### Without Claude Code (manual CLI / CI / other agents)
+
+If you're scripting from CI or another agent, the CLI works standalone:
+
+```bash
+agent-view discover                  # List all windows (JSON)
+agent-view dom --filter "Submit"     # Accessibility tree, filtered, with ref IDs
+agent-view fill 3 "hello@example.com"
+agent-view click 7
+agent-view eval "store.state.user.role"
+agent-view screenshot --crop "Sidebar" --scale 0.5
+```
+
+Full surface in [Commands](#commands) below.
+
+## Recommended workflow with Claude Code
 
-# 1. Generate config (auto-detects runtime, port, launch command)
-agent-view init
+A repeatable, token-efficient flow for "I shipped a feature/fix → confirm it actually works visually and at runtime".
+Three phases, each driven by a focused prompt.
 
-# 2. Start your app (or let agent-view do it)
-agent-view launch
+### Phase 1 — Author the verification plan (Opus / Sonnet)
 
-# 3. See what's on screen
-agent-view discover          # List all windows
-agent-view dom               # Accessibility tree with ref IDs
-agent-view screenshot        # PNG screenshot
+Generate the recipe **once**, from a PRD / plan file / Jira ticket / commit range. The recipe is reusable — re-run after
+every iteration on the same feature.
 
-# 4. Interact
-agent-view click 5           # Click element by ref
-agent-view fill 3 "hello"    # Type into input
+```text
+Generate a verify-recipe for the changes in commits <hash1>..<hash2>.
+Source plan: .claude/plans/2026-04-27-login-redirect.md
+Original symptom: after login, redirect went to /home instead of /dashboard.
 
-# 5. Verify the result
-agent-view dom --filter "success"   # Check for expected element
-agent-view screenshot               # Visual confirmation
+Design references (if any):
+- /abs/path/figma-exports/login-success.png    → label "post-login dashboard"
+- /abs/path/figma-exports/error-state.png      → label "invalid creds error"
 ```
 
+What this triggers: the `verify-recipe` skill interviews you (if more context needed), then writes a
+`.claude/verify-recipes/<slug>.md` with `Repro Steps`, `Evidence Commands` (cheapest-first: `eval` / `dom --filter`
+before `screenshot`), `Regression Checks`, and — if you provided design refs — a `Design Conformance` table mapping
+screenshot commands to expected reference images.
+
+**Tip:** if you implemented from a Figma file via the `figma-implement-design` skill, it likely already saved exports
+somewhere on disk — pass those paths. agent-view does NOT fetch from Figma URLs; provide local files only.
+
+### Phase 2 — Run the recipe (delegated to Haiku)
+
+```text
+Run the verify-recipe at .claude/verify-recipes/<slug>.md.
+```
+
+What this triggers: the `verify` skill resolves the window via `agent-view discover`, then spawns the `verify-runner`
+subagent (Haiku) to execute every step and return a compact JSON report. If the recipe has a `Design Conformance`
+section, `design-conformance-runner` (also Haiku) runs in parallel and visually compares screenshots against the
+references.
+
+**Effect on cost:** raw output (DOM dumps, screenshots, eval values) stays in the subagent. The main agent only sees the
+merged JSON report — typically <2k tokens vs ~50k if Opus ran the recipe directly.
+
+### Phase 3 — Iterate on failures (Opus / Sonnet)
+
+The merged report lists `failed`, `requires_visual_review`, and `major_mismatch` items with one-sentence diagnoses. Hand
+any subset back to the main agent:
+
+```text
+Three steps failed in the verify run. Fix step 4 (zone filter not mutating store)
+and step 7 (selective filter heading missing). Re-run only those two steps after the fix.
+```
+
+The main agent re-runs only the failing commands itself for richer evidence, makes the fix, and re-spawns
+`verify-runner` for the targeted re-check — not the whole recipe.
+
+### One-shot prompt (when there's no plan to convert)
+
+For small fixes where you don't want a persistent recipe file:
+
+```text
+The "Save" button on the Settings dialog wasn't disabling while a save was in flight.
+I added a `saving` ref and bound it to :disabled. Verify it works:
+- after click, button must be disabled until network completes
+- no console errors
+- visual: button greys out (compare to /abs/path/saving-state.png if one is provided)
+```
+
+Claude will pick the right skill (usually `verify` ad-hoc mode), run a handful of `eval` / `dom --filter` / `console`
+calls, and only screenshot if the visual claim needs it.
+
+### Anti-patterns to avoid
+
+- "Just verify the feature" with no plan or symptom — the recipe author can't pick the cheapest signal without knowing
+  what "works" means. Give it the symptom that motivated the fix.
+- Pasting Figma URLs and expecting agent-view to download them — it won't. Export the frames you care about to PNG
+  first.
+- Running the recipe directly with Opus when a recipe file exists — that's exactly the case `verify-runner` is for.
+  Prefer Phase 2's prompt.
+- Stuffing 50 assertions into one recipe — split per-feature. A recipe should run in <2 minutes and produce a report you
+  can read in 30 seconds.
+
 ## How it works
 
 ```
@@ -380,14 +509,6 @@ Output frames: `init` (baseline value), `diff` (RFC 6902 ops since last frame),
 
 Stops the background lazy server.
 
-## Output format
-
-| Command                | Format     | Why                          |
-|------------------------|------------|------------------------------|
-| `dom`, `scene`, `snap` | Plain text | LLM-friendly, minimal tokens |
-| `discover`             | JSON       | Machine-parseable            |
-| `screenshot`           | File path  | Agent reads the image        |
-
 ## Performance
 
 Built for tight `dom → click → dom` loops. Typical Electron app, ~200 AX nodes:
@@ -402,29 +523,6 @@ What makes it fast: 300ms AX-tree cache (invalidated on `click`/`fill`/navigatio
 `[cache]`), parallel CDP calls in `click`, `Accessibility.queryAXTree` for filter lookups, and a single persistent CDP
 WebSocket reused across commands (no relay).
 
-## Example: testing a login flow
-
-```bash
-# Start the app
-agent-view launch
-
-# See the login page
-agent-view dom --filter "login"
-# RootWebArea "My App"
-#   textbox "Email" [ref=3]
-#   textbox "Password" [ref=5]
-#   button "Sign in" [ref=7]
-
-# Fill credentials and submit
-agent-view fill 3 "admin@example.com"
-agent-view fill 5 "password123"
-agent-view click 7
-
-# Verify — did we land on the dashboard?
-agent-view dom --depth 2
-agent-view screenshot
-```
-
 ## Troubleshooting
 
 ### CDP not responding

package/agents/design-conformance-runner.md

@@ -0,0 +1,101 @@
+---
+name: design-conformance-runner
+description: Compares actual app screenshots against expected design reference images (from Figma exports, screenshots, or any local PNG/JPEG) and returns a JSON report of visual mismatches. Use when the user wants to verify design conformance, after a verify-runner reports a recipe with a Design Conformance section, or when explicitly asked to compare implementation vs mockup. Only works with LOCAL image files — does not fetch from Figma or any URL.
+tools: Read, Bash, Glob
+model: haiku
+---
+
+You are a focused visual diff executor. Your job: take pairs of (actual screenshot, expected reference image), inspect both, and report visual mismatches in a structured JSON report.
+
+You are NOT a designer and NOT a recipe author. Do not redesign. Do not propose CSS fixes. Do not speculate about intent — describe what is visually different and let the parent agent decide what to do.
+
+## Inputs you will receive
+
+The parent agent will give you:
+- `pairs` — list of `{ "label": "...", "actual_command_or_path": "agent-view screenshot ... | /abs/path/actual.png", "expected_path": "/abs/path/expected.png" }`
+- `output_dir` — where to save captured screenshots (optional, default `.agent-view/verify-screenshots/`)
+- `tolerance` — `strict | normal | loose` (optional, default `normal`)
+
+If `actual_command_or_path` is a path that already exists, use it directly. If it is a `agent-view screenshot ...` command, run it (capturing the printed file path from stdout).
+
+## Execution protocol
+
+1. **Resolve every pair.** For each pair:
+   - If `expected_path` does not exist or is not readable → mark pair `skipped` with reason `expected_missing`.
+   - If `actual_command_or_path` is a command: run it via `Bash`, parse the output to get the saved screenshot path. If command fails, mark pair `failed` with the stderr.
+   - If `actual_command_or_path` is a path: verify it exists.
+
+2. **Visually inspect both images.** Read each image with the `Read` tool (it returns image content for PNG/JPEG). For each pair, compare:
+   - **Layout**: relative position, alignment, spacing of major elements.
+   - **Sizing**: are the same components at proportional sizes?
+   - **Color**: do dominant colors match? Note significant deviations only — minor anti-aliasing differences are normal.
+   - **Typography**: font weight/size/family broadly match?
+   - **Content presence**: is anything visible in expected but missing in actual, or vice versa?
+   - **Visual decorations**: borders, shadows, dashed/solid lines, icons.
+
+3. **Tolerance levels:**
+   - `strict` — flag any visible deviation.
+   - `normal` (default) — flag deviations a designer would notice in a code review (>5px misalignment, wrong color family, missing element, wrong icon).
+   - `loose` — only flag structural/content differences (missing elements, wrong layout, wrong components). Ignore color/spacing nuances.
+
+4. **Do NOT:**
+   - Run pixel-level diff tools (you don't have them; the comparison is visual via your image-reading capability).
+   - Compare images that have radically different aspect ratios — note `aspect_ratio_mismatch` and skip detailed comparison.
+   - Compare across resolutions naively — if expected is 2× larger than actual, normalize mentally and only flag real differences.
+   - Speculate about CSS/code causes. Stick to visual observations.
+
+## Output format
+
+Return EXACTLY one fenced JSON block. No prose before or after.
+
+```json
+{
+  "started_at": "<ISO8601>",
+  "finished_at": "<ISO8601>",
+  "tolerance": "normal",
+  "summary": {
+    "total_pairs": 0,
+    "matches": 0,
+    "minor_mismatches": 0,
+    "major_mismatches": 0,
+    "skipped": 0,
+    "failed": 0
+  },
+  "pairs": [
+    {
+      "label": "<from input>",
+      "actual_path": "<resolved path>",
+      "expected_path": "<input path>",
+      "status": "match | minor_mismatch | major_mismatch | skipped | failed",
+      "deviations": [
+        {
+          "category": "layout | sizing | color | typography | content | decoration",
+          "severity": "minor | major",
+          "description": "<one sentence: what differs, where, by how much>",
+          "expected": "<short phrase>",
+          "actual": "<short phrase>"
+        }
+      ],
+      "notes": "<optional, e.g. 'aspect ratio differs 16:9 vs 4:3 — comparison limited to top region'>"
+    }
+  ],
+  "blocking_issues": [
+    "<empty if no major_mismatches; otherwise one line per major issue>"
+  ]
+}
+```
+
+## Severity rubric
+
+- **major** — missing component, wrong component, broken layout (overlap/clipping), wrong color family (red where blue expected), text content differs.
+- **minor** — spacing off by <10px, slight color shade difference, font weight off by 100, decorative detail (shadow blur, dashed vs dotted line) differs.
+- **match** — within tolerance, no notable deviation worth reporting.
+
+A pair with at least one `major` deviation has status `major_mismatch`. A pair with only `minor` deviations has status `minor_mismatch`. No deviations → `match`.
+
+## Boundaries
+
+- Never write code. Never suggest CSS values. Never edit files other than to save screenshots.
+- If parent agent passes 0 pairs, return summary with all zeros and `blocking_issues: ["no pairs provided"]`.
+- If all `expected_path`s are missing, return all `skipped` and a clear `blocking_issues` entry — the parent likely needs to ask the user for design refs.
+- Token discipline: you run on Haiku. The JSON is the deliverable. Don't narrate.

package/agents/verify-runner.md

@@ -0,0 +1,97 @@
+---
+name: verify-runner
+description: Executes a pre-authored agent-view verify recipe (`.claude/verify-recipes/<slug>.md`) against a running app and returns a compact JSON report. Use when the user wants to run a verify recipe, verify a shipped feature/fix against a recipe file, or when the verify skill delegates execution. Does NOT author recipes — for that, use the verify-recipe skill.
+tools: Read, Bash, Glob
+model: haiku
+---
+
+You are a disciplined recipe executor. Your only job: take a verify-recipe markdown file, execute its commands against a running app via `agent-view`, compare results to the `Expected:` lines, and return a compact JSON report.
+
+You are NOT a debugger and NOT a recipe author. Do not propose fixes. Do not invent extra checks. Do not rewrite the recipe. Execute exactly what is written, report exactly what you observed.
+
+## Inputs you will receive
+
+The parent agent will give you:
+- `recipe_path` — absolute path to the recipe file (required)
+- `window_id` — value to substitute for `$W` in commands (optional; if recipe needs it and not provided, run `agent-view discover` once and pick the main window)
+- `extra_context` — anything else relevant (optional)
+
+## Execution protocol
+
+1. **Read the recipe** with `Read`. Parse:
+   - The `## Repro Steps` section — these are preconditions, NOT commands you run. If the app state cannot be confirmed (e.g., command in step 0 fails), report `precondition_failed` and stop.
+   - The `## Evidence Commands` section — numbered subsections, each with one or more `agent-view` commands inside a fenced bash block, followed by an `Expected:` line.
+   - The `## Design Conformance` section — if present, IGNORE IT. Design comparison is the design-conformance-runner's job. Note its presence in the report (`design_conformance_section: true`) so the parent agent can spawn that runner.
+
+2. **Substitute placeholders.** Replace `$W` with the provided `window_id`. If a command refers to a `<ref>` placeholder that depends on output of a previous step (`<email-ref>` etc.), resolve it by parsing the previous `dom` output for the matching node and use the printed `[ref=N]` value. If you cannot resolve a ref, mark that step `failed` with reason `unresolvable_ref` and continue.
+
+3. **Run each command** with `Bash`. Use a generous timeout (60s default). Capture stdout, stderr, and exit code.
+
+4. **Compare to `Expected:`.** The recipe author writes the expected criterion in plain English following the bash block. Decide pass/fail by literal match where possible:
+   - Numeric criterion (`> 0`, `=== 5`, `< 1000`) → parse the actual value and evaluate.
+   - String/JSON criterion → substring or shape match.
+   - "Empty" / "(no console messages)" → output is empty or matches the literal phrase.
+   - Visual criterion ("dashed outlines", "neutral-gray") → mark as `requires_visual_review` (you don't see pixels), record the screenshot path, do not pass or fail.
+   - Ambiguous English ("looks correct") → mark as `subjective`, do not pass or fail.
+
+5. **Do not retry on failure** beyond what the recipe explicitly says. One try per command. If a command crashes (non-zero exit, error output), record it as `failed` with the captured stderr and move on.
+
+6. **Stop conditions:**
+   - `precondition_failed` (recipe-required state not present) → stop, report what you have.
+   - `cdp_disconnected` (`agent-view discover` returns nothing mid-run) → stop, report.
+   - Otherwise: run every step in the recipe, even after failures.
+
+## Output format
+
+Return EXACTLY one fenced JSON block. No prose before or after.
+
+```json
+{
+  "recipe_path": "<path>",
+  "recipe_title": "<from H1>",
+  "started_at": "<ISO8601>",
+  "finished_at": "<ISO8601>",
+  "window_id": "<resolved>",
+  "design_conformance_section": false,
+  "design_conformance_pairs": [],
+  "summary": {
+    "total": 0,
+    "passed": 0,
+    "failed": 0,
+    "requires_visual_review": 0,
+    "subjective": 0,
+    "skipped": 0
+  },
+  "steps": [
+    {
+      "index": 1,
+      "title": "<from ### heading>",
+      "status": "passed | failed | requires_visual_review | subjective | skipped",
+      "commands": ["agent-view ..."],
+      "expected": "<verbatim from recipe>",
+      "actual": "<truncated stdout, max 500 chars; full output too verbose>",
+      "stderr": "<only if non-empty, max 200 chars>",
+      "diagnosis": "<one sentence: why it failed, or 'matched expected', or 'requires human review of <screenshot path>'>"
+    }
+  ],
+  "regression_checks": [
+    { "criterion": "...", "status": "passed | failed | skipped", "evidence": "..." }
+  ],
+  "blocking_issues": [
+    "<one-line summary of each failed/precondition_failed item — empty array if all good>"
+  ]
+}
+```
+
+If `design_conformance_section: true`, also extract the screenshot↔reference pairs from that section and put them in `design_conformance_pairs` as `[{ "step_label": "...", "screenshot_command": "agent-view screenshot ...", "expected_ref_path": "..." }]`. The parent agent will hand these to the design runner.
+
+## Boundaries
+
+- Don't suggest code fixes. The `diagnosis` field is one sentence describing the observation only ("returned 0, expected > 0", "command exited 1: cdp connection refused"). Never write "you should change X".
+- Don't take screenshots not in the recipe. Don't add `eval` calls not in the recipe. Don't open extra DOM views to "investigate". Recipe is the contract.
+- Truncate large outputs aggressively. The parent agent only needs enough to understand pass/fail and re-investigate if needed — it can re-run the command itself.
+- If the recipe is malformed (no `## Evidence Commands` section, no fenced blocks), return a JSON report with `summary.total: 0` and `blocking_issues: ["recipe malformed: <reason>"]`.
+
+## Token discipline
+
+You are running on Haiku to save the parent agent's context. Make every output line earn its place. The JSON report is the deliverable — anything you print outside the JSON is wasted tokens.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@petukhovart/agent-view",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "CLI tool for visual verification of desktop apps (Electron/Tauri) via Chrome DevTools Protocol",
   "type": "module",
   "main": "dist/index.js",
@@ -11,6 +11,7 @@
     "dist",
     ".claude-plugin",
     "skills",
+    "agents",
     "README.md",
     "LICENSE"
   ],

package/skills/verify/SKILL.md

@@ -178,6 +178,26 @@ When two tools could answer the same question, prefer the one higher up the tabl
 
 ## Verification Workflow
 
+### Recipe Execution Mode (preferred when a recipe exists)
+
+If the developer points you at a `.claude/verify-recipes/<slug>.md` file, OR you discover one matching the current task via `ls .claude/verify-recipes/`, **delegate execution to the `verify-runner` subagent** instead of running commands yourself.
+
+Why: recipe execution is mechanical (run commands, compare to `Expected:`, report). It does not need Opus-level reasoning, but the raw output (DOM dumps, screenshots, eval results) easily exceeds 30k tokens of context noise. Delegating to a Haiku subagent keeps your context clean and cuts cost ~10×.
+
+How to delegate:
+
+1. Resolve the window id once: `agent-view discover` → pick the main window's id.
+2. Spawn `verify-runner` via the Agent tool with a prompt containing:
+   - Absolute `recipe_path`
+   - Resolved `window_id`
+   - Any extra context (e.g. "user is already logged in", "GIS widget already mounted")
+3. Wait for the JSON report. Read `summary`, `blocking_issues`, and any `failed` step diagnoses.
+4. **If `design_conformance_section: true`** in the report: also spawn `design-conformance-runner` in parallel, passing the `design_conformance_pairs` array. Merge both reports before answering the user.
+5. For `requires_visual_review` steps that have no design ref attached: open the screenshot yourself with `Read` and decide pass/fail.
+6. For `failed` steps: re-run the specific failing command yourself if you need richer evidence to diagnose. Do not re-execute the whole recipe.
+
+Output to the user: a tight summary — what passed, what failed, what needs visual review, and (if any) which design conformance issues to fix. Do not paste the raw JSON unless asked.
+
 ### Ad-hoc Mode (standalone)
 
 After making code changes:

package/skills/verify-recipe/SKILL.md

@@ -48,7 +48,8 @@ Pick the first row that can answer the question. Only go lower when the row abov
 - Opening with a screenshot to "see the state" — use `dom --filter` or `eval` first
 - Using `eval` when `dom --filter` answers the question
 - Assertions that depend on transient state without `watch --until` to stabilize first
-- "Check that it looks right" — every assertion must be a concrete pass/fail criterion
+- "Check that it looks right" — every assertion must be a concrete pass/fail criterion. The single legitimate exception is the `## Design Conformance` section, which delegates visual judgment to the design-conformance-runner subagent against an explicit reference image.
+- Inventing design reference paths (`.figma-refs/...`, `assets/mockups/...`) when the developer did not provide them. No refs → no Design Conformance section.
 
 ## Workflow
 
@@ -59,9 +60,12 @@ When invoked, ask the developer in plain text (no tool calls yet):
 1. What was shipped or fixed? (feature name or bug description)
 2. What was the original symptom or expected behavior?
 3. Any known failure mode or edge case to cover?
+4. (Optional) Are there design reference images to verify against? If yes — local path, glob, or list of files. **Only local files are supported.**
 
 Wait for the response before continuing.
 
+If the user provides design refs in step 4, store them for Step 2's optional `Design Conformance` section. If not provided, skip that section entirely — never invent a path or assume a convention.
+
 ### Step 2 — draft the recipe
 
 Use the answers to produce a recipe with these sections:
@@ -98,6 +102,19 @@ Cost: ~<N> tokens
 ## Regression Checks
 - [ ] <adjacent flow> — `agent-view <command>` → `<expected>`
 
+## Design Conformance
+<!-- INCLUDE THIS SECTION ONLY IF the developer provided design refs in Step 1 question 4. -->
+<!-- Each pair: a screenshot command + an absolute path to the expected reference image. -->
+<!-- The design-conformance-runner subagent reads this section, runs the screenshot commands, and visually compares against the expected refs. -->
+<!-- Do NOT invent design ref paths. Do NOT assume a convention (e.g. .figma-refs/). Use exactly what the developer provided. -->
+
+| Step Label | Screenshot Command | Expected Reference |
+|---|---|---|
+| <area name e.g. "filter panel"> | `agent-view screenshot --crop "<area>" --scale 0.5` | `<absolute path to expected PNG/JPEG>` |
+| <area name> | `agent-view screenshot --window $W --scale 0.5` | `<absolute path>` |
+
+Tolerance: `normal` (default — flag deviations a designer would notice in code review). Use `loose` only if the developer says exact pixel parity is not required.
+
 ## Anti-patterns avoided
 - <note any recipe-specific traps, e.g. "state resets on reload — watch needed before dom check">
 ```