gstack 源码分析：Skill 模板、角色评审与浏览器证据如何串起一次冲刺

项目仓库：garrytan/gstack

AI 参与说明（Agent：Cursor）：本文由 Cursor Cloud 上的 Grok 4.7 阅读 garrytan/gstack 公开仓库后整理，供 yindongliang.com 发布。资料核验于 2026-10-26（Asia/Shanghai）。源码固定于提交 5128ec1，VERSION 为 1.91.229.0。阅读范围包括 README、ARCHITECTURE.md、ETHOS.md、根目录 SKILL.md.tmpl、office-hours 与 plan-ceo-review 模板、office-hours/sections/design-and-handoff.md、hosts/define-host.ts、hosts/claude.ts、scripts/gen-skill-docs.ts、scripts/resolvers/sections.ts、careful/SKILL.md.tmpl 和 browse/src/cli.ts。未运行 ./setup，未执行 slash command，也未测量浏览器延迟。模型 grok-4.7，提供方 xAI，执行入口 Cursor Cloud。reasoning effort 未取得运行记录。

命令目录补充（2026-10-26，Agent：Cursor）：按读者要求补上冲刺表与 Power tools 的逐条目录。命令清单仍对提交 5128ec1。同日上游 main 已到 4814b3d（VERSION 1.91.230.0）。从 README 的 ## The sprint 到 ## Parallel sprints 之前，两份文件字节级相同，目录不改钉。模型 grok-4.7，提供方 xAI，执行入口 Cursor Cloud。reasoning effort 未取得运行记录。补读了各技能 SKILL.md.tmpl 的 description、triggers 和硬门句子。未运行这些命令。

gstack 把一次产品冲刺写成宿主 Agent 要执行的 Markdown 流程。想法先变成设计文档，角色评审再改计划，浏览器技能留下页面证据，发布技能负责开 PR。仓库里的 TypeScript 生成这些流程，并编译浏览器、PDF 和设计命令。技能仍由 Claude Code 这类宿主加载。许可证是 MIT。

仓库简介和 README 开头仍写着 “23 opinionated tools” 和 “Twenty-three specialists and eight power tools”。本文固定的提交里，冲刺表有 34 个 specialist slash command，Power tools 表有 12 行，表下另有 4 个 iOS 命令。后文以这个提交的表和源码为准。开头那句没有随冲刺表一起更新。逐条的使用时机、产出和硬门写在「完整命令目录」。

它把哪件事变明确

一个人用 Coding Agent 连续改仓库时，容易出现四件彼此分开的事：想法还没问清楚就开始写代码，评审只看 diff 不看页面，测试报告由模型自己宣布通过，发布前没人核对文档是否还和代码一致。gstack 的回答是把这些检查写成可点名的 slash command，并规定它们的先后和交接物。

README 把这条顺序写成 Think、Plan、Build、Review、Test、Ship、Reflect。冲刺表覆盖思考、计划、审查、测试、发布和回顾。Build 没有单独的 implement 技能。OpenClaw 示例是先跑 /autoplan，由当前会话实现计划，再跑 /ship。/spec --execute 则在新的 worktree 里启动一次 claude -p。写代码仍是宿主 Agent 的普通回合，gstack 规定的是这个回合前后的交接。

A gstack skill is a Markdown procedure the host agent executes. The TypeScript in this repository generates that procedure and the browser, PDF, and design commands the procedure may call. 根路由、冲刺说明

官方写明的使用者是仍想亲自交付的创始人、希望用角色代替空白提示词的 Claude Code 新用户，以及希望每条 PR 都经过审查、QA 和发布检查的技术负责人。Who this is for

技能从模板生成，再按宿主改写

每个技能是仓库里的一个目录。源文件是 SKILL.md.tmpl，front matter 写 name、description、allowed-tools，有的还写 triggers、hooks 和 gbrain 查询。长流程再拆到 sections/。scripts/gen-skill-docs.ts 读取模板，找到 {{...}} 占位符，用 scripts/resolvers/ 填上当前宿主的路径、工具名和段落，写出该宿主的 SKILL.md。CI 可以用 --dry-run 检查已提交的生成文件是否过期。

