UI Flow Hunter

What It Does

Two skills ship in one plugin. Setup prepares any repo in one pass; the hunter then runs continuously against your app.

• Persona-based crawling — hunts as guest, authenticated user, and admin. Reaching an admin-only page as a guest is a finding, not a technique
• Three audit passes per route — render integrity (clipping, overlaps, FOUC, loading states), behavioral perturbation (input boundaries, double-submission, history thrash, route tampering), and UX friction review
• Dual analysis — broken things become [BUG-UI] issues; working-but-awkward flows become [UX-PROPOSAL] enhancements
• Evidence, not rumors — screenshots captured at the moment of failure, uploaded as GitHub release assets so issue images render inline for anyone with repo access
• Tracker hygiene — deduplication against open issues, per-run issue cap (default 5), environment gating so dev runs never file to your production tracker
• Retest mode — re-runs repros of issues labeled for retest, posts FIXED / STILL REPRODUCIBLE verdicts with evidence, and closes verified fixes
• Black-box by design — works only through the rendered surface; never reads source or touches your existing test suites; all state in an isolated, git-ignored .bug-hunter/ workspace
• Parallel subagent hunts — one agent per persona, so batches stay fast while the main thread stays interactive

Workspace Structure

All hunter state lives in one isolated, git-ignored folder at the target repo root:

.bug-hunter/
├── config.json             ← written by setup: URL, personas, drivers, dispatch rules
├── test-plan.json          ← traversal queue + audited set (never re-audits blind)
├── state-ledger.json       ← per-persona session state
├── artifacts/
│   ├── screenshots/        ← evidence captured at the moment of failure
│   └── traces/             ← driver traces
└── reports/
    ├── bug/                ← issue drafts (filed or unfiled)
    ├── enhancement/
    └── retest/             ← FIXED / STILL REPRODUCIBLE verdicts

Tooling — Installed Automatically

The setup skill ships an idempotent bootstrap script (scripts/setup-tooling.sh) so a fresh install can run without a human babysitting prerequisites:

• Node.js ≥ 18 — detected; usually already on the machine
• Playwright — installed globally via npm if missing
• Chrome / Chromium — uses your system Chrome when present, else installs the Playwright Chromium bundle
• GitHub CLI — installed via brew/apt/dnf if missing

The one step that can never be automated is gh auth login — setup tells you when it is the only thing left, and without it the hunter still runs and saves reports locally instead of filing issues.

When to Use

• Before a release — sweep your staging app for layout breakage, validation gaps, and silent failures
• Continuous quality on a long-lived app — each run extends the test plan and never re-audits blind
• After a fix lands — retest mode verifies the fix against the deployed environment and closes the issue
• "Try to break the UI" — the hunter literally accepts that as an invocation

How to Use

Run setup once per repo, then hunt as often as you like:

Or invoke the skills directly:

Setup ends by offering a dry-run smoke hunt (guest persona, one route, no issues filed) to prove the browser driver works before the first real batch.

Source & Changelog

Skill source: skills/setup-ui-flow-hunter/ · skills/continuous-ui-flow-hunter/