name: gstack preamble-tier: 1 version: 1.1.0 description: | Fast headless browser for QA testing and site dogfooding. Navigate pages, interact with elements, verify state, diff before/after, take annotated screenshots, test responsive layouts, forms, uploads, dialogs, and capture bug evidence. Use when asked to open or test a site, verify a deployment, dogfood a user flow, or file a bug with screenshots. (gstack) allowed-tools:

Bash
Read
AskUserQuestion triggers:
browse this page
take a screenshot
navigate to url
inspect the page

Preamble (run first)

Run: source <(~/.claude/skills/gstack/bin/gstack-skill-start -s gstack -t 1 2>/dev/null || .claude/skills/gstack/bin/gstack-skill-start -s gstack -t 1 2>/dev/null || true)

Skill Invocation During Plan Mode

Follow the preamble command's PLAN_MODE output. Fallback: safe ops $B/$D/codex/~/.gstack//plan files/artifact open; invoked skill starts Step 0; AskUserQuestion ends turn (else ## Decisions to confirm or BLOCKED — AskUserQuestion unavailable); STOP stops; ExitPlanMode only fallback/completion/cancel; run PLAN MODE EXCEPTION — ALWAYS RUN.

Runtime Guidance

Run and follow output (stop on *_ERROR; obey ARTIFACTS_SYNC_ACTION:; continue otherwise): ~/.claude/skills/gstack/bin/gstack-skill-guidance -s gstack -t 1 2>/dev/null || true Fallback closeout if helper unavailable: DONE/DONE_WITH_CONCERNS/BLOCKED/NEEDS_CONTEXT plus evidence; after repeated/security/unverified failure include STATUS/REASON/ATTEMPTED/RECOMMENDATION; telemetry last: ~/.claude/skills/gstack/bin/gstack-skill-complete -s "gstack" -o "OUTCOME" -b "USED_BROWSE" 2>/dev/null || true; before ExitPlanMode ensure ## GSTACK REVIEW REPORT (try ~/.claude/skills/gstack/bin/gstack-skill-guidance -x plan-file-review-report, else append "NO REVIEWS YET" rows). Voice fallback if Runtime Guidance unavailable: direct, concrete, user-outcome-led; cite files/commands/next action; avoid filler, corporate/academic tone, em dashes, and AI vocabulary.

If PROACTIVE=false, only run explicitly invoked skills. If PROACTIVE=true (default), invoke the Skill tool whenever a request matches a gstack skill; do not answer inline when a specialist workflow exists.

Routing: idea/brainstorm → /office-hours; strategy/scope/ambition → /plan-ceo-review; architecture/plan lock → /plan-eng-review; design system/brand → /design-consultation; plan design critique → /plan-design-review; plan DX/API/CLI/SDK → /plan-devex-review; all reviews → /autoplan; bug/error/broken/wtf → /investigate; QA/test site/check deploy → /qa; report-only QA → /qa-only; code/diff/pre-landing review → /review; live visual polish → /design-review; live DX audit/TTHW → /devex-review; ship/deploy/push/PR/land/send → /ship; merge+deploy+verify → /land-and-deploy; deploy config → /setup-deploy; post-deploy monitoring → /canary; post-ship docs → /document-release; weekly retro → /retro; second opinion/codex review → /codex; safety/careful → /careful or /guard; restrict edits → /freeze or /unfreeze; upgrade gstack → /gstack-upgrade; save progress → /context-save; resume/restore → /context-restore; security/OWASP/vulnerabilities → /cso; PDF/publication → /make-pdf; visible browser → /open-gstack-browser; import auth cookies → /setup-browser-cookies; performance/page speed → /benchmark; learnings → /learn; question tuning → /plan-tune; health check → /health.

When in doubt, invoke the matching skill. If none matches, answer directly. Use gstack-config set proactive false|true when the user opts out or back in.

gstack browse: QA Testing & Dogfooding

Persistent headless Chromium. First call auto-starts (~3s), then ~100-200ms per command. State persists: cookies, tabs, sessions. Auto-shuts down after 30 min idle.

SETUP (run before browse commands)

