Excellent. I've thoroughly explored the gstack project. Now let me provide a comprehensive summary to the user:

---

# Complete gstack Project Exploration

## What is gstack?

**gstack** is Garry Tan's (YC President & CEO) open-source AI engineering workflow system built on top of Claude Code. It transforms Claude Code into a virtual engineering team with 13 specialized roles and command-driven skills — all free, MIT licensed, and available as slash commands in Markdown.

The core philosophy: **Structured roles instead of generic agent chaos**. Each skill is opinionated, follows a specific methodology, and produces structured outputs. Rather than a blank prompt, users get a CEO, engineer manager, designer, QA lead, and release engineer all as slash commands.

## Key Stats & Vision

- **Author:** Shipping 10,000-20,000 usable lines of code per day as CEO while managing YC
- **600,000+ lines** written in 60 days (35% tests)
- **1,237+ GitHub contributions in 2026** (massive acceleration vs prior years)
- **Compression:** Boilerplate ~100x faster, tests ~50x, features ~30x, bugs ~20x with CC+gstack vs human team
- **Latest version:** 0.6.4 (as of March 17, 2026)

## The Architecture: Persistent Browser Daemon

gstack's secret sauce is the **headless browser daemon**:

```
Claude Code → CLI (binary) → HTTP POST → Server (Bun) → Chromium (persistent)
                                                              ↓
                        ~3s first call, ~100-200ms subsequent calls
```

**Why daemon, not per-command browser?**
- Cookies, login sessions, localStorage persist
- Sub-second latency after startup
- 30-minute idle auto-shutdown
- No state loss between commands

**Technical stack:**
- **Bun runtime** — compiled binary (~58MB), native SQLite, native TypeScript
- **Playwright** for browser control
- **localhost-only HTTP** with bearer token auth
- **Random port selection** (10000-60000) for multi-workspace support
- **Ref system** — `@e1`, `@e2` refs instead of CSS selectors

## The 13 Specialist Skills

| Slash Command | Role | What It Does |
|---|---|---|
| `/plan-ceo-review` | CEO/Founder | Rethink the problem → 10x product vision. 4 modes: EXPANSION, SELECTIVE EXPANSION, HOLD SCOPE, REDUCTION. Saves plans to disk. |
| `/plan-eng-review` | Eng Manager | Lock architecture, data flows, diagrams, tests. Full interactive review with one issue per AskUserQuestion. Writes test plan artifacts. |
| `/plan-design-review` | Senior Designer | Interactive design audit (0-10 rating per dimension). Fixes the plan to get to 10. For live sites, use `/design-review`. |
| `/design-consultation` | Design Partner | Builds complete design system from scratch. Research + proposal + SAFE/RISK breakdown. Creates DESIGN.md. |
| `/review` | Staff Engineer | Pre-landing diff review. SQL safety, race conditions, LLM trust boundaries, enum completeness, design checks. Auto-fixes obvious issues. |
| `/ship` | Release Engineer | Complete workflow: sync main, run tests, coverage audit, bump VERSION, update CHANGELOG, commit, push, create PR. One command. |
| `/browse` | QA Engineer | Fast headless Chromium. ~40+ commands: navigate, interact, assert, screenshot, responsive testing, file upload, dialogs. |
| `/qa` | QA Lead | Systematically tests app and fixes bugs. Find → Fix → Verify loop with atomic commits and before/after screenshots. |
| `/qa-only` | QA Reporter | Same testing methodology as `/qa` but report-only (no fixes). |
| `/design-review` | Designer + Coder | Design audit on live site, then iteratively fixes CSS/HTML with atomic commits and screenshots. |
| `/setup-browser-cookies` | Session Manager | Import cookies from Chrome, Arc, Brave, Edge into headless session. Test authenticated pages. |
| `/retro` | Eng Manager | Weekly retrospective. Per-person stats, commit history, test health, Greptile signal, TODOS backlog health. |
| `/document-release` | Technical Writer | Post-ship doc updates. Reads diff, updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md, polishes CHANGELOG. |

### Bonus Skills
- `/gstack-upgrade` — Update to latest version
- `/design-consultation` — Build design system

## Key Features & Innovations

### 1. **Four CEO Review Modes**
- **EXPANSION:** Dream big, 10x thinking, opt-in ceremony
- **SELECTIVE EXPANSION:** Hold scope, cherry-pick expansions individually
- **HOLD SCOPE:** Maximum rigor, bulletproof the plan
- **SCOPE REDUCTION:** Ruthlessly cut to MVP

Plans saved to `~/.gstack/projects/{slug}/ceo-plans/` with scope decisions table.

