Impetus 含义：推动力

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

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

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

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

为什么需要 Impetus

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

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

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

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

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

你能学到什么

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

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

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

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

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

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

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

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

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

安装

前置要求：

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

npm install -g @cylx/impetus

快速开始

cd your-project
impetus init

impetus init 会：

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

[!TIP] 更新版本号

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

CLI命令

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

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

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

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

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

创建 impetus-review 运行目录，并生成 bundle.json、findings.json、report.md、report.html 四件套骨架。

| 选项 | 描述 | |--------|-------------| | --change <name> | 审查指定活跃 change | | --profile <profile> | 审查 profile：standard、strict、security、architecture | | --output-dir <path> | 显式指定审查输出目录 | | --dry-run | 只预览，不写文件 | | --json | 输出结构化 JSON |

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

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

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

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

从已归档的 Impetus change 创建 Markdown 知识笔记：

impetus knowledge . --target obsidian --source archive --vault ~/Obsidian/Engineering

按主题创建一个 AI 可继续整理的知识工作台笔记：

impetus knowledge . --target obsidian --source topic --topic "认证安全" --vault ~/Obsidian/Engineering

归档笔记写入 Impetus/Archive/，主题笔记写入 Impetus/Topics/。

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

支持平台

impetus init 支持 多 个 AI 编码平台：

| 平台 | 技能目录 | 平台 | 技能目录 | |----------|-----------|----------|-----------| | Claude Code | .claude/ | Cursor | .cursor/ | | Codex | .codex/ | OpenCode | .opencode/ |

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

技能

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

Impetus 技能

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

守护与自动化脚本

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

OpenSpec 技能

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

Superpowers 技能

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

工作流

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

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

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

/impetus-solution（方案路径，包含头脑风暴，不写代码）
  open  -->  design  -->  review  -->  published

五个阶段

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

技术方案工作流

| 阶段 | 命令 | 归属 | 产出物 | |------|------|------|--------| | Open | /impetus-solution | OpenSpec | proposal.md、design.md、tasks.md | | Design | /impetus-solution | Superpowers | 经过 brainstorming 的技术方案 | | Review | /impetus-solution | Both | 打磨后的方案文档 | | Published | /impetus-solution | Both | 可评审或未来开发引用的最终方案 |

核心原则

• 头脑风暴不可跳过 — 每个变更必须经过深度设计（hotfix/tweak 除外）
• 方案模式只做方案不写代码 — /impetus-solution 通过 open → design → review → published 产出技术方案，不进入 build/verify/archive
• Delta spec 是活文档 — 在阶段 3 中可自由编辑，归档时同步
• 保持 tasks.md 同步 — 每完成一个任务就勾选
• 在正确边界提交 — executing-plans 默认整个 change 一次 build 提交；不得每个任务一个 commit
• 先验证再归档 — /impetus-verify 必须通过才能执行 /impetus-archive

状态管理

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

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

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

.impetus.yaml 关键字段：

workflow: full
phase: build
build_mode: subagent-driven-development
build_pause: null
isolation: branch
verify_mode: null
verify_strategy: standard
review_profile: standard
design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
solution_doc: null
solution_version: 1
solution_status: active
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>/.impetus/handoff/design-context.json
handoff_hash: <sha256>

full workflow 初始化时 build_mode、build_pause、isolation 和 verify_mode 可以暂时为 null；进入 build → verify 前必须完成 build_mode 与 isolation 决策并写入合法值。verify_mode 表示验证强度（light / full），verify_strategy 表示验证调度方式（standard / subagent-driven-verify），review_profile 控制 impetus-review 门禁。build_pause 记录 build 阶段内部暂停点：null 表示无暂停，plan-ready 表示 plan 已生成，用户在选择隔离方式和执行方式前暂停。它不是执行方式，不得写入 build_mode。verification_report 在验证报告生成前保持 null，verify-pass 要求该报告文件存在且 branch_status: handled。solution workflow 中，solution_doc、solution_version、solution_status 用于跟踪已发布技术方案，流程停在 published。示例中 archived 之后的字段是可选字段或脚本派生字段：direct_override 只在 full workflow 直接构建时需要，项目命令未配置时可以不存在，handoff_context 和 handoff_hash 由 impetus-handoff.sh 在离开 design 阶段前写入。项目可在 change 或仓库根配置中设置 build_command / verify_command，guard 会优先运行并打印失败输出。

可靠性特性

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

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

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

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

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

3. 模式校验 — impetus-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. 归档自动化 — impetus-archive.sh 一键处理完整归档流程

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

项目结构

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

License

MIT