Hyperspec

HyperSpec

规格驱动 + 工程纪律的完整开发工作流。协调 OpenSpec（规格管理）和 Superpowers（TDD + 子代理审查），从需求到实现到归档一条流程走完。

OpenSpec 管「做什么和为什么」，Superpowers 管「怎么做和做得对不对」。HyperSpec 是纯编排层，只做状态检测、阶段路由、commit 纪律，不重写任何原生 skill 的功能。

编排协议

HyperSpec 是纯编排层，只做以下四件事：

1. 项目感知 — 自动探测语言/框架/构建工具，生成 project_profile 驱动后续阶段的自适应行为
2. 状态检测 — 通过结构化状态文件 + 实际文件验证确定当前阶段和断点位置
3. 阶段路由 — 加载对应 prompt 文件，按其中的流程调用原生 skill
4. Commit 纪律 — 每个 task/fix 完成后自动 commit，编译前置，不做 push

HyperSpec 不做：

• 不手动创建 openspec artifacts（由 openspec-propose 负责）
• 不手动转 tasks → plan（由 superpowers:writing-plans 负责）
• 不手动执行归档操作（由 openspec-archive-change 负责）
• 不重申 TDD 规则（由 superpowers:subagent-driven-development 负责）
• 不重申审查规则（由 superpowers:requesting-code-review 负责）

各阶段委托的原生 Skill

前提检查

触发后先检查两项：

检查1：Superpowers — 看 brainstorming 等 skill 是否可用。不可用则提示：/plugin install superpowers@claude-plugins-official

检查2：OpenSpec — 看项目根目录是否有 openspec/。没有则提示：npx @fission-ai/openspec init

注意：openspec init 除了创建 openspec/ 目录外，还会在 .claude/ 下生成配置文件和 slash commands。这些都是正常的副作用，不需要特别处理。

两项都通过后才继续。

项目分析器（Project Profiler）

前提检查通过后，在首次运行或状态文件不存在时，自动扫描项目生成 project_profile。结果保存到 .hyperspec-state.yaml 的 project_profile 字段。

检测逻辑

构建命令映射

下表为默认推导值。项目分析器会在推导后执行运行时验证（见下方），根据实际环境校准命令。

命令运行时验证

默认推导完成后，按以下顺序验证（先检测参数，再执行验证）：

1. 项目特有参数检测（在执行命令之前）：检查项目配置文件中是否有需要额外传入的参数：
   • Maven：检查根目录是否有 settings.xml，有则 compile_command 附加 -gs ./settings.xml
   • Gradle：检查是否有自定义 gradle.properties 或 local.properties
   • npm：检查 .npmrc 是否有 registry 配置
2. 执行编译命令：运行调整后的 compile_command（如果非 null）
3. 成功：确认命令可用，写入 project_profile
4. 失败且为环境问题（JDK/Node 版本不匹配、依赖下载失败等）：立即阻塞并报告，等待用户确认正确的命令
5. 失败且为代码问题（已有代码编译错误）：命令本身可用，写入 project_profile，编译错误留到 apply 阶段处理
6. test_command：不强制运行（可能依赖外部服务），但检查 test framework 是否安装（如 which pytest、检查 package.json 的 devDependencies）

项目 profile 的传递方式

project_profile 不会直接传给 openspec-propose 或 writing-plans（它们有自己的上下文读取机制），但 HyperSpec 在调用它们之前，会将 profile 信息作为上下文前缀拼接到 args 中：

• 调用 openspec-propose 时，在 description 前附加 [项目: {languages} + {frameworks}, 构建: {build_tool}]
• 调用 writing-plans 时，在 args 中附加 项目技术栈: {languages} + {frameworks}，构建工具: {build_tool}，测试框架: {test_command}
• apply 阶段使用 compile_command 和 test_command 驱动编译检查和验证

状态管理

状态文件：.hyperspec-state.yaml

位于项目根目录，HyperSpec 的快速路由入口。结构：

