This document provides a high-level introduction to gstack: its purpose, architecture, and design philosophy. It explains how gstack transforms AI agents from generalist assistants into a coordinated team of specialists through a structured skill system, backed by a persistent headless browser infrastructure and a semantic memory layer.
gstack is designed for technical founders, CEOs, and staff engineers who want to ship code at an accelerated scale—leveraging agentic workflows to move faster than a traditional team README.md29-33
gstack is an "open source software factory" README.md23 It provides specialized cognitive modes for different engineering activities, invoked via slash commands. The system consists of three primary layers:
/office-hours, /plan-ceo-review, /review, /ship) that define persona-driven prompts and workflows README.md23-24 These are generated from templates in .tmpl files using a resolution pipeline involving scripts/gen-skill-docs.ts CLAUDE.md86/browse and /qa skills to interact with web applications with sub-second latency ARCHITECTURE.md7-10{{BRAIN_PREFLIGHT}} templates to load context from digests of typed entities like gstack/product or gstack/goal CHANGELOG.md41-45| Skill | Specialist Persona | Primary Function |
|---|---|---|
/office-hours | YC Partner | Reframes product ideas via 6 forcing questions; brain-aware docs/skills.md7 CHANGELOG.md43 |
/plan-ceo-review | CEO / Founder | Rethinks the problem; finds the "10-star product" docs/skills.md9 |
/plan-eng-review | Eng Manager | Locks architecture, data flow, and edge cases docs/skills.md10 |
/review | Staff Engineer | Finds bugs that pass CI but fail in production docs/skills.md13 |
/qa | QA Lead | Tests apps, finds bugs, and verifies via browser docs/skills.md18 |
/ship | Release Engineer | Automates PR creation, test runs, and doc syncing docs/skills.md22 |
/browse | QA Engineer | Provides the agent "eyes" via a persistent browser docs/skills.md30 |
/investigate | Debugger | Systematic root-cause debugging with an "Iron Law" of no fixes without investigation docs/skills.md14 |
Sources: README.md23-24 docs/skills.md5-50 CLAUDE.md109-131 CHANGELOG.md41-46
Standard AI agents often suffer from "blank prompt" syndrome or inconsistent depth. gstack solves several specific bottlenecks:
/office-hours to push back on premises docs/skills.md7This diagram bridges the Natural Language Space (user commands) to the Code Entity Space (specific implementation files and classes).
Sources: ARCHITECTURE.md12-34 CLAUDE.md78-131 CHANGELOG.md41-61 package.json12
gstack's browser is not a one-off script; it is a persistent daemon. The key insight is that an AI agent needs sub-second latency and persistent state to be effective ARCHITECTURE.md7-10
The following diagram illustrates how a command like $B click @e1 moves through the codebase.
Key Architecture Decisions:
.gstack/browse.json for a running server. If none exists, it spawns the server which writes a random port and bearer token to this file ARCHITECTURE.md64-73snapshot system in browse/src/snapshot.ts assigns temporary handles (e.g., @e1) based on the ARIA accessibility tree ARCHITECTURE.md112-121Sources: ARCHITECTURE.md52-81 ARCHITECTURE.md112-121 ARCHITECTURE.md88-109
gstack assumes that a single prompt cannot handle the nuance of a CEO, an Architect, and a QA Engineer simultaneously. By splitting these into separate skills, the model is forced into a specific depth of analysis docs/skills.md7-19
Planning skills are no longer stateless. They preflight a typed entity model from gbrain (Wintermute or local PGLite) before asking questions. This allows the agent to detect contradictions with prior plans (e.g., "this contradicts your January CEO plan") CHANGELOG.md41-45
gstack is designed to work across a wide variety of AI hosts (Claude, Codex, Gemini, Cursor, OpenClaw, etc.). It uses a template-based generation system (scripts/gen-skill-docs.ts) to adapt core skill logic to the specific constraints of each model CLAUDE.md86-93
gstack uses a tiered testing system:
bun test) CLAUDE.md128claude -p to verify real-world behavior (bun run test:e2e) CLAUDE.md129bun run test:evals) CLAUDE.md131The choice of Bun enables compiled binaries via bun build --compile for sub-millisecond startup and native SQLite access for cookie decryption ARCHITECTURE.md42-45
Sources: docs/skills.md7-19 CLAUDE.md86-131 ARCHITECTURE.md38-51 CHANGELOG.md41-46
Refresh this wiki