Imported from nota-america/forgecat-agent-profiles (profiles/garrytan/gstack/for-forgecat/refs/gstack-runtime/AGENTS.md). Install upstream with npx skills add nota-america/forgecat-agent-profiles --skill gstack-runtime. Copyright stays with the author.

gstack — AI Engineering Workflow

gstack is a collection of SKILL.md files that give AI agents structured roles for software development. Each skill is a specialist: CEO reviewer, eng manager, designer, QA lead, release engineer, debugger, and more.

Available skills

Skills live in .agents/skills/ (or ~/.claude/skills/gstack/ on Claude Code). Invoke them by name (e.g., /office-hours).

Plan-mode reviews

Skill	What it does
`/office-hours`	Start here. Reframes your product idea before you write code.
`/plan-ceo-review`	CEO-level review: find the 10-star product in the request.
`/plan-eng-review`	Lock architecture, data flow, edge cases, and tests.
`/plan-design-review`	Rate each design dimension 0-10, explain what a 10 looks like.
`/plan-devex-review`	DX-mode review: TTHW, magical moments, friction points, persona traces.
`/plan-tune`	Self-tune AskUserQuestion sensitivity per question.
`/autoplan`	One command runs CEO → design → DX → eng review (eng always last).
`/design-consultation`	Build a complete design system from scratch.
`/spec`	Turn vague intent into a precise, executable spec in five phases. Files a GitHub issue, optionally spawns a Claude Code agent in a fresh worktree, and lets `/ship` close the source issue on merge.

Implementation + review

Skill	What it does
`/review`	Pre-landing PR review. Finds bugs that pass CI but break in prod.
`/codex`	Second opinion via OpenAI Codex. Review, challenge, or consult modes. Available outside the Codex harness.
`/claude-code`	Second opinion via Claude Code. Review, challenge, or consult modes. Available outside the Claude Code harness.
`/investigate`	Systematic root-cause debugging. No fixes without investigation.
`/design-review`	Live-site visual audit + fix loop with atomic commits.
`/design-shotgun`	Generate multiple AI design variants, comparison board, iterate.
`/design-html`	Generate production-quality Pretext-native HTML/CSS.
`/devex-review`	Live developer experience audit (TTHW measured against the real flow).
`/qa`	Open a real browser, find bugs, fix them, re-verify.
`/qa-only`	Same methodology as /qa but report only — no code changes.
`/scrape`	Pull data from a web page in your Aside browser, with your real logged-in state. Read-only. On the fallback browser a codified browser-skill answers a repeat intent in ~200ms.
`/skillify`	Codify the most recent successful `/scrape` flow into a permanent browser-skill (fallback browser only).

Release + deploy

