@hottaiger/SpecDrive

███████╗██████╗ ███████╗ ██████╗    ██████╗ ██████╗ ██╗██╗   ██╗███████╗
██╔════╝██╔══██╗██╔════╝██╔════╝    ██╔══██╗██╔══██╗██║██║   ██║██╔════╝
███████╗██████╔╝█████╗  ██║         ██║  ██║██████╔╝██║██║   ██║█████╗
╚════██║██╔═══╝ ██╔══╝  ██║         ██║  ██║██╔══██╗██║╚██╗ ██╔╝██╔══╝
███████║██║     ███████╗╚██████╗    ██████╔╝██║  ██║██║ ╚████╔╝ ███████╗
╚══════╝╚═╝     ╚══════╝ ╚═════╝    ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═══╝  ╚══════╝

English version: README-en.md

OpenSpec + Superpowers 双星开发工作流 — 从创意到归档，一条命令。

OpenSpec 处理 WHAT（大纲、提案、spec 生命周期、归档）。

Superpowers 处理 HOW（技术设计、规划、执行、收尾）。

SpecDrive 将二者串联为五阶段自动化流水线。

[!NOTE] 本项目 fork 自 Comet（原作者 rpamis）。SpecDrive 在其基础上继续演进；CLI 与技能命名已迁移为 SpecDrive，并保留对部分旧 Comet 配置与 skill 目录的兼容。

[!IMPORTANT] 0.3.7 亮点 — 一键接入 CodeGraph 语义代码索引（官方：成本 ↓16%、工具调用 ↓58%）；

新增 Beta 上下文压缩，Build 阶段输入 token 降低 25–30%； 新增主动上下文压缩机制，释放读取 Spec 和 brainstorming 消耗的上下文，为后续 Build 阶段保留窗口 新增 6 项 Token 工作流优化默认开启； 新增 auto_transition 配置，支持自动流转或手动推进阶段切换； 基于 Hook 和 Rule 的防漂移阶段守护； 可选 TDD 模式与子代理调度确认； 支持大型 PRD 拆分为多个 change； 归档前确认与回退、验证重试限制、系统化调试拦截和验证完成检查等流程加固。

详见 NEWS.md。

为什么需要 Comet

OpenSpec 擅长管理需求、做提案、管理 Spec 生命周期和归档，但使用过程中 OpenSpec 的提案和 Task 没有像 Superpowers 头脑风暴那样细致。

Superpowers 在头脑风暴后会产出 Spec 文档，但这个文档通常没有进行状态化设计——做完需求之后 Spec 仅在文档上对 Task 打勾，甚至 Agent 还会忘记打勾，造成下一次断点开始时，Agent 需要重新查看文档和项目代码来核验，产生较多 Token 浪费。

SpecDrive 合并了两者的强项，将核心流程整合为 5 个阶段

主入口 /comet 支持当前 Spec 状态检测，适用于长任务——中途关闭当前 AI 编码会话后，回来只需 /comet，SpecDrive 会自动读取活跃的 Spec（多个则列出选择），动态识别当前执行到哪个阶段，继续往下执行。

同时，Comet具备Spec全生命周期管理能力，运行过程中能够将 OpenSpec 的 change/spec 制品与 Superpowers 的设计、计划文档进行关联，并自动完成交接、状态更新、校验和归档同步，把原本需要用户频繁提醒 Agent 维护文档同步和关联关系的操作自动化。

你能学到什么

现有的 Skill 市场中有很多优秀的 Skill 项目，但普遍存在偏好性问题——用户可能只喜欢部分功能。比如同时使用 OpenSpec 和 Superpowers 时，可能只用 OpenSpec 的 Spec 管理能力，而编码上更喜欢 Superpowers 的 TDD 驱动。

长期使用 Skill 的人都知道，这些能力是可以自由组合的，但具体怎么做依然需要真正的实践。SpecDrive 项目可以作为参考：

• 如何稳定触发嵌套 Skill — 不是让 Agent 依靠文档描述做了“看起来像触发了 Skill”的操作（比如根据 Skill 描述写了文件），而是真正触发 Skill（核心特征：CC 上有 Skill 触发的打印）。SpecDrive 中会触发大量来自 OpenSpec 和 Superpowers 的能力，这段 Prompt 是怎么写的？

