mirror of
https://github.com/garrytan/gstack.git
synced 2026-06-19 00:00:13 +02:00
Garry Tan
4288756aac
Five stale gstack-config references in docs/ pointed to the deprecated gbrain_sync_mode key (renamed to artifacts_sync_mode in v1.27.0.0): - docs/gbrain-sync.md: lines 62, 110, 111, 173 - docs/gbrain-sync-errors.md: lines 26, 203 Users following the docs would set a key that gstack-brain-sync no longer reads, silently breaking artifacts sync. Originated from @realcarsonterry PR #1461 (verbatim). Also register /document-generate in AGENTS.md (Operational + memory table) and docs/skills.md (skill index). The skill shipped in v1.35.0.0 but the doc-inventory cross-check in test/skill-validation.test.ts was failing because neither file mentioned it. Allowlist the new test/docs-config-keys.test.ts file in test/no-stale-gstack-brain-refs.test.ts — it intentionally lists the deprecated keys in its DEPRECATED_KEYS denylist (defending the rename). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
116 lines
6.0 KiB
Markdown
116 lines
6.0 KiB
Markdown
# 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 → eng → DX review. |
|
|
| `/design-consultation` | Build a complete design system from scratch. |
|
|
|
|
### 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. |
|
|
| `/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. First call prototypes; codified call runs in ~200ms. |
|
|
| `/skillify` | Codify the most recent successful `/scrape` flow into a permanent browser-skill. |
|
|
|
|
### 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 using the browse daemon. |
|
|
| `/landing-report` | Read-only dashboard for the workspace-aware ship queue. |
|
|
| `/document-release` | Update all docs to match what you just shipped. |
|
|
| `/document-generate` | Write missing docs from scratch in four Diataxis quadrants. |
|
|
| `/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` | OWASP Top 10 + STRIDE security audit. |
|
|
| `/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
|
|
|
|
| Skill | What it does |
|
|
|-------|-------------|
|
|
| `/browse` | Headless browser — real Chromium, real clicks, ~100ms/command. |
|
|
| `/open-gstack-browser` | Launch the visible GStack Browser with sidebar + stealth. |
|
|
| `/setup-browser-cookies` | Import cookies from your real browser for authenticated testing. |
|
|
| `/pair-agent` | Pair a remote AI agent (OpenClaw, Codex, etc.) with your browser. |
|
|
|
|
### 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. |
|
|
|
|
## Build commands
|
|
|
|
```bash
|
|
bun install # install dependencies
|
|
bun test # run free tests (no API spend)
|
|
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.
|
|
|
|
## 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.
|
|
- The browse binary provides headless browser access. Use `$B <command>` in skills.
|
|
- 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 `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.
|