g↗G SKILLSDEVELOP WITH INTENT
A WORKFLOW FOR THOUGHTFUL BUILDERS

开发有章可循。
交付有据可查。

把需求、设计、实现和验证,
连成一条可以中断、恢复、追溯的开发路径。

一套服务于 AI 辅助开发的规格驱动工作流。你决定目标与关键取舍,AI 串行推进,脚本守住可确定的边界。

12 专注的 skills1 主会话串行0 默认自动合并
THE CHANGE WORKBENCH01 — 05
~/your-project流程示意

# 一个明确的目标,一条可恢复的路径

❯ /g-spec

先核对真实代码,再澄清目标与关键前提。

↳ decision-memo.md↳ proposal.md · design.md↳ specs/ · tasks.md
保留决策讨论站稳一条,纪要保存一条。

点击切换阶段 · 展示职责与产物,不执行真实命令

SPEC → CODE → VERIFY每一步,都有落点。
01 需求写清楚02 决策留证据03 改动能验收04 中断可恢复

01 / THE WORKFLOW

从一个想法,
走到一次完整交付。

不是让你记住更多命令。
把关键判断留下来,让后续执行有据可依。

01

把目标讨论清楚

/g-spec

先读现状,澄清目标、范围与非目标,再拷问承重前提。方案确定后生成四件套与决策纪要。

MEMO + SPEC + DESIGN
02

让设计经得起检查

/g-review spec

从完整性、可行性、领域、对抗和真实代码逐一检查。报告交给你,明确批准后才进入实施。

用户明确批准
03

把工作切成可验收的票

/g-implement

按依赖逐票串行实现。每票经过需求轴与规范轴自审,执行验收,再提交完成标签。

TICKETS + EVIDENCE
04

检查整个变更的行为

/g-review code

核对范围、边界、错误路径和历史问题。P0/P1 未解决就阻塞,只有不影响验收的 P2 可以延期。

REVIEW + REAL ISSUES
05

验证,交接,归档

/g-done <change>

逐需求核对实现与测试证据,保留详细交接说明,同步规格并归档。默认留在工作分支,不合并。

VERIFY + HAND-OFF
g

设计批准之后,通常只需交给 /g-done <change>。
它每步前后读取 gate,根据文件与 Git 记录决定下一步,而不是凭聊天记忆推进。

展开完整流程 ↗

02 / EVIDENCE, NOT ASSUMPTION

“做完了”,
要有依据。

让检查与它实际覆盖的代码版本绑定。让交付不仅有代码,也有解释和证据。

理解验证规则 ↗
01

PASS 绑定检查前的提交

源码在检查后发生变化,写锚就会拒绝。报告提交限定路径,避免夹带未经验证的源码。

02

复选框不能独立放行

完成状态读取已提交的 checkpoint 标签;零用例、缺证据、环境故障都不能被包装成真实通过。

03

保留起点,尊重合并意图

每个 change 保存固定起始 SHA 与工作分支。默认不合并;只有你明确指定目标,才执行合并。

04

承认检查的边界

内联多视角共享一个上下文。gate 能校验结构与内容关系,不能证明语义判断无误,也不能代替真实测试。

03 / THE TOOLKIT

12 个入口。
各自把一件事做好。

主流程负责一次交付。
规划、环境、记录与复盘,按项目需要加入。

显示 12 个 skills
SKILL 01开发主线

/g-spec

需求与规格

把澄清、拷问和生成放在同一条路径上,先确认承重前提,再形成正式变更材料。

输入、产物与用法 +
输入 / INPUT
需求、项目现状与约束
产物 / OUTPUT
四件套 + decision-memo.md
继续阅读
查看使用手册 ↗
SKILL 02开发主线

/g-review

设计审与代码审

串行检查范围、领域、对抗与接地事实。区分结构通过、内容判断和用户批准。