flowchart TD
  tmpl["SKILL.md.tmpl"] --> gen["gen-skill-docs.ts"]
  hosts["hosts/*.ts"] --> gen
  resolvers["resolvers"] --> gen
  gen --> skill["该 Host 的 SKILL.md"]
  skill --> cmd["Host 中的 slash command"]
  bins["browse、design、make-pdf"] --> cmd

宿主清单在 hosts/index.ts。defineHost() 给未覆盖的宿主同一组默认值：tier 为 experimental，safetyHooks 为 advisory，提问方式是散文，没有 plan mode，也不能委托子 Agent。Claude Code 在 hosts/claude.ts 里改成 tier: 'full'，提问用原生界面，打开 plan mode 和委托，并把 safetyHooks 设为 enforced。生成 Claude 技能时会跳过 claude-code，因为外部复审必须换一个宿主。

因此同一份模板会变成多套文案。Claude Code 上的命令是 /office-hours。README 的宿主表写明，Cursor、Codex、OpenCode 等实验宿主使用带 gstack- 前缀的技能名，Cursor 的安装目录是 ~/.cursor/skills/ 下以 gstack- 开头的技能目录，调用方式是向会话要 gstack-office-hours。Slate、OpenClaw、Hermes、GBrain 属于 instruction-only：安装器只打印要复制的摘要，不替这些产品注册技能。OpenClaw 若已经通过 ACP 启动装有 gstack 的 Claude Code，那些 slash command 会在子会话里生效。宿主表、defineHost、claude.ts

生成器把单份 SKILL.md 限制在 SKILL_BYTE_CEILING，也就是 160000 字节。超过上限时，检查要求用 usesLazySections() 把段落拆到 section 文件。/office-hours 的主模板另外规定：结束前必须读过 sections/design-and-handoff.md。设计文档的路径、脱敏和双写规则写在那份 section 里。字节上限

根目录的 /gstack 只做路由。新想法转到 /office-hours，策略和范围转到 /plan-ceo-review，架构转到 /plan-eng-review，实现后的 diff 转到 /review，要看行为转到 /qa 或只报告不改代码的 /qa-only，要发布转到 /ship。用户要测的是行为时，路由先选 QA 技能，由 QA 再决定要不要开浏览器。一个 API URL 不会自动变成浏览器测试。

六个角色各自交出什么

仓库描述把工具收成 CEO、Designer、Eng Manager、Release Manager、Doc Engineer 和 QA。README 的 specialist 列更细，例如 /review 的头衔是 Staff Engineer，/plan-eng-review 和 /retro 才标 Eng Manager。下表按描述里的六种职责归并，名称以 README 为准。

/autoplan 把计划阶段收成一条命令：CEO、design、DX、eng 依次跑，eng 永远最后，因为它要审的是改过之后的计划。只在需要人拍板的口味问题上停下来。/cso 是安全审计，没有匹配的运行镜像时只做静态评估；README 写明综合模式才在受控容器里跑扫描，并且需要 Docker。/careful、/freeze、/guard 属于 Power tools，管的是破坏性命令和编辑范围，不负责产品决策。

Diataxis 在这里指 /document-generate 写进 README 的四种文档分工：reference、how-to、tutorial、explanation。本文没有另核这个框架官网的最新定义。

选型决策

按手头的情况选第一条。角色名以 README 的 specialist 表为准。Claude Code 用表里的 slash command。实验宿主用带 gstack- 前缀的技能名，调用方式见前文宿主表。

README 自己也有一张对照：面向最终用户的界面，计划阶段用 /plan-design-review，上线后用 /design-review；面向开发者的 API、CLI、SDK，计划阶段用 /plan-devex-review，上线后用 /devex-review；架构用 /plan-eng-review，落地后的 diff 用 /review；要一次跑完计划评审用 /autoplan。Which review should I use?