• 如何让组合 Skill 多阶段自动流转 — 不是靠人工介入。SpecDrive 的 5 阶段流程，除必要的用户选择项外，核心流程能够自动进行 Skill 触发，同时状态机机制也能保障状态扭转的可靠性。

• 如何把 Spec 生命周期做成可恢复流程 — SpecDrive 会把 OpenSpec 的 change/spec 制品与 Superpowers 的设计、计划文档关联起来，并通过 .specdrive.yaml 记录阶段、执行模式、验证结果和归档状态，让 Agent 中断后能够继续，而不是重新翻文档猜进度。

• 如何把文档同步从“用户提醒”变成自动化 — SpecDrive 将 handoff、状态更新、校验和归档同步放进脚本化流程，减少“记得更新 design doc”“记得同步 spec”“记得归档 change”这类反复提示。

• 如何设计 Agent 可执行的守护条件 — SpecDrive 的阶段退出不是简单相信 Agent 说“完成了”，而是通过 specdrive-guard.sh、 specdrive-yaml-validate.sh、specdrive-state.sh 等脚本检查任务、状态字段、验证证据和归档条件，满足条件后才允许推进。

• 如何做跨平台 Skill 分发和安装 — SpecDrive 支持多种 AI 编码平台、项目级/全局安装、中文/英文 Skill 选择，以及平台差异化目录（例如 Antigravity 的项目级和全局路径不同），可以作为 CLI 安装器和 Skill 打包结构的参考。

• 如何把 shell 脚本写成 Agent 工作流基础设施 — SpecDrive 的脚本需要兼容 macOS、Linux、Windows Git Bash，处理 hash、YAML 字段、状态机和归档流程。它展示了如何把原本容易写散在 Prompt 里的流程控制，沉淀成可测试、可复用的工具。

安装

前置要求：

• Node.js 20+
• npm/npx
• Git
• 可运行 bash 的 shell 环境（Windows 用户建议使用 Git Bash 或等价环境）

npm install -g @lion_zs/SpecDrive

快速开始

cd your-project
specdrive init

specdrive init 会：

1. 提示你选择 AI 平台（自动检测已有配置）
2. 选择安装范围：项目级（当前目录）或全局（用户主目录）
3. 选择 SpecDrive 技能语言：English 或 中文
4. 安装 OpenSpec 技能
5. 安装 Superpowers 技能
6. 将 SpecDrive 技能（你选择的语言）部署到所选平台
7. 在项目级安装时创建 docs/superpowers/specs/ 和 docs/superpowers/plans/ 工作目录

[!TIP] 更新版本号

执行 specdrive update 或者 npm install -g @hottaiger/SpecDrive@latest 即可更新到最新版本。

CLI命令

为选定的 AI 编码平台初始化 OpenSpec、Superpowers 和 SpecDrive 技能。

| 选项 | 描述 | | ----------------- | ---------------------------------------------------- | | --yes | 非交互模式，自动选择已检测平台（未检测到则选择全部） | | --scope <scope> | 安装范围：project 或 global | | --skip-existing | 跳过已安装的组件 | | --overwrite | 覆盖已安装的组件 | | --json | 输出结构化 JSON |

当同一平台检测到多个已安装组件时，交互式 init 会先提供一次批量选择：全部覆盖、全部跳过，或逐项选择。

显示活跃更改、任务进度，以及推荐的下一步 SpecDrive 工作流命令。

| 选项 | 描述 | | -------- | ---------------------------------- | | --json | 输出活跃更改，并包含 nextCommand |

检查项目级/全局安装、工作目录、已安装技能、脚本和 SpecDrive 状态文件。

| 选项 | 描述 | | ----------------- | ------------------------------------------------------- | | --json | 输出结构化诊断结果 | | --scope <scope> | 诊断 auto、project 或 global 范围（默认：auto） |

更新 npm 包，并刷新已检测到的项目级/全局 SpecDrive 技能。

| 选项 | 描述 | | ------------------- | ---------------------------------------- | | --json | 以 JSON 输出 npm 和 skill 更新结果 | | --language <lang> | 覆盖自动检测到的 skill 语言 (en, zh) | | --scope <scope> | 仅更新 global 或 project 范围 |

| 命令 | 描述 | | --------------------- | -------- | | specdrive --help | 显示帮助 | | specdrive --version | 显示版本 |

支持平台

specdrive init 支持 28 个 AI 编码平台：

