Browser Review

Variables

HEADED: false # Show browser windows. Derived from $ARGUMENTS if "headed" passed VISION: false # Screenshot-as-image validation. Derived from $ARGUMENTS if "vision" passed STORIES_DIR: ai_review/user_stories # Directory containing YAML story files AGENT_TIMEOUT: 300 # Seconds before agent timeout FILENAME_FILTER: "" # Restrict discovery to matching YAML filenames

Workflow

1. Validate Prerequisites

   • Confirm browser skill and browser-qa agent are installed
   • Confirm playwright-cli is available: which playwright-cli
   • IF: any missing → report what's missing and stop
   • Example: which playwright-cli returns path → proceed

2. Parse Arguments

   • Scan $ARGUMENTS for keywords (case-insensitive)
   • IF: "headed" → set HEADED=true
   • IF: "vision" → set VISION=true
   • Remaining text → set FILENAME_FILTER
   • Example: "headed hackernews" → HEADED=true, FILENAME_FILTER="hackernews"
   • Example: no args → all defaults (headless, no vision, all stories)

3. Discover Stories

   • Glob: <STORIES_DIR>/*.yaml
   • IF: FILENAME_FILTER is set → only include files matching filter
   • Parse each YAML → extract stories array
   • Count total stories across all files
   • Create timestamped run directory: screenshots/browser-qa/<YYYY-MM-DD>_<HH-MM-SS>_<uuid>/
   • IF: no stories found → report "No stories found in " and stop
   • Example: found hackernews.yaml with 3 stories → 3 agents needed

4. Spawn Parallel Agents

   • For each story, spawn a browser-qa agent using the Agent tool with run_in_background: true
   • Each agent gets:

     Execute this user story:
     
     **Story:** <story-name>
     **URL:** <story-url>
     **Headed:** <HEADED>
     **Vision:** <VISION>
     **Screenshots Directory:** <run-dir>/<source-file>/<story-slug>/
     
     **Workflow:**
     <story-workflow>
     

   • Launch ALL agents in a single message (parallel execution)
   • Example: 3 stories → 3 parallel Agent tool calls in one message

5. Collect Results

   • Wait for all background agents to complete
   • Parse each agent's report for: PASS/FAIL status, step count, screenshot directory
   • Example: Agent 1 → "PASS 3/3 steps", Agent 2 → "FAIL 2/4 steps"

6. Generate Summary Report

   • Format:

     UI REVIEW SUMMARY
     Run: <timestamp>
     Stories: <total> | Passed: <pass-count> | Failed: <fail-count>
     
     | # | Story | Source | Status | Steps | Screenshots |
     |---|-------|--------|--------|-------|-------------|
     | 1 | Front page loads | hackernews.yaml | PASS | 3/3 | path/ |
     | 2 | View comments | hackernews.yaml | FAIL | 2/3 | path/ |
     

   • IF: any failures → include full failure reports below the table
   • Report screenshot root directory for easy browsing

Works well with

Optional collaborators — browser-review runs standalone and these degrade gracefully if absent.

• browser — the underlying capability it fans out across parallel sessions.
• browser-qa (agent) — the per-story validator browser-review spawns and aggregates.
• browser-microscope — escalate here to dissect a layout failure a story surfaced.