version: 1
active_change: add-user-auth
phase: propose | apply | archive
checkpoint: profiler-done | requirements-confirmed | openspec-generated | plan-generated | plan-generated-and-confirmed | task-N-complete | verified | reviewed | apply-done | consistency-verified | archived | done
project_profile:
  languages: [java]
  frameworks: [spring-boot]
  build_tool: maven
  compile_command: mvn compile
  test_command: mvn test
  structure: single-module
  has_ci: true

安全策略：状态文件 vs 实际文件

状态文件用于快速路由（避免每次扫描所有目录），但在关键节点必须验证实际文件状态：

原则：实际文件状态是 ground truth，状态文件只是缓存。两者冲突时，以实际文件为准并修正状态文件。

状态检测

检查 .hyperspec-state.yaml 和实际文件状态，确定应该进入哪个阶段：

Step 1：读取状态文件

• 状态文件不存在 → 这是首次运行，执行项目分析器，然后进入 propose 阶段
• 状态文件存在 → 读取 phase 和 checkpoint

Step 2：验证状态文件与实际文件一致性

根据状态文件中的 phase，验证对应的前提条件：

phase = propose 时验证：

• openspec/changes/ 下是否有活跃（非 archive）变更目录？ → 无则一致（propose 刚开始）
• 通用规则（适用于所有 checkpoint）：如果有活跃变更目录且 superpowers/plans/ 下有对应的计划文件（含 <!-- hyperspec change: <active_change> -->），说明实际进度已进入 apply 阶段，修正 phase: apply，根据 checkbox 状态判定 checkpoint
• 如果有活跃变更目录但无计划文件：根据变更目录下 artifacts 的完整程度判定 checkpoint（artifacts 完整 → openspec-generated，不完整 → requirements-confirmed）
• 如果 checkpoint ≥ openspec-generated：变更目录下的 artifacts 是否存在且非空？ → 有空文件则回退 checkpoint 到 requirements-confirmed

phase = apply 时验证：

• superpowers/plans/ 下是否有包含 <!-- hyperspec change: <active_change> --> 的计划文件？ → 无则回退到 propose 阶段
• 计划文件中是否至少有 1 个 checkbox？ → 无则回退到 propose 阶段（plan 不完整）
• 如果 checkpoint 声称 task-N-complete：计划文件中对应的 checkbox 是否确实已勾选？ → 未勾选则回退到上一个确认一致的 checkpoint

phase = archive 时验证：

• 所有计划 checkbox 是否已勾选？ → 未全勾选则修正状态文件为 phase: apply, checkpoint: reviewed，路由到 apply
• 如果 checkpoint ≥ consistency-verified：openspec/changes/archive/ 下是否有对应目录？ → 无则回退到 consistency-verified（重做归档）
• 如果 checkpoint ≥ archived：openspec/changes/archive/ 下是否有对应目录？ → 无则回退到 consistency-verified（归档中断）
• 注意：.close-verification-done 的存在性由 archive.md 内部处理（断点恢复表），SKILL.md 不据此覆盖 checkpoint，避免基于过期文件做错误路由

Step 3：路由

Step 4：无状态文件时的降级检测

如果状态文件不存在（可能是旧项目或手动删除），降级为文件扫描检测：

路由

根据检测结果，用 Read 工具加载对应文件并执行：

• propose 阶段 → 读取 skill 目录下的 propose.md，按其中流程执行
• apply 阶段 → 读取 skill 目录下的 apply.md，按其中流程执行
• archive 阶段 → 读取 skill 目录下的 archive.md，按其中流程执行

加载后严格按照文件中定义的流程、出口条件和硬门执行，不要跳步。

用户意图覆盖

如果用户明确指定了阶段（如「先做规格」「直接开始实现」「归档收尾」），以用户意图为准，跳过状态检测直接加载对应文件。但如果前置条件不满足（如用户说「直接实现」但 superpowers/plans/ 下没有计划文件），需要提醒用户先完成前置阶段。

状态文件更新时机

Source: wind7rui/HyperSpec — distributed by TomeVault.