| 平台 | 技能目录 | 平台 | 技能目录 | | ------------------ | ------------ | ---------- | ------------- | | Claude Code | .claude/ | Cursor | .cursor/ | | Codex | .codex/ | OpenCode | .opencode/ | | Windsurf | .windsurf/ | Cline | .cline/ | | RooCode | .roo/ | Continue | .continue/ | | GitHub Copilot | .github/ | Gemini CLI | .gemini/ | | Amazon Q Developer | .amazonq/ | Qwen Code | .qwen/ | | Kilo Code | .kilocode/ | Auggie | .augment/ | | Kiro | .kiro/ | Lingma | .lingma/ | | Junie | .junie/ | CodeBuddy | .codebuddy/ | | CoStrict | .cospec/ | Crush | .crush/ | | Factory Droid | .factory/ | iFlow | .iflow/ | | Pi | .pi/ | Qoder | .qoder/ | | Antigravity | .agents/ | Bob Shell | .bob/ | | ForgeCode | .forge/ | Trae | .trae/ |

部分平台的项目级目录和全局目录不同。例如 OpenCode 全局安装使用 .config/opencode，Lingma 全局安装使用 .lingma ，Antigravity 全局安装使用 .gemini/antigravity。

技能

specdrive init 完成后，三组技能将被安装到所选平台的 skills/ 目录：

SpecDrive 技能

| 技能 | 描述 | | ---------------- | ---------------------------------------------------------- | | /comet | 主入口 — 自动检测阶段并分派到子命令 | | /comet-open | 阶段 1：打开变更（提案、设计、任务分解） | | /comet-design | 阶段 2：深度设计（头脑风暴、设计文档） | | /comet-build | 阶段 3：规划与构建（实现计划、代码提交） | | /comet-verify | 阶段 4：验证与完成（测试、验证报告） | | /comet-archive | 阶段 5：归档（delta spec 同步、状态标注） | | /comet-hotfix | 快捷路径：快速 bug 修复（跳过头脑风暴，不需要能力设计） | | /comet-tweak | 快捷路径：小改动（文案调整、配置调整、文档或 Prompt 优化） |

守护与自动化脚本

| 脚本 | 用途 | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------- | | specdrive-env.sh | 脚本发现助手 — 导出 SPECDRIVE_GUARD、SPECDRIVE_STATE、SPECDRIVE_HANDOFF、SPECDRIVE_ARCHIVE 等内置脚本路径 | | specdrive-guard.sh | 阶段转换守护 — 验证退出条件，--apply 自动更新 .specdrive.yaml | | specdrive-handoff.sh | 设计交接 — 从 OpenSpec 制品生成带 SHA256 追踪的确定性上下文包 | | specdrive-archive.sh | 一键归档 — 验证状态、同步 specs、移至归档、更新状态 | | specdrive-yaml-validate.sh | 模式校验器 — 校验 .specdrive.yaml 结构和字段值 | | specdrive-state.sh | 统一状态管理 — init/set/get/check/scale，agent 的专属 YAML 接口 | | specdrive-hook-guard.sh | 阶段写入守护 — PreToolUse hook，在 open/design/archive 阶段拦截文件写入 |

OpenSpec 技能

Spec 生命周期管理：propose、explore、sync、verify、archive 等。

Superpowers 技能

开发方法论：brainstorming、TDD、subagent-driven development、code review、plan writing 等。

工作流

/comet
  ↓ auto-detect
/specdrive-open  -->  /specdrive-design  -->  /specdrive-build  -->  /specdrive-verify  -->  /comet-archive
(OpenSpec)         (Superpowers)       (Superpowers)       (Both)           (OpenSpec)

/comet-hotfix（快捷路径，跳过头脑风暴）
  open  -->  build  -->  verify  -->  archive

/comet-tweak（快捷路径，跳过头脑风暴和完整计划）
  open  -->  轻量构建  -->  轻量验证  -->  archive

五个阶段

| 阶段 | 命令 | 归属 | 产出物 | | ------------------ | ---------------- | ----------- | -------------------------------- | | 1. Open | /comet-open | OpenSpec | proposal.md、design.md、tasks.md | | 2. Deep Design | /comet-design | Superpowers | Design Doc、delta spec | | 3. Plan & Build | /comet-build | Superpowers | 实现计划、代码提交 | | 4. Verify & Finish | /comet-verify | Both | 验证报告、分支处理 | | 5. Archive | /comet-archive | OpenSpec | delta→main spec 同步、归档 |

