AGENTS.md

1# gstack — AI Engineering Workflow
2 
3gstack is a collection of SKILL.md files that give AI agents structured roles for
4software development. Each skill is a specialist: CEO reviewer, eng manager,
5designer, QA lead, release engineer, debugger, and more.
6 
7## Available skills
8 
9Skills live in `.agents/skills/` (or `$GSTACK_ROOT/` on Claude Code).
10Invoke them by name (e.g., `/office-hours`).
11 
12### Plan-mode reviews
13 
14| Skill | What it does |
15|-------|-------------|
16| `/office-hours` | Start here. Reframes your product idea before you write code. |
17| `/plan-ceo-review` | CEO-level review: find the 10-star product in the request. |
18| `/plan-eng-review` | Lock architecture, data flow, edge cases, and tests. |
19| `/plan-design-review` | Rate each design dimension 0-10, explain what a 10 looks like. |
20| `/plan-devex-review` | DX-mode review: TTHW, magical moments, friction points, persona traces. |
21| `/plan-tune` | Self-tune AskUserQuestion sensitivity per question. |
22| `/autoplan` | One command runs CEO → design → eng → DX review. |
23| `/design-consultation` | Build a complete design system from scratch. |
24 
25### Implementation + review
26 
27| Skill | What it does |
28|-------|-------------|
29| `/review` | Pre-landing PR review. Finds bugs that pass CI but break in prod. |
30| `/codex` | Second opinion via OpenAI Codex. Review, challenge, or consult modes. |
31| `/investigate` | Systematic root-cause debugging. No fixes without investigation. |
32| `/design-review` | Live-site visual audit + fix loop with atomic commits. |
33| `/design-shotgun` | Generate multiple AI design variants, comparison board, iterate. |
34| `/design-html` | Generate production-quality Pretext-native HTML/CSS. |
35| `/devex-review` | Live developer experience audit (TTHW measured against the real flow). |
36| `/qa` | Open a real browser, find bugs, fix them, re-verify. |
37| `/qa-only` | Same methodology as /qa but report only — no code changes. |
38| `/scrape` | Pull data from a web page. First call prototypes; codified call runs in ~200ms. |
39| `/skillify` | Codify the most recent successful `/scrape` flow into a permanent browser-skill. |
40 
41### Release + deploy
42 
43| Skill | What it does |
44|-------|-------------|
45| `/ship` | Run tests, review, push, open PR. Workspace-aware version queue. |
46| `/land-and-deploy` | Merge the PR, wait for CI and deploy, verify production health. |
47| `/canary` | Post-deploy monitoring loop using the browse daemon. |
48| `/landing-report` | Read-only dashboard for the workspace-aware ship queue. |
49| `/document-release` | Update all docs to match what you just shipped. |
50| `/document-generate` | Generate Diataxis docs (tutorial / how-to / reference / explanation) from code. |
51| `/setup-deploy` | One-time deploy config detection (Fly.io, Render, Vercel, etc.). |
52| `/gstack-upgrade` | Update gstack to the latest version. |
53 
54### Operational + memory
55 
56| Skill | What it does |
57|-------|-------------|
58| `/context-save` | Save working context (git state, decisions, remaining work). |
59| `/context-restore` | Resume from a saved context, even across Conductor workspaces. |
60| `/learn` | Manage what gstack learned across sessions. |
61| `/retro` | Weekly retro with per-person breakdowns and shipping streaks. |
62| `/health` | Code quality dashboard (type checker, linter, tests, dead code). |
63| `/benchmark` | Performance regression detection (page load, Core Web Vitals). |
64| `/benchmark-models` | Cross-model benchmark for skills (Claude, GPT, Gemini side-by-side). |
65| `/cso` | OWASP Top 10 + STRIDE security audit. |
66| `/setup-gbrain` | Set up gbrain for cross-machine session memory sync. |
67| `/sync-gbrain` | Keep gbrain current with this repo's code; refresh agent search guidance in CLAUDE.md. |
68 
69### Browser + agent integration
70 
71| Skill | What it does |
72|-------|-------------|
73| `/browse` | Headless browser — real Chromium, real clicks, ~100ms/command. |
74| `/open-gstack-browser` | Launch the visible GStack Browser with sidebar + stealth. |
75| `/setup-browser-cookies` | Import cookies from your real browser for authenticated testing. |
76| `/pair-agent` | Pair a remote AI agent (OpenClaw, Codex, etc.) with your browser. |
77 
78### iOS QA — drive real iPhones over USB or Tailscale (v1.43.0.0+)
79 
80| Skill | What it does |
81|-------|-------------|
82| `/ios-qa` | Live-device iOS QA via USB CoreDevice tunnel + embedded StateServer. Optionally exposes the device over Tailscale so remote agents can drive it. |
83| `/ios-fix` | Autonomous iOS bug fixer with regression snapshot capture. |
84| `/ios-design-review` | Designer's-eye QA on a real iPhone — 10-dimension Apple HIG rubric. |
85| `/ios-clean` | Convenience: strip DebugBridge + #if DEBUG wiring before a Release build. |
86| `/ios-sync` | Regenerate the iOS debug bridge against the latest upstream templates. |
87 
88Companion CLIs (run on the Mac that's plugged into the device):
89 
90| Command | What it does |
91|---------|-------------|
92| `gstack-ios-qa-daemon` | Mac-side broker. Loopback by default; `--tailnet` adds a Tailscale-facing listener with capability tiers and audit logging. |
93| `gstack-ios-qa-mint` | Owner-grant CLI for the tailnet allowlist (`grant`/`revoke`/`list`). |
94 
95End-to-end walkthrough: [docs/howto-ios-testing-with-gstack.md](docs/howto-ios-testing-with-gstack.md).
96 
97### Safety + scoping
98 
99| Skill | What it does |
100|-------|-------------|
101| `/careful` | Warn before destructive commands (rm -rf, DROP TABLE, force-push). |
102| `/freeze` | Lock edits to one directory. Hard block, not just a warning. |
103| `/guard` | Activate both careful + freeze at once. |
104| `/unfreeze` | Remove directory edit restrictions. |
105| `/make-pdf` | Turn any markdown file into a publication-quality PDF. |
106 
107## Build commands
108 
109```bash
110bun install              # install dependencies
111bun test                 # run free tests (no API spend)
112bun run test:windows     # curated Windows-safe subset (runs on windows-latest)
113bun run build            # generate docs + compile binaries
114bun run gen:skill-docs   # regenerate SKILL.md files from templates
115bun run skill:check      # health dashboard for all skills
116```
117 
118## Platform support
119 
120- **macOS** + **Linux**: full test suite supported.
121- **Windows**: curated Windows-safe subset runs on `windows-latest` via the
122  `windows-free-tests` CI job. Setup script (`./setup`) requires Git Bash or
123  MSYS today; native PowerShell support is a future expansion. The `bin/gstack-paths`
124  helper resolves state roots through `CLAUDE_PLUGIN_DATA` / `GSTACK_HOME` so plugin
125  installs work on every platform.
126 
127## Key conventions
128 
129- SKILL.md files are **generated** from `.tmpl` templates. Edit the template, not the output.
130- Run `bun run gen:skill-docs --host codex` to regenerate Codex-specific output.
131- The browse binary provides headless browser access. Use `$B <command>` in skills.
132- Safety skills (careful, freeze, guard) use inline advisory prose — always confirm before destructive operations.
133- State paths resolve via `bin/gstack-paths` (sourced via `eval "$(...)"`). Honors `GSTACK_HOME`, `CLAUDE_PLUGIN_DATA`, `CLAUDE_PLANS_DIR`.
134- The `claude` CLI binary resolves via `browse/src/claude-bin.ts` (`Bun.which()` + `GSTACK_CLAUDE_BIN` override). Set `GSTACK_CLAUDE_BIN=wsl` plus `GSTACK_CLAUDE_BIN_ARGS='["claude"]'` to run Claude through WSL on Windows.
135