1. Core Thesis

2. Browser + Runtime Architecture

3. End-to-End Workflow Loop

4. Skill Contracts

5. Productization, Memory, Portability

gstack

一句话：把 Claude Code 从“一个泛化助手”变成“多个专长明确的工程角色”。

本体 = 2 层

认知层：一组高度 opinionated 的 slash skills，分别负责 CEO 式问题重构、工程计划审查、PR 审查、QA、发布、复盘。
感知/执行层：一个持久化本地浏览器系统，让 agent 真正看见页面、保留 cookie/tab/session，并能低延迟连续操作。

最终目标

把“想法 -> 计划 -> 实现 -> 审查 -> 真实页面验证 -> 出货 -> 复盘”做成默认流水线。
用显式模式切换取代 mushy generic mode。

它在解决什么

默认只有一种模糊模式：会执行，但不一定会重新定义问题。
浏览器若每次冷启动，就无法高频 QA。
PR review 深度不稳定，ship 常退化成人工 checklist。
agent 会写代码，但对真实 UI、登录态、console/network 错误半盲。
团队知识不会自动沉淀为 TODO、抑制规则、retro 历史、评测基线。

核心公理

Explicit gears：规划、审查、发布、QA、复盘是不同心智模式。
速度决定可用性：浏览器必须首调用约 3s、后续 100-200ms。
状态必须跨命令存活：cookie、tab、localStorage、refs 不能丢。
证据优先：截图、snapshot diff、console/network、git diff、retro 数据都是一等产物。
零静默失败：错误要被命名、被观测、被展示。
文档不能漂移：命令说明从模板和代码元数据生成。

浏览器架构骨架

Claude Code -> compiled CLI -> localhost HTTP server -> Playwright/Chromium

CLI 是薄层：读 .gstack/browse.json，带 bearer token 发命令。
Server 常驻：管理 Chromium、tab、refs、buffers、cookie import。
Browser 持久：首调用自动启动，30 分钟 idle 自动退出。
每个项目根目录都有独立 .gstack/ 状态和日志。

关键 insight：真正难的不是 prompt，而是让 agent 以极低延迟、持久状态去操作浏览器。

为什么不是“每次命令都开浏览器”

QA/狗粮流程常有 20+ 个命令，冷启动会浪费几十秒。
状态会丢：登录态、打开 tab、localStorage、调试上下文都无法连续。
gstack 选择 daemon 模型，本质上把浏览器变成一个本地有状态服务。
README 里的“10 sessions at once”只有在这个前提下才成立。

Ref 系统是交互抽象的关键

snapshot -i 读取 ARIA tree，为元素分配 @e1/@e2...。
snapshot -C 额外捕捉 cursor:pointer / onclick / tabindex 的非 ARIA 交互元素，生成 @c1/@c2...。
后续 click @e3 / fill @e4 会映射到 Playwright Locator。

为什么重要

避免 agent 写脆弱 CSS/XPath。
不改 DOM，因此不怕 CSP、hydrate、shadow DOM。
交互对象来自可读快照，便于 reasoning。

运行时机制

