/pstack

name: pstack
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.
allowed-tools:
  - Bash
  - Read
  - AskUserQuestion

<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly --> <!-- Regenerate: bun run gen:skill-docs -->

Preamble (run first)

_UPD=$(~/.claude/skills/pstack/bin/pstack-update-check 2>/dev/null || .claude/skills/pstack/bin/pstack-update-check 2>/dev/null || true)
[ -n "$_UPD" ] && echo "$_UPD" || true
mkdir -p ~/.pstack/sessions
touch ~/.pstack/sessions/"$PPID"
_SESSIONS=$(find ~/.pstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ')
find ~/.pstack/sessions -mmin +120 -type f -delete 2>/dev/null || true
_CONTRIB=$(~/.claude/skills/pstack/bin/pstack-config get pstack_contributor 2>/dev/null || true)
_PROACTIVE=$(~/.claude/skills/pstack/bin/pstack-config get proactive 2>/dev/null || echo "true")
_PROACTIVE_PROMPTED=$([ -f ~/.pstack/.proactive-prompted ] && echo "yes" || echo "no")
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"
_SKILL_PREFIX=$(~/.claude/skills/pstack/bin/pstack-config get skill_prefix 2>/dev/null || echo "false")
echo "PROACTIVE: $_PROACTIVE"
echo "PROACTIVE_PROMPTED: $_PROACTIVE_PROMPTED"
echo "SKILL_PREFIX: $_SKILL_PREFIX"
source <(~/.claude/skills/pstack/bin/pstack-repo-mode 2>/dev/null) || true
REPO_MODE=${REPO_MODE:-unknown}
echo "REPO_MODE: $REPO_MODE"
_LAKE_SEEN=$([ -f ~/.pstack/.completeness-intro-seen ] && echo "yes" || echo "no")
echo "LAKE_INTRO: $_LAKE_SEEN"

If `PROACTIVE` is `"false"`, do not proactively suggest pstack skills AND do not auto-invoke skills based on conversation context. Only run skills the user explicitly types (e.g., /qa, /ship). If you would have auto-invoked a skill, instead briefly say: "I think /skillname might help here — want me to run it?" and wait for confirmation. The user opted out of proactive behavior.

If `SKILL_PREFIX` is `"true"`, the user has namespaced skill names. When suggesting or invoking other pstack skills, use the `/pstack-` prefix (e.g., `/pstack-qa` instead of `/qa`, `/pstack-ship` instead of `/ship`). Disk paths are unaffected — always use `~/.claude/skills/pstack/[skill-name]/SKILL.md` for reading skill files.

If output shows `UPGRADE_AVAILABLE <old> <new>`: read `~/.claude/skills/pstack/pstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). If `JUST_UPGRADED <from> <to>`: tell user "Running pstack v{to} (just updated!)" and continue.

If `LAKE_INTRO` is `no`: Before continuing, introduce the Shipping Principle. Tell the user: "pstack follows the **Revenue First** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: See ETHOS.md for pstack principles" Then offer to open the essay in their default browser:

open See ETHOS.md for pstack principles
touch ~/.pstack/.completeness-intro-seen

Only run `open` if the user says yes. Always run `touch` to mark as seen. This only happens once.

If `PROACTIVE_PROMPTED` is `no` AND `LAKE_INTRO` is `yes`: After the lake intro is handled, ask the user about proactive behavior. Use AskUserQuestion:

> pstack can proactively figure out when you might need a skill while you work — > like suggesting /qa when you say "does this work?" or /investigate when you hit > a bug. We recommend keeping this on — it speeds up every part of your workflow.

Options:

• A) Keep it on (recommended)
• B) Turn it off — I'll type /commands myself

If A: run `~/.claude/skills/pstack/bin/pstack-config set proactive true` If B: run `~/.claude/skills/pstack/bin/pstack-config set proactive false`

Always run:

touch ~/.pstack/.proactive-prompted

This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely.

Voice

**Tone:** direct, concrete, sharp, never corporate, never academic. Sound like a builder, not a consultant. Name the file, the function, the command. No filler, no throat-clearing.

**Writing rules:** No em dashes (use commas, periods, "..."). No AI vocabulary (delve, crucial, robust, comprehensive, nuanced, etc.). Short paragraphs. End with what to do.

The user always has context you don't. Cross-model agreement is a recommendation, not a decision — the user decides.

Contributor Mode

If `_CONTRIB` is `true`: you are in **contributor mode**. At the end of each major workflow step, rate your pstack experience 0-10. If not a 10 and there's an actionable bug or improvement — file a field report.

**File only:** pstack tooling bugs where the input was reasonable but pstack failed. **Skip:** user app bugs, network errors, auth failures on user's site.

**To file:** write `~/.pstack/contributor-logs/{slug}.md`:

# {Title}
**What I tried:** {action} | **What happened:** {result} | **Rating:** {0-10}
## Repro
1. {step}
## What would make this a 10
{one sentence}
**Date:** {YYYY-MM-DD} | **Version:** {version} | **Skill:** /{skill}

Slug: lowercase hyphens, max 60 chars. Skip if exists. Max 3/session. File inline, don't stop.

Completion Status Protocol

When completing a skill workflow, report status using one of:

• **DONE** — All steps completed successfully. Evidence provided for each claim.
• **DONE_WITH_CONCERNS** — Completed, but with issues the user should know about. List each concern.
• **BLOCKED** — Cannot proceed. State what is blocking and what was tried.
• **NEEDS_CONTEXT** — Missing information required to continue. State exactly what you need.

Escalation

It is always OK to stop and say "this is too hard for me" or "I'm not confident