gstack

name	gstack
description	gstack v1.12.2.0 integration sub-skill. Full routing table for web browsing, QA, shipping, planning reviews, design, DX audits, retros, and GBrain. Activates for: /browse, /qa, /ship, /review, /investigate, /design-review, /canary, /benchmark, /retro, gbrain, gstack skills, web browsing, QA testing, deploy, design review, canary monitoring, performance benchmarks.
version	1.0.0
license	Apache 2.0
compatibility	claude-code
parent_skill	orama-system
gstack_version	1.12.2.0
gstack_install	~/.claude/skills/gstack (global-git)

gstack Integration

gstack v1.12.2.0 is the agent skill framework for web browsing, planning, review, QA, and deployment workflows. Installed globally at ~/.claude/skills/gstack (global-git).

Rules

• ALWAYS use /browse for all web browsing — NEVER use mcp__claude-in-chrome__* tools directly
• Use /investigate for root-cause analysis of adapter or orchestration failures
• Use /ship before any npm publish

Install / Update

Fresh install:

git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup

Upgrade to latest:

/skill ~/.claude/skills/gstack/gstack-upgrade/SKILL.md

Or: /gstack-upgrade

Available Skills

Skill	Purpose
/browse	Headless browser for web browsing and site docs
/qa	Systematically QA test a web application and fix issues
/qa-only	Report-only QA testing
/design-review	Designer's eye QA: visual inconsistency, spacing, contrast
/design-html	Generate production-quality HTML designs
/design-shotgun	Generate multiple AI design variants
/design-consultation	Understand your product and provide design guidance
/review	Pre-landing PR review
/ship	Ship workflow: detect + merge base branch, run tests, deploy
/land-and-deploy	Land and deploy workflow
/canary	Post-deploy canary monitoring
/benchmark	Performance regression detection
/office-hours	YC Office Hours — startup or project mode
/plan-ceo-review	CEO/founder-mode plan review
/plan-eng-review	Eng manager-mode plan review
/plan-design-review	Designer's eye plan review
/plan-devex-review	Interactive developer experience plan review
/autoplan	Auto-review pipeline
/devex-review	Live developer experience audit
/retro	Weekly engineering retrospective
/investigate	Systematic debugging with root cause investigation
/document-release	Post-ship documentation update
/codex	OpenAI Codex CLI wrapper
/cso	Chief Security Officer mode
/learn	Manage project learnings
/careful	Safety guardrails for destructive commands
/freeze	Restrict file edits to a specific directory
/unfreeze	Clear the freeze boundary set by /freeze
/guard	Full safety mode: destructive command warnings
/setup-browser-cookies	Import cookies from real Chromium browser
/setup-deploy	Configure deployment settings
/setup-gbrain	Set up gbrain for this coding agent
/connect-chrome	Pair a remote AI agent with your browser
/gstack-upgrade	Upgrade gstack to the latest version
/skillify	Create a new orama-system or gstack skill interactively

Skill Routing

When the user's request matches a skill below, invoke it via the Skill tool. Multi-step workflows and quality gates produce better results than ad-hoc answers. A false positive is cheaper than a false negative.

Signal	Invoke
Product ideas, "is this worth building", brainstorming	/office-hours
Strategy, scope, "think bigger", "what should we build"	/plan-ceo-review
Architecture, "does this design make sense"	/plan-eng-review
Design system, brand, "how should this look"	/design-consultation
Design review of a plan	/plan-design-review
Developer experience of a plan	/plan-devex-review
"Review everything", full review pipeline	/autoplan
Bugs, errors, "why is this broken", "this doesn't work"	/investigate
Test the site, find bugs, "does this work"	/qa or /qa-only
Code review, check the diff, "look at my changes"	/review
Visual polish, design audit, "this looks off"	/design-review
Developer experience audit, try onboarding	/devex-review
Ship, deploy, create a PR, "send it"	/ship
Merge + deploy + verify	/land-and-deploy
Configure deployment	/setup-deploy
Post-deploy monitoring	/canary
Update docs after shipping	/document-release
Weekly retro, "how'd we do"	/retro
Second opinion, codex review	/codex
Safety mode, careful mode, lock it down	/careful or /guard
Restrict edits to a directory	/freeze or /unfreeze
Upgrade gstack	/gstack-upgrade
Save progress, "save my work"	/context-save
Resume, restore, "where was I"	/context-restore
Security audit, OWASP, "is this secure"	/cso
Make a PDF, document, publication	/make-pdf
Launch real browser for QA	/open-gstack-browser
Import cookies for authenticated testing	/setup-browser-cookies
Performance regression, page speed, benchmarks	/benchmark
Review what gstack has learned	/learn
Tune question sensitivity	/plan-tune
Code quality dashboard	/health
Create a new skill	/skillify

GBrain Configuration