$B will be the browser CLI command. This discovers the compiled browser binary and prints READY: <path> (exports B=<path>) or NEEDS_SETUP; stop on NEEDS_SETUP.

_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || true)
source <(~/.claude/skills/gstack/bin/gstack-skill-browse-setup -s 2>/dev/null || { [ -n "$_ROOT" ] && [ -x "$_ROOT/bin/gstack-skill-browse-setup" ] && "$_ROOT/bin/gstack-skill-browse-setup" -s 2>/dev/null; } || printf '%s\n' 'echo NEEDS_SETUP' 'export _GSTACK_BROWSE_STATUS=NEEDS_SETUP' 'unset B')

If NEEDS_SETUP: ask "gstack browse needs a one-time build (~10 seconds). OK to proceed?" then STOP. With approval run cd "$_GSTACK_SKILL_DIR" && ./setup; if setup lacks bun, run ~/.claude/skills/gstack/bin/gstack-skill-browse-setup -g, follow output, rerun. After READY, $B is the compiled browser CLI; run commands as $B goto <url>, $B snapshot -i, and $B screenshot /tmp/page.png. Do not run browse commands after NEEDS_SETUP until setup succeeds.

IMPORTANT

Use the compiled binary via Bash: $B <command>
NEVER use mcp__claude-in-chrome__* tools. They are slow and unreliable.
Browser state persists; dialogs auto-accept by default.
Show screenshots: After $B screenshot, $B snapshot -a -o, or $B responsive, always use the Read tool on the output PNG(s) so the user can see them. Without this, screenshots are invisible.

Core Browse Loop

# Page/prod check
$B goto https://yourapp.com
$B text
$B console
$B network
$B is visible ".hero-section"
$B screenshot /tmp/prod-check.png

# User flow: refs → act → diff/assert/evidence
$B goto https://app.example.com/login
$B snapshot -i
$B fill @e3 "$TEST_EMAIL"
$B fill @e4 "$TEST_PASSWORD"
$B click @e5
$B snapshot -D
$B is visible ".dashboard"
$B screenshot /tmp/after-login.png

Extended Workflows

Run: ~/.claude/skills/gstack/bin/gstack-skill-guidance -x browse-workflows 2>/dev/null || echo "BROWSE_WORKFLOWS_ERROR"

Snapshot System

The snapshot is your primary tool for understanding and interacting with pages. $B is the browse binary (resolved from $_ROOT/.claude/skills/gstack/browse/dist/browse or ~/.claude/skills/gstack/browse/dist/browse).

Syntax: $B snapshot [flags]

-i        --interactive           Interactive elements only (buttons, links, inputs) with @e refs. Also auto-enables cursor-interactive scan (-C) to capture dropdowns and popovers.
-c        --compact               Compact (no empty structural nodes)
-d <N>    --depth                 Limit tree depth (0 = root only, default: unlimited)
-s <sel>  --selector              Scope to CSS selector
-D        --diff                  Unified diff against previous snapshot (first call stores baseline)
-a        --annotate              Annotated screenshot with red overlay boxes and ref labels
-o <path> --output                Output path for annotated screenshot (default: <temp>/browse-annotated.png)
-C        --cursor-interactive    Cursor-interactive elements (@c refs — divs with pointer, onclick). Auto-enabled when -i is used.
-H <json> --heatmap               Color-coded overlay screenshot from JSON map: '{"@e1":"green","@e3":"red"}'. Valid colors: green, yellow, red, blue, orange, gray.

All flags can be combined. -o only applies with -a; -D stores/compares a baseline; refs invalidate on navigation. Use @refs as selectors after snapshot:

$B click @e3       $B fill @e4 "value"     $B hover @e1
$B html @e2        $B css @e5 "color"      $B attrs @e6
$B click @c1       # cursor-interactive ref (from -C)

Example: $B snapshot -i -a -C -o /tmp/annotated.png.

Command Reference

Run: ~/.claude/skills/gstack/bin/gstack-skill-guidance -x browse-command-reference 2>/dev/null || echo "BROWSE_COMMAND_REFERENCE_ERROR"

Gstack - Headless Browser for QA

Recommended for