| 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.
