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