Architecture

What sits inside the gstack repository. The four moving parts that make 47 skills work as one team.

The repository on disk has four distinct layers. Understanding them separately is the prerequisite for understanding how a single contributor can claim 810x the throughput of a 2013 baseline.

The four layers

47 SKILL.md files

Markdown prompts with YAML frontmatter that Claude Code loads as native slash-commands. The substantive intelligence of the system. See the runtime.

A compiled browser daemon

browse/dist/browse is a 58 MB Bun-compiled Playwright Chromium server that persists between calls. First invocation costs roughly 3 seconds. Every call after that runs in about 100 milliseconds.

A GPT-Image designer

design/dist/design is a CLI that drives the GPT Image API for mockup generation. Used by /design-shotgun, /design-consultation, /design-html, and the design review skills.

Per-AI-agent host configs

hosts/*.ts defines installation paths and tool-name aliases for Claude Code, Codex, Cursor, OpenCode, Factory, Slate, Kiro, Hermes, GBrain, and OpenClaw.

Repository tree

gstack/ (top level)

gstack/
├── SKILL.md                  # Top-level meta-skill. gstack itself plus /browse primitives
├── SKILL.md.tmpl             # Template source for the above
├── README.md                 # 42 KB marketing and install guide
├── CLAUDE.md                 # 48 KB internal contributor rules
├── ARCHITECTURE.md           # 32 KB internal architecture notes
├── ETHOS.md                  # 7 KB "Boil the Lake" philosophy
├── CHANGELOG.md              # 647 KB release history
├── VERSION                   # Current four-digit version
├── setup                     # 44 KB Bash installer that wires skills into each host
├── package.json              # Bun-based build tooling
│
├── <46 skill directories>/   # Each contains SKILL.md, SKILL.md.tmpl, and assets
│   ├── office-hours/
│   ├── plan-ceo-review/
│   ├── plan-eng-review/
│   ├── review/
│   ├── qa/
│   ├── ship/
│   └── ...                   # See the full catalog
│
├── browse/                   # Headless Chromium daemon (Bun-compiled binary)
│   ├── src/                  # CLI plus server plus commands
│   ├── dist/browse           # 58 MB Mach-O arm64 binary
│   └── test/
├── design/                   # GPT Image API CLI for mockups
├── bin/                      # Roughly 60 Bash and TypeScript helpers
├── scripts/                  # Build pipeline and template generator
│   ├── gen-skill-docs.ts     # Template to SKILL.md generator (Bun)
│   └── resolvers/            # Over 20 template-variable resolvers
├── hosts/                    # Per-AI-agent host configs
├── docs/                     # Tutorials and how-tos
├── test/                     # 149 test files
└── openclaw/                 # Native OpenClaw skill variants

Why every skill ships both SKILL.md and SKILL.md.tmpl. The template is the source of truth. The rendered .md is generated by bun run gen:skill-docs and committed alongside so that hosts without the build toolchain still get a working file. CI checks freshness on every PR.

The browser daemon

The browse/ binary is the largest single component by line count and the most clever piece of engineering in the repo. It is a Playwright Chromium server compiled to a standalone executable through bun build --compile. Skills invoke it through a shell alias $B that the preamble resolves to the binary path.

Persistence

The browser stays alive across calls. Cookies, localStorage, and tabs carry over. Auto-shuts down after 30 minutes idle.

Roughly 70 commands

goto, snapshot, click, fill, screenshot, console, network, js, responsive, cookie-import-browser, handoff, cdp, and dozens more.

Headed escape hatch

$B handoff transfers to a visible Chrome at the same URL, preserving session, for CAPTCHA or MFA. $B resume returns to headless.

Prompt-injection defense

A 22 MB ONNX classifier scans every page output. A Haiku classifier votes on the full transcript. A canary token catches session exfiltration attempts. BLOCK requires 2-of-N agreement.

Multi-host support

The same SKILL.md files are installed into different paths depending on which AI coding agent the user runs. The setup script reads hosts/*.ts to know where each agent expects skills.

AI agent	Install path	Detection flag
Claude Code	~/.claude/skills/gstack-*/	default
Codex CLI	~/.codex/skills/gstack-*/	--host codex
OpenCode	~/.config/opencode/skills/gstack-*/	--host opencode
Cursor	~/.cursor/skills/gstack-*/	--host cursor
Factory Droid	~/.factory/skills/gstack-*/	--host factory
Slate	~/.slate/skills/gstack-*/	--host slate
Kiro	~/.kiro/skills/gstack-*/	--host kiro
Hermes	~/.hermes/skills/gstack-*/	--host hermes
GBrain (mod)	~/.gbrain/skills/gstack-*/	--host gbrain
OpenClaw	openclaw/skills/, published via ClawHub	n/a

The skill files themselves are vendor-agnostic prompts. The host configs only adjust the install path and a handful of tool-name aliases. Adding a tenth supported agent is one TypeScript file in hosts/.

The build pipeline

scripts/gen-skill-docs.ts is the single entry point for converting templates to rendered skills.

1. Read every SKILL.md.tmpl

   The script walks the skill directories and locates each template by convention.

2. Resolve placeholders

   Each {{PLACEHOLDER}} is replaced by output from a module in scripts/resolvers/. Twenty top-level resolvers plus over twenty preamble sub-generators expand forty-eight distinct placeholder patterns. {{PREAMBLE}}, {{BROWSE_SETUP}}, {{REVIEW_DASHBOARD}}, {{LEARNINGS_SEARCH}}, {{QA_METHODOLOGY}}, and so on.

3. Apply host-specific transforms

   For Claude Code the frontmatter passes through. For Factory the sensitive field is preserved. For Codex the description is condensed to fit a 120-character limit. All host-specific logic lives in scripts/host-adapters/.

4. Write SKILL.md alongside the template

   Each rendered file gets a <!-- AUTO-GENERATED --> header. CI fails the build if any generated file drifts from its template.

The token ceiling for generated SKILL.md files is 160 KB, about 40K tokens. This is a soft warning, not a hard gate. Flagship Claude models have context windows of 200K to 1M tokens. The largest skills (/ship, /plan-ceo-review, /office-hours) legitimately pack 25K to 35K tokens of behavior.

What this is, and what it is not

gstack is a convention layer on top of Claude Code’s existing primitives. It is not a runtime, not a framework, not an agent. Every skill invocation is claude -p with a SKILL.md as the system prompt. The “intelligence” is Opus 4.7 reading a carefully tuned prompt. The repository’s value is the prompts themselves and the shared ~/.gstack/ state directory that lets them compose.

Continue to the skill catalog to see every slash command by name, or jump to the runtime mechanism to understand how a single skill actually executes.