     1→---
     2→name: design-review
     3→version: 2.0.0
     4→description: |
     5→  Designer's eye QA: finds visual inconsistency, spacing issues, hierarchy problems,
     6→  AI slop patterns, and slow interactions — then fixes them. Iteratively fixes issues
     7→  in source code, committing each fix atomically and re-verifying with before/after
     8→  screenshots. For plan-mode design review (before implementation), use /plan-design-review.
     9→allowed-tools:
    10→  - Bash
    11→  - Read
    12→  - Write
    13→  - Edit
    14→  - Glob
    15→  - Grep
    16→  - AskUserQuestion
    17→  - WebSearch
    18→---
    19→
    20→{{PREAMBLE}}
    21→
    22→# /design-review: Design Audit → Fix → Verify
    23→
    24→You are a senior product designer AND a frontend engineer. Review live sites with exacting visual standards — then fix what you find. You have strong opinions about typography, spacing, and visual hierarchy, and zero tolerance for generic or AI-generated-looking interfaces.
    25→
    26→## Setup
    27→
    28→**Parse the user's request for these parameters:**
    29→
    30→| Parameter | Default | Override example |
    31→|-----------|---------|-----------------:|
    32→| Target URL | (auto-detect or ask) | `https://myapp.com`, `http://localhost:3000` |
    33→| Scope | Full site | `Focus on the settings page`, `Just the homepage` |
    34→| Depth | Standard (5-8 pages) | `--quick` (homepage + 2), `--deep` (10-15 pages) |
    35→| Auth | None | `Sign in as user@example.com`, `Import cookies` |
    36→
    37→**If no URL is given and you're on a feature branch:** Automatically enter **diff-aware mode** (see Modes below).
    38→
    39→**If no URL is given and you're on main/master:** Ask the user for a URL.
    40→
    41→**Check for DESIGN.md:**
    42→
    43→Look for `DESIGN.md`, `design-system.md`, or similar in the repo root. If found, read it — all design decisions must be calibrated against it. Deviations from the project's stated design system are higher severity. If not found, use universal design principles and offer to create one from the inferred system.
    44→
    45→**Require clean working tree before starting:**
    46→
    47→```bash
    48→if [ -n "$(git status --porcelain)" ]; then
    49→  echo "ERROR: Working tree is dirty. Commit or stash changes before running /design-review."
    50→  exit 1
    51→fi
    52→```
    53→
    54→**Find the browse binary:**
    55→
    56→{{BROWSE_SETUP}}
    57→
    58→**Check test framework (bootstrap if needed):**
    59→
    60→{{TEST_BOOTSTRAP}}
    61→
    62→**Create output directories:**
    63→
    64→```bash
    65→REPORT_DIR=".gstack/design-reports"
    66→mkdir -p "$REPORT_DIR/screenshots"
    67→```
    68→
    69→---
    70→
    71→## Phases 1-6: Design Audit Baseline
    72→
    73→{{DESIGN_METHODOLOGY}}
    74→
    75→Record baseline design score and AI slop score at end of Phase 6.
    76→
    77→---
    78→
    79→## Output Structure
    80→
    81→```
    82→.gstack/design-reports/
    83→├── design-audit-{domain}-{YYYY-MM-DD}.md    # Structured report
    84→├── screenshots/
    85→│   ├── first-impression.png                  # Phase 1
    86→│   ├── {page}-annotated.png                  # Per-page annotated
    87→│   ├── {page}-mobile.png                     # Responsive
    88→│   ├── {page}-tablet.png
    89→│   ├── {page}-desktop.png
    90→│   ├── finding-001-before.png                # Before fix
    91→│   ├── finding-001-after.png                 # After fix
    92→│   └── ...
    93→└── design-baseline.json                      # For regression mode
    94→```
    95→
    96→---
    97→
    98→## Phase 7: Triage
    99→
   100→Sort all discovered findings by impact, then decide which to fix:


