> ## Documentation Index
> Fetch the complete documentation index at: https://prof-lee.zikun.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CardGroup cols={2}>
  <Card title="47 SKILL.md files" icon="file-text">
    Markdown prompts with YAML frontmatter that Claude Code loads as native slash-commands. The substantive intelligence of the system. [See the runtime](/runtime).
  </Card>

  <Card title="A compiled browser daemon" icon="globe">
    `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.
  </Card>

  <Card title="A GPT-Image designer" icon="palette">
    `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.
  </Card>

  <Card title="Per-AI-agent host configs" icon="grid-2x2-plus">
    `hosts/*.ts` defines installation paths and tool-name aliases for Claude Code, Codex, Cursor, OpenCode, Factory, Slate, Kiro, Hermes, GBrain, and OpenClaw.
  </Card>
</CardGroup>

## Repository tree

```text gstack/ (top level) theme={null}
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
```

<Info>
  **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.
</Info>

## 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.

<CardGroup cols={2}>
  <Card title="Persistence" icon="circle-power">
    The browser stays alive across calls. Cookies, localStorage, and tabs carry over. Auto-shuts down after 30 minutes idle.
  </Card>

  <Card title="Roughly 70 commands" icon="terminal">
    `goto`, `snapshot`, `click`, `fill`, `screenshot`, `console`, `network`, `js`, `responsive`, `cookie-import-browser`, `handoff`, `cdp`, and dozens more.
  </Card>

  <Card title="Headed escape hatch" icon="hand">
    `$B handoff` transfers to a visible Chrome at the same URL, preserving session, for CAPTCHA or MFA. `$B resume` returns to headless.
  </Card>

  <Card title="Prompt-injection defense" icon="shield-check">
    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.
  </Card>
</CardGroup>

## 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.

<Steps>
  <Step title="Read every SKILL.md.tmpl" icon="file-search">
    The script walks the skill directories and locates each template by convention.
  </Step>

  <Step title="Resolve placeholders" icon="git-merge">
    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.
  </Step>

  <Step title="Apply host-specific transforms" icon="grid-2x2-plus">
    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/`.
  </Step>

  <Step title="Write SKILL.md alongside the template" icon="file-output">
    Each rendered file gets a `<!-- AUTO-GENERATED -->` header. CI fails the build if any generated file drifts from its template.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## What this is, and what it is not

<Tip>
  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.
</Tip>

Continue to the [skill catalog](/skills) to see every slash command by name, or jump to the [runtime mechanism](/runtime) to understand how a single skill actually executes.