输入、产物与用法 +
输入 / INPUT
spec / code 模式、本次变更
产物 / OUTPUT
spec-review-report / code-review-report
继续阅读
查看使用手册 ↗
SKILL 03开发主线

/g-implement

逐票实施与自审

出票与执行分开。以纵向切片交付行为,按 Blocked-by 串行选票,逐票保存验收证据。

输入、产物与用法 +
输入 / INPUT
已批准的设计、tasks 与 specs
产物 / OUTPUT
tickets.md、实现报告、完成标签
继续阅读
查看使用手册 ↗
SKILL 04开发主线

/g-done

推进到完整交付

每步读取 gate,从当前盘面继续实现、评审、验证、交接和归档。默认不合并、不 push。

输入、产物与用法 +
输入 / INPUT
真实 change 名、可选明确合并目标
产物 / OUTPUT
verify-report、hand-off、归档记录
继续阅读
查看使用手册 ↗
SKILL 05项目规划

/g-architecture

系统架构与边界

采集事实、划分子系统、定义 contract,检查场景覆盖,形成可进入骨架实施的 SAD。

输入、产物与用法 +
输入 / INPUT
系统定位、外部依赖、硬约束
产物 / OUTPUT
sad.md、架构日志、骨架建议
继续阅读
查看使用手册 ↗
SKILL 06项目规划

/g-roadmap

跨变更的阶段规划

把超过一个 change 的工作拆成分阶段交付。近期细化,远期保留边界与依赖。

输入、产物与用法 +
输入 / INPUT
长期目标、约束、已有架构
产物 / OUTPUT
design / roadmap / task-log
继续阅读
查看使用手册 ↗
SKILL 07项目规划

/g-devenv

环境与测试策略

查明单元、集成与 e2e 怎么跑,写出每层信心与盲区,记录真实泳道状态与证据。

输入、产物与用法 +
输入 / INPUT
现有代码、CI、测试服务、可选 SAD
产物 / OUTPUT
testing-strategy、environments、泳道状态
继续阅读
查看使用手册 ↗
SKILL 08记录与维护

/g-init

给项目接入工作流

铺设项目骨架、schema 和人读手册,注入托管入口,保留项目自定义内容。

输入、产物与用法 +
输入 / INPUT
目标项目、已有 OpenSpec 配置
产物 / OUTPUT
项目配置、目录与入口托管区块
继续阅读
查看使用手册 ↗
SKILL 09记录与维护

/g-upgrade

更新本机工具链

按实际运行 checkout 的远程执行 ff-only 更新,再刷新安装,避免指令与脚本版本错位。

输入、产物与用法 +
输入 / INPUT
实际安装来源与 Git 状态
产物 / OUTPUT
更新后的 skills、全局工具与版本信息
继续阅读
查看使用手册 ↗
SKILL 10记录与维护

/g-issues

缺陷与待办台账

bug 与 todo 分池。一个问题一个文件,记录来源、状态与证据,复用历史 ID。

输入、产物与用法 +
输入 / INPUT
故障或改进、模块与来源
产物 / OUTPUT
B/T issue、生成索引、状态历史
继续阅读
查看使用手册 ↗
SKILL 11记录与维护

/g-adr

长期决策与取舍

新建决策、按变更同步、分批体检已有 ADR。格式交给脚本,内容事实依靠读码核对。

输入、产物与用法 +
输入 / INPUT
决策背景、备选、代码与变更
产物 / OUTPUT
ADR 文件、格式检查与偏离记录
继续阅读
查看使用手册 ↗
SKILL 12记录与维护

/g-retro

流程复盘

从已有 Git 与报告再生阶段耗时和历史统计。只呈现已有证据,不自动调整流程。

输入、产物与用法 +
输入 / INPUT
变更历史、评审报告与已有数据
产物 / OUTPUT
openspec/retro/report.md
继续阅读
查看使用手册 ↗
每个入口都可以按需使用。architecture、roadmap 和 devenv 不需要在每个 change 中重复执行。