核心原则

• 头脑风暴不可跳过 — 每个变更必须经过深度设计（hotfix/tweak 除外）
• Delta spec 是活文档 — 在阶段 3 中可自由编辑，归档时同步
• 保持 tasks.md 同步 — 每完成一个任务就勾选
• 频繁提交 — 每个任务一个 commit，message 体现设计意图
• 先验证再归档 — /comet-verify 必须通过才能执行 /comet-archive

状态管理

SpecDrive 使用解耦状态架构，YAML 文件独立管理：

| 文件 | 归属 | 用途 | | ----------------- | --------- | ------------------------------ | | .openspec.yaml | OpenSpec | Spec 生命周期、变更元数据 | | .specdrive.yaml | SpecDrive | 工作流阶段、执行模式、验证状态 |

所有状态和运行阶段都通过脚本更新，并且会在每个阶段退出前校验任务是否真实完成。相比于将复杂状态管理写在 Skill 文本中，脚本化状态机能更稳定地保障阶段流转、YAML 正确性和断点恢复；Agent 只需要通过 SpecDrive 内置命令读取状态，就能知道当前 Spec 处于哪个阶段。

.specdrive.yaml 关键字段：

workflow: full
auto_transition: true
phase: build
build_mode: subagent-driven-development
build_pause: null
isolation: branch
verify_mode: null
design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
verify_result: pending
verification_report: null
branch_status: pending
verified_at: null
archived: false
direct_override: false
build_command: null
verify_command: null
handoff_context: openspec/changes/<name>/.specdrive/handoff/design-context.json
handoff_hash: <sha256>
tdd_mode: null
subagent_dispatch: null

full workflow 初始化时 build_mode、build_pause、isolation、verify_mode、tdd_mode 和 subagent_dispatch 可以暂时为 null；进入 build → verify 前必须完成 build_mode 与 isolation 决策并写入合法值。auto_transition 控制阶段完成后是否自动触发下一个 Skill — 详见 AUTO-TRANSITION.md。build_pause 记录 build 阶段内部暂停点： null 表示无暂停，plan-ready 表示 plan 已生成，用户在选择隔离方式和执行方式前暂停。它不是执行方式，不得写入 build_mode。 verification_report 在验证报告生成前保持 null，verify-pass 要求该报告文件存在且 branch_status: handled。示例中 archived 之后的字段是可选字段或脚本派生字段：direct_override 只在 full workflow 直接构建时需要，项目命令未配置时可以不存在， handoff_context 和 handoff_hash 由 specdrive-handoff.sh 在离开 design 阶段前写入。项目可在 change 或仓库根配置中设置 build_command / verify_command，guard 会优先运行并打印失败输出。

可靠性特性

SpecDrive 通过自动化状态转换确保 agent 执行可靠性：

1. 入口验证 — 每个阶段在执行前验证前置条件

   • 检查文件存在、状态一致性、阶段转换
   • 验证失败时输出 [HARD STOP] 及可操作建议

2. 自动化状态转换 — specdrive-guard.sh --apply 自动更新 .specdrive.yaml

   • 所有阶段转换（open → design/build → verify → archive）使用 guard --apply
   • 无需手动状态编辑 — 消除写入验证错误
   • specdrive-state.sh 是 agent 对状态操作的专属接口
   • Guard 和 archive 脚本内部使用 specdrive-state.sh 进行状态管理

3. 模式校验 — specdrive-yaml-validate.sh 确保数据完整性

   • 校验必填字段和可选字段
   • 校验枚举值（包括 direct_override）
   • 校验 design_doc、plan、handoff_context 路径存在，并校验 handoff_hash 格式
   • 检测未知/拼写错误字段

4. Build 决策强制 — Guard 和状态转换同时拦截跳过关键选择

   • isolation 必须是 branch 或 worktree
   • build_mode 必须已选择
   • build_pause: plan-ready 是 plan 生成后的可恢复暂停点，不是 build_mode
   • full workflow 的 build_mode: direct 必须有 direct_override: true