./setup 负责 bun install、编译二进制、安装 Chromium、建立 skill symlink。
build 会写 .version；CLI 发现 server 版本旧会自动重启，避免 stale binary。
logs 用 ring buffer + 异步 flush：console/network/dialog 都进 .gstack/*.log。
cookie import 直接读 Chromium SQLite，解密在内存里做，不把明文 cookie 落盘。
错误消息是给 agent 用的：少 stack trace，多下一步动作。

多工作区隔离

每个 git/worktree/Conductor workspace 各起一套浏览器实例。
随机端口 + 每项目 .gstack/browse.json，避免并行 agent 抢一个浏览器。
这让多个 /browse、/qa、/review 会话可以同时跑，互不污染。

安全与可观测性

server 只绑定 localhost，命令走 bearer token。
真实浏览器 cookie 读取需要用户通过 Keychain 授权。
console/network/dialog 既给 agent 实时读，也能供事后排查。
cookie DB 复制到临时只读文件，避免锁冲突；密钥只在会话内存里缓存。
设计基调是：本地可控 + 对 agent 可解释。

输入

feature idea
bug / hotfix
ready branch
staging / local app QA
weekly retro

gstack 的假设：一个 session 只做一种模式，但同一个人可以同时跑很多 session。

`/plan-ceo-review`

角色：Founder / CEO 任务：先挑战问题定义，再决定扩 scope、hold scope、还是砍 scope。

核心动作

先做 system audit：git log、diff、TODO/FIXME、TODOS、架构文档。
问“这是不是对的问题”“如果什么都不做会怎样”“现有代码能复用什么”。
三种模式：SCOPE EXPANSION / HOLD SCOPE / SCOPE REDUCTION。

产物

dream state delta
NOT in scope
what already exists
error/rescue registry
diagrams / failure modes / TODO 候选

`/plan-eng-review`

角色：Eng manager / tech lead 任务：把想法变成可构建的执行计划。

关注点

Step 0 先挑战 scope、复用现有代码、做 complexity check。
4 段 review：Architecture / Code Quality / Test / Performance。
强制产出 test diagram、failure modes、ASCII diagrams。
每个真实分歧通过 AskUserQuestion 单点推进，而不是含混默认。

产物

最小可行变更集
依赖/边界/瓶颈
必测路径与缺口
延期事项与 TODO 草案

实现阶段

gstack 不直接定义代码实现细节；它更像把实现前后的上下文塑形成高质量输入/出口。
实现阶段的成功条件是：后续 /review、/qa、/ship 能机械化接上。
换句话说，gstack 更像“研发操作系统”，不是单纯代码生成器。

`/review`

角色：Pre-landing PR reviewer 对象：当前分支相对 origin/main 的 full diff。

两遍法

Pass 1 blocking：SQL/Data Safety、Race/Concurrency、LLM trust boundary。
Pass 2 informational：副作用分支、magic numbers、prompt drift、test gaps、crypto/time-window/type coercion、frontend。

本质

不是“代码好不好看”。
而是“哪些结构性风险会在生产炸，但 CI 未必告诉你”。

`/browse` + `/qa`

角色：给 agent 眼睛，并把 QA 制度化。

/browse

低级操作层：goto / snapshot / click / fill / screenshot / console / network / diff / responsive / cookies。
适合手工探索、验证一个流、抓证据。

/qa

高级流程层：
- feature branch 无 URL 时，默认进入 diff-aware mode。
- 从 git diff main...HEAD 反推受影响页面/route/API。
- 自动找本地 dev server 或 staging URL。
- 测交互、截图、看 console，最后给 health score。

`/ship`

角色：release engineer 原则：能自动化的全自动化；除少数 stop 条件外，不来回确认。

流水线

检查分支与 diff
merge origin/main
跑 tests
若改到 prompt，补跑 eval suites
pre-landing review
处理 Greptile
自动决定 version bump
更新 CHANGELOG / TODOS
拆 bisectable commits
push + create PR

它依赖 GitHub、VERSION、CHANGELOG、TODOS 等约定。

`/retro`

角色：engineering manager for yourself / team 输入：git log、per-commit numstat、session detection、hotspot、PR 编号、Greptile history、TODOS backlog。

输出

commit / LOC / test ratio / session / focus score
team vs personal breakdown
ship of the week
praise + growth opportunities
周环比趋势

结果落到 .context/retros/，成为下次 planning/review 的历史输入。

`/setup-browser-cookies`

不是核心思维节点，但它解决了 authenticated QA 的关键阻碍。
通过真实浏览器 cookie 导入，让 headless 会话直接进入已登录状态。
这让 /browse 与 /qa 能覆盖 staging / admin / dashboard 等真实页面。

合同：`/plan-ceo-review`

Trigger：feature idea / vague request / "should we build this?"
Reads：git history、diff、stashes、TODO/FIXME、TODOS、架构文档
Decision：扩 scope / 持 scope / 砍 scope
Produces：dream state、what exists、not-in-scope、error/rescue map、diagrams
Success：从“做什么功能”转成“为什么做、做到哪一层”

合同：`/plan-eng-review`

Trigger：方向已定，需要 buildable plan
Inputs：Step 0 scope challenge + existing code leverage
Review axes：architecture / code quality / tests / performance
Produces：test diagram、failure modes、minimal diff plan、TODO candidates
Success：实现阶段几乎不再有语义性歧义

合同：`/review`

Trigger：branch ready, before landing
Unit of analysis：git diff origin/main
Blocking categories：SQL/data safety、race/concurrency、LLM trust boundary
Non-blocking：副作用分支、prompt drift、test gaps、crypto/time windows、frontend
Success：优先抓 CI 不一定发现、但足以挡住 /ship 的真实问题

合同：`/browse` + `/qa`

Trigger：need evidence on real UI
/browse：imperative low-level control
/qa：diff-aware 或 full-system exploration，最终落结构化报告和 health score
Evidence：annotated screenshots、snapshot diffs、console/network、repro steps
Success：让“它应该能 work”变成“真实浏览过并拿到证据”

合同：`/ship`

Trigger：ready branch，不是做产品决策的时候
Automates：merge main、tests、evals、review、Greptile triage、version bump、changelog、commits、push、PR
Stops only for：冲突、失败测试、关键审查决策、少数版本/TODO 决策
Success：从长回合人工 release 退化成一条可重复流水线

合同：`/retro`

Trigger：周期性复盘
Inputs：git history、session timing、hotspot、PRs、tests、Greptile history、TODO backlog
Produces：summary table、leaderboard、focus score、ship of the week、personal deep-dive、teammate praise/growth
Persistence：.context/retros/*.json
Success：让下次 planning/review 有历史参照，而不是只靠印象