---
name: visual-validation-3aa5182799e5
description: Autonomous screenshot verification — captures, compares, and AI-evaluates UI changes for visual regressions
when-to-use: When a UI or static-asset change needs visual verification before shipping
user-invocable: false
effort: medium
---

# Visual Validation — Autonomous Screenshot Verification

## Philosophy

Every UI change should be visually verified before it ships. Peekaboo captures pixel-accurate screenshots. The system compares before/after and flags visual regressions. No manual "looks good to me" — the machine verifies what the machine built.

## Autonomous Flow

```
static/* files modified (detected by auto-review-hook or E2E testkit)
    ↓
peekaboo image --mode screen → ~/.maggy/visual-verify/after-{ts}.png
    ↓
Compare with latest baseline (previous after-*.png)
    ↓
AI evaluation: Gemini Flash analyzes screenshot for visual regressions
    ↓
Report: CLEAN or REGRESSION_DETECTED with specific issues
```

## Quick Commands

```bash
# Install
brew install steipete/tap/peekaboo

# Capture full system screenshot
peekaboo image --mode screen --retina --path /tmp/screen.png

# Capture specific window
peekaboo image --mode window --app "Google Chrome" --path /tmp/window.png

# Verify Maggy dashboard after code change
peekaboo image --mode window --app "Google Chrome" --path ~/.maggy/visual-verify/after-$(date -u +%Y%m%d-%H%M%S).png

# Compare two screenshots
ls -la ~/.maggy/visual-verify/after-*.png  # review before/after pairs
```

## Autonomous Verification Flow (Claude Code)

```bash
# After making any static/ file change, Claude should:
1. git add maggy/maggy/static/ && git diff --stat HEAD  # check what changed
2. Restart Maggy: lsof -ti :8080 | xargs kill && python3 -m maggy.main &
3. Wait for health: curl -s http://localhost:8080/api/health
4. Capture screenshot: peekaboo image --mode screen --path ~/.maggy/visual-verify/after-$(date -u +%Y%m%d-%H%M%S).png
5. Compare with latest baseline in ~/.maggy/visual-verify/
6. AI evaluation: ~/bin/gemini-api --flash "Analyze this screenshot for visual regressions"
7. Report findings
```

## Maggy Dashboard Verification

```bash
# One-shot verification
curl -s http://localhost:8080/api/health && \
peekaboo image --mode screen --path ~/.maggy/visual-verify/verify.png && \
echo "✓ Dashboard verified — screenshot at ~/.maggy/visual-verify/verify.png"
```

## Integration Points

### Auto-Review Hook (already wired)
- Detects `static/` changes in git diff
- Auto-captures Peekaboo screenshot
- Saves before/after pairs in `~/.maggy/visual-verify/`

### E2E Testkit Plugin
- Visual regression testing as part of `POST /api/testkit/run`
- Compares screenshots against baselines
- Flags pixel differences above threshold

### Build-in-Public Plugin
- Peekaboo screenshots replace AI-generated images
- Real product captures for LinkedIn/X posts

## When to Use

| Scenario | Command |
|----------|---------|
| After static/ change | `peekaboo image --mode screen --path ~/.maggy/visual-verify/after.png` |
| Before committing UI change | Run verification flow above |
| Reviewing dashboard | Screenshot + AI analysis |
| Build-in-public post | Auto-captured by plugin |
| Cross-browser check | `peekaboo image --mode window --app "Safari"` |


---
Source attribution: alinaqi
Original project: https://github.com/alinaqi/maggy/blob/55aabe2493627e1de9cd09459d555181d66f3111/skills/visual-validation/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Dave AI.

## Upstream license notice

MIT License

Copyright (c) 2025 Ali Naqi

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Dave AI resource metadata

Creator / publisher: alinaqi
Original project: https://github.com/alinaqi/maggy/blob/55aabe2493627e1de9cd09459d555181d66f3111/skills/visual-validation/SKILL.md
Attribution basis: Source repository record

Fields of work: Development & Engineering
Roles: DevOps / SRE, Frontend Developer, QA / Test Engineer
Specialties: Backend, Testing
Tools: Gemini Api, Peekaboo
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 6b15911ba7b5d899fa11379b9784234a2166ed55811f03d531cce674cf66817d