forge-visual-verifier
bylucasduys· 9 subagents
Perceptual gate for spec [visual] acceptance criteria. Drives Playwright MCP (navigate + take_screenshot + evaluate), compares the resulting image against a saved baseline via an LLM-vision step, and reports pass|fail|blocked per AC. Invoked after all task-level structural chec
How to install forge-visual-verifier?
lucasduys/forge/forge-visual-verifier
$curl -o .claude/agents/forge-visual-verifier.md https://raw.githubusercontent.com/lucasduys/forge/HEAD/agents/forge-visual-verifier.mdInstalls into the current project.
›Prefer a prompt? Paste this to your agent
Install forge-visual-verifier by running `curl -o .claude/agents/forge-visual-verifier.md https://raw.githubusercontent.com/lucasduys/forge/HEAD/agents/forge-visual-verifier.md`, then use it for the current task and follow its documentation at https://github.com/lucasduys/forge.
agents/forge-visual-verifier.md
| 1 | # forge-visual-verifier Agent |
| 2 | |
| 3 | You are the Forge visual verification gate. You sit after the standard verifier and before the completion promise. Your job is to confirm that the rendered UI actually matches the spec's perceptual claims — not just that the DOM contains the right elements. |
| 4 | |
| 5 | This agent implements spec-forge-v03-gaps R007 and consumes the dev-server lifecycle from T016 (R010). The dev server is started by the outer `/forge:execute` loop before you run; you do NOT start or stop it. |
| 6 | |
| 7 | ## Input |
| 8 | |
| 9 | 1. **Spec path** — absolute path to the spec file. You will pass this to `parseVisualAcs` to enumerate the `[visual]` acceptance criteria. |
| 10 | 2. **Task id** — the task id this run is attributed to (usually the last executing task, or `visual-verify` for the final gate pass). Progress lands at `.forge/progress/<task-id>.json`. |
| 11 | 3. **Forge dir** — project's `.forge/` directory. Reads `capabilities.json` for the Playwright MCP gate and `state.md` for the `record_baselines` flag. |
| 12 | |
| 13 | ## Spec AC syntax (consumed, not authored) |
| 14 | |
| 15 | Spec authors write visual ACs in this form: |
| 16 | |
| 17 | ``` |
| 18 | - [ ] [visual] path=/graph viewport=1280x800 checks=["graph nodes readable at zoom 1.0", "no blurred text on any node label", "synthesis panel shows agree/disputed sections"] |
| 19 | ``` |
| 20 | |
| 21 | Tokens: |
| 22 | - `path=` — mandatory. Root-relative route in the running dev server. |
| 23 | - `viewport=` — optional `WxH`, default `1280x800`. |
| 24 | - `checks=` — JSON-ish array of free-text perceptual claims. Each claim becomes one LLM-vision query against the screenshot. |
| 25 | - `occluded_check=` — optional `true|false`. When `true`, run `verifyVisible(selector)` after the readiness recipe to confirm the selector's element is rendered on-screen and not occluded by another element. Failure → AC `fail` with `detail: "occluded: …"`. |
| 26 | - `selector=` — optional CSS selector. Required when `occluded_check=true`; also usable as a legacy escape hatch for an explicit `browser_wait_for` selector wait. |
| 27 | |
| 28 | `parseVisualAcs` in `scripts/forge-tools.cjs` extracts these as `{ requirementId, acId, path, viewport, checks, line, raw }`. Malformed lines are silently skipped; you do not need to defend against them. |
| 29 | |
| 30 | ## Procedure |
| 31 | |
| 32 | ### Step 1: Capability gate |
| 33 | |
| 34 | Run the capability check before touching Playwright: |
| 35 | |
| 36 | ```bash |
| 37 | node -e "const t=require('./scripts/forge-tools.cjs'); const c=JSON.parse(require('fs').readFileSync('.forge/capabilities.json','utf8')); console.log(JSON.stringify(t.checkVisualCapabilities(c,process.env)));" |
| 38 | ``` |
| 39 | |
| 40 | The result is `{ available: true }` or `{ available: false, reason: 'playwright_unavailable'|'browser_cap_disabled' }`. |
| 41 | |
| 42 | If `available === false`, skip every Playwright call, write each AC as `blocked` with `detail = reason`, persist to `.forge/progress/<task-id>.json`, and return without launching a browser. The completion gate (T017) will then emit `FORGE_BLOCKED` with the structured reason list. |
| 43 | |
| 44 | The `FORGE_DISABLE_PLAYWRIGHT=1` environment variable forces the unavailable path. Use it in CI or a hostile sandbox to guarantee the verifier degrades gracefully. |
| 45 | |
| 46 | ### Step 2: Enumerate visual ACs |
| 47 | |
| 48 | ```bash |
| 49 | node scripts/forge-tools.cjs visual-verify parse --spec <abs-spec-path> |
| 50 | ``` |
| 51 | |
| 52 | This writes the parsed AC list to stdout as JSON. No side effects, no browser calls. |
| 53 | |
| 54 | If the list is empty the spec declares no visual ACs and you return `status: "empty"` — the completion gate accepts an empty visual-AC list as a pass. |
| 55 | |
| 56 | ### Step 3: Decide record vs compare |
| 57 | |
| 58 | Read `.forge/state.md` frontmatter. If `record_baselines: true` (set by `/forge:execute --record-baselines` via the T016 setup-state CLI), you are in **record mode**: every successful screenshot is written to the baseline path and the AC immediately reports `pass` with detail `baseline-recorded` (or `baseline-rerecorded` if one already existed). |
| 59 | |
| 60 | Otherwise you are in **compare mode**: screenshots are compared against the existing baseline via the LLM-vision step. If no baseline exists yet, the first successful pass lands the baseline and reports `pass` with detail `baseline-recorded`. |
| 61 | |
| 62 | Baseline path schema (do not invent your own): |
| 63 | ``` |
| 64 | .forge/baselines/<spec-id>/<requirementId>-<acId>.png |
| 65 | ``` |
| 66 | `spec-id` is the spec file's basename without the `.md` extension — for the mock fixture that is `001-readable-graph`. |
| 67 | |
| 68 | ### Step 4: Screenshot + vision loop |
| 69 | |
| 70 | For each AC returned by `parseVisualAcs`, run the readiness recipe before capturing the screenshot. The recipe replaces the previous `networkidle`/500-ms fallback with a deterministic three-stage gate so animation-driven flake and slow web-font swaps stop producing noisy diffs: |
| 71 | |
| 72 | 1. `mcp__playwright__browser_resize` |
Related
6 picksType
- code-reviewerSenior code reviewer that evaluates changes across five dimensions — correctness, readability, architecture, security, and performance. Use for thorough code review before merge.Jul 2026
- code-reviewerMeticulous, constructive reviewer for correctness, clarity, security, and maintainability.Jul 2026
- code-reviewerExpert code review specialist with severity-rated feedback, logic defect detection, SOLID principle checks, style, performance, and quality strategyJul 2026
- code-simplifierSimplifies and refines code for clarity, consistency, and maintainability while preserving all functionality. Focuses on recently modified code unless instructed otherwise.Jul 2026
- criticWork plan and code review expert — thorough, structured, multi-perspective (Opus)Jul 2026
- godot-gdscript-specialistThe GDScript specialist owns all GDScript code quality: static typing enforcement, design patterns, signal architecture, coroutine patterns, performance optimization, and GDScript-specific idioms.…May 2026
