gstack is an open-source AI coding factory and virtual engineering team workflow created by Garry Tan, current President and CEO of Y Combinator. The project is built on a core philosophy: AI should not work in a single generic cognitive mode — it needs clearly defined role specialization.
By encapsulating structured software engineering roles (CEO, Engineering Manager, Designer, QA, Release Engineer, etc.) as specific AI skills (Skills), gstack successfully transforms AI coding assistants such as Claude Code into a disciplined virtual engineering team where every member has a well-defined job. Garry Tan himself has publicly stated that with this workflow, while serving as YC CEO, he wrote over 600,000 lines of production-grade code in 60 days on a part-time schedule (10,000–20,000 lines per day). The community has hailed this as “one person with the productivity of a twenty-person engineering team.”
Core features of the project include:
/plan-eng-review and /review steps, producing high-quality architecture diagrams and code.gstack’s system architecture is primarily divided into two dimensions: the AI skill dispatch layer and the headless browser interaction layer. To solve the cold-start latency (~2–3 seconds) and state loss (e.g., Cookies, login state) that AI agents encounter when frequently invoking the browser, gstack innovatively introduces a C/S (client/server) daemon model.
We can think of this architecture as a virtual test engineer:
$B click @e1) and delivers them at extreme speed over long-lived HTTP connections.The entire system achieves strict decoupling from top to bottom: the AI agent at the top issues commands by invoking a locally compiled CLI tool; the CLI acts as a lightweight client communicating with a resident Bun Server over HTTP; the Server drives the underlying Playwright Chromium instance directly via CDP (Chrome DevTools Protocol) and asynchronously flushes logs to disk.
graph TD
subgraph AI Agent Layer
A[Claude Code / Codex] -->|Invoke Skill| B[SKILL.md Prompts]
B -->|Tool Call: $B command| C(CLI - Compiled Binary)
end
subgraph gstack Browse Daemon
C -->|1. Read .gstack/browse.json| C
C -->|2. HTTP POST| D[Server - Bun.serve]
D -->|Dispatch| E[Browser Manager]
end
subgraph Headless Browser
E -->|CDP| F[Chromium - Playwright]
F -->|Render| G[Web Page]
F -.->|Log/Network/Dialog| H[(In-Memory Buffers)]
H -.->|Async Flush| I[Disk Logs]
end
This section details several key design decisions in the system architecture, including the use of the Bun runtime, the state persistence scheme, and security isolation strategies.
bun build --compile to package the CLI into a single executable, eliminating runtime node_modules dependencies, ~58MB in size.better-sqlite3, greatly improving cross-platform compatibility.Bun.serve() to provide a minimal HTTP service handling 20+ core routes, avoiding the overhead of redundant Express/Fastify frameworks.bun run server.ts directly without precompilation.localhost, forbidding external network access.Bearer Auth) to prevent unauthorized cross-process calls.page.accessibility.snapshot() to obtain the ARIA (Accessible Rich Internet Applications) tree and assigns sequential numbers to each element (e.g., @e1, @e2).count() === 0 throws an exception), solving the frequent failures of traditional CSS selectors with Shadow DOM and framework hydration.framenavigated event), all Refs are automatically cleaned up. This is a defensive design that requires the agent to re-run snapshot after navigation to obtain fresh references, avoiding clicks on wrong or stale elements.@c1, @c2), captured via the -C flag for elements not present in the ARIA tree but actually clickable by cursor (e.g., divs with cursor: pointer or custom onclick).This chapter analyzes the low-level infrastructure modules in the gstack project. Unlike the Markdown-based skill definitions, these modules are developed in TypeScript and are primarily responsible for system-level interactions and automation tasks. Among them, the Headless Browser Engine provides AI agents with the ability to parse and interact with page DOM elements; the Skill Template Compiler is responsible for managing and generating the final skill documents, ensuring configuration consistency across environments.
browse)This module lives in the browse/src/ directory and is built on Playwright to run automated browser tasks in the background and expose standard interaction interfaces.
cli.ts)
.gstack/browse.json state file to obtain the current daemon’s PID, port, and auth Token. When the process is missing or the binary version (binaryVersion) has changed, it automatically spawns and initializes server.ts, then forwards interaction commands over HTTP POST.server.ts)
browser-manager.ts)
disconnected event and proactively terminates the process when the Chromium instance crashes abnormally, avoiding zombie processes and inconsistent state.@e1) for interactive elements on the page, so AI agents can precisely locate and operate on DOM nodes via plain-text commands, avoiding the performance cost of directly processing complex HTML trees.gen-skill-docs)This module lives at scripts/gen-skill-docs.ts and mainly implements automated building and rendering of skill documents (SKILL.md).
.md skill documents, forcing .tmpl templates to be converted into final documents through the compilation script, thereby keeping code and documentation synchronized.This chapter details all the core skills stored in the .agents/skills/ directory. By defining specific system prompts, allowed tools, and execution hooks, these skills grant AI agents different professional roles. Based on where they apply in the software development lifecycle, these skills can be divided into four core layers: the product planning layer, the quality assurance layer, the release & operations layer, and the infrastructure layer.
Skills in this layer are mainly used in the requirements analysis and architecture design phase before code is written, ensuring clear product goals, sound technical architecture, and consistent design standards.
/office-hours (Product Diagnosis and Reframing)
Bash, Read, Grep, Glob, Write, Edit, AskUserQuestion./plan-ceo-review (Product Boundary Review)
Read, Grep, Glob, Bash, AskUserQuestion./plan-eng-review (Engineering Architecture Review)
Read, Write, Grep, Glob, AskUserQuestion, Bash./plan-design-review (Design Proposal Evaluation)
Read, Edit, Grep, Glob, Bash, AskUserQuestion./design-consultation (Design System Construction)
Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion, WebSearch.Skills in this layer run through the code development and testing phases, with the core goals of discovering latent defects, ensuring the robustness of code logic, and precise visual fidelity.
/review (Code Logic Review)
Bash, Read, Edit, Write, Grep, Glob, AskUserQuestion./investigate and /debug (Systematic Root-Cause Debugging)
/debug is its common alias.Bash, Read, Write, Edit, Grep, Glob, AskUserQuestion.PreToolUse interceptor that automatically runs check-freeze.sh before any Edit or Write execution, enforcing debugging scope boundaries and preventing out-of-bounds modifications./qa (End-to-End Automated Testing and Fixing)
Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion, WebSearch./qa <URL> and it will automatically perform clicks, inputs, and other operations. When issues are found, it fixes the code with atomic commits and re-verifies./qa-only (End-to-End Read-Only Testing)
/qa; only executes tests and reports, making no code changes.Bash, Read, Write, AskUserQuestion; the code editing tool (Edit) is disabled./design-review (Design Implementation Review and Fixing)
Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion, WebSearch./codex (Adversarial Code Review)
Bash, Read, Write, Glob, Grep, AskUserQuestion./review is recommended for multi-dimensional code evaluation reports.Skills in this layer are mainly used for automated management of the version release process and retrospective summaries of project cycles, ensuring efficient and transparent delivery.
/ship (One-Click Release Pipeline)
Bash, Read, Write, Edit, Grep, Glob, AskUserQuestion, WebSearch./document-release (Documentation Sync)
Bash, Read, Write, Edit, Grep, Glob, AskUserQuestion./ship) changes project characteristics./retro (Periodic Retrospective and Analysis)
Bash, Read, Write, Glob, AskUserQuestion.Skills in this layer provide the underlying tools, system configuration entry points, and core security protection mechanisms that support higher-level business logic.
/gstack (Global Workflow and Browser Entry)
Bash, Read, AskUserQuestion./review or /ship) based on the user’s current development stage. To disable proactive recommendations, modify the configuration as prompted./browse (Headless Browser Control)
Bash, Read, AskUserQuestion./qa; developers can also send low-level control commands manually from the terminal via $B <command>./setup-browser-cookies (Browser Session Sync)
Bash, Read, AskUserQuestion./qa to ensure the headless browser has the correct user authentication context./careful (Destructive Operation Alert)
rm -rf or DROP TABLE.Bash, Read.PreToolUse interceptor that automatically runs the check-careful.sh script to scan for destructive commands before any Bash execution./freeze and /unfreeze (Edit Scope Locking)
Bash, Read, AskUserQuestion./freeze configures a PreToolUse interceptor that enforces check-freeze.sh path permission validation before invoking the Edit or Write tools./freeze to lock a directory; after completing the task, you must call /unfreeze to lift the restriction./guard (Global Maximum Security Mode)
/careful’s command alerting and /freeze’s edit locking simultaneously.Bash and checking boundary restrictions before Edit / Write./gstack-upgrade (System Self-Update)
Bash, Read, Write, AskUserQuestion.This chapter analyzes three representative .tmpl skill templates (/qa, /review, /plan-eng-review) in depth to show how gstack uses advanced prompt engineering techniques to transform AI from a “passive Q&A bot” into a “proactive engineering partner.” Building on this, we summarize reusable prompt design patterns.
The following is a detailed analysis of the underlying workflows and prompt designs of gstack’s core skills, with excerpts of real template source code (prompt snippets).
/qa: End-to-End Testing and Fix LoopThis skill demonstrates how to orchestrate an extremely complex “test-fix-regress” multi-step state machine.
Target URL, Tier, and Scope.git status --porcelain. If the workspace is not clean, it triggers an AskUserQuestion asking the user to Commit or Stash, protecting the subsequent “Atomic Commits” from polluting the code history.Source excerpt (dirty check interception):
**Check for clean working tree:**
`git status --porcelain`
If the output is non-empty (working tree is dirty), **STOP** and use AskUserQuestion:
"Your working tree has uncommitted changes. /qa needs a clean tree so each bug fix gets its own atomic commit."
/plan-eng-review (*-test-plan-*.md) from ~/.gstack/projects/ as the test baseline. Only when the test plan is missing does it degrade to git diff heuristic analysis.Phases 1-6: QA Baseline (Phase 1: Initialize through Phase 6: Wrap Up) to Phase 7: Triage (filtering bugs by the configured Tier), then to Phase 8: Fix Loop, Phase 9: Final QA, and Phase 10: Report.before/after screenshot comparisons and regression test writing./review: Architecture-Level Review Beyond SyntaxThis skill demonstrates how to get AI out of the “code formatter” mindset and perform deep business-logic review.
Step 1.5 forces the AI to first read TODOS.md or the PR description, extract the “stated intent,” and then compare it against the actual code diff, thereby detecting “scope creep” or “missed requirements.”Source excerpt (scope drift detection):
## Step 1.5: Scope Drift Detection
Before reviewing code quality, check: **did they build what was requested — nothing more, nothing less?**
1. Read `TODOS.md` (if it exists). Read PR description...
2. Identify the **stated intent** — what was this branch supposed to accomplish?
3. Run `git diff origin/<base> --stat` and compare the files changed against the stated intent.
Step 2, dynamically reads the external rule base .claude/skills/review/checklist.md, and in Step 4 performs a “two-pass review.” The first pass looks exclusively for critical issues (SQL injection, race conditions); the second pass covers routine issues (hardcoding, test coverage).AUTO-FIX and ASK. Mechanical issues are fixed automatically; architectural or business issues are batched to the user via AskUserQuestion with multiple options (including fix suggestions) for decision. This prevents ineffective “report-only, no-fix” reviews./plan-eng-review: Injecting Expert-Level Mental ModelsThis skill demonstrates how to inject the intuition and values of a senior human engineer into AI.
Source excerpt (cognitive pattern injection):
## Cognitive Patterns — How Great Eng Managers Think
These are not additional checklist items. They are the instincts that experienced engineering leaders develop over years... 2. **Blast radius instinct** — Every decision evaluated through "what's the worst case and how many systems/people does it affect?" 3. **Boring by default** — "Every company gets about three innovation tokens." Everything else should be proven technology. 10. **Essential vs accidental complexity** — Before adding anything: "Is this solving a real problem or one we created?"
Source excerpt (complexity blocking):
3. **Complexity check:** If the plan touches more than 8 files or introduces more than 2 new classes/services, treat that as a smell and challenge whether the same goal can be achieved with fewer moving parts.
STOP directive, forcing the AI to “call AskUserQuestion once per issue” and to include a “cost-benefit assessment” every time — thoroughly breaking the AI’s habit of generating long-winded output in one shot.From the teardown above, we can extract four core design patterns for building advanced AI skills:
AskUserQuestion to handle anomalies, avoiding destructive behavior.~/.gstack/projects/). Downstream skills (e.g., /qa) must prioritize reading the outputs of upstream skills (e.g., /plan-eng-review), forming a closed information loop.STOP. Call AskUserQuestion. Let the AI handle the tedious analysis and execution, but firmly return decision-making on critical paths (e.g., whether to refactor, whether to fix a risk) to humans.CRITICAL (must fix or ask) from INFORMATIONAL (for reference only) information levels, the review stays rigorous without over-blocking the workflow pipeline.This chapter walks through different types of skill commands to show how system components collaborate to fulfill AI agent requests. gstack’s execution flows fall roughly into two categories: plain-text planning (Markdown-driven) and system operations (code/browser-driven).
/plan-eng-review)The core of such skills lies in context reading and mental model injection. The execution flow is as follows:
bash scripts to read the current branch state and the project directory structure.*-design-*.md (design docs) generated by upstream phases.AskUserQuestion to ask the user whether to reduce the scope./qa with Browser Operations)Taking the AI agent invoking the /qa skill and performing a click on a web page (executing the $B click @e1 command) as an example, the end-to-end flow involves calls to external processes:
sequenceDiagram
participant Agent as AI Agent
participant CLI as browse CLI
participant Server as Bun Server
participant Manager as BrowserManager
participant Playwright as Chromium
Agent->>CLI: Execute command $B click @e1
CLI->>CLI: Check state file
alt Server not started or stale
CLI->>Server: spawn background process
Server-->>CLI: Write new process info
end
CLI->>Server: Send HTTP POST request (with Token)
Server->>Server: Authenticate and route command
Server->>Manager: Call handler function
Manager->>Manager: Parse @e1 to resolve node reference
Manager->>Playwright: Execute click action
Playwright-->>Manager: Page response events
Manager-->>Server: Return operation result
Server-->>CLI: Return HTTP status code
CLI-->>Agent: Output result to console
In this flow, thanks to the daemon architecture, only the first call triggers a cold start; subsequent HTTP POST interactions are compressed to 100–200 ms of latency.
This chapter assesses the project’s engineering quality across multiple dimensions, including system performance and automated test coverage, and distills best practices for testing AI skills.
Thanks to the resident-in-memory daemon architecture, the browser’s initial startup takes about 2–3 seconds, but all subsequent commands — DOM interactions, snapshot captures, network requests, and more — are compressed to 100–200 ms of latency. This lets AI agents “browse” pages as fluidly as humans, dramatically improving the execution efficiency of the /qa and /design-review skills.
Testing an AI agent with “autonomous thinking and operation capabilities” is a highly challenging engineering problem. gstack provides a textbook-worthy three-tier test architecture (see the test/ directory):
This tier validates the basic logic and stability of the underlying core toolchain without depending on external LLM APIs.
bun test. Before running locally, ensure the underlying dependencies are ready (e.g., run npx playwright install to download the Chromium engine).gen-skill-docs) works correctly and that the headless browser CLI (browse/src/) handles basic logic, path safety, state caching, etc. correctly. The suite contains several hundred test cases and completes in seconds, since no LLM APIs are called.Example run:
# Install dependencies and browser engine, then run tests
bun install && npx playwright install && bun test
Sample test output:
✓ Navigation > goto navigates to URL [17.33ms]
✓ Content extraction > accessibility returns ARIA tree [24.31ms]
✓ Interaction > click on option ref auto-routes to selectOption [50.01ms]
✓ CLI lifecycle > dead state file triggers a clean restart [1185.15ms]
...
This tier validates the AI agent’s actual ability to orchestrate external tools (e.g., the headless browser) and fix issues by simulating a human-AI conversation in a real sandbox environment.
child_process.spawn to genuinely launch a claude -p command-line process.$B browser interaction commands) and whether it successfully discovers and fixes the “deliberately planted bugs” in the sandbox.Because AI agent output is non-deterministic, this tier introduces a high-intelligence third-party model to quantitatively evaluate the quality and accuracy of the results.
expect(x).toBe(y)) cannot work. Another LLM (e.g., claude-sonnet-4-6) is therefore introduced as the “judge.”test/helpers/llm-judge.ts, the judge model reads and evaluates the QA reports or design docs generated by the AI agent:
Beyond performance and test coverage, gstack also introduces several mechanisms to ensure process management safety and pure isolation of the test environment.
git rev-parse HEAD). Once a binary update is detected, the next invocation automatically kills the old Server and restarts, thoroughly eliminating “process version mismatch” voodoo bugs./setup-browser-cookies, ensuring automated tests run in a real authenticated environment.This chapter details the project’s dependency management, build process, and deployment mechanisms. gstack provides a highly automated build script (setup) that greatly reduces configuration costs for users.
The project uses Bun as its core package manager and build tool, greatly simplifying toolchain complexity in the Node.js ecosystem:
bun install completes installation of the project’s dependencies (mainly playwright and @anthropic-ai/sdk) in seconds.bun build --compile compiles TypeScript source (e.g., the headless browser CLI) directly into a single-file binary executable of ~58MB. This means end users don’t even need a Node.js environment installed on their machine to run gstack (on macOS/Linux).bun run build)Running bun run build triggers a chain of automated build actions, including:
gen-skill-docs.ts to render all .tmpl template files into standard SKILL.md files, adapting paths to the host environment (Claude or Codex).browse/src/cli.ts into browse/dist/browse.git rev-parse HEAD) and writes it to the .version file, for later validation by the zombie process prevention mechanism.setup)gstack provides a powerful setup bash script that handles complex environment detection and deployment logic:
browse/dist/browse exists and intelligently decides whether to re-trigger the build by comparing modification times of the source code, package.json, or bun.lock.--host auto parameter, automatically detecting whether Claude Code or Codex is installed on the current system and dynamically symlinking the generated skill directories to the corresponding global config directory (e.g., ~/.claude/skills/gstack). This design ensures convenience of global invocation while allowing developers’ modifications in the source directory to take effect live.This chapter is a guide for users who want to quickly experience the gstack workflow in their own Vibe Coding IDEs (e.g., Cursor, Trae).
Before getting started, ensure the current system meets the following baseline environment:
SKILL.md standard.To let the AI assistant invoke gstack’s 23 core skills in any project, we recommend installing it into the global ~/.claude/skills directory.
Open a terminal and run the following commands:
# Clone the gstack repository to a local directory
git clone https://github.com/garrytan/gstack.git ~/gstack
# Enter the directory and run the automated install script
cd ~/gstack && ./setup --host auto
[!NOTE] The
setupscript automatically detects the AI tools installed on the system (e.g., Claude or Codex) and symlinks the compiled binaries and skill templates to the corresponding~/.claude/skills/gstackor~/.codex/skills/gstackdirectories.
If you want other team members to have the same AI skill environment right after cloning the repository, you can pin gstack into the current project.
In the project root directory, run:
# Copy the globally installed gstack into the project's hidden directory
cp -Rf ~/.claude/skills/gstack .claude/skills/gstack
# Remove git history to avoid nested repository issues
rm -rf .claude/skills/gstack/.git
# Rebuild and register the skills inside the project
cd .claude/skills/gstack && ./setup
After that, we recommend creating a CLAUDE.md (or the IDE’s corresponding custom system prompt file) in the project root with the following content, guiding the AI on how to use these skills:
# AI Workflow Guide
Please use the skills provided under `.claude/skills/gstack` in this project.
- Use `/office-hours` and `/plan-ceo-review` during the planning phase
- Use `/review` for code review
- Use `/qa` and `/browse` for feature testing, and **never** use the built-in `mcp__claude-in-chrome__*` tools.
After installation, open the IDE chat window and try the following “conversation flow” to experience the full gstack closed loop:
I want to add a user feedback collection popup to the current project, /office-hours./plan-eng-review./qa http://localhost:3000 (replace with your local dev address) and let it click the popup itself, discover bugs, and fix them./ship — it will automatically run tests, generate commits, and push to the repository.This article was written based on a snapshot of the gstack repository from July 2026. The repository is continuously and rapidly evolving, so some data may be outdated.