### 2. **Interactive, Structured Questions**
Every AskUserQuestion has:
- Clear context (project, branch, what's happening)
- Explicit recommendation ("I recommend X because...")
- Numbered options with outcomes
- No "pick one of 8 things" — typically 2-3 focused choices

### 3. **Smart Review Routing**
- Design review auto-runs on frontend changes via `/review` and `/ship`
- CEO review only recommended (not required) for product changes
- Eng review is the gating review; CEO/Design are informational
- Review readiness dashboard shows which reviews are done

### 4. **Completeness Principle**
> When AI coding compresses implementation time 10-100x, always recommend the complete solution. No shortcuts when the full version costs seconds with CC.

Dual-time estimates throughout (human team time vs CC+gstack time).

### 5. **E2E Test Infrastructure (3-tier)**
- **Tier 1:** Static validation (free, <1s)
- **Tier 2:** E2E via `claude -p` (~$3.85/run)
- **Tier 3:** LLM-as-judge (~$0.15/run)

Diff-based test selection: only run tests affected by changed files. Use `bun run eval:select` to preview.

### 6. **QA with Real Browser**
`/qa` finds bugs and fixes them in source code with:
- Atomic `test(qa): ...` commits
- Before/after screenshots
- Regression test auto-generation
- Health score tracking (before/after)

### 7. **Design System Integration**
- **DESIGN.md** as single source of truth
- `/design-consultation` builds complete systems (aesthetic, typography, color, layout, spacing, motion)
- Design decisions flow through all review stages
- AI slop detection (purple gradients, 3-col grids, generic copy)

### 8. **Ref System (Not Selectors)**
- Accessibility tree → `@e1`, `@e2`, etc.
- Playwright Locators (no DOM mutation, no CSP issues)
- Cursor-interactive refs `@c1`, `@c2` for custom components
- Stale ref detection on SPAs

### 9. **Browser Commands (~40 total)**

**Navigation:** `goto`, `back`, `forward`, `reload`, `url`

**Reading:** `text`, `html`, `links`, `forms`, `accessibility`, `js`, `eval`, `css`, `attrs`, `console`, `network`, `cookies`, `storage`, `perf`

**Inspection:** `is` (visible/hidden/enabled/disabled/checked/editable/focused), `dialog`

**Interaction:** `click`, `fill`, `select`, `hover`, `type`, `press`, `scroll`, `wait`, `viewport`, `cookie`, `cookie-import`, `cookie-import-browser`, `header`, `useragent`, `upload`, `dialog-accept`, `dialog-dismiss`

**Visual:** `screenshot` (element crop, region clip, viewport), `pdf`, `responsive` (mobile/tablet/desktop), `diff`

**Tabs:** `tabs`, `tab`, `newtab`, `closetab`

**Server:** `status`, `stop`, `restart`

**Meta:** `snapshot` (accessibility tree with refs), `chain` (JSON command batch)

### 10. **Snapshot Flags**
```
snapshot -i          # interactive elements only
snapshot -c          # compact (no empty structural nodes)
snapshot -d N        # depth limit
snapshot -s SEL      # scope to selector
snapshot -D          # diff vs previous
snapshot -a          # annotated screenshot with overlay
snapshot -o PATH     # output path
snapshot -C          # cursor-interactive elements
```

## Installation

```bash
# 30 seconds — two-step install
git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack && ./setup

# Optional: add to project for teammates
cp -Rf ~/.claude/skills/gstack .claude/skills/gstack
rm -rf .claude/skills/gstack/.git
cd .claude/skills/gstack && ./setup
```

The `setup` script:
1. Builds browse binary if needed
2. Installs Playwright Chromium
3. Creates `~/.gstack` global state directory
4. Symlinks skills to `.claude/skills/`

## Development & Testing

**Build commands:**
```bash
bun install              # install dependencies
bun run build            # gen docs + compile binaries
bun run gen:skill-docs   # regenerate SKILL.md from templates
bun run dev:skill        # watch mode: auto-regen + validate
bun run skill:check      # health dashboard
```

**Testing (3 tiers):**
```bash
bun test                 # free tests (validate + snapshot)
bun run test:evals       # paid evals: LLM judge + E2E
bun run eval:list        # list past eval runs
bun run eval:compare     # compare two runs
```

**Dev mode:**
```bash
bun run dev <cmd>        # run CLI in dev, e.g. bun run dev goto https://example.com
EVALS_ALL=1 bun run test:evals  # force all evals regardless of diff
```

## Project Structure

```
gstack/
├── browse/                  # Headless browser CLI + server
│   ├── src/
│   │   ├── cli.ts          # Thin CLI wrapper
│   │   ├── server.ts       # Bun HTTP server
│   │   ├── commands.ts     # Command registry (single source of truth)
│   │   ├── snapshot.ts     # Accessibility tree + ref system
│   │   ├── browser-manager.ts  # Chromium lifecycle + state
│   │   ├── read-commands.ts    # Text, html, js, eval, etc.
│   │   ├── write-commands.ts   # Click, fill, navigate, etc.
│   │   ├── meta-commands.ts    # Screenshots, chain, diff
│   │   ├── cookie-import-browser.ts  # Keychain + AES decryption
│   │   └── config.ts       # Path resolution
│   ├── test/               # 166+ integration tests
│   └── dist/browse         # Compiled binary
│
├── skills/
│   ├── plan-ceo-review/        # CEO/founder mode
│   ├── plan-eng-review/        # Eng manager mode
│   ├── plan-design-review/     # Designer mode (plan)
│   ├── design-consultation/    # Design system builder
│   ├── design-review/          # Designer + coder (live)
│   ├── review/                 # Staff engineer (pre-land)
│   ├── ship/                   # Release engineer
│   ├── qa/                     # QA + fixer
│   ├── qa-only/                # QA reporter
│   ├── retro/                  # Weekly retrospective
│   ├── document-release/       # Post-ship doc updates
│   ├── setup-browser-cookies/  # Session mgmt
│   └── gstack-upgrade/         # Update system
│
├── scripts/
│   ├── gen-skill-docs.ts       # SKILL.md.tmpl → SKILL.md
│   ├── skill-check.ts          # Health dashboard
│   ├── dev-skill.ts            # Watch mode
│   ├── eval-*.ts               # Eval tools
│
├── bin/
│   ├── gstack-slug             # Git remote → owner/repo
│   ├── gstack-config           # Config get/set/list
│   ├── gstack-diff-scope       # Categorize changes
│   ├── gstack-update-check     # Version check + snooze
│   ├── dev-setup / dev-teardown # Contributor mode
│
├── test/
│   ├── skill-validation.test.ts  # Static: command/flag validation
│   ├── gen-skill-docs.test.ts    # Generator quality
│   ├── skill-llm-eval.test.ts    # LLM-as-judge evals
│   ├── skill-e2e.test.ts         # E2E via claude -p
│   └── helpers/
│       ├── skill-parser.ts       # Extract $B commands from MD
│       ├── session-runner.ts     # Agent SDK wrapper
│       └── touchfiles.ts         # Diff-aware test selection
│
├── docs/
│   └── skills.md               # Deep dives with examples
│
├── ARCHITECTURE.md             # Design decisions
├── CONTRIBUTING.md             # Dev setup guide
├── CLAUDE.md                   # Development instructions
├── CHANGELOG.md                # Version history
├── README.md                   # Hero + hero shot + demo
└── package.json                # Bun project config
```

## Template System

**The problem:** Hand-maintained SKILL.md docs drift from code.

**The solution:** `.tmpl` files with placeholders, auto-generated at build time.

```
plan-ceo-review/SKILL.md.tmpl
    ↓
gen-skill-docs.ts (reads source metadata)
    ↓
plan-ceo-review/SKILL.md (committed)
```

**Placeholders:**
- `{{PREAMBLE}}` — update check + session tracking
- `{{BASE_BRANCH_DETECT}}` — PR base branch detection
- `{{COMMAND_REFERENCE}}` — Browse command table from `commands.ts`
- `{{SNAPSHOT_FLAGS}}` — Snapshot flag reference from `snapshot.ts`
- `{{BROWSE_SETUP}}` — Binary discovery
- `{{TEST_BOOTSTRAP}}` — Test framework setup
- `{{QA_METHODOLOGY}}` — Shared QA methodology
- `{{DESIGN_METHODOLOGY}}` — Shared design audit
- `{{REVIEW_DASHBOARD}}` — Review readiness display
- `{{DESIGN_REVIEW_LITE}}` — Auto design check on `/review` and `/ship`

## CLAUDE.md - Project Development Instructions

The project includes comprehensive development docs:
- **Commands section** — all bun scripts with descriptions
- **Project structure** — detailed walkthrough
- **SKILL.md workflow** — how to edit templates
- **Browser interaction** — use `/browse`, never MCP tools
- **Commit style** — bisect commits (one logical change each)
- **CHANGELOG style** — user-forward release notes, not impl details
- **AI effort compression** — dual-time estimates throughout
- **E2E eval failure blame protocol** — never claim "unrelated" without proof

## Security

- **Localhost-only HTTP** binding
- **Bearer token auth** on every request
- **Keychain integration** for cookie decryption (requires user click)
- **Read-only cookie DB access** (copies to /tmp)
- **No cookie values in logs** (metadata only)
- **No shell injection** (hardcoded registry, argument arrays)

## Contributing & CI/CD

- **Skill docs auto-generated** — `.github/workflows/skill-docs.yml` fails if generated output differs
- **3-tier testing** — validation (free) → E2E ($) → LLM-judge ($)
- **Planted-bug fixtures** — eval tests with known bugs to verify detection
- **Diff-based test selection** — only run tests affected by changed files
- **Pre-commit hooks** — skill validation, command drift detection
- **Contributor mode** — `gstack-config set gstack_contributor true` for auto-bug reports

## Philosophy & Cognitive Patterns

gstack deeply embeds frameworks from:

**CEO/Founder mode:**
- Bezos (one-way doors, Day 1 proxy skepticism)
- Grove (paranoia)
- Munger (inversion)
- Horowitz (wartime awareness)
- Chesky/Graham (founder mode)
- Altman (leverage obsession)

**Eng Manager mode:**
- Larson (team state diagnosis)
- McKinley (boring by default)
- Brooks (essential vs accidental complexity)
- Beck (make change easy)
- Majors (own code in production)
- Google SRE (error budgets)

**Designer mode:**
- Rams (subtraction default)
- Norman (3 levels of design)
- Zhuo (principled taste)
- Gebbia (design for trust, storyboard journey)
- Ive (care is visible)

These aren't checklists — they're "latent space activation." The LLM internalizes the frameworks, making each review a genuine perspective shift.

## Completeness as Core Feature

The **Completeness Principle** permeates every skill:

> With AI-assisted coding compressing human effort 10-100x, always recommend the complete solution when marginal cost is minimal. The lake is cheap — boil it.

- Plan reviews flag shortcut implementations
- Dual-time estimates show CC time is mostly free
- Test coverage and edge case handling default to complete
- Deferred work is explicitly written to TODOS.md

## Latest Innovations (v0.6.4)

- `/plan-design-review` now interactive (0-10 ratings, fixes plan)
- CEO review auto-activates design section when UI is in scope
- 14/15 skills now have full test coverage (E2E + LLM-judge)
- Bisect commit style enforced (one logical change per commit)
- Smart review routing (CEO recommended, Eng required, Design on frontend)

## Real-World Example (From README)

```
You:    I want to add photo upload for sellers.
You:    /plan-ceo-review
Claude: [8 expansion proposals with effort/impact]

You:    /plan-design-review
Claude: Design Score: B | AI Slop Score: C
        [80-item audit, fixes to bring scores up]

You:    /plan-eng-review
Claude: [Architecture diagrams, test matrix, error paths]

You:    [Approve plan] → Claude writes 2,400 lines in 11 files

You:    /review
Claude: [AUTO-FIXED] 2 issues | [ASK] 1 race condition

You:    /qa https://staging.myapp.com
Claude: [Finds + fixes bug in preview clearing]
        [Auto-generates regression test]

You:    /ship
Claude: Tests: 42 → 51 (+9 new)
        Coverage: 14/14 code paths (100%)
        PR: github.com/you/app/pull/42
```

One feature. Seven commands. Entire virtual team.

---

**This is the most thorough, production-grade AI engineering workflow toolkit available as of March 2026.**

agentId: a94df73d60989dd84 (use SendMessage with to: 'a94df73d60989dd84' to continue this agent)
<usage>total_tokens: 92213
tool_uses: 26
duration_ms: 298347</usage>

Prompt:
Thoroughly explore the gstack project at /root/projects/gits/gstack. I need to understand:

1. What is gstack? Read the README.md, package.json, CHANGELOG.md to understand the project's purpose and features
2. Read the main SKILL.md.tmpl template to understand what skills/commands it provides to users
3. Read the browse/ directory - understand what the headless browser CLI does (browse/src/commands.ts, browse/src/snapshot.ts, browse/src/index.ts or main entry)
4. Look at the setup script to understand installation
5. Read any skill directories (ship/, review/, qa-only/, plan-design-review/, retro/, etc.) - read their SKILL.md.tmpl files to understand each skill

Be very thorough - read actual file contents, not just list files. I need detailed understanding of every major feature.


I now have a comprehensive understanding of gstack. Let me write the plan document in Chinese as requested. The user wants a detailed document explaining the project's goals, how it works, and how to use it, especially the AI capabilities.

Let me write this to the plan file.


现在我已经对项目有了全面的了解，让我撰写详细的中文文档。


Write

# gstack 项目详细文档

> **注意：这不是一个实施计划，而是用户要求的项目分析文档。**

---

## 一、项目概述

**gstack** 是由 Y Combinator 总裁兼 CEO Garry Tan 开源的 **AI 工程工作流系统**，构建在 Claude Code 之上。它将 Claude Code 从一个通用 AI 编程助手，转变为一个拥有 **15 个专业角色**的虚拟工程团队——CEO、工程经理、设计师、QA 主管、发布工程师等，全部通过斜杠命令（slash commands）调用。

**核心理念：** 用结构化的角色分工取代泛化的 AI 对话。每个 skill 都是一套完整的方法论，有明确的输入、输出和流程。

**关键数据：**
- MIT 开源协议，完全免费
- 作者声称使用 gstack 每天可产出 10,000-20,000 行可用代码
- 60 天内产出 600,000+ 行代码（35% 为测试代码）
- 效率压缩比：模板代码 ~100x、测试 ~50x、功能开发 ~30x、Bug 修复 ~20x
- 当前版本 v0.6.4（2026 年 3 月）

---

## 二、核心架构

### 2.1 整体架构图

```
用户 → Claude Code → /skill 命令 → SKILL.md prompt → AI Agent 执行
                         ↓
                    browse 二进制 → HTTP 请求 → Bun 服务器 → Chromium 浏览器（持久守护进程）
```

gstack 由两大核心组件构成：

1. **Skill 系统**：15 个 Markdown 格式的 prompt 模板，每个代表一个专业角色
2. **Browse 浏览器引擎**：基于 Playwright 的无头浏览器守护进程，提供 ~50 个命令

### 2.2 Browse 浏览器守护进程

这是 gstack 的"秘密武器"。与每次调用都启动新浏览器不同，gstack 维护一个**持久运行的 Chromium 守护进程**：

- **首次调用 ~3 秒**启动，后续调用 **~100-200ms**
- Cookie、登录态、localStorage **跨命令持久保存**
- 30 分钟空闲自动关闭，节省资源
- 本地 HTTP 服务器 + Bearer Token 认证，安全隔离

**技术栈：**
- Bun 运行时，编译为 ~58MB 独立二进制
- Playwright 控制 Chromium
- 随机端口（10000-60000），支持多工作区并行

### 2.3 Ref 引用系统（非 CSS 选择器）

gstack 不使用脆弱的 CSS 选择器操作页面元素，而是基于**无障碍树（Accessibility Tree）**建立引用：

```
snapshot 命令输出：
  @e1 [heading] "Welcome" [level=1]
  @e2 [textbox] "Email"
  @e3 [button] "Submit"

后续操作：
  click @e3    → 点击 Submit 按钮
  fill @e2 "test@example.com"  → 填写邮箱
```

- `@e1`, `@e2` 等是基于 Playwright Locator 的稳定引用，不需要修改 DOM
- 不会触发 CSP（Content Security Policy）问题
- 支持 SPA 过期检测

### 2.4 模板生成系统

SKILL.md 文件不是手写的，而是由 `.tmpl` 模板 + `gen-skill-docs.ts` 脚本**自动生成**的：

```
SKILL.md.tmpl （手工编写的模板）
    ↓  gen-skill-docs.ts 读取源码元数据
SKILL.md （自动生成，提交到 Git）
```

10 个模板变量从源码中提取真实数据：
- `{{COMMAND_REFERENCE}}` → 从 `commands.ts` 生成命令表
- `{{SNAPSHOT_FLAGS}}` → 从 `snapshot.ts` 生成快照标志
- `{{PREAMBLE}}` → 通用前置段（升级检查、会话追踪）
- `{{QA_METHODOLOGY}}` → 共享的 QA 测试方法论
- `{{DESIGN_METHODOLOGY}}` → 共享的设计审查方法论
- 等等...

这确保了**文档永远与代码同步**。

---

## 三、15 个 AI 专业技能（Skills）

### 3.1 规划阶段（Plan Review）

| 命令 | 角色 | 功能 |
|------|------|------|
| `/plan-ceo-review` | CEO/创始人 | 重新审视问题本质，寻找 10 倍产品机会。4 种模式：扩展、选择性扩展、保持范围、缩减范围 |
| `/plan-eng-review` | 工程经理 | 锁定架构、数据流、测试计划。每次只抛出一个问题，交互式审查 |
| `/plan-design-review` | 高级设计师 | 交互式设计审查（每个维度 0-10 评分），逐项修复至满分 |
| `/design-consultation` | 设计合伙人 | 从零构建完整设计系统，输出 DESIGN.md 和 HTML 预览页 |

**CEO 审查的 4 种模式**特别值得关注：
- **EXPANSION（扩展）**：放大思考，寻找 10 倍机会，需要用户明确同意
- **SELECTIVE EXPANSION（选择性扩展）**：保持范围，逐项提议扩展供用户选择
- **HOLD SCOPE（保持范围）**：最大严谨度，加固现有计划
- **SCOPE REDUCTION（缩减范围）**：无情削减到最小可行产品

### 3.2 测试与修复阶段（QA & Fix）

| 命令 | 角色 | 功能 |
|------|------|------|
| `/qa` | QA 主管 + 修复者 | 系统化测试应用并修复发现的 Bug，生成回归测试 |
| `/qa-only` | QA 报告员 | 仅测试和报告，**绝不修改代码** |
| `/design-review` | 设计师 + 编码者 | 对线上网站做设计审查，然后逐项修复 CSS/HTML |
| `/browse` | QA 工程师 | 底层浏览器操作，~50 个命令 |

`/qa` 的工作流程：
1. 分析 git diff 确定测试范围
2. 系统化浏览每个页面并截图
3. 交互测试（表单填写、按钮点击、边界测试）
4. 发现 Bug → 修复 → 原子化提交（`test(qa): ...`）
5. 自动生成回归测试
6. 输出详细报告，含前后对比截图

### 3.3 发布阶段（Ship & Post-Ship）

| 命令 | 角色 | 功能 |
|------|------|------|
| `/review` | Staff 工程师 | PR 代码审查：SQL 安全、竞态条件、LLM 信任边界、枚举完整性 |
| `/ship` | 发布工程师 | 全自动发布流程：测试→覆盖率→审查→版本号→CHANGELOG→提交→推送→创建 PR |
| `/document-release` | 技术写手 | 发布后文档更新：README、ARCHITECTURE、CONTRIBUTING、CLAUDE.md |
| `/retro` | 工程经理 | 周回顾：提交统计、测试健康度、工作模式分析 |

**`/ship` 是最复杂的 skill（165KB 模板），实现完全自动化发布：**
1. Pre-flight 检查（分支状态、未提交变更）
2. 合并基础分支（自动解决简单冲突）
3. 运行测试（Rails + Vitest 并行）
4. **测试覆盖率审计**（ASCII 图表展示代码路径覆盖）
5. **Pre-landing 代码审查**（调用 `/review` 工作流）
6. 版本号自动递增
7. CHANGELOG 自动生成
8. TODOS.md 自动更新
9. Bisect 提交（每个提交一个逻辑变更）
10. 推送并创建 PR（包含完整的审查报告）

### 3.4 辅助工具

| 命令 | 功能 |
|------|------|
| `/setup-browser-cookies` | 从 Chrome/Arc/Brave/Edge 导入 Cookie 到无头浏览器 |
| `/gstack-upgrade` | 检查和安装 gstack 更新 |

---

## 四、AI 能力深度解析

### 4.1 AI 作为虚拟团队

gstack 的核心创新在于**将不同的 AI prompt 策略映射为不同的专业角色**。每个角色内嵌了该领域大师的思维框架：

**CEO 模式内嵌的思维框架：**
- Bezos（单向门决策、Day 1 思维）
- Andy Grove（偏执危机感）
- Charlie Munger（逆向思维）
- Ben Horowitz（战时 CEO 意识）
- Chesky/Graham（创始人模式）
- Sam Altman（杠杆偏执）

**工程经理模式：**
- Will Larson（团队状态诊断）
- Tanya Reilly（boring by default）
- Fred Brooks（本质 vs 偶然复杂性）
- Kent Beck（让变更变得容易）

**设计师模式：**
- Dieter Rams（减法优先）
- Don Norman（设计的三个层次）
- Julie Zhuo（有原则的品味）
- Jony Ive（关怀是可见的）

这不是简单的 checklist——它通过"潜在空间激活"让 LLM 内化这些框架，使每次审查都成为一次真正的视角转换。

### 4.2 AI 驱动的浏览器自动化

gstack 让 AI Agent 能够**直接操作真实浏览器**，这远超传统的代码分析能力：

**~50 个浏览器命令分类：**

| 类别 | 命令示例 | 用途 |
|------|---------|------|
| 导航 | `goto`, `back`, `forward`, `reload` | 页面跳转 |
| 读取 | `text`, `html`, `links`, `forms`, `accessibility`, `console`, `network` | 提取页面信息 |
| 交互 | `click`, `fill`, `select`, `hover`, `type`, `press`, `scroll` | 模拟用户操作 |
| 视觉 | `screenshot`, `responsive`, `diff`, `pdf` | 截图/对比/响应式测试 |
| 检查 | `is`（visible/hidden/enabled/checked）, `cookies`, `storage`, `perf` | 状态断言 |
| 标签页 | `tabs`, `tab`, `newtab`, `closetab` | 多标签管理 |

**关键能力：**
- `snapshot -i` — 仅交互元素的无障碍树快照，让 AI 快速理解页面结构
- `responsive` — 一键在手机/平板/桌面三种视口下截图
- `diff` — 对比两次快照的差异（SPA 状态变化检测）
- `chain` — JSON 格式批量执行命令，减少往返次数
- `cookie-import-browser` — 从本地浏览器导入认证 Cookie，测试登录后页面

### 4.3 三层 AI 评估管道

gstack 拥有一套**用 AI 测试 AI 的完整评估体系**：

#### Tier 1：静态验证（免费，<1 秒）
- 验证 SKILL.md 中所有 `$B` 命令语法正确
- 检查 snapshot 标志合法性
- 确保生成文件与模板同步

#### Tier 2：端到端评估（~$3.85/运行）
- 通过 `claude -p` 子进程**完整运行 AI Agent 工作流**
- 实时流式输出 NDJSON 格式的工具调用
- 使用"植入 Bug"（planted bugs）的方式测试 QA 技能的 Bug 检出率
- 自动记录成本（美元）、token 用量、工具调用次数

#### Tier 3：LLM-as-Judge（~$0.15/运行）
- 使用 claude-sonnet-4-6 模型评估文档质量
- 三个评分维度：**清晰度、完整性、可操作性**（1-5 分）
- 对于 planted-bug 测试，评估：**检出率、误报数、证据质量**

#### 智能差异化测试选择
- 每个测试声明自己依赖的文件（touchfiles）
- 只运行受 `git diff` 影响的测试
- 全局 touchfile 变更（如 session-runner.ts）触发全量测试
- 大幅降低 CI 成本

### 4.4 完整性原则（Completeness Principle）

gstack 的核心哲学之一——贯穿所有 skill：

> 当 AI 辅助编码将实施时间压缩 10-100 倍时，始终推荐完整方案。边际成本几乎为零时，不要走捷径。

体现在：
- 计划审查会标记偷工减料的实现
- 全程展示双时间估算（人工团队时间 vs CC+gstack 时间）
- 测试覆盖率和边界情况默认追求完整
- 被推迟的工作会明确写入 TODOS.md

### 4.5 AI Slop（AI 垃圾风格）检测

设计审查中内置了**AI 生成内容的垃圾风格检测**：
- 紫色渐变背景
- 千篇一律的三栏布局
- 泛化的营销文案
- 过度使用的设计模式

这帮助团队避免 AI 生成的内容看起来像"AI 做的"。

### 4.6 交互式 AI 审查

所有审查 skill 都采用**结构化交互**模式：
- 每次只提出一个问题（绝不批量提问）
- 每个问题都有明确的上下文（项目名、分支名、当前步骤）
- 提供推荐选项并说明原因
- 通常只给 2-3 个选择，避免决策疲劳

---

## 五、安装与使用

### 5.1 安装（约 30 秒）

```bash
# 全局安装
git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack && ./setup

# 可选：为项目团队本地安装
cp -Rf ~/.claude/skills/gstack .claude/skills/gstack
rm -rf .claude/skills/gstack/.git
cd .claude/skills/gstack && ./setup
```

`setup` 脚本会：
1. 构建 browse 二进制（如需要）
2. 安装 Playwright Chromium
3. 创建 `~/.gstack` 全局状态目录
4. 建立技能符号链接

### 5.2 日常使用示例

一个完整的功能开发流程：

```
你：    我想给卖家添加照片上传功能。
你：    /plan-ceo-review
Claude: [提出 8 个扩展提议，附带努力/影响评估]

你：    /plan-design-review
Claude: 设计评分: B | AI Slop 评分: C
        [80 项设计审查，逐项修复至满分]

你：    /plan-eng-review
Claude: [架构图、测试矩阵、错误路径分析]

你：    [批准计划] → Claude 在 11 个文件中写入 2,400 行代码

你：    /review
Claude: [自动修复] 2 个问题 | [询问] 1 个竞态条件

你：    /qa https://staging.myapp.com
Claude: [发现并修复预览清除 Bug]
        [自动生成回归测试]

你：    /ship
Claude: 测试: 42 → 51 (+9 新增)
        覆盖率: 14/14 代码路径 (100%)
        PR: github.com/you/app/pull/42
```

**一个功能。七个命令。一整个虚拟团队。**

### 5.3 开发与测试命令

```bash
bun install              # 安装依赖
bun test                 # 免费测试（浏览器 + 快照 + 技能验证）
bun run test:evals       # 付费评估：LLM 判官 + 端到端
bun run test:e2e         # 仅端到端测试
bun run eval:select      # 预览差异化测试会选中哪些测试
bun run dev <cmd>        # 开发模式运行 CLI
bun run build            # 生成文档 + 编译二进制
bun run gen:skill-docs   # 重新生成 SKILL.md
bun run skill:check      # 技能健康仪表盘
```

---

## 六、项目目录结构

```
gstack/
├── browse/              # 无头浏览器 CLI + 服务器
│   ├── src/
│   │   ├── cli.ts       # CLI 入口
│   │   ├── server.ts    # Bun HTTP 服务器
│   │   ├── commands.ts  # 命令注册表（唯一真相源）
│   │   ├── snapshot.ts  # 无障碍树 + Ref 引用系统
│   │   └── browser-manager.ts  # Chromium 生命周期管理
│   ├── test/            # 166+ 集成测试
│   └── dist/browse      # 编译后的二进制
│
├── plan-ceo-review/     # CEO 审查 skill
├── plan-eng-review/     # 工程经理审查 skill
├── plan-design-review/  # 设计审查 skill（计划阶段）
├── design-consultation/ # 设计系统构建 skill
├── design-review/       # 设计审查 + 修复 skill（线上）
├── review/              # 代码审查 skill
├── ship/                # 发布流程 skill（165KB 模板）
├── qa/                  # QA 测试 + 修复 skill
├── qa-only/             # QA 仅报告 skill
├── retro/               # 周回顾 skill
├── document-release/    # 发布后文档更新 skill
├── setup-browser-cookies/ # Cookie 导入 skill
├── gstack-upgrade/      # 升级 skill
│
├── scripts/
│   ├── gen-skill-docs.ts    # 模板 → SKILL.md 生成器
│   ├── skill-check.ts       # 健康仪表盘
│   └── dev-skill.ts         # 开发模式（文件监视）
│
├── test/
│   ├── helpers/
│   │   ├── session-runner.ts  # 端到端子进程编排
│   │   ├── llm-judge.ts       # LLM-as-Judge 评估
│   │   ├── eval-store.ts      # 评估结果持久化 + 对比
│   │   └── touchfiles.ts      # 差异化测试选择
│   ├── skill-validation.test.ts  # Tier 1: 静态验证
│   ├── skill-e2e.test.ts         # Tier 2: 端到端评估
│   └── skill-llm-eval.test.ts    # Tier 3: LLM 判官
│
├── bin/                 # 工具脚本
├── SKILL.md.tmpl        # 根技能模板
├── SKILL.md             # 自动生成（勿直接编辑）
├── CLAUDE.md            # 开发指引
├── CHANGELOG.md         # 版本历史
└── package.json         # Bun 项目配置
```

---

## 七、核心设计理念总结

1. **角色化 AI**：不是一个万能 Agent，而是 15 个专精角色，各有方法论
2. **持久浏览器**：守护进程模式带来亚秒级响应和状态持久
3. **代码即文档**：模板系统保证文档永远与代码一致
4. **AI 测试 AI**：三层评估管道确保 skill 质量
5. **完整性优先**：AI 压缩了实施成本，因此永远选择完整方案
6. **交互式审查**：一次一个问题，减少认知负荷
7. **开箱即用**：30 秒安装，一个命令就能调用整个虚拟团队


node "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js" "pre:write:doc-file-warning" "scripts/hooks/doc-file-warning.js" "standard,strict"


node "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js" "pre:edit-write:suggest-compact" "scripts/hooks/suggest-compact.js" "standard,strict"


bash "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags-shell.sh" "pre:observe" "skills/continuous-learning-v2/hooks/observe.sh" "standard,strict"


node "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js" "pre:insaits-security" "scripts/hooks/insaits-security-wrapper.js" "standard,strict"


node "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js" "post:quality-gate" "scripts/hooks/quality-gate.js" "standard,strict"


bash "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags-shell.sh" "post:observe" "skills/continuous-learning-v2/hooks/observe.sh" "standard,strict"


File created successfully at: /root/.claude/plans/typed-twirling-raccoon.md

# gstack 项目详细文档

> **注意：这不是一个实施计划，而是用户要求的项目分析文档。**

---

## 一、项目概述

**gstack** 是由 Y Combinator 总裁兼 CEO Garry Tan 开源的 **AI 工程工作流系统**，构建在 Claude Code 之上。它将 Claude Code 从一个通用 AI 编程助手，转变为一个拥有 **15 个专业角色**的虚拟工程团队——CEO、工程经理、设计师、QA 主管、发布工程师等，全部通过斜杠命令（slash commands）调用。

**核心理念：** 用结构化的角色分工取代泛化的 AI 对话。每个 skill 都是一套完整的方法论，有明确的输入、输出和流程。

**关键数据：**
- MIT 开源协议，完全免费
- 作者声称使用 gstack 每天可产出 10,000-20,000 行可用代码
- 60 天内产出 600,000+ 行代码（35% 为测试代码）
- 效率压缩比：模板代码 ~100x、测试 ~50x、功能开发 ~30x、Bug 修复 ~20x
- 当前版本 v0.6.4（2026 年 3 月）

---

## 二、核心架构

### 2.1 整体架构图

```
用户 → Claude Code → /skill 命令 → SKILL.md prompt → AI Agent 执行
                         ↓
                    browse 二进制 → HTTP 请求 → Bun 服务器 → Chromium 浏览器（持久守护进程）
```

gstack 由两大核心组件构成：

1. **Skill 系统**：15 个 Markdown 格式的 prompt 模板，每个代表一个专业角色
2. **Browse 浏览器引擎**：基于 Playwright 的无头浏览器守护进程，提供 ~50 个命令

### 2.2 Browse 浏览器守护进程

这是 gstack 的"秘密武器"。与每次调用都启动新浏览器不同，gstack 维护一个**持久运行的 Chromium 守护进程**：

- **首次调用 ~3 秒**启动，后续调用 **~100-200ms**
- Cookie、登录态、localStorage **跨命令持久保存**
- 30 分钟空闲自动关闭，节省资源
- 本地 HTTP 服务器 + Bearer Token 认证，安全隔离

**技术栈：**
- Bun 运行时，编译为 ~58MB 独立二进制
- Playwright 控制 Chromium
- 随机端口（10000-60000），支持多工作区并行

### 2.3 Ref 引用系统（非 CSS 选择器）

gstack 不使用脆弱的 CSS 选择器操作页面元素，而是基于**无障碍树（Accessibility Tree）**建立引用：

```
snapshot 命令输出：
  @e1 [heading] "Welcome" [level=1]
  @e2 [textbox] "Email"
  @e3 [button] "Submit"

后续操作：
  click @e3    → 点击 Submit 按钮
  fill @e2 "test@example.com"  → 填写邮箱
```

- `@e1`, `@e2` 等是基于 Playwright Locator 的稳定引用，不需要修改 DOM
- 不会触发 CSP（Content Security Policy）问题
- 支持 SPA 过期检测

### 2.4 模板生成系统

SKILL.md 文件不是手写的，而是由 `.tmpl` 模板 + `gen-skill-docs.ts` 脚本**自动生成**的：

```
SKILL.md.tmpl （手工编写的模板）
    ↓  gen-skill-docs.ts 读取源码元数据
SKILL.md （自动生成，提交到 Git）
```

10 个模板变量从源码中提取真实数据：
- `{{COMMAND_REFERENCE}}` → 从 `commands.ts` 生成命令表
- `{{SNAPSHOT_FLAGS}}` → 从 `snapshot.ts` 生成快照标志
- `{{PREAMBLE}}` → 通用前置段（升级检查、会话追踪）
- `{{QA_METHODOLOGY}}` → 共享的 QA 测试方法论
- `{{DESIGN_METHODOLOGY}}` → 共享的设计审查方法论
- 等等...

这确保了**文档永远与代码同步**。

---

## 三、15 个 AI 专业技能（Skills）

### 3.1 规划阶段（Plan Review）

| 命令 | 角色 | 功能 |
|------|------|------|
| `/plan-ceo-review` | CEO/创始人 | 重新审视问题本质，寻找 10 倍产品机会。4 种模式：扩展、选择性扩展、保持范围、缩减范围 |
| `/plan-eng-review` | 工程经理 | 锁定架构、数据流、测试计划。每次只抛出一个问题，交互式审查 |
| `/plan-design-review` | 高级设计师 | 交互式设计审查（每个维度 0-10 评分），逐项修复至满分 |
| `/design-consultation` | 设计合伙人 | 从零构建完整设计系统，输出 DESIGN.md 和 HTML 预览页 |

**CEO 审查的 4 种模式**特别值得关注：
- **EXPANSION（扩展）**：放大思考，寻找 10 倍机会，需要用户明确同意
- **SELECTIVE EXPANSION（选择性扩展）**：保持范围，逐项提议扩展供用户选择
- **HOLD SCOPE（保持范围）**：最大严谨度，加固现有计划
- **SCOPE REDUCTION（缩减范围）**：无情削减到最小可行产品

### 3.2 测试与修复阶段（QA & Fix）

| 命令 | 角色 | 功能 |
|------|------|------|
| `/qa` | QA 主管 + 修复者 | 系统化测试应用并修复发现的 Bug，生成回归测试 |
| `/qa-only` | QA 报告员 | 仅测试和报告，**绝不修改代码** |
| `/design-review` | 设计师 + 编码者 | 对线上网站做设计审查，然后逐项修复 CSS/HTML |
| `/browse` | QA 工程师 | 底层浏览器操作，~50 个命令 |

`/qa` 的工作流程：
1. 分析 git diff 确定测试范围
2. 系统化浏览每个页面并截图
3. 交互测试（表单填写、按钮点击、边界测试）
4. 发现 Bug → 修复 → 原子化提交（`test(qa): ...`）
5. 自动生成回归测试
6. 输出详细报告，含前后对比截图

### 3.3 发布阶段（Ship & Post-Ship）

| 命令 | 角色 | 功能 |
|------|------|------|
| `/review` | Staff 工程师 | PR 代码审查：SQL 安全、竞态条件、LLM 信任边界、枚举完整性 |
| `/ship` | 发布工程师 | 全自动发布流程：测试→覆盖率→审查→版本号→CHANGELOG→提交→推送→创建 PR |
| `/document-release` | 技术写手 | 发布后文档更新：README、ARCHITECTURE、CONTRIBUTING、CLAUDE.md |
| `/retro` | 工程经理 | 周回顾：提交统计、测试健康度、工作模式分析 |

**`/ship` 是最复杂的 skill（165KB 模板），实现完全自动化发布：**
1. Pre-flight 检查（分支状态、未提交变更）
2. 合并基础分支（自动解决简单冲突）
3. 运行测试（Rails + Vitest 并行）
4. **测试覆盖率审计**（ASCII 图表展示代码路径覆盖）
5. **Pre-landing 代码审查**（调用 `/review` 工作流）
6. 版本号自动递增
7. CHANGELOG 自动生成
8. TODOS.md 自动更新
9. Bisect 提交（每个提交一个逻辑变更）
10. 推送并创建 PR（包含完整的审查报告）

### 3.4 辅助工具

| 命令 | 功能 |
|------|------|
| `/setup-browser-cookies` | 从 Chrome/Arc/Brave/Edge 导入 Cookie 到无头浏览器 |
| `/gstack-upgrade` | 检查和安装 gstack 更新 |

---

## 四、AI 能力深度解析

### 4.1 AI 作为虚拟团队

gstack 的核心创新在于**将不同的 AI prompt 策略映射为不同的专业角色**。每个角色内嵌了该领域大师的思维框架：

**CEO 模式内嵌的思维框架：**
- Bezos（单向门决策、Day 1 思维）
- Andy Grove（偏执危机感）
- Charlie Munger（逆向思维）
- Ben Horowitz（战时 CEO 意识）
- Chesky/Graham（创始人模式）
- Sam Altman（杠杆偏执）

**工程经理模式：**
- Will Larson（团队状态诊断）
- Tanya Reilly（boring by default）
- Fred Brooks（本质 vs 偶然复杂性）
- Kent Beck（让变更变得容易）

**设计师模式：**
- Dieter Rams（减法优先）
- Don Norman（设计的三个层次）
- Julie Zhuo（有原则的品味）
- Jony Ive（关怀是可见的）

这不是简单的 checklist——它通过"潜在空间激活"让 LLM 内化这些框架，使每次审查都成为一次真正的视角转换。

### 4.2 AI 驱动的浏览器自动化

gstack 让 AI Agent 能够**直接操作真实浏览器**，这远超传统的代码分析能力：

**~50 个浏览器命令分类：**

| 类别 | 命令示例 | 用途 |
|------|---------|------|
| 导航 | `goto`, `back`, `forward`, `reload` | 页面跳转 |
| 读取 | `text`, `html`, `links`, `forms`, `accessibility`, `console`, `network` | 提取页面信息 |
| 交互 | `click`, `fill`, `select`, `hover`, `type`, `press`, `scroll` | 模拟用户操作 |
| 视觉 | `screenshot`, `responsive`, `diff`, `pdf` | 截图/对比/响应式测试 |
| 检查 | `is`（visible/hidden/enabled/checked）, `cookies`, `storage`, `perf` | 状态断言 |
| 标签页 | `tabs`, `tab`, `newtab`, `closetab` | 多标签管理 |

**关键能力：**
- `snapshot -i` — 仅交互元素的无障碍树快照，让 AI 快速理解页面结构
- `responsive` — 一键在手机/平板/桌面三种视口下截图
- `diff` — 对比两次快照的差异（SPA 状态变化检测）
- `chain` — JSON 格式批量执行命令，减少往返次数
- `cookie-import-browser` — 从本地浏览器导入认证 Cookie，测试登录后页面

### 4.3 三层 AI 评估管道

gstack 拥有一套**用 AI 测试 AI 的完整评估体系**：

#### Tier 1：静态验证（免费，<1 秒）
- 验证 SKILL.md 中所有 `$B` 命令语法正确
- 检查 snapshot 标志合法性
- 确保生成文件与模板同步

#### Tier 2：端到端评估（~$3.85/运行）
- 通过 `claude -p` 子进程**完整运行 AI Agent 工作流**
- 实时流式输出 NDJSON 格式的工具调用
- 使用"植入 Bug"（planted bugs）的方式测试 QA 技能的 Bug 检出率
- 自动记录成本（美元）、token 用量、工具调用次数

#### Tier 3：LLM-as-Judge（~$0.15/运行）
- 使用 claude-sonnet-4-6 模型评估文档质量
- 三个评分维度：**清晰度、完整性、可操作性**（1-5 分）
- 对于 planted-bug 测试，评估：**检出率、误报数、证据质量**

#### 智能差异化测试选择
- 每个测试声明自己依赖的文件（touchfiles）
- 只运行受 `git diff` 影响的测试
- 全局 touchfile 变更（如 session-runner.ts）触发全量测试
- 大幅降低 CI 成本

### 4.4 完整性原则（Completeness Principle）

gstack 的核心哲学之一——贯穿所有 skill：

> 当 AI 辅助编码将实施时间压缩 10-100 倍时，始终推荐完整方案。边际成本几乎为零时，不要走捷径。

体现在：
- 计划审查会标记偷工减料的实现
- 全程展示双时间估算（人工团队时间 vs CC+gstack 时间）
- 测试覆盖率和边界情况默认追求完整
- 被推迟的工作会明确写入 TODOS.md

### 4.5 AI Slop（AI 垃圾风格）检测

设计审查中内置了**AI 生成内容的垃圾风格检测**：
- 紫色渐变背景
- 千篇一律的三栏布局
- 泛化的营销文案
- 过度使用的设计模式

这帮助团队避免 AI 生成的内容看起来像"AI 做的"。

### 4.6 交互式 AI 审查

所有审查 skill 都采用**结构化交互**模式：
- 每次只提出一个问题（绝不批量提问）
- 每个问题都有明确的上下文（项目名、分支名、当前步骤）
- 提供推荐选项并说明原因
- 通常只给 2-3 个选择，避免决策疲劳

---

## 五、安装与使用

### 5.1 安装（约 30 秒）

```bash
# 全局安装
git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack && ./setup

# 可选：为项目团队本地安装
cp -Rf ~/.claude/skills/gstack .claude/skills/gstack
rm -rf .claude/skills/gstack/.git
cd .claude/skills/gstack && ./setup
```

`setup` 脚本会：
1. 构建 browse 二进制（如需要）
2. 安装 Playwright Chromium
3. 创建 `~/.gstack` 全局状态目录
4. 建立技能符号链接

### 5.2 日常使用示例

一个完整的功能开发流程：

```
你：    我想给卖家添加照片上传功能。
你：    /plan-ceo-review
Claude: [提出 8 个扩展提议，附带努力/影响评估]

你：    /plan-design-review
Claude: 设计评分: B | AI Slop 评分: C
        [80 项设计审查，逐项修复至满分]

你：    /plan-eng-review
Claude: [架构图、测试矩阵、错误路径分析]

你：    [批准计划] → Claude 在 11 个文件中写入 2,400 行代码

你：    /review
Claude: [自动修复] 2 个问题 | [询问] 1 个竞态条件

你：    /qa https://staging.myapp.com
Claude: [发现并修复预览清除 Bug]
        [自动生成回归测试]

你：    /ship
Claude: 测试: 42 → 51 (+9 新增)
        覆盖率: 14/14 代码路径 (100%)
        PR: github.com/you/app/pull/42
```

**一个功能。七个命令。一整个虚拟团队。**

### 5.3 开发与测试命令

```bash
bun install              # 安装依赖
bun test                 # 免费测试（浏览器 + 快照 + 技能验证）
bun run test:evals       # 付费评估：LLM 判官 + 端到端
bun run test:e2e         # 仅端到端测试
bun run eval:select      # 预览差异化测试会选中哪些测试
bun run dev <cmd>        # 开发模式运行 CLI
bun run build            # 生成文档 + 编译二进制
bun run gen:skill-docs   # 重新生成 SKILL.md
bun run skill:check      # 技能健康仪表盘
```

---

## 六、项目目录结构

```
gstack/
├── browse/              # 无头浏览器 CLI + 服务器
│   ├── src/
│   │   ├── cli.ts       # CLI 入口
│   │   ├── server.ts    # Bun HTTP 服务器
│   │   ├── commands.ts  # 命令注册表（唯一真相源）
│   │   ├── snapshot.ts  # 无障碍树 + Ref 引用系统
│   │   └── browser-manager.ts  # Chromium 生命周期管理
│   ├── test/            # 166+ 集成测试
│   └── dist/browse      # 编译后的二进制
│
├── plan-ceo-review/     # CEO 审查 skill
├── plan-eng-review/     # 工程经理审查 skill
├── plan-design-review/  # 设计审查 skill（计划阶段）
├── design-consultation/ # 设计系统构建 skill
├── design-review/       # 设计审查 + 修复 skill（线上）
├── review/              # 代码审查 skill
├── ship/                # 发布流程 skill（165KB 模板）
├── qa/                  # QA 测试 + 修复 skill
├── qa-only/             # QA 仅报告 skill
├── retro/               # 周回顾 skill
├── document-release/    # 发布后文档更新 skill
├── setup-browser-cookies/ # Cookie 导入 skill
├── gstack-upgrade/      # 升级 skill
│
├── scripts/
│   ├── gen-skill-docs.ts    # 模板 → SKILL.md 生成器
│   ├── skill-check.ts       # 健康仪表盘
│   └── dev-skill.ts         # 开发模式（文件监视）
│
├── test/
│   ├── helpers/
│   │   ├── session-runner.ts  # 端到端子进程编排
│   │   ├── llm-judge.ts       # LLM-as-Judge 评估
│   │   ├── eval-store.ts      # 评估结果持久化 + 对比
│   │   └── touchfiles.ts      # 差异化测试选择
│   ├── skill-validation.test.ts  # Tier 1: 静态验证
│   ├── skill-e2e.test.ts         # Tier 2: 端到端评估
│   └── skill-llm-eval.test.ts    # Tier 3: LLM 判官
│
├── bin/                 # 工具脚本
├── SKILL.md.tmpl        # 根技能模板
├── SKILL.md             # 自动生成（勿直接编辑）
├── CLAUDE.md            # 开发指引
├── CHANGELOG.md         # 版本历史
└── package.json         # Bun 项目配置
```

---

## 七、核心设计理念总结

1. **角色化 AI**：不是一个万能 Agent，而是 15 个专精角色，各有方法论
2. **持久浏览器**：守护进程模式带来亚秒级响应和状态持久
3. **代码即文档**：模板系统保证文档永远与代码一致
4. **AI 测试 AI**：三层评估管道确保 skill 质量
5. **完整性优先**：AI 压缩了实施成本，因此永远选择完整方案
6. **交互式审查**：一次一个问题，减少认知负荷
7. **开箱即用**：30 秒安装，一个命令就能调用整个虚拟团队


文档已撰写完成，涵盖了以下内容：

**项目目标**：将 Claude Code 转化为拥有 15 个专业角色的虚拟工程团队

**工作原理**：
- 持久化 Chromium 浏览器守护进程（亚秒级响应）
- 基于无障碍树的 Ref 引用系统（取代脆弱的 CSS 选择器）
- 模板生成系统（代码即文档，永远同步）
- 三层 AI 评估管道（静态验证 → 端到端 → LLM 判官）

**15 个 AI 技能**：按规划→测试→发布→回顾四个阶段详细说明

**AI 能力深度解析**：
- 内嵌大师思维框架的角色化 AI
- ~50 个浏览器自动化命令
- AI Slop 垃圾风格检测
- 完整性原则（边际成本为零时不走捷径）
- 智能差异化测试选择


ExitPlanMode

# gstack 项目详细文档

> **注意：这不是一个实施计划，而是用户要求的项目分析文档。**

---

## 一、项目概述

**gstack** 是由 Y Combinator 总裁兼 CEO Garry Tan 开源的 **AI 工程工作流系统**，构建在 Claude Code 之上。它将 Claude Code 从一个通用 AI 编程助手，转变为一个拥有 **15 个专业角色**的虚拟工程团队——CEO、工程经理、设计师、QA 主管、发布工程师等，全部通过斜杠命令（slash commands）调用。

**核心理念：** 用结构化的角色分工取代泛化的 AI 对话。每个 skill 都是一套完整的方法论，有明确的输入、输出和流程。

**关键数据：**
- MIT 开源协议，完全免费
- 作者声称使用 gstack 每天可产出 10,000-20,000 行可用代码
- 60 天内产出 600,000+ 行代码（35% 为测试代码）
- 效率压缩比：模板代码 ~100x、测试 ~50x、功能开发 ~30x、Bug 修复 ~20x
- 当前版本 v0.6.4（2026 年 3 月）

---

## 二、核心架构

### 2.1 整体架构图

```
用户 → Claude Code → /skill 命令 → SKILL.md prompt → AI Agent 执行
                         ↓
                    browse 二进制 → HTTP 请求 → Bun 服务器 → Chromium 浏览器（持久守护进程）
```

gstack 由两大核心组件构成：

1. **Skill 系统**：15 个 Markdown 格式的 prompt 模板，每个代表一个专业角色
2. **Browse 浏览器引擎**：基于 Playwright 的无头浏览器守护进程，提供 ~50 个命令

### 2.2 Browse 浏览器守护进程

这是 gstack 的"秘密武器"。与每次调用都启动新浏览器不同，gstack 维护一个**持久运行的 Chromium 守护进程**：

- **首次调用 ~3 秒**启动，后续调用 **~100-200ms**
- Cookie、登录态、localStorage **跨命令持久保存**
- 30 分钟空闲自动关闭，节省资源
- 本地 HTTP 服务器 + Bearer Token 认证，安全隔离

**技术栈：**
- Bun 运行时，编译为 ~58MB 独立二进制
- Playwright 控制 Chromium
- 随机端口（10000-60000），支持多工作区并行

### 2.3 Ref 引用系统（非 CSS 选择器）

gstack 不使用脆弱的 CSS 选择器操作页面元素，而是基于**无障碍树（Accessibility Tree）**建立引用：

```
snapshot 命令输出：
  @e1 [heading] "Welcome" [level=1]
  @e2 [textbox] "Email"
  @e3 [button] "Submit"

后续操作：
  click @e3    → 点击 Submit 按钮
  fill @e2 "test@example.com"  → 填写邮箱
```

- `@e1`, `@e2` 等是基于 Playwright Locator 的稳定引用，不需要修改 DOM
- 不会触发 CSP（Content Security Policy）问题
- 支持 SPA 过期检测

### 2.4 模板生成系统

SKILL.md 文件不是手写的，而是由 `.tmpl` 模板 + `gen-skill-docs.ts` 脚本**自动生成**的：

```
SKILL.md.tmpl （手工编写的模板）
    ↓  gen-skill-docs.ts 读取源码元数据
SKILL.md （自动生成，提交到 Git）
```

10 个模板变量从源码中提取真实数据：
- `{{COMMAND_REFERENCE}}` → 从 `commands.ts` 生成命令表
- `{{SNAPSHOT_FLAGS}}` → 从 `snapshot.ts` 生成快照标志
- `{{PREAMBLE}}` → 通用前置段（升级检查、会话追踪）
- `{{QA_METHODOLOGY}}` → 共享的 QA 测试方法论
- `{{DESIGN_METHODOLOGY}}` → 共享的设计审查方法论
- 等等...

这确保了**文档永远与代码同步**。

---

## 三、15 个 AI 专业技能（Skills）

### 3.1 规划阶段（Plan Review）

| 命令 | 角色 | 功能 |
|------|------|------|
| `/plan-ceo-review` | CEO/创始人 | 重新审视问题本质，寻找 10 倍产品机会。4 种模式：扩展、选择性扩展、保持范围、缩减范围 |
| `/plan-eng-review` | 工程经理 | 锁定架构、数据流、测试计划。每次只抛出一个问题，交互式审查 |
| `/plan-design-review` | 高级设计师 | 交互式设计审查（每个维度 0-10 评分），逐项修复至满分 |
| `/design-consultation` | 设计合伙人 | 从零构建完整设计系统，输出 DESIGN.md 和 HTML 预览页 |

**CEO 审查的 4 种模式**特别值得关注：
- **EXPANSION（扩展）**：放大思考，寻找 10 倍机会，需要用户明确同意
- **SELECTIVE EXPANSION（选择性扩展）**：保持范围，逐项提议扩展供用户选择
- **HOLD SCOPE（保持范围）**：最大严谨度，加固现有计划
- **SCOPE REDUCTION（缩减范围）**：无情削减到最小可行产品

### 3.2 测试与修复阶段（QA & Fix）

| 命令 | 角色 | 功能 |
|------|------|------|
| `/qa` | QA 主管 + 修复者 | 系统化测试应用并修复发现的 Bug，生成回归测试 |
| `/qa-only` | QA 报告员 | 仅测试和报告，**绝不修改代码** |
| `/design-review` | 设计师 + 编码者 | 对线上网站做设计审查，然后逐项修复 CSS/HTML |
| `/browse` | QA 工程师 | 底层浏览器操作，~50 个命令 |

`/qa` 的工作流程：
1. 分析 git diff 确定测试范围
2. 系统化浏览每个页面并截图
3. 交互测试（表单填写、按钮点击、边界测试）
4. 发现 Bug → 修复 → 原子化提交（`test(qa): ...`）
5. 自动生成回归测试
6. 输出详细报告，含前后对比截图

### 3.3 发布阶段（Ship & Post-Ship）

| 命令 | 角色 | 功能 |
|------|------|------|
| `/review` | Staff 工程师 | PR 代码审查：SQL 安全、竞态条件、LLM 信任边界、枚举完整性 |
| `/ship` | 发布工程师 | 全自动发布流程：测试→覆盖率→审查→版本号→CHANGELOG→提交→推送→创建 PR |
| `/document-release` | 技术写手 | 发布后文档更新：README、ARCHITECTURE、CONTRIBUTING、CLAUDE.md |
| `/retro` | 工程经理 | 周回顾：提交统计、测试健康度、工作模式分析 |

**`/ship` 是最复杂的 skill（165KB 模板），实现完全自动化发布：**
1. Pre-flight 检查（分支状态、未提交变更）
2. 合并基础分支（自动解决简单冲突）
3. 运行测试（Rails + Vitest 并行）
4. **测试覆盖率审计**（ASCII 图表展示代码路径覆盖）
5. **Pre-landing 代码审查**（调用 `/review` 工作流）
6. 版本号自动递增
7. CHANGELOG 自动生成
8. TODOS.md 自动更新
9. Bisect 提交（每个提交一个逻辑变更）
10. 推送并创建 PR（包含完整的审查报告）

### 3.4 辅助工具

| 命令 | 功能 |
|------|------|
| `/setup-browser-cookies` | 从 Chrome/Arc/Brave/Edge 导入 Cookie 到无头浏览器 |
| `/gstack-upgrade` | 检查和安装 gstack 更新 |

---

## 四、AI 能力深度解析

### 4.1 AI 作为虚拟团队

gstack 的核心创新在于**将不同的 AI prompt 策略映射为不同的专业角色**。每个角色内嵌了该领域大师的思维框架：

**CEO 模式内嵌的思维框架：**
- Bezos（单向门决策、Day 1 思维）
- Andy Grove（偏执危机感）
- Charlie Munger（逆向思维）
- Ben Horowitz（战时 CEO 意识）
- Chesky/Graham（创始人模式）
- Sam Altman（杠杆偏执）

**工程经理模式：**
- Will Larson（团队状态诊断）
- Tanya Reilly（boring by default）
- Fred Brooks（本质 vs 偶然复杂性）
- Kent Beck（让变更变得容易）

**设计师模式：**
- Dieter Rams（减法优先）
- Don Norman（设计的三个层次）
- Julie Zhuo（有原则的品味）
- Jony Ive（关怀是可见的）

这不是简单的 checklist——它通过"潜在空间激活"让 LLM 内化这些框架，使每次审查都成为一次真正的视角转换。

### 4.2 AI 驱动的浏览器自动化

gstack 让 AI Agent 能够**直接操作真实浏览器**，这远超传统的代码分析能力：

**~50 个浏览器命令分类：**

| 类别 | 命令示例 | 用途 |
|------|---------|------|
| 导航 | `goto`, `back`, `forward`, `reload` | 页面跳转 |
| 读取 | `text`, `html`, `links`, `forms`, `accessibility`, `console`, `network` | 提取页面信息 |
| 交互 | `click`, `fill`, `select`, `hover`, `type`, `press`, `scroll` | 模拟用户操作 |
| 视觉 | `screenshot`, `responsive`, `diff`, `pdf` | 截图/对比/响应式测试 |
| 检查 | `is`（visible/hidden/enabled/checked）, `cookies`, `storage`, `perf` | 状态断言 |
| 标签页 | `tabs`, `tab`, `newtab`, `closetab` | 多标签管理 |

**关键能力：**
- `snapshot -i` — 仅交互元素的无障碍树快照，让 AI 快速理解页面结构
- `responsive` — 一键在手机/平板/桌面三种视口下截图
- `diff` — 对比两次快照的差异（SPA 状态变化检测）
- `chain` — JSON 格式批量执行命令，减少往返次数
- `cookie-import-browser` — 从本地浏览器导入认证 Cookie，测试登录后页面

### 4.3 三层 AI 评估管道

gstack 拥有一套**用 AI 测试 AI 的完整评估体系**：

#### Tier 1：静态验证（免费，<1 秒）
- 验证 SKILL.md 中所有 `$B` 命令语法正确
- 检查 snapshot 标志合法性
- 确保生成文件与模板同步

#### Tier 2：端到端评估（~$3.85/运行）
- 通过 `claude -p` 子进程**完整运行 AI Agent 工作流**
- 实时流式输出 NDJSON 格式的工具调用
- 使用"植入 Bug"（planted bugs）的方式测试 QA 技能的 Bug 检出率
- 自动记录成本（美元）、token 用量、工具调用次数

#### Tier 3：LLM-as-Judge（~$0.15/运行）
- 使用 claude-sonnet-4-6 模型评估文档质量
- 三个评分维度：**清晰度、完整性、可操作性**（1-5 分）
- 对于 planted-bug 测试，评估：**检出率、误报数、证据质量**

#### 智能差异化测试选择
- 每个测试声明自己依赖的文件（touchfiles）
- 只运行受 `git diff` 影响的测试
- 全局 touchfile 变更（如 session-runner.ts）触发全量测试
- 大幅降低 CI 成本

### 4.4 完整性原则（Completeness Principle）

gstack 的核心哲学之一——贯穿所有 skill：

> 当 AI 辅助编码将实施时间压缩 10-100 倍时，始终推荐完整方案。边际成本几乎为零时，不要走捷径。

体现在：
- 计划审查会标记偷工减料的实现
- 全程展示双时间估算（人工团队时间 vs CC+gstack 时间）
- 测试覆盖率和边界情况默认追求完整
- 被推迟的工作会明确写入 TODOS.md

### 4.5 AI Slop（AI 垃圾风格）检测

设计审查中内置了**AI 生成内容的垃圾风格检测**：
- 紫色渐变背景
- 千篇一律的三栏布局
- 泛化的营销文案
- 过度使用的设计模式

这帮助团队避免 AI 生成的内容看起来像"AI 做的"。

### 4.6 交互式 AI 审查

所有审查 skill 都采用**结构化交互**模式：
- 每次只提出一个问题（绝不批量提问）
- 每个问题都有明确的上下文（项目名、分支名、当前步骤）
- 提供推荐选项并说明原因
- 通常只给 2-3 个选择，避免决策疲劳

---

## 五、安装与使用

### 5.1 安装（约 30 秒）

```bash
# 全局安装
git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack && ./setup

# 可选：为项目团队本地安装
cp -Rf ~/.claude/skills/gstack .claude/skills/gstack
rm -rf .claude/skills/gstack/.git
cd .claude/skills/gstack && ./setup
```

`setup` 脚本会：
1. 构建 browse 二进制（如需要）
2. 安装 Playwright Chromium
3. 创建 `~/.gstack` 全局状态目录
4. 建立技能符号链接

### 5.2 日常使用示例

一个完整的功能开发流程：

```
你：    我想给卖家添加照片上传功能。
你：    /plan-ceo-review
Claude: [提出 8 个扩展提议，附带努力/影响评估]

你：    /plan-design-review
Claude: 设计评分: B | AI Slop 评分: C
        [80 项设计审查，逐项修复至满分]

你：    /plan-eng-review
Claude: [架构图、测试矩阵、错误路径分析]

你：    [批准计划] → Claude 在 11 个文件中写入 2,400 行代码

你：    /review
Claude: [自动修复] 2 个问题 | [询问] 1 个竞态条件

你：    /qa https://staging.myapp.com
Claude: [发现并修复预览清除 Bug]
        [自动生成回归测试]

你：    /ship
Claude: 测试: 42 → 51 (+9 新增)
        覆盖率: 14/14 代码路径 (100%)
        PR: github.com/you/app/pull/42
```

**一个功能。七个命令。一整个虚拟团队。**

### 5.3 开发与测试命令

```bash
bun install              # 安装依赖
bun test                 # 免费测试（浏览器 + 快照 + 技能验证）
bun run test:evals       # 付费评估：LLM 判官 + 端到端
bun run test:e2e         # 仅端到端测试
bun run eval:select      # 预览差异化测试会选中哪些测试
bun run dev <cmd>        # 开发模式运行 CLI
bun run build            # 生成文档 + 编译二进制
bun run gen:skill-docs   # 重新生成 SKILL.md
bun run skill:check      # 技能健康仪表盘
```

---

## 六、项目目录结构

```
gstack/
├── browse/              # 无头浏览器 CLI + 服务器
│   ├── src/
│   │   ├── cli.ts       # CLI 入口
│   │   ├── server.ts    # Bun HTTP 服务器
│   │   ├── commands.ts  # 命令注册表（唯一真相源）
│   │   ├── snapshot.ts  # 无障碍树 + Ref 引用系统
│   │   └── browser-manager.ts  # Chromium 生命周期管理
│   ├── test/            # 166+ 集成测试
│   └── dist/browse      # 编译后的二进制
│
├── plan-ceo-review/     # CEO 审查 skill
├── plan-eng-review/     # 工程经理审查 skill
├── plan-design-review/  # 设计审查 skill（计划阶段）
├── design-consultation/ # 设计系统构建 skill
├── design-review/       # 设计审查 + 修复 skill（线上）
├── review/              # 代码审查 skill
├── ship/                # 发布流程 skill（165KB 模板）
├── qa/                  # QA 测试 + 修复 skill
├── qa-only/             # QA 仅报告 skill
├── retro/               # 周回顾 skill
├── document-release/    # 发布后文档更新 skill
├── setup-browser-cookies/ # Cookie 导入 skill
├── gstack-upgrade/      # 升级 skill
│
├── scripts/
│   ├── gen-skill-docs.ts    # 模板 → SKILL.md 生成器
│   ├── skill-check.ts       # 健康仪表盘
│   └── dev-skill.ts         # 开发模式（文件监视）
│
├── test/
│   ├── helpers/
│   │   ├── session-runner.ts  # 端到端子进程编排
│   │   ├── llm-judge.ts       # LLM-as-Judge 评估
│   │   ├── eval-store.ts      # 评估结果持久化 + 对比
│   │   └── touchfiles.ts      # 差异化测试选择
│   ├── skill-validation.test.ts  # Tier 1: 静态验证
│   ├── skill-e2e.test.ts         # Tier 2: 端到端评估
│   └── skill-llm-eval.test.ts    # Tier 3: LLM 判官
│
├── bin/                 # 工具脚本
├── SKILL.md.tmpl        # 根技能模板
├── SKILL.md             # 自动生成（勿直接编辑）
├── CLAUDE.md            # 开发指引
├── CHANGELOG.md         # 版本历史
└── package.json         # Bun 项目配置
```

---

## 七、核心设计理念总结

1. **角色化 AI**：不是一个万能 Agent，而是 15 个专精角色，各有方法论
2. **持久浏览器**：守护进程模式带来亚秒级响应和状态持久
3. **代码即文档**：模板系统保证文档永远与代码一致
4. **AI 测试 AI**：三层评估管道确保 skill 质量
5. **完整性优先**：AI 压缩了实施成本，因此永远选择完整方案
6. **交互式审查**：一次一个问题，减少认知负荷
7. **开箱即用**：30 秒安装，一个命令就能调用整个虚拟团队


The user doesn't want to proceed with this tool use. The tool use was rejected (eg. if it was a file edit, the new_string was NOT written to the file). STOP what you are doing and wait for the user to tell you how to proceed.


[Request interrupted by user for tool use]