CalvinBackup/gstack
1
0
Fork 0
mirror of https://github.com/garrytan/gstack.git synced 2026-09-21 04:10:47 +02:00
Code Issues Packages Projects Releases Wiki Activity

document gstack 2 evidence and blocked gates

Browse Source
This commit is contained in:
Sinabina
2026-07-17 11:08:51 -07:00
parent 9919c4cdd3
commit 7d760ff1d1
19 changed files with 10026 additions and 208 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+112 -125
View File
@@ -1,136 +1,123 @@
# gstack — AI Engineering Workflow
# gstack — AI engineering judgment layer
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.
GStack 2 exposes exactly six default public skills. Treat this as a routing
surface over preserved specialist judgment, not permission to simplify that
judgment into generic checklists.
## Available skills
## Public skills
Skills live in `.agents/skills/` (or `~/.claude/skills/gstack/` on Claude Code).
Invoke them by name (e.g., `/office-hours`).
| Skill | Primary responsibility |
|---|---|
| `/plan` | Product framing, CEO scope, engineering architecture, DX, autoplan, executable specs, and planning preferences. |
| `/design` | Design systems, alternatives, HTML/CSS, plan and live-interface review, and physical-iOS HIG review. |
| `/qa` | Report-only or fix-and-verify web QA, physical-iOS QA, DX journeys, performance, and canaries. |
| `/debug` | Root-cause investigation, physical-iOS fixes, and internal safety controls. |
| `/review` | Diff, security, repository-health, and independent outside-voice review. |
| `/ship` | PR preparation, landing/deployment, queue inspection, release docs, upgrade, and internal iOS release operations. |
### Plan-mode reviews
`/plan` has exactly six top-level modes: **Discovery, Product, Engineering,
DX, Specification, and Full chain**. Planning preferences and other old names
are internal routing aliases, not additional top-level modes.
| 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. |
| `/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. |
Each dispatcher must infer from product stage, surface, requested artifact,
mutation authority, evidence needs, and deployment state—not prompt keywords.
Before executing, state:
### 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` | 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` | 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. |
### 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`). |
End-to-end walkthrough: [docs/howto-ios-testing-with-gstack.md](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. |
| `/diagram` | English in, diagram out: mermaid source + editable .excalidraw + SVG/PNG, offline. |
## 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
```text
Target:
Mode:
Depth:
Mutation:
Active modules:
Skipped modules:
Web context:
```
## Platform support
Then read every active file under `skills/<skill>/references/legacy/` in full.
Its question order, pressure, smart skips, STOP/approval gates, evidence,
artifacts, mutation boundary, exit behavior, and voice are binding. Preserve
report-only versus fix behavior. List skipped primary modules and why.
- **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.
The exhaustive 55-command compatibility map is in
[`docs/gstack-2/SKILL-MIGRATION.md`](docs/gstack-2/SKILL-MIGRATION.md). Old
names are opt-in routing aliases and must print their replacement invocation;
they contain no copied judgment. Representative mappings:
## Key conventions
| Old invocation | GStack 2 replacement |
|---|---|
| `/office-hours` | `/plan --mode product` |
| `/plan-ceo-review` | `/plan --mode ceo` |
| `/plan-eng-review` | `/plan --mode eng` |
| `/design-consultation` | `/design --mode consult` |
| `/design-review` | `/design --mode live-review` |
| `/qa-only` | `/qa --mode report` |
| `/investigate` | `/debug --mode investigate` |
| `/cso` | `/review --mode security` |
| `/land-and-deploy` | `/ship --mode land` |
- 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.
## Installation and capabilities
Canonical installation is standards-based:
```bash
npx skills add time-attack/gstack
```
Delegate host detection, placement, project/global scope, selected-skill
installation, updates, and removal to the Agent Skills installer. Never
silently enroll a host. Pure judgment works without the optional runtime.
The browser is the existing local Chromium/Playwright implementation. Do not
add a cloud browser or remote browser provider. Physical iOS uses only the
existing DebugBridge/CoreDevice harness; do not add an alternate device
backend. PDF and Mermaid/Excalidraw remain internal. Do not install ComfyUI,
local model weights, checkpoints, or GPU runtimes.
Context.dev is the only new external service and only for public web context.
It is off until explicit consent. Never send authenticated/private pages,
localhost, intranet/private URLs, cookies, tokens, repository content, or user
files. When unavailable, use an explicitly selected host-native public search,
the local browser, or continue without research and label the result unverified.
Persist that choice with `gstack context select host|local-browser|none`;
`gstack context options` prints the four-choice UX without granting consent.
## Build and verification
```bash
bun install
bun run gen:gstack2 # regenerate six dispatchers, preserved modules, parity fixtures
bun run test:gstack2 # GStack 2 routing, provenance, parity, runtime, privacy, upgrade
bun test # full free suite, including design + iOS daemon tests
bun run test:windows # curated Windows-safe subset
bun run build
bun run skill:check
```
Legacy `SKILL.md` files outside `skills/` are generated from `.tmpl` templates;
edit the template, not its output. GStack 2 generated sources are identified by
their header; edit `scripts/gstack2/` inputs and regenerate instead.
## Contribution boundaries
- A new public command, external service, or first-party host adapter requires
an accepted issue; an external service also requires maintainer approval.
- Contributions must improve judgment/evidence, remove surface, fix a linked
reproduction, or repair infrastructure.
- New public nouns are a last resort. Prefer a mode, internal utility, or
community extension.
- Do not mutate GitHub labels/templates merely because their design is present
in this repository.
- State resolves through the host-neutral runtime under `$GSTACK_HOME` or
`~/.gstack`; do not invent host-specific state roots or shell-evaluated path
assignments.
- Never claim GStack 2 is done without the evidence in
[`docs/gstack-2/STATUS.md`](docs/gstack-2/STATUS.md).
## Platform contract
Portable means the canonical skill tree follows the Agent Skills specification.
Verified must name its layer. The six-host project/global/selection/removal
matrix is **Verified — installer**; host UI/process execution is still pending.
Native means a necessary host API is covered while consuming the same canonical
judgment. These labels require evidence; see
[`docs/gstack-2/HOST-COMPATIBILITY.md`](docs/gstack-2/HOST-COMPATIBILITY.md).