bash "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags-shell.sh" "post:observe" "skills/continuous-learning-v2/hooks/observe.sh" "standard,strict"


     1→---
     2→name: document-release
     3→version: 1.0.0
     4→description: |
     5→  Post-ship documentation update. Reads all project docs, cross-references the
     6→  diff, updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped,
     7→  polishes CHANGELOG voice, cleans up TODOS, and optionally bumps VERSION.
     8→allowed-tools:
     9→  - Bash
    10→  - Read
    11→  - Write
    12→  - Edit
    13→  - Grep
    14→  - Glob
    15→  - AskUserQuestion
    16→---
    17→
    18→{{PREAMBLE}}
    19→
    20→{{BASE_BRANCH_DETECT}}
    21→
    22→# Document Release: Post-Ship Documentation Update
    23→
    24→You are running the `/document-release` workflow. This runs **after `/ship`** (code committed, PR
    25→exists or about to exist) but **before the PR merges**. Your job: ensure every documentation file
    26→in the project is accurate, up to date, and written in a friendly, user-forward voice.
    27→
    28→You are mostly automated. Make obvious factual updates directly. Stop and ask only for risky or
    29→subjective decisions.
    30→
    31→**Only stop for:**
    32→- Risky/questionable doc changes (narrative, philosophy, security, removals, large rewrites)
    33→- VERSION bump decision (if not already bumped)
    34→- New TODOS items to add
    35→- Cross-doc contradictions that are narrative (not factual)
    36→
    37→**Never stop for:**
    38→- Factual corrections clearly from the diff
    39→- Adding items to tables/lists
    40→- Updating paths, counts, version numbers
    41→- Fixing stale cross-references
    42→- CHANGELOG voice polish (minor wording adjustments)
    43→- Marking TODOS complete
    44→- Cross-doc factual inconsistencies (e.g., version number mismatch)
    45→
    46→**NEVER do:**
    47→- Overwrite, replace, or regenerate CHANGELOG entries — polish wording only, preserve all content
    48→- Bump VERSION without asking — always use AskUserQuestion for version changes
    49→- Use `Write` tool on CHANGELOG.md — always use `Edit` with exact `old_string` matches
    50→
    51→---
    52→
    53→## Step 1: Pre-flight & Diff Analysis
    54→
    55→1. Check the current branch. If on the base branch, **abort**: "You're on the base branch. Run from a feature branch."
    56→
    57→2. Gather context about what changed:
    58→
    59→```bash
    60→git diff <base>...HEAD --stat
    61→```
    62→
    63→```bash
    64→git log <base>..HEAD --oneline
    65→```
    66→
    67→```bash
    68→git diff <base>...HEAD --name-only
    69→```
    70→
    71→3. Discover all documentation files in the repo:
    72→
    73→```bash
    74→find . -maxdepth 2 -name "*.md" -not -path "./.git/*" -not -path "./node_modules/*" -not -path "./.gstack/*" -not -path "./.context/*" | sort
    75→```
    76→
    77→4. Classify the changes into categories relevant to documentation:
    78→   - **New features** — new files, new commands, new skills, new capabilities
    79→   - **Changed behavior** — modified services, updated APIs, config changes
    80→   - **Removed functionality** — deleted files, removed commands
    81→   - **Infrastructure** — build system, test infrastructure, CI
    82→
    83→5. Output a brief summary: "Analyzing N files changed across M commits. Found K documentation files to review."
    84→
    85→---
    86→
    87→## Step 2: Per-File Documentation Audit
    88→
    89→Read each documentation file and cross-reference it against the diff. Use these generic heuristics
    90→(adapt to whatever project you're in — these are not gstack-specific):
    91→
    92→**README.md:**
    93→- Does it describe all features and capabilities visible in the diff?
    94→- Are install/setup instructions consistent with the changes?
    95→- Are examples, demos, and usage descriptions still valid?
    96→- Are troubleshooting steps still accurate?
    97→
    98→**ARCHITECTURE.md:**
    99→- Do ASCII diagrams and component descriptions match the current code?
   100→- Are design decisions and "why" explanations still accurate?
   101→- Be conservative — only update things clearly contradicted by the diff. Architecture docs
   102→  describe things unlikely to change frequently.
   103→
   104→**CONTRIBUTING.md — New contributor smoke test:**
   105→- Walk through the setup instructions as if you are a brand new contributor.
   106→- Are the listed commands accurate? Would each step succeed?
   107→- Do test tier descriptions match the current test infrastructure?
   108→- Are workflow descriptions (dev setup, contributor mode, etc.) current?
   109→- Flag anything that would fail or confuse a first-time contributor.
   110→
   111→**CLAUDE.md / project instructions:**
   112→- Does the project structure section match the actual file tree?
   113→- Are listed commands and scripts accurate?
   114→- Do build/test instructions match what's in package.json (or equivalent)?
   115→
   116→**Any other .md files:**
   117→- Read the file, determine its purpose and audience.
   118→- Cross-reference against the diff to check if it contradicts anything the file says.
   119→
   120→For each file, classify needed updates as:


Bash

ls -la /root/projects/gits/gstack/ | head -30

List main gstack directory


node "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js" "pre:bash:tmux-reminder" "scripts/hooks/pre-bash-tmux-reminder.js" "strict"


node "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js" "pre:bash:git-push-reminder" "scripts/hooks/pre-bash-git-push-reminder.js" "strict"


bash "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags-shell.sh" "pre:observe" "skills/continuous-learning-v2/hooks/observe.sh" "standard,strict"


node "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js" "pre:insaits-security" "scripts/hooks/insaits-security-wrapper.js" "standard,strict"


node "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js" "post:bash:pr-created" "scripts/hooks/post-bash-pr-created.js" "standard,strict"


node "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js" "post:bash:build-complete" "scripts/hooks/post-bash-build-complete.js" "standard,strict"


total 216
drwxr-xr-x 22 root root  4096 Mar 18 15:58 .
drwxr-xr-x  4 root root    33 Mar 18 15:58 ..
-rw-r--r--  1 root root 20797 Mar 18 15:58 ARCHITECTURE.md
drwxr-xr-x  2 root root   135 Mar 18 15:58 bin
drwxr-xr-x  5 root root    77 Mar 18 15:58 browse
-rw-r--r--  1 root root 16159 Mar 18 15:58 BROWSER.md
-rw-r--r--  1 root root 46273 Mar 18 15:58 CHANGELOG.md
-rw-r--r--  1 root root  9988 Mar 18 15:58 CLAUDE.md
-rw-r--r--  1 root root    87 Mar 18 15:58 conductor.json
-rw-r--r--  1 root root 13456 Mar 18 15:58 CONTRIBUTING.md
drwxr-xr-x  2 root root    43 Mar 18 15:58 design-consultation
drwxr-xr-x  2 root root    43 Mar 18 15:58 design-review
drwxr-xr-x  3 root root    37 Mar 18 15:58 docs
drwxr-xr-x  2 root root    43 Mar 18 15:58 document-release
-rw-r--r--  1 root root   171 Mar 18 15:58 .env.example
drwxr-xr-x  8 root root   163 Mar 18 15:58 .git
drwxr-xr-x  3 root root    23 Mar 18 15:58 .github
-rw-r--r--  1 root root   127 Mar 18 15:58 .gitignore
drwxr-xr-x  2 root root    43 Mar 18 15:58 gstack-upgrade
-rw-r--r--  1 root root  1066 Mar 18 15:58 LICENSE
-rw-r--r--  1 root root  1879 Mar 18 15:58 package.json
drwxr-xr-x  2 root root    43 Mar 18 15:58 plan-ceo-review
drwxr-xr-x  2 root root    43 Mar 18 15:58 plan-design-review
drwxr-xr-x  2 root root    43 Mar 18 15:58 plan-eng-review
drwxr-xr-x  4 root root    78 Mar 18 15:58 qa
drwxr-xr-x  2 root root    43 Mar 18 15:58 qa-only
-rw-r--r--  1 root root 14319 Mar 18 15:58 README.md
drwxr-xr-x  2 root root    43 Mar 18 15:58 retro
drwxr-xr-x  2 root root   139 Mar 18 15:58 review


Perfect. Now let me get a quick overview of the browse/src structure and the remaining skills:


List browse source files


total 176
drwxr-xr-x 2 root root  4096 Mar 18 15:58 .
drwxr-xr-x 5 root root    77 Mar 18 15:58 ..
-rw-r--r-- 1 root root 15877 Mar 18 15:58 browser-manager.ts
-rw-r--r-- 1 root root  4276 Mar 18 15:58 buffers.ts
-rw-r--r-- 1 root root 11046 Mar 18 15:58 cli.ts
-rw-r--r-- 1 root root  7899 Mar 18 15:58 commands.ts
-rw-r--r-- 1 root root  4694 Mar 18 15:58 config.ts
-rw-r--r-- 1 root root 15632 Mar 18 15:58 cookie-import-browser.ts
-rw-r--r-- 1 root root  7704 Mar 18 15:58 cookie-picker-routes.ts
-rw-r--r-- 1 root root 16745 Mar 18 15:58 cookie-picker-ui.ts
-rw-r--r-- 1 root root  1654 Mar 18 15:58 find-browse.ts
-rw-r--r-- 1 root root  9221 Mar 18 15:58 meta-commands.ts
-rw-r--r-- 1 root root 11743 Mar 18 15:58 read-commands.ts
-rw-r--r-- 1 root root 13412 Mar 18 15:58 server.ts
-rw-r--r-- 1 root root 15117 Mar 18 15:58 snapshot.ts
-rw-r--r-- 1 root root 13237 Mar 18 15:58 write-commands.ts


List all skill directories


/root/projects/gits/gstack/bin/:
total 32
drwxr-xr-x  2 root root  135 Mar 18 15:58 .
drwxr-xr-x 22 root root 4096 Mar 18 15:58 ..
-rwxr-xr-x  1 root root 1952 Mar 18 15:58 dev-setup
-rwxr-xr-x  1 root root  946 Mar 18 15:58 dev-teardown
-rwxr-xr-x  1 root root 1134 Mar 18 15:58 gstack-config
-rwxr-xr-x  1 root root 2480 Mar 18 15:58 gstack-diff-scope
-rwxr-xr-x  1 root root  476 Mar 18 15:58 gstack-slug
-rwxr-xr-x  1 root root 5636 Mar 18 15:58 gstack-update-check

/root/projects/gits/gstack/browse/:
total 32
drwxr-xr-x  5 root root    77 Mar 18 15:58 .
drwxr-xr-x 22 root root  4096 Mar 18 15:58 ..
drwxr-xr-x  2 root root    44 Mar 18 15:58 bin
-rw-r--r--  1 root root 16291 Mar 18 15:58 SKILL.md
-rw-r--r--  1 root root  3254 Mar 18 15:58 SKILL.md.tmpl
drwxr-xr-x  2 root root  4096 Mar 18 15:58 src
drwxr-xr-x  3 root root  4096 Mar 18 15:58 test

/root/projects/gits/gstack/design-consultation/:
total 52
drwxr-xr-x  2 root root    43 Mar 18 15:58 .
drwxr-xr-x 22 root root  4096 Mar 18 15:58 ..
-rw-r--r--  1 root root 26030 Mar 18 15:58 SKILL.md
-rw-r--r--  1 root root 18398 Mar 18 15:58 SKILL.md.tmpl

/root/projects/gits/gstack/design-review/:
total 56
drwxr-xr-x  2 root root    43 Mar 18 15:58 .
drwxr-xr-x 22 root root  4096 Mar 18 15:58 ..
-rw-r--r--  1 root root 39162 Mar 18 15:58 SKILL.md
-rw-r--r--  1 root root  8529 Mar 18 15:58 SKILL.md.tmpl

/root/projects/gits/gstack/docs/:
total 40
drwxr-xr-x  3 root root    37 Mar 18 15:58 .
drwxr-xr-x 22 root root  4096 Mar 18 15:58 ..
drwxr-xr-x  2 root root    52 Mar 18 15:58 images
-rw-r--r--  1 root root 32964 Mar 18 15:58 skills.md

/root/projects/gits/gstack/document-release/:
total 44
drwxr-xr-x  2 root root    43 Mar 18 15:58 .
drwxr-xr-x 22 root root  4096 Mar 18 15:58 ..
-rw-r--r--  1 root root 21444 Mar 18 15:58 SKILL.md
-rw-r--r--  1 root root 13720 Mar 18 15:58 SKILL.md.tmpl

/root/projects/gits/gstack/gstack-upgrade/:
total 20
drwxr-xr-x  2 root root   43 Mar 18 15:58 .
drwxr-xr-x 22 root root 4096 Mar 18 15:58 ..
-rw-r--r--  1 root root 7962 Mar 18 15:58 SKILL.md
-rw-r--r--  1 root root 7850 Mar 18 15:58 SKILL.md.tmpl

/root/projects/gits/gstack/plan-ceo-review/:
total 112
drwxr-xr-x  2 root root    43 Mar 18 15:58 .
drwxr-xr-x 22 root root  4096 Mar 18 15:58 ..
-rw-r--r--  1 root root 58363 Mar 18 15:58 SKILL.md
-rw-r--r--  1 root root 48103 Mar 18 15:58 SKILL.md.tmpl

/root/projects/gits/gstack/plan-design-review/:
total 52
drwxr-xr-x  2 root root    43 Mar 18 15:58 .
drwxr-xr-x 22 root root  4096 Mar 18 15:58 ..
-rw-r--r--  1 root root 26803 Mar 18 15:58 SKILL.md
-rw-r--r--  1 root root 16543 Mar 18 15:58 SKILL.md.tmpl

/root/projects/gits/gstack/plan-eng-review/:
total 52
drwxr-xr-x  2 root root    43 Mar 18 15:58 .
drwxr-xr-x 22 root root  4096 Mar 18 15:58 ..
-rw-r--r--  1 root root 26059 Mar 18 15:58 SKILL.md
-rw-r--r--  1 root root 16490 Mar 18 15:58 SKILL.md.tmpl

/root/projects/gits/gstack/qa/:
total 52
drwxr-xr-x  4 root root    78 Mar 18 15:58 .
drwxr-xr-x 22 root root  4096 Mar 18 15:58 ..
drwxr-xr-x  2 root root    31 Mar 18 15:58 references
-rw-r--r--  1 root root 36115 Mar 18 15:58 SKILL.md
-rw-r--r--  1 root root 10302 Mar 18 15:58 SKILL.md.tmpl
drwxr-xr-x  2 root root    35 Mar 18 15:58 templates

/root/projects/gits/gstack/qa-only/:
total 32
drwxr-xr-x  2 root root    43 Mar 18 15:58 .
drwxr-xr-x 22 root root  4096 Mar 18 15:58 ..
-rw-r--r--  1 root root 21885 Mar 18 15:58 SKILL.md
-rw-r--r--  1 root root  3628 Mar 18 15:58 SKILL.md.tmpl

/root/projects/gits/gstack/retro/:
total 56
drwxr-xr-x  2 root root    43 Mar 18 15:58 .
drwxr-xr-x 22 root root  4096 Mar 18 15:58 ..
-rw-r--r--  1 root root 28236 Mar 18 15:58 SKILL.md
-rw-r--r--  1 root root 21203 Mar 18 15:58 SKILL.md.tmpl

/root/projects/gits/gstack/review/:
total 72
drwxr-xr-x  2 root root   139 Mar 18 15:58 .
drwxr-xr-x 22 root root  4096 Mar 18 15:58 ..
-rw-r--r--  1 root root 10034 Mar 18 15:58 checklist.md
-rw-r--r--  1 root root  6603 Mar 18 15:58 design-checklist.md
-rw-r--r--  1 root root  8271 Mar 18 15:58 greptile-triage.md
-rw-r--r--  1 root root 17852 Mar 18 15:58 SKILL.md
-rw-r--r--  1 root root  8271 Mar 18 15:58 SKILL.md.tmpl
-rw-r--r--  1 root root  1660 Mar 18 15:58 TODOS-format.md

/root/projects/gits/gstack/scripts/:
total 96
drwxr-xr-x  2 root root   182 Mar 18 15:58 .
drwxr-xr-x 22 root root  4096 Mar 18 15:58 ..
-rw-r--r--  1 root root  2501 Mar 18 15:58 dev-skill.ts
-rw-r--r--  1 root root  3033 Mar 18 15:58 eval-compare.ts
-rw-r--r--  1 root root  3571 Mar 18 15:58 eval-list.ts
-rw-r--r--  1 root root  3186 Mar 18 15:58 eval-select.ts
-rw-r--r--  1 root root  6591 Mar 18 15:58 eval-summary.ts
-rw-r--r--  1 root root  5568 Mar 18 15:58 eval-watch.ts
-rw-r--r--  1 root root 54855 Mar 18 15:58 gen-skill-docs.ts
-rw-r--r--  1 root root  3977 Mar 18 15:58 skill-check.ts

/root/projects/gits/gstack/setup-browser-cookies/:
total 20
drwxr-xr-x  2 root root   43 Mar 18 15:58 .
drwxr-xr-x 22 root root 4096 Mar 18 15:58 ..
-rw-r--r--  1 root root 9699 Mar 18 15:58 SKILL.md
-rw-r--r--  1 root root 2067 Mar 18 15:58 SKILL.md.tmpl

/root/projects/gits/gstack/ship/:
total 80
drwxr-xr-x  2 root root    43 Mar 18 15:58 .
drwxr-xr-x 22 root root  4096 Mar 18 15:58 ..
-rw-r--r--  1 root root 47354 Mar 18 15:58 SKILL.md
-rw-r--r--  1 root root 28372 Mar 18 15:58 SKILL.md.tmpl

/root/projects/gits/gstack/test/:
total 236
drwxr-xr-x  4 root root   4096 Mar 18 15:58 .
drwxr-xr-x 22 root root   4096 Mar 18 15:58 ..
drwxr-xr-x  2 root root   4096 Mar 18 15:58 fixtures
-rw-r--r--  1 root root  14350 Mar 18 15:58 gen-skill-docs.test.ts
drwxr-xr-x  2 root root   4096 Mar 18 15:58 helpers
-rw-r--r--  1 root root 116100 Mar 18 15:58 skill-e2e.test.ts
-rw-r--r--  1 root root  28582 Mar 18 15:58 skill-llm-eval.test.ts
-rw-r--r--  1 root root   5436 Mar 18 15:58 skill-parser.test.ts
-rw-r--r--  1 root root  39647 Mar 18 15:58 skill-validation.test.ts
-rw-r--r--  1 root root   9678 Mar 18 15:58 touchfiles.test.ts


     1→---
     2→name: qa-only
     3→version: 1.0.0
     4→description: |
     5→  Report-only QA testing. Systematically tests a web application and produces a
     6→  structured report with health score, screenshots, and repro steps — but never
     7→  fixes anything. Use when asked to "just report bugs", "qa report only", or
     8→  "test but don't fix". For the full test-fix-verify loop, use /qa instead.
     9→allowed-tools:
    10→  - Bash
    11→  - Read
    12→  - Write
    13→  - AskUserQuestion
    14→---
    15→
    16→{{PREAMBLE}}
    17→
    18→# /qa-only: Report-Only QA Testing
    19→
    20→You are a QA engineer. Test web applications like a real user — click everything, fill every form, check every state. Produce a structured report with evidence. **NEVER fix anything.**
    21→
    22→## Setup
    23→
    24→**Parse the user's request for these parameters:**
    25→
    26→| Parameter | Default | Override example |
    27→|-----------|---------|-----------------:|
    28→| Target URL | (auto-detect or required) | `https://myapp.com`, `http://localhost:3000` |
    29→| Mode | full | `--quick`, `--regression .gstack/qa-reports/baseline.json` |
    30→| Output dir | `.gstack/qa-reports/` | `Output to /tmp/qa` |
    31→| Scope | Full app (or diff-scoped) | `Focus on the billing page` |
    32→| Auth | None | `Sign in to user@example.com`, `Import cookies from cookies.json` |
    33→
    34→**If no URL is given and you're on a feature branch:** Automatically enter **diff-aware mode** (see Modes below). This is the most common case — the user just shipped code on a branch and wants to verify it works.
    35→
    36→**Find the browse binary:**
    37→
    38→{{BROWSE_SETUP}}
    39→
    40→**Create output directories:**
    41→
    42→```bash
    43→REPORT_DIR=".gstack/qa-reports"
    44→mkdir -p "$REPORT_DIR/screenshots"
    45→```
    46→
    47→---
    48→
    49→## Test Plan Context
    50→
    51→Before falling back to git diff heuristics, check for richer test plan sources:
    52→
    53→1. **Project-scoped test plans:** Check `~/.gstack/projects/` for recent `*-test-plan-*.md` files for this repo
    54→   ```bash
    55→   eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)
    56→   ls -t ~/.gstack/projects/$SLUG/*-test-plan-*.md 2>/dev/null | head -1
    57→   ```
    58→2. **Conversation context:** Check if a prior `/plan-eng-review` or `/plan-ceo-review` produced test plan output in this conversation
    59→3. **Use whichever source is richer.** Fall back to git diff analysis only if neither is available.
    60→
    61→---
    62→
    63→{{QA_METHODOLOGY}}
    64→
    65→---
    66→
    67→## Output
    68→
    69→Write the report to both local and project-scoped locations:
    70→
    71→**Local:** `.gstack/qa-reports/qa-report-{domain}-{YYYY-MM-DD}.md`
    72→
    73→**Project-scoped:** Write test outcome artifact for cross-session context:
    74→```bash
    75→eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)
    76→mkdir -p ~/.gstack/projects/$SLUG
    77→```
    78→Write to `~/.gstack/projects/{slug}/{user}-{branch}-test-outcome-{datetime}.md`
    79→
    80→### Output Structure


     1→---
     2→name: gstack-upgrade
     3→version: 1.1.0
     4→description: |
     5→  Upgrade gstack to the latest version. Detects global vs vendored install,
     6→  runs the upgrade, and shows what's new.
     7→allowed-tools:
     8→  - Bash
     9→  - Read
    10→  - Write
    11→  - AskUserQuestion
    12→---
    13→
    14→# /gstack-upgrade
    15→
    16→Upgrade gstack to the latest version and show what's new.
    17→
    18→## Inline upgrade flow
    19→
    20→This section is referenced by all skill preambles when they detect `UPGRADE_AVAILABLE`.
    21→
    22→### Step 1: Ask the user (or auto-upgrade)
    23→
    24→First, check if auto-upgrade is enabled:
    25→```bash
    26→_AUTO=""
    27→[ "${GSTACK_AUTO_UPGRADE:-}" = "1" ] && _AUTO="true"
    28→[ -z "$_AUTO" ] && _AUTO=$(~/.claude/skills/gstack/bin/gstack-config get auto_upgrade 2>/dev/null || true)
    29→echo "AUTO_UPGRADE=$_AUTO"
    30→```
    31→
    32→**If `AUTO_UPGRADE=true` or `AUTO_UPGRADE=1`:** Skip AskUserQuestion. Log "Auto-upgrading gstack v{old} → v{new}..." and proceed directly to Step 2. If `./setup` fails during auto-upgrade, restore from backup (`.bak` directory) and warn the user: "Auto-upgrade failed — restored previous version. Run `/gstack-upgrade` manually to retry."
    33→
    34→**Otherwise**, use AskUserQuestion:
    35→- Question: "gstack **v{new}** is available (you're on v{old}). Upgrade now?"
    36→- Options: ["Yes, upgrade now", "Always keep me up to date", "Not now", "Never ask again"]
    37→
    38→**If "Yes, upgrade now":** Proceed to Step 2.
    39→
    40→**If "Always keep me up to date":**
    41→```bash
    42→~/.claude/skills/gstack/bin/gstack-config set auto_upgrade true
    43→```
    44→Tell user: "Auto-upgrade enabled. Future updates will install automatically." Then proceed to Step 2.
    45→
    46→**If "Not now":** Write snooze state with escalating backoff (first snooze = 24h, second = 48h, third+ = 1 week), then continue with the current skill. Do not mention the upgrade again.
    47→```bash
    48→_SNOOZE_FILE=~/.gstack/update-snoozed
    49→_REMOTE_VER="{new}"
    50→_CUR_LEVEL=0
    51→if [ -f "$_SNOOZE_FILE" ]; then
    52→  _SNOOZED_VER=$(awk '{print $1}' "$_SNOOZE_FILE")
    53→  if [ "$_SNOOZED_VER" = "$_REMOTE_VER" ]; then
    54→    _CUR_LEVEL=$(awk '{print $2}' "$_SNOOZE_FILE")
    55→    case "$_CUR_LEVEL" in *[!0-9]*) _CUR_LEVEL=0 ;; esac
    56→  fi
    57→fi
    58→_NEW_LEVEL=$((_CUR_LEVEL + 1))
    59→[ "$_NEW_LEVEL" -gt 3 ] && _NEW_LEVEL=3
    60→echo "$_REMOTE_VER $_NEW_LEVEL $(date +%s)" > "$_SNOOZE_FILE"
    61→```
    62→Note: `{new}` is the remote version from the `UPGRADE_AVAILABLE` output — substitute it from the update check result.
    63→
    64→Tell user the snooze duration: "Next reminder in 24h" (or 48h or 1 week, depending on level). Tip: "Set `auto_upgrade: true` in `~/.gstack/config.yaml` for automatic upgrades."
    65→
    66→**If "Never ask again":**
    67→```bash
    68→~/.claude/skills/gstack/bin/gstack-config set update_check false
    69→```
    70→Tell user: "Update checks disabled. Run `~/.claude/skills/gstack/bin/gstack-config set update_check true` to re-enable."
    71→Continue with the current skill.
    72→
    73→### Step 2: Detect install type
    74→
    75→```bash
    76→if [ -d "$HOME/.claude/skills/gstack/.git" ]; then
    77→  INSTALL_TYPE="global-git"
    78→  INSTALL_DIR="$HOME/.claude/skills/gstack"
    79→elif [ -d ".claude/skills/gstack/.git" ]; then
    80→  INSTALL_TYPE="local-git"
    81→  INSTALL_DIR=".claude/skills/gstack"
    82→elif [ -d ".claude/skills/gstack" ]; then
    83→  INSTALL_TYPE="vendored"
    84→  INSTALL_DIR=".claude/skills/gstack"
    85→elif [ -d "$HOME/.claude/skills/gstack" ]; then
    86→  INSTALL_TYPE="vendored-global"
    87→  INSTALL_DIR="$HOME/.claude/skills/gstack"
    88→else
    89→  echo "ERROR: gstack not found"
    90→  exit 1
    91→fi
    92→echo "Install type: $INSTALL_TYPE at $INSTALL_DIR"
    93→```
    94→
    95→The install type and directory path printed above will be used in all subsequent steps.
    96→
    97→### Step 3: Save old version
    98→
    99→Use the install directory from Step 2's output below:
   100→


Excellent. I've thoroughly explored the gstack project. Now let me provide a comprehensive summary to the user:

---

# Complete gstack Project Exploration

## What is gstack?

**gstack** is Garry Tan's (YC President & CEO) open-source AI engineering workflow system built on top of Claude Code. It transforms Claude Code into a virtual engineering team with 13 specialized roles and command-driven skills — all free, MIT licensed, and available as slash commands in Markdown.

The core philosophy: **Structured roles instead of generic agent chaos**. Each skill is opinionated, follows a specific methodology, and produces structured outputs. Rather than a blank prompt, users get a CEO, engineer manager, designer, QA lead, and release engineer all as slash commands.

## Key Stats & Vision

- **Author:** Shipping 10,000-20,000 usable lines of code per day as CEO while managing YC
- **600,000+ lines** written in 60 days (35% tests)
- **1,237+ GitHub contributions in 2026** (massive acceleration vs prior years)
- **Compression:** Boilerplate ~100x faster, tests ~50x, features ~30x, bugs ~20x with CC+gstack vs human team
- **Latest version:** 0.6.4 (as of March 17, 2026)

## The Architecture: Persistent Browser Daemon

gstack's secret sauce is the **headless browser daemon**:

```
Claude Code → CLI (binary) → HTTP POST → Server (Bun) → Chromium (persistent)
                                                              ↓
                        ~3s first call, ~100-200ms subsequent calls
```

**Why daemon, not per-command browser?**
- Cookies, login sessions, localStorage persist
- Sub-second latency after startup
- 30-minute idle auto-shutdown
- No state loss between commands

**Technical stack:**
- **Bun runtime** — compiled binary (~58MB), native SQLite, native TypeScript
- **Playwright** for browser control
- **localhost-only HTTP** with bearer token auth
- **Random port selection** (10000-60000) for multi-workspace support
- **Ref system** — `@e1`, `@e2` refs instead of CSS selectors

## The 13 Specialist Skills

| Slash Command | Role | What It Does |
|---|---|---|
| `/plan-ceo-review` | CEO/Founder | Rethink the problem → 10x product vision. 4 modes: EXPANSION, SELECTIVE EXPANSION, HOLD SCOPE, REDUCTION. Saves plans to disk. |
| `/plan-eng-review` | Eng Manager | Lock architecture, data flows, diagrams, tests. Full interactive review with one issue per AskUserQuestion. Writes test plan artifacts. |
| `/plan-design-review` | Senior Designer | Interactive design audit (0-10 rating per dimension). Fixes the plan to get to 10. For live sites, use `/design-review`. |
| `/design-consultation` | Design Partner | Builds complete design system from scratch. Research + proposal + SAFE/RISK breakdown. Creates DESIGN.md. |
| `/review` | Staff Engineer | Pre-landing diff review. SQL safety, race conditions, LLM trust boundaries, enum completeness, design checks. Auto-fixes obvious issues. |
| `/ship` | Release Engineer | Complete workflow: sync main, run tests, coverage audit, bump VERSION, update CHANGELOG, commit, push, create PR. One command. |
| `/browse` | QA Engineer | Fast headless Chromium. ~40+ commands: navigate, interact, assert, screenshot, responsive testing, file upload, dialogs. |
| `/qa` | QA Lead | Systematically tests app and fixes bugs. Find → Fix → Verify loop with atomic commits and before/after screenshots. |
| `/qa-only` | QA Reporter | Same testing methodology as `/qa` but report-only (no fixes). |
| `/design-review` | Designer + Coder | Design audit on live site, then iteratively fixes CSS/HTML with atomic commits and screenshots. |
| `/setup-browser-cookies` | Session Manager | Import cookies from Chrome, Arc, Brave, Edge into headless session. Test authenticated pages. |
| `/retro` | Eng Manager | Weekly retrospective. Per-person stats, commit history, test health, Greptile signal, TODOS backlog health. |
| `/document-release` | Technical Writer | Post-ship doc updates. Reads diff, updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md, polishes CHANGELOG. |

### Bonus Skills
- `/gstack-upgrade` — Update to latest version
- `/design-consultation` — Build design system

## Key Features & Innovations

### 1. **Four CEO Review Modes**
- **EXPANSION:** Dream big, 10x thinking, opt-in ceremony
- **SELECTIVE EXPANSION:** Hold scope, cherry-pick expansions individually
- **HOLD SCOPE:** Maximum rigor, bulletproof the plan
- **SCOPE REDUCTION:** Ruthlessly cut to MVP

Plans saved to `~/.gstack/projects/{slug}/ceo-plans/` with scope decisions table.

### 2. **Interactive, Structured Questions**
Every AskUserQuestion has:
- Clear context (project, branch, what's happening)
- Explicit recommendation ("I recommend X because...")
- Numbered options with outcomes
- No "pick one of 8 things" — typically 2-3 focused choices

### 3. **Smart Review Routing**
- Design review auto-runs on frontend changes via `/review` and `/ship`
- CEO review only recommended (not required) for product changes
- Eng review is the gating review; CEO/Design are informational
- Review readiness dashboard shows which reviews are done

### 4. **Completeness Principle**
> When AI coding compresses implementation time 10-100x, always recommend the complete solution. No shortcuts when the full version costs seconds with CC.

Dual-time estimates throughout (human team time vs CC+gstack time).

### 5. **E2E Test Infrastructure (3-tier)**
- **Tier 1:** Static validation (free, <1s)
- **Tier 2:** E2E via `claude -p` (~$3.85/run)
- **Tier 3:** LLM-as-judge (~$0.15/run)

Diff-based test selection: only run tests affected by changed files. Use `bun run eval:select` to preview.

### 6. **QA with Real Browser**
`/qa` finds bugs and fixes them in source code with:
- Atomic `test(qa): ...` commits
- Before/after screenshots
- Regression test auto-generation
- Health score tracking (before/after)

### 7. **Design System Integration**
- **DESIGN.md** as single source of truth
- `/design-consultation` builds complete systems (aesthetic, typography, color, layout, spacing, motion)
- Design decisions flow through all review stages
- AI slop detection (purple gradients, 3-col grids, generic copy)

### 8. **Ref System (Not Selectors)**
- Accessibility tree → `@e1`, `@e2`, etc.
- Playwright Locators (no DOM mutation, no CSP issues)
- Cursor-interactive refs `@c1`, `@c2` for custom components
- Stale ref detection on SPAs

### 9. **Browser Commands (~40 total)**

**Navigation:** `goto`, `back`, `forward`, `reload`, `url`

**Reading:** `text`, `html`, `links`, `forms`, `accessibility`, `js`, `eval`, `css`, `attrs`, `console`, `network`, `cookies`, `storage`, `perf`

**Inspection:** `is` (visible/hidden/enabled/disabled/checked/editable/focused), `dialog`

**Interaction:** `click`, `fill`, `select`, `hover`, `type`, `press`, `scroll`, `wait`, `viewport`, `cookie`, `cookie-import`, `cookie-import-browser`, `header`, `useragent`, `upload`, `dialog-accept`, `dialog-dismiss`

**Visual:** `screenshot` (element crop, region clip, viewport), `pdf`, `responsive` (mobile/tablet/desktop), `diff`

**Tabs:** `tabs`, `tab`, `newtab`, `closetab`

**Server:** `status`, `stop`, `restart`

**Meta:** `snapshot` (accessibility tree with refs), `chain` (JSON command batch)

### 10. **Snapshot Flags**
```
snapshot -i          # interactive elements only
snapshot -c          # compact (no empty structural nodes)
snapshot -d N        # depth limit
snapshot -s SEL      # scope to selector
snapshot -D          # diff vs previous
snapshot -a          # annotated screenshot with overlay
snapshot -o PATH     # output path
snapshot -C          # cursor-interactive elements
```

## Installation

```bash
# 30 seconds — two-step install
git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack && ./setup

# Optional: add to project for teammates
cp -Rf ~/.claude/skills/gstack .claude/skills/gstack
rm -rf .claude/skills/gstack/.git
cd .claude/skills/gstack && ./setup
```

The `setup` script:
1. Builds browse binary if needed
2. Installs Playwright Chromium
3. Creates `~/.gstack` global state directory
4. Symlinks skills to `.claude/skills/`

## Development & Testing

**Build commands:**
```bash
bun install              # install dependencies
bun run build            # gen docs + compile binaries
bun run gen:skill-docs   # regenerate SKILL.md from templates
bun run dev:skill        # watch mode: auto-regen + validate
bun run skill:check      # health dashboard
```

**Testing (3 tiers):**
```bash
bun test                 # free tests (validate + snapshot)
bun run test:evals       # paid evals: LLM judge + E2E
bun run eval:list        # list past eval runs
bun run eval:compare     # compare two runs
```

**Dev mode:**
```bash
bun run dev <cmd>        # run CLI in dev, e.g. bun run dev goto https://example.com
EVALS_ALL=1 bun run test:evals  # force all evals regardless of diff
```

## Project Structure

```
gstack/
├── browse/                  # Headless browser CLI + server
│   ├── src/
│   │   ├── cli.ts          # Thin CLI wrapper
│   │   ├── server.ts       # Bun HTTP server
│   │   ├── commands.ts     # Command registry (single source of truth)
│   │   ├── snapshot.ts     # Accessibility tree + ref system
│   │   ├── browser-manager.ts  # Chromium lifecycle + state
│   │   ├── read-commands.ts    # Text, html, js, eval, etc.
│   │   ├── write-commands.ts   # Click, fill, navigate, etc.
│   │   ├── meta-commands.ts    # Screenshots, chain, diff
│   │   ├── cookie-import-browser.ts  # Keychain + AES decryption
│   │   └── config.ts       # Path resolution
│   ├── test/               # 166+ integration tests
│   └── dist/browse         # Compiled binary
│
├── skills/
│   ├── plan-ceo-review/        # CEO/founder mode
│   ├── plan-eng-review/        # Eng manager mode
│   ├── plan-design-review/     # Designer mode (plan)
│   ├── design-consultation/    # Design system builder
│   ├── design-review/          # Designer + coder (live)
│   ├── review/                 # Staff engineer (pre-land)
│   ├── ship/                   # Release engineer
│   ├── qa/                     # QA + fixer
│   ├── qa-only/                # QA reporter
│   ├── retro/                  # Weekly retrospective
│   ├── document-release/       # Post-ship doc updates
│   ├── setup-browser-cookies/  # Session mgmt
│   └── gstack-upgrade/         # Update system
│
├── scripts/
│   ├── gen-skill-docs.ts       # SKILL.md.tmpl → SKILL.md
│   ├── skill-check.ts          # Health dashboard
│   ├── dev-skill.ts            # Watch mode
│   ├── eval-*.ts               # Eval tools
│
├── bin/
│   ├── gstack-slug             # Git remote → owner/repo
│   ├── gstack-config           # Config get/set/list
│   ├── gstack-diff-scope       # Categorize changes
│   ├── gstack-update-check     # Version check + snooze
│   ├── dev-setup / dev-teardown # Contributor mode
│
├── test/
│   ├── skill-validation.test.ts  # Static: command/flag validation
│   ├── gen-skill-docs.test.ts    # Generator quality
│   ├── skill-llm-eval.test.ts    # LLM-as-judge evals
│   ├── skill-e2e.test.ts         # E2E via claude -p
│   └── helpers/
│       ├── skill-parser.ts       # Extract $B commands from MD
│       ├── session-runner.ts     # Agent SDK wrapper
│       └── touchfiles.ts         # Diff-aware test selection
│
├── docs/
│   └── skills.md               # Deep dives with examples
│
├── ARCHITECTURE.md             # Design decisions
├── CONTRIBUTING.md             # Dev setup guide
├── CLAUDE.md                   # Development instructions
├── CHANGELOG.md                # Version history
├── README.md                   # Hero + hero shot + demo
└── package.json                # Bun project config
```

## Template System

**The problem:** Hand-maintained SKILL.md docs drift from code.

**The solution:** `.tmpl` files with placeholders, auto-generated at build time.

```
plan-ceo-review/SKILL.md.tmpl
    ↓
gen-skill-docs.ts (reads source metadata)
    ↓
plan-ceo-review/SKILL.md (committed)
```

**Placeholders:**
- `{{PREAMBLE}}` — update check + session tracking
- `{{BASE_BRANCH_DETECT}}` — PR base branch detection
- `{{COMMAND_REFERENCE}}` — Browse command table from `commands.ts`
- `{{SNAPSHOT_FLAGS}}` — Snapshot flag reference from `snapshot.ts`
- `{{BROWSE_SETUP}}` — Binary discovery
- `{{TEST_BOOTSTRAP}}` — Test framework setup
- `{{QA_METHODOLOGY}}` — Shared QA methodology
- `{{DESIGN_METHODOLOGY}}` — Shared design audit
- `{{REVIEW_DASHBOARD}}` — Review readiness display
- `{{DESIGN_REVIEW_LITE}}` — Auto design check on `/review` and `/ship`

## CLAUDE.md - Project Development Instructions

The project includes comprehensive development docs:
- **Commands section** — all bun scripts with descriptions
- **Project structure** — detailed walkthrough
- **SKILL.md workflow** — how to edit templates
- **Browser interaction** — use `/browse`, never MCP tools
- **Commit style** — bisect commits (one logical change each)
- **CHANGELOG style** — user-forward release notes, not impl details
- **AI effort compression** — dual-time estimates throughout
- **E2E eval failure blame protocol** — never claim "unrelated" without proof

## Security

- **Localhost-only HTTP** binding
- **Bearer token auth** on every request
- **Keychain integration** for cookie decryption (requires user click)
- **Read-only cookie DB access** (copies to /tmp)
- **No cookie values in logs** (metadata only)
- **No shell injection** (hardcoded registry, argument arrays)

## Contributing & CI/CD

- **Skill docs auto-generated** — `.github/workflows/skill-docs.yml` fails if generated output differs
- **3-tier testing** — validation (free) → E2E ($) → LLM-judge ($)
- **Planted-bug fixtures** — eval tests with known bugs to verify detection
- **Diff-based test selection** — only run tests affected by changed files
- **Pre-commit hooks** — skill validation, command drift detection
- **Contributor mode** — `gstack-config set gstack_contributor true` for auto-bug reports

## Philosophy & Cognitive Patterns

gstack deeply embeds frameworks from:

**CEO/Founder mode:**
- Bezos (one-way doors, Day 1 proxy skepticism)
- Grove (paranoia)
- Munger (inversion)
- Horowitz (wartime awareness)
- Chesky/Graham (founder mode)
- Altman (leverage obsession)

**Eng Manager mode:**
- Larson (team state diagnosis)
- McKinley (boring by default)
- Brooks (essential vs accidental complexity)
- Beck (make change easy)
- Majors (own code in production)
- Google SRE (error budgets)

**Designer mode:**
- Rams (subtraction default)
- Norman (3 levels of design)
- Zhuo (principled taste)
- Gebbia (design for trust, storyboard journey)
- Ive (care is visible)

These aren't checklists — they're "latent space activation." The LLM internalizes the frameworks, making each review a genuine perspective shift.

## Completeness as Core Feature

The **Completeness Principle** permeates every skill:

> With AI-assisted coding compressing human effort 10-100x, always recommend the complete solution when marginal cost is minimal. The lake is cheap — boil it.

- Plan reviews flag shortcut implementations
- Dual-time estimates show CC time is mostly free
- Test coverage and edge case handling default to complete
- Deferred work is explicitly written to TODOS.md

## Latest Innovations (v0.6.4)

- `/plan-design-review` now interactive (0-10 ratings, fixes plan)
- CEO review auto-activates design section when UI is in scope
- 14/15 skills now have full test coverage (E2E + LLM-judge)
- Bisect commit style enforced (one logical change per commit)
- Smart review routing (CEO recommended, Eng required, Design on frontend)

## Real-World Example (From README)

```
You:    I want to add photo upload for sellers.
You:    /plan-ceo-review
Claude: [8 expansion proposals with effort/impact]

You:    /plan-design-review
Claude: Design Score: B | AI Slop Score: C
        [80-item audit, fixes to bring scores up]

You:    /plan-eng-review
Claude: [Architecture diagrams, test matrix, error paths]

You:    [Approve plan] → Claude writes 2,400 lines in 11 files

You:    /review
Claude: [AUTO-FIXED] 2 issues | [ASK] 1 race condition

You:    /qa https://staging.myapp.com
Claude: [Finds + fixes bug in preview clearing]
        [Auto-generates regression test]

You:    /ship
Claude: Tests: 42 → 51 (+9 new)
        Coverage: 14/14 code paths (100%)
        PR: github.com/you/app/pull/42
```

One feature. Seven commands. Entire virtual team.

---

**This is the most thorough, production-grade AI engineering workflow toolkit available as of March 2026.**