Skill	What it does
`/ship`	Run tests, review, push, open PR. Workspace-aware version queue.
`/land-and-deploy`	Merge the PR, wait for CI and deploy, verify production health.
`/canary`	Post-deploy monitoring loop in your Aside browser (or gstack's own when Aside is absent).
`/landing-report`	Read-only dashboard for the workspace-aware ship queue.
`/document-release`	Update all docs to match what you just shipped.
`/document-generate`	Generate Diataxis docs (tutorial / how-to / reference / explanation) from code.
`/setup-deploy`	One-time deploy config detection (Fly.io, Render, Vercel, etc.).
`/gstack-upgrade`	Update gstack to the latest version.

Operational + memory

Skill	What it does
`/context-save`	Save working context (git state, decisions, remaining work).
`/context-restore`	Resume from a saved context, even across Conductor workspaces.
`/learn`	Manage what gstack learned across sessions.
`/retro`	Weekly retro with per-person breakdowns and shipping streaks.
`/health`	Code quality dashboard (type checker, linter, tests, dead code).
`/benchmark`	Performance regression detection (page load, Core Web Vitals).
`/benchmark-models`	Cross-model benchmark for skills (Claude, GPT, Gemini side-by-side).
`/cso`	Supported security findings with explicit coverage. Static assessment remains available without catalog profiles; contained runtime/scanner execution requires matching qualified profiles. Runtime-tested bundles authenticate separate external assertions. Project-test completion remains `self_reported` because target code controls the test process; `tested` is reserved for a future target-independent completion witness.
`/setup-gbrain`	Set up gbrain for cross-machine session memory sync.
`/sync-gbrain`	Keep gbrain current with this repo's code; refresh agent search guidance in CLAUDE.md.

Browser + agent integration

Every browser skill drives the Aside AI browser first (macOS 15+, aside.com) — the user's real browser with their real sessions, through aside repl scripts; gstack never installs it. When Aside is not installed or not running (Linux, Windows, a closed Aside app) the same skills fall back automatically to gstack's own headless Chromium ($B), which is where the three skills under /browse apply.

Skill	What it does
`/browse`	Drive a browser: open a page, read it, click through a flow, screenshots, console errors. Aside first; gstack's own Chromium (~100ms/command) as the fallback. Every other browser skill stands on it.
`/open-gstack-browser`	Launch the visible GStack Browser with sidebar + stealth — the headed face of the fallback engine.
`/setup-browser-cookies`	Import cookies from your real browser into the fallback engine for authenticated testing. Unnecessary on Aside.
`/pair-agent`	Pair a remote AI agent (OpenClaw, Codex, etc.) with gstack's own browser over a scoped tunnel.

iOS QA — drive real iPhones over USB or Tailscale (v1.43.0.0+)

Skill	What it does
`/ios-qa`	Live-device iOS QA via USB CoreDevice tunnel + embedded StateServer. Optionally exposes the device over Tailscale so remote agents can drive it.
`/ios-fix`	Autonomous iOS bug fixer with regression snapshot capture.
`/ios-design-review`	Designer's-eye QA on a real iPhone — 10-dimension Apple HIG rubric.
`/ios-clean`	Convenience: strip DebugBridge + #if DEBUG wiring before a Release build.
`/ios-sync`	Regenerate the iOS debug bridge against the latest upstream templates.

Companion CLIs (run on the Mac that's plugged into the device):

Command	What it does
`gstack-ios-qa-daemon`	Mac-side broker. Loopback by default; `--tailnet` adds a Tailscale-facing listener with capability tiers and audit logging.
`gstack-ios-qa-mint`	Owner-grant CLI for the tailnet allowlist (`grant`/`revoke`/`list`).
`gstack-ios-qa-regen`	Regenerate the canonical local DebugBridge package and typed accessors (`--app-source` / `--bridge-dir`).

End-to-end walkthrough: docs/howto-ios-testing-with-gstack.md.

Safety + scoping

Skill	What it does
`/careful`	Warn before destructive commands (rm -rf, DROP TABLE, force-push).
`/freeze`	Lock edits to one directory. Hard block, not just a warning.
`/guard`	Activate both careful + freeze at once.
`/unfreeze`	Remove directory edit restrictions.
`/make-pdf`	Turn any markdown file into a publication-quality PDF. Renders through Aside, or gstack's own browser when Aside is absent.
`/diagram`	English in, diagram out: mermaid source + editable .excalidraw + SVG/PNG, offline. Renders through Aside, or gstack's own browser when Aside is absent.

Build commands

bun install              # install dependencies
bun run test             # run free tests via the strict shard runner (no API spend, ~90-100s)
bun run test:windows     # curated Windows-safe subset (runs on windows-latest)
bun run build            # generate docs + compile binaries
bun run gen:skill-docs   # regenerate SKILL.md files from templates
bun run skill:check      # health dashboard for all skills

Platform support

macOS + Linux: full test suite supported.
Windows: curated Windows-safe subset runs on windows-latest via the windows-free-tests CI job. Setup script (./setup) requires Git Bash or MSYS today; native PowerShell support is a future expansion. The bin/gstack-paths helper resolves state roots through CLAUDE_PLUGIN_DATA / GSTACK_HOME so plugin installs work on every platform.
CSO native helper: /cso additionally needs Bun's four --no-compile-autoload-* flags and a native toolchain (static-capable C on Linux, Xcode command-line tools on macOS, or VS 2022 C++ Build Tools on Windows). Setup installs everything else and leaves /cso explicitly unavailable when that optional toolchain is absent.
Browser and renderer: the browser skills, /make-pdf, and /diagram drive the Aside browser first, which is macOS 15+ only. On Linux and Windows (or a Mac with Aside closed) the readiness check says so once and the same skills use gstack's own bundled browser, built by ./setup.

Key conventions

SKILL.md files are generated from .tmpl templates. Edit the template, not the output.
Run bun run gen:skill-docs --host codex to regenerate Codex-specific output.
Browser steps in skills are aside repl scripts per scripts/resolvers/aside.ts (Aside first), each with a $B equivalent for the fallback engine — $B <command> is the browse binary and is a legitimate tool when the Aside probe does not print READY. Local HTML renders through bin/gstack-render.ts, which picks the same way.
Safety skills (careful, freeze, guard) use inline advisory prose — always confirm before destructive operations.
State paths resolve via bin/gstack-paths (sourced via eval "$(...)"). Honors GSTACK_HOME, CLAUDE_PLUGIN_DATA, CLAUDE_PLANS_DIR.
The claude CLI binary resolves via lib/claude-bin.ts (re-exported from browse/src/claude-bin.ts for browse internals; Bun.which() + GSTACK_CLAUDE_BIN override). Set GSTACK_CLAUDE_BIN=wsl plus GSTACK_CLAUDE_BIN_ARGS='["claude"]' to run Claude through WSL on Windows.

gstack-runtime

About