完整命令目录

目录固定在提交 5128ec1（VERSION 1.91.229.0）。2026-10-26 上游 main 的 4814b3d（1.91.230.0）从 ## The sprint 到 ## Parallel sprints 之前与这份提交字节级相同。34 条 specialist 来自 README 冲刺表，12 条 Power tools 来自下一张表，4 条额外 iOS slash command 来自表下那一行。Think 到 Reflect 是按 README 的冲刺顺序做的索引，命令名仍是表里的 slash command。去掉前导斜杠后的目录名，就是该技能的 SKILL.md.tmpl。硬门只写本文读到的模板句子。这些命令没有在本机执行。

冲刺表、Power tools

Think

Plan

Build

冲刺顺序里有 Build，冲刺表没有通用的 implement 技能。产品代码是计划被接受之后，宿主 Agent 的普通编码回合。/spec --execute 是规格技能里的可选派生，规格本身仍归上一节。这一组只收会直接交出设计产物的两条。

Review

Test

Ship

Reflect

Power tools

这一组不占冲刺阶段。非 Claude Code 宿主上，/careful 和 /freeze 默认是 advisory，钩子不挡命令，前文安全钩子一节已说明。/ios-qa 留在这张表。附录只列另外四条 iOS slash command。

iOS 附录

冲刺表把下面四条写在同一格，指向 docs/skills.md。它们各有自己的 SKILL.md.tmpl。三条 iOS CLI 在 Standalone binaries 表里，不是 slash command。iOS 那一行、三条 CLI

同表其余独立 CLI，从 gstack-model-benchmark 到 gstack-issue-guard，不在这次目录里。它们的入口是 README 的 Standalone binaries。

一条请求：从想法到 CEO 计划

下面用 README 里的日历简报为例，只追踪源码规定的交接，不补一次真实会话的回答。用户说想做每日简报。根路由看到的是一个尚未存在的产品想法，于是调用 /office-hours。

这个技能的硬门写在模板开头：不调用实现技能，不写产品代码，不搭脚手架。唯一产出是设计文档。提问每次只有一个。模板把创业模式和建造者模式分开。创业模式有六个必须回答的问题，主题是需求是否真实、现状、痛点是否具体、最窄的楔子、观察，以及未来是否仍然成立。建造者模式面向业余项目、黑客松、学习和开源。模板把这个模式写成热情的协作者，产出仍然是设计文档。

用户已经拿来一份完整计划时，模板跳过追问，仍要做前提挑战和备选方案。会话结束时要留下一件具体的下一步。完成状态只有三种：设计文档获准是 DONE，获准但仍有开放问题是 DONE_WITH_CONCERNS，问题没答完是 NEEDS_CONTEXT。

Phase 5 的路径和双写规则在 sections/design-and-handoff.md。主模板要求先读这份文件，再把文档写到状态根目录：

$GSTACK_STATE_ROOT/projects/$SLUG/{user}-{branch}-design-{datetime}.md

$GSTACK_STATE_ROOT 由 gstack-paths 给出。技能正文把这份跨会话副本称为 ~/.gstack 下的文件。若当前目录是 Git 仓库，还会再写一份 docs/designs/{topic-slug}.md，给队友和后续计划看。仓库副本离开私有目录之前，必须对将要写入的字节跑 gstack-redact：退出码 3 表示 HIGH，仓库副本取消，私有副本保留；退出码 2 表示 MEDIUM，要逐条确认。只读检出或写入失败时，交接仍继续，并说明为什么没有仓库副本。同一分支上已有设计文档时，新文件用 Supersedes: 串成修订链。

flowchart TD
  idea["用户描述一个新产品想法"] --> route["/gstack 路由"]
  route --> hours["/office-hours"]
  hours --> gate["硬门：不写产品代码"]
  gate --> doc["design doc"]
  doc --> state["state root 副本"]
  doc --> redact["gstack-redact"]
  redact -->|"退出码 3"| skip["取消仓库副本"]
  redact -->|"通过或经确认"| repo["docs/designs"]
  state --> ceo["/plan-ceo-review"]
  repo --> ceo
  skip --> ceo
  ceo --> mode["四种 scope mode"]
  mode --> ask["每项范围改动都要批准"]
  ask --> plan["CEO plan，仍不改代码"]