Engine: postgres (Supabase pooler). Config: ~/.gbrain/config.json. DB URL lives in ~/.gbrain/.env as GBRAIN_DATABASE_URL — sourced by ~/.zshrc and the MCP wrapper, NOT by non-interactive Bash shells.

Source	ID	Pages	Federated?
AlphaClaw	gstack-code-claw-4dc4a8f3-aa4479	~478	yes
Perpetua-Tools	gstack-code-ools-27e2b79c-df8a28	~725	yes
orama-system	orama-src	~191	no (isolated)
periscope	periscope-src	~14	yes

Re-run setup: /setup-gbrain

GBrain Ops — Failure Modes and Fixes

Hard-won 2026-05-30 after an agent rewrote git history across all three repos.

0. Non-interactive shell missing DB URL

GBRAIN_DATABASE_URL is in ~/.gbrain/.env, not in the environment of a Bash tool shell. Always prefix:

set -a; source "$HOME/.gbrain/.env" 2>/dev/null; set +a

The "No database URL" message is diagnostic only — config.json intentionally omits the URL; env wins over config.

1. Write failures: prepared statement "x" does not exist / CONNECTION_CLOSED

Cause: config.json "prepare": true against a Supabase pooler. Pooled reconnects drop server-side prepared statements.

Fix:

cp ~/.gbrain/config.json "~/.gbrain/config.json.bak.$(date +%Y%m%d-%H%M%S)"
python3 -c "import json; p='$HOME/.gbrain/config.json'; d=json.load(open(p)); d['prepare']=False; json.dump(d,open(p,'w'),indent=2)"

Then restart any running gbrain process (autopilot, MCP server).

2. Correct resync after a git history rewrite

Two traps to avoid:

• gbrain sync (pin-aware, from inside a repo with a space in the path) calls git pull first and fails silently on Terminal xCode-style paths. Non-fatal but pulls nothing.
• gbrain sync --repo "<path>" without --source dumps into default, not the repo's pinned source.

Always pass both --repo (quoted) and --source:

set -a; source "$HOME/.gbrain/.env" 2>/dev/null; set +a
OPENCLAW_HOME="${OPENCLAW_HOME:-$HOME/openclaw-v1}"
PT_ROOT="${PERPETUA_TOOLS_PATH:-${PERPETUA_TOOLS_ROOT:-$OPENCLAW_HOME/Perpetua-Tools}}"
ORAMA_ROOT="${ORAMA_INSTALL_DIR:-$REPO_ROOT}"
gbrain sync --repo "$OPENCLAW_HOME/AlphaClaw" \
            --source gstack-code-claw-4dc4a8f3-aa4479 --skip-failed
gbrain sync --repo "$PT_ROOT" \
            --source gstack-code-ools-27e2b79c-df8a28 --skip-failed
gbrain sync --repo "$ORAMA_ROOT" \
            --source orama-src --skip-failed
gbrain sources list

--skip-failed also acknowledges stale createVersion failed history-rewrite failures. Verify with gbrain doctor --fast → health should reach ~95.

3. Stale createVersion failed failures

Acknowledged by --skip-failed (above). gbrain doctor then shows all acknowledged.

4. gbrain list / gbrain get return wrong or empty results

• Without --source, list/get target default, not the pinned source.
• Slugs are lowercased, .md stripped: docs/MIGRATION.md → docs/migration.
• Verify indexing via content search: gbrain search "<distinctive first line>".

5. Restarting a wedged autopilot daemon

PID=$(cat ~/.gbrain/autopilot.lock 2>/dev/null)
kill "$PID" 2>/dev/null
n=0; until ! kill -0 "$PID" 2>/dev/null; do n=$((n+1)); [ "$n" -ge 15 ] && kill -9 "$PID"; sleep 1; done
rm -f ~/.gbrain/autopilot.lock
pgrep -fl "gbrain autopilot" || echo "(stopped)"

Restart only after applying the prepare:false fix — otherwise it re-wedges on the same pooler write failures.

Quick Reference

Symptom	Fix
No database URL in a script	set -a; source ~/.gbrain/.env; set +a first
prepared statement does not exist	set "prepare": false in config.json, restart procs
Resync left per-repo source stale	sync --repo "<quoted>" --source <id> — never bare --repo
git pull failed in /Users/.../claude/	non-fatal space-in-path; fs import still proceeds
N unacknowledged createVersion failures	add --skip-failed to sync
gbrain get docs/MIGRATION → not found	slug is lowercased: docs/migration
autopilot wedged 12h+	kill via lock pid, clear lock, apply prepare:false, restart

Symbol vs Text Search

For SYMBOL questions (def, refs, callers, callees), use gbrain code-def / code-refs / code-callers / code-callees — graph data. For TEXT with exact strings, regex, or file globs, use Grep. Never default to Grep first for code questions.