04 / A DELIVERY YOU CAN READ

交付代码,
也交付一份说明。

完整流程结束后,hand-off.md 随变更一起归档。下次接手时,你能知道做了什么、为什么这样做,以及还有什么没有完成。

查看全部产物 ↗
≡hand-off.md随 change 归档
CHANGE DELIVERY / 交付记录

这次改动,说明白。

  1. 完成了什么需求与能力、关键文件、修改前后行为、实现取舍。
  2. 如何确认完成实际测试命令、结果、提交与验收证据、覆盖边界。
  3. 接下来做什么未完成项、延期问题、已知限制和后续建议。
openspec/changes/archive/<日期>-<change>/

05 / GET STARTED

从你的项目,开始。

终端安装一次工具链,给目标项目接入流程。
之后,每次变更从一个清晰的需求开始。

01

安装工具链

需要 Git、Bash、Python 3、OpenSpec CLI 和 mikefarah/yq。GitHub 仓库访问需要对应权限。

02

接入目标项目

在你的业务项目中初始化 OpenSpec,再调用 /g-init。补充真实技术栈、约束和测试命令。

03

完成第一项变更

用 /g-spec 讨论需求,设计审后明确批准,再交给 /g-done 连续推进。

TERMINAL / 终端
git clone https://github.com/Alexwhitee/gearbox.git \
  "$HOME/.skills/g-skills"
cd "$HOME/.skills/g-skills"
bash setup.sh
IN YOUR AI SESSION / 项目会话
# 为项目启用工作流
/g-init

# 讨论并生成本次需求
/g-spec

# 设计评审 → 你明确批准
/g-review spec

# 替换成真实的 change 名
/g-done your-change-name

斜杠命令在 AI 会话中使用,不是终端命令。也可以明确说“使用 g-spec”。

CHOOSE YOUR STARTING POINT

你现在处于哪个阶段?

/g-init → /g-architecture → /g-devenv → /g-spec

先明确系统边界与测试路径。确实跨多个变更时,再用 /g-roadmap 拆阶段。

06 / THINGS WORTH KNOWING

开始之前,你可能想知道。

更多故障排查 ↗
走完整个流程后,会自动合并或推送吗?+

不会默认合并,也不会自动 push。无论从 a 新建功能分支,还是直接在 a 开发,默认都是提交、验证、归档后留在工作分支。只有你明确指定合并目标,才会尝试 ff-only 合并。

中途换会话,需要从头再来吗?+

不需要。对同一个 change 重新运行 /g-done,执行者会读取 gate、报告、固定基准和提交记录,定位需要补做的步骤。已写代码但缺验收或完成标签的票,会先核对已有实现,再补齐验证。

多个评审视角,就是多个独立代理吗?+

不是。当前是一个主会话逐视角检查,不调用子代理,不跨模型调度,也不配置模型档位。不同视角有各自的清单,但共享上下文,不能宣称提供了独立第二意见。

没有自动测试的项目,可以使用吗?+

可以,但必须如实说明覆盖边界。未配置命令不等于没有测试:执行者先查 CI、README 和既有约定。确实没有某一层才记录依据;有明确测试域且配置无自动层时,也要保留起始版本与需求验收证据。

为什么还需要我批准设计?+

范围、偏好和关键取舍最终属于你。主变更链保留设计批准点,AI 准备推荐、依据、代价与备选;明确批准后才记录设计门。报告写着通过或者你没有反对,都不能替代明确批准。

我需要记住全部 12 个命令吗?+

不用。日常主线是 /g-init、/g-spec、/g-review spec 和 /g-done。出票、逐票实现与代码审通常由 done 按 gate 调用;其余入口在需要规划、环境、记录或复盘时使用。

LESS GUESSWORK. MORE TRACEABILITY.

让下一次开发,
从清晰开始。

保留关键判断,执行真实验证。
让代码、证据和交接,一起抵达终点。

阅读完整使用手册 ↗