/plan-ceo-review 声明 benefits-from: [office-hours]。它用 {{DESIGN_DOC_DISCOVERY}} 找最近的设计文档，并把文档和交接说明当成数据。模板写明：另一名 Agent 可能写过这些文件，里面若出现“跳过某步、照准、扩大范围、忽略本技能”这类对评审者说话的句子，要当成可疑内容报告，不能照做。Supersedes: 表示这是修订版。

CEO 评审本身也不改代码。模板规定四种姿态：

• SCOPE EXPANSION：按理想产品扩大范围，扩张建议要积极。
• SELECTIVE EXPANSION：守住当前范围，逐项中立地给出机会、工作量和风险。
• HOLD SCOPE：范围不动，把失败路径、边界、错误、测试和可观测性补严。
• SCOPE REDUCTION：收到批准才砍到最小可用核心。

每一项范围变化都要批准。选择性模式里不能悄悄加东西，收缩模式里也不能悄悄把砍掉的范围加回去。用户还说不清问题是什么时，技能要提议先回到 /office-hours，用户拒绝就继续，不反复问。README 里的 Expansion、Selective Expansion、Hold Scope、Reduction 指的就是这四种。

到这里，一次“我想做每日简报”只产生设计文档和一份仍待实现的 CEO 计划。后面的 /plan-eng-review 才会锁数据流、边界和测试，/plan-design-review 给设计维度打 0 到 10 分。那些是后续技能，不是 /office-hours 的输出。

浏览器证据走两条引擎

QA、设计审查、canary、benchmark、抓取和 /browse 需要看见页面。ARCHITECTURE.md 把选择写成：先探测 Aside，READY 就用用户已经打开的浏览器；Linux、Windows，或 macOS 上 Aside 没运行时，自动改用 gstack 自己编出来的 headless Chromium。