5. 验证证据强制 — Guard 在阶段流转前强制要求验证凭证

   • verify-pass 转换要求 verification_report 指向已存在的验证报告文件
   • branch_status 必须为 handled 才能通过验证
   • Guard 检查 verification_report exists 和 branch_status=handled 作为硬性前提
   • 防止验证或分支处理被跳过时产生虚假的阶段推进

6. 归档自动化 — specdrive-archive.sh 一键处理完整归档流程

   • 验证入口状态、通过 OpenSpec 将 delta specs 合并到 main specs
   • 标注设计文档和计划文档的 frontmatter
   • 将变更移至归档目录并更新 archived: true
   • 支持 --dry-run 预览

7. 防漂移阶段守护 — 长上下文会话中的阶段意识保障

   • Rule 层：comet-phase-guard.md 每轮注入阶段感知、Skill 调用规范和上下文恢复指令（所有平台通用）
   • Hook 层：specdrive-hook-guard.sh 在 open/design/archive 阶段硬拦截文件写入（Claude Code 等支持 hook 的平台）
   • 白名单路径：openspec/*、docs/superpowers/*、.claude/*、.specdrive/*

项目结构

your-project/
├── .specdrive/
│   └── config.yaml              # 项目级全局配置（context_compression、auto_transition 等）
├── .claude/skills/              # 平台技能目录（SpecDrive + OpenSpec + Superpowers）
│   ├── comet/SKILL.md
│   │   └── scripts/
│   │       ├── specdrive-guard.sh       # 阶段转换守护（--apply 自动更新状态）
│   │       ├── specdrive-env.sh         # 脚本发现助手
│   │       ├── specdrive-handoff.sh     # 设计交接（OpenSpec → Superpowers 上下文追踪）
│   │       ├── specdrive-archive.sh     # 一键归档自动化
│   │       ├── specdrive-yaml-validate.sh # 模式校验器
│   │       ├── specdrive-hook-guard.sh    # 阶段写入守护（PreToolUse hook）
│   │       └── specdrive-state.sh       # 统一状态管理（init/set/get/check/scale）
│   ├── comet-*/SKILL.md
│   ├── openspec-*/SKILL.md
│   └── brainstorming/SKILL.md
├── openspec/                    # OpenSpec — WHAT
│   ├── config.yaml
│   └── changes/
│       └── <name>/
│           ├── .openspec.yaml       # OpenSpec 状态
│           ├── .specdrive.yaml          # SpecDrive 工作流状态（解耦）
│           ├── proposal.md
│           ├── design.md
│           ├── specs/<capability>/spec.md
│           └── tasks.md
└── docs/superpowers/            # Superpowers — HOW
    ├── specs/                   # 设计文档
    └── plans/                   # 实现计划

SpecDrive 支持在 Design → Build 阶段交接时进行上下文压缩。启用后，specdrive-handoff.sh 会生成精简的上下文包，在不影响实现正确性的前提下，将 Build 阶段的输入 token 降低 25–30%。

| 模式 | 行为 | Token 节省 | | ------ | ----------------------------------------------------------------------- | ---------- | | off | handoff 嵌入 OpenSpec 源文件摘录（proposal / design / tasks / spec.md） | 基线 | | beta | verbatim 投影 delta spec.md；支持文件仅以 SHA256 引用 | ~25–30% |

Benchmark 核心结论：

• 测试通过率：所有档位均为 100%（压缩不影响实现正确性）
• Spec 覆盖率：off 100% vs beta 95%（压缩可能丢失少量边缘需求细节）
• 规模效应：任务越大，绝对节省量越高（large 档位节省可达 15,000 tokens）

启用方式：在 .specdrive/config.yaml 中设置 context_compression: beta

详见 CONTEXT-COMPRESSION.md 获取完整 Benchmark 报告、压缩原理和复现步骤。

auto_transition 控制阶段完成后是否自动调用下一个 Skill，还是暂停等待用户手动触发。阶段推进本身始终执行，该配置仅影响 Skill 调用。

| 值 | 行为 | | ------- | ---------------------------------------- | | true | 阶段完成后自动调用下一个 Skill（默认） | | false | 阶段完成后暂停，用户手动触发下一个 Skill |

三层配置与优先级：change 级 .specdrive.yaml 显式值 > SPECDRIVE_AUTO_TRANSITION 环境变量 > .specdrive/config.yaml（项目级）> 默认 true。

详见 AUTO-TRANSITION.md 获取配置详情、工作流映射和常见问题。