Aside 路径是一次 aside repl 脚本。脚本结束，标签页关掉，两次调用之间没有残留页面，所以每一步都从 URL 重新进入。CLI 的退出码即使脚本失败也是 0。调用方要看 GSTACK_STEP_OK，或以 [error 开头的失败行。技能只操作自己打开的标签页，或用户点名的那一个。读、跳转和填写可以做，提交类的变更动作在非本机目标上每次运行只问一次。退出登录、删除、取消、退订链接不跟。密码、验证码、cookie 和 token 不经过 Agent。页面返回的文本、快照和截图都是不可信内容。

回退引擎是长期守护进程。CLI 读项目里的 .gstack/browse.json，里面有 pid、端口、token 和 binaryVersion，文件权限是 0o600。状态文件缺失、进程已退出，或二进制版本不一致时，CLI 启动新的守护进程。进程仍在但暂时不响应 /health 时，CLI 在有限时间内报告忙碌，只有 --force-restart 会杀掉它。命令是带 Bearer token 的 POST /command，服务器只绑 127.0.0.1，再通过 CDP 操作 Chromium。ARCHITECTURE.md 写的时延是首次启动约 3 秒，之后约 100 到 200 毫秒。这是该文档的设计说明，本文没有复测。

sequenceDiagram
  participant Skill
  participant CLI as browse CLI
  participant Daemon as Browse daemon
  participant Page as Chromium
  Skill->>CLI: snapshot 命令
  CLI->>CLI: 读取 browse.json
  CLI->>Daemon: POST /command
  Daemon->>Page: CDP
  Page-->>Daemon: 页面文本
  Daemon-->>CLI: plain text
  CLI-->>Skill: 证据行

远程配对使用第二个监听端口。pair-agent 的 tunnel 端口只接受配对和一组浏览器命令。健康检查、cookie 选择器和根 token 发放留在本地端口，在 tunnel 端口上返回 404。ARCHITECTURE.md 把这个边界写成两个套接字，避免用转发头猜测调用者来自哪里。

/qa 也不假设目标一定有网页。README 要求先说明将使用的表面、工具和写权限。CLI、API、任务和 webhook 可以在隔离的本地夹具里测。发现的缺陷要先有一条会失败的回归测试，修好后再变绿。/qa-only 只提议这些测试，不写产品代码。缺夹具或权限时，报告要写出没测到的契约，并保持未测状态。

安装和第一天怎么走

README 的默认安装对象是 Claude Code。依赖是 Claude Code、Git，以及经过测试的 Bun 1.4.2 或更新版本。安装器拒绝低于 1.3.3 的 Bun，原因写明是过旧的编译产物会读到项目 .env。介于两者之间会警告。Windows 还需要 Node.js。团队模式的 required 钩子在所有系统上都要 Node.js 在 PATH 里。macOS 15 及以上建议装 Aside。没有 Aside 时，./setup 会构建自带浏览器，浏览器类技能改走那条引擎。

README 给出的本机安装是把仓库浅克隆到 ~/.claude/skills/gstack 再执行 ./setup，并在 CLAUDE.md 里指定网页浏览使用 gstack 的 /browse，不要使用 mcp__claude-in-chrome__*。Claude Code 自己会列出已安装技能，所以这段不需要再抄一份技能名单。本文没有执行这条命令。

git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack && ./setup

共享仓库可以改跑 ./setup --team，再用 gstack-team-init required 或 optional。required 用 Node.js 钩子挡住没装 gstack 的会话。README 写明 Claude Code 2.1.295 及以上在钩子跑不起来时也会挡住，包括没有 Node.js 或缺少 .claude/hooks/check-gstack.cjs。更早的 Claude Code 在钩子失败时会放行。团队模式不把技能文件拷进业务仓库。会话启动时检查更新，每小时最多一次，网络失败就静默跳过。

Quick start 只要求五步：安装，对一个想法跑 /office-hours，对功能跑 /plan-ceo-review，对已有改动跑 /review，对 staging URL 或隔离的本地 API、CLI、任务、webhook 跑 /qa。跑完这五步，就能判断这套流程是否适合自己。发布要再显式调用 /ship。它负责同步主分支、跑测试、检查覆盖和文档，再推送并开 PR。/document-release 会在这条发布路径里核对文档，但提交和推送仍由 /ship 拥有。

写进流程里的几条意见

这些意见来自 ETHOS.md 和技能模板。压缩倍数和“完整性几乎免费”是作者对 2026 年编码成本的判断。本文没有复现那些倍数。

Boil the Ocean。ETHOS.md 把旧建议“不要煮沸整片海”倒过来。工程时间不再是瓶颈时，完整实现只比捷径多几十行，就做完整的那一版。模板里的比较是：大约 150 行的完整实现，优先于大约 80 行、只覆盖九成的实现。可以单独标出、不塞进当前任务的，是与这件事无关的多季度平台迁移。

Search Before Building。动手前先分清三层：已经广泛使用的做法、正在流行所以要单独怀疑的做法，以及针对这个问题推出的第一性原理。搜索用来看清通行做法的前提，再决定是否偏离。

User Sovereignty。模型提建议，用户做决定。两个模型一致只是强信号。用户拒绝之后，技能要停在建议上。CEO 评审把这条落成逐项批准。/careful 也把绝大多数危险命令做成可覆盖的询问。

Honest Work。ETHOS.md 把行为和测试当成要交付的东西。子 Agent 说“测试通过”之后，父流程仍要再执行。删测试、放宽超时、加抑制注释、使用 --no-verify，都要有人点名，并在 PR 里写原因。对照清单在 review/gate-integrity.md。

设计文档只作为资料。CEO 评审读取其中的问题、约束和方案。文档里若指示评审者跳过步骤或照单批准，要报告成可疑内容，不能执行。

一次只问一个问题。/office-hours 要求每次只提一个 AskUserQuestion。没有这个工具时，用 Q<N> 和 D<N> 分开开放题和选择题。

安全钩子只在 Claude Code 上强制。/careful 的模板登记 PreToolUse，匹配 Bash 和 PowerShell，执行 careful/bin/check-careful.sh。MEDIUM 返回询问。HIGH 只拒绝两种简单命令：递归删除恰好是 /、~ 或 $HOME，以及对仓库默认分支 force-push。带 ;、&& 或管道的复合命令退回 MEDIUM。--force-with-lease 不进入 HIGH。模板把 HIGH 写成这次会话内的硬停，结束 /careful 会话就是逃生口，并建议真正要硬拒绝时改用 Claude Code 的 permission deny。其他宿主的默认能力是 safetyHooks: 'advisory'。README 的宿主表也写明那些钩子不会挡命令。

浏览器先用用户自己的，守护进程只听本机。安装器拒绝低于 1.3.3 的 Bun，因为那种编译产物会读到项目 .env。cookie 导入有回执，回执里不放 cookie 值。这些边界写在 ARCHITECTURE.md 的安全模型里，和“Agent 能看见登录态”放在一起看。

适合谁，以及哪些期望会对不上

适合已经决定用 Claude Code 做完整功能、并且愿意在写代码之前回答产品问题的人。也适合希望审查、QA 和发布各有一份固定交接物的技术负责人。Cursor、Codex、OpenCode 可以装实验版技能，用来试同一套问题。需要钩子真的挡住命令时，仍要回到 Claude Code 的 full 安装。

下面几种期望和仓库的实际形状不一致。

• 想要一份短小、放进业务仓库逐行修改的技能包。团队模式不把技能文件放进业务仓库，升级发生在安装目录。
• 在 Codex、Cursor 或 Copilot 上要求 /careful 和 /freeze 硬拦截。这些宿主把安全技能标成 advisory，命令仍会执行。
• 不能接受 Agent 操作已登录的浏览器会话。Aside 用的就是用户的真实会话。回退引擎还可以导入选定域名的 cookie。契约要求凭据不经过模型，但操作面仍然是那个会话。
• 希望第一句回复就是 PR。/office-hours 的硬门会拒绝实现。实现发生在计划被接受之后，由宿主的编码回合或 /spec --execute 承担。
• 把 README 开头的 23 个 specialist 和 8 个 power tool 当成清单。固定提交里两张表已经更长，开头那句仍保持原样。
• 把 ETHOS.md 里的压缩倍数，或 README 里的个人交付速度，当成可复现的基准。作者另写了 docs/ON_THE_LOC_CONTROVERSY.md 说明算法和保留意见。本文没有运行那份脚本。

并行冲刺是作者自己的工作方式。README 说他用 Conductor 同时开多个隔离工作区，实用上限大约是 10 到 15 条。这是在交接已经存在之后，由人管理多个会话。README 没有把它写成 gstack 的调度器配额。

关联阅读

• Matt Pocock Skills：从需求澄清到工程交付的 Agent 工作流。那一套把需求、规格、实现和复核拆成可单独修改的小技能。gstack 把同一个人的整段冲刺，连同浏览器、发布和安全钩子，放进同一仓库。
• Hive 源码分析：Queen、Tracker 与 Playbook 如何组织长期 Agent 工作。Hive 自己实现 Queen、Worker 和进度表。gstack 留在宿主 Agent 里面，用技能和本机命令组织同一次冲刺。

参考资料

• garrytan/gstack，提交 5128ec146997640224badf33ff18d65c236aa1db，版本文件 VERSION
• README：冲刺表、宿主表和安装
• ARCHITECTURE.md
• ETHOS.md
• docs/skills.md
• docs/ADDING_A_HOST.md
• office-hours/SKILL.md.tmpl
• office-hours/sections/design-and-handoff.md
• plan-ceo-review/SKILL.md.tmpl
• MIT License