| name | openspec-superpowers |
| description | 当用户执行 /opsx:propose（或 /opsx-propose）、/opsx:apply（或 /opsx-apply）、/opsx:explore（或 /opsx-explore）、/opsx:archive（或 /opsx-archive）时触发。将 OpenSpec 文档管理与 Superpowers 质量工程能力集成为统一开发流程。 |
OpenSpec + Superpowers 集成技能
核心理念
- OpenSpec 管理「做什么」— 规范管理、变更追踪、文档归档
- Superpowers 管理「怎么高质量地做」— 设计讨论、TDD、代码审查、系统调试
- 本技能 是桥梁 — 在 OpenSpec 的每个阶段自动调用对应的 Superpowers 技能
技能基础路径
本技能所有文件引用使用相对路径。执行时先确定 SKILL_BASE：
- 当前已加载 SKILL.md 所在目录（首选）
- 兜底：搜索
openspec-superpowers/SKILL.md
确定后，所有 read_file 使用 ${SKILL_BASE}/<相对路径>。
入口路由
根据用户消息中的命令关键字路由到对应阶段（同时支持冒号 : 和连字符 - 两种格式，以兼容 Cursor command 命名）：
| 用户消息包含 | 执行路径 | 阶段 |
|---|
opsx:propose 或 opsx-propose 或 openspec:proposal | Phase 0 → 1 → 1.5 → 2 | 需求输入 → 设计 → 环境检查 → 文档生成 |
opsx:apply 或 opsx-apply 或 openspec:apply | Phase 3 | 实施 |
opsx:explore 或 opsx-explore | 原生 OpenSpec explore | 探索（无需集成） |
opsx:archive 或 opsx-archive | Phase 4 | Delta Spec 同步 → 归档 |
opsx:rollback 或 opsx-rollback | 上下文检测 → Phase 3 或 Phase 4 回滚 | 回滚 |
| 无法判断 | 询问用户 | — |
propose 路径
【必须】先 read_file 读取 ${SKILL_BASE}/phases/phase1-design.md，严格按该文件执行 Phase 0 → 1 → 1.5 → 2。
apply 路径
【必须】先 read_file 读取 ${SKILL_BASE}/phases/phase3-implement.md，严格按该文件执行 Phase 3。
archive 路径
【必须】先 read_file 读取 ${SKILL_BASE}/phases/phase4-archive.md，严格按该文件执行 Phase 4。
rollback 路径
上下文检测：根据当前状态自动判断回滚目标阶段。
检测逻辑：
- 检查
openspec/changes/archive/ 下是否有今天归档的变更 → 有则提供 Phase 4 回滚选项
- 检查
openspec/changes/ 下是否有活跃变更的 tasks.md 含 [x] 标记 → 有则提供 Phase 3 回滚选项
- 两者都有 → 用
AskQuestion 让用户选择回滚哪个阶段
- 都没有 → 提示无可回滚内容
确定目标后：
- Phase 3 回滚 → 读取
${SKILL_BASE}/phases/phase3-implement.md 的「回滚」节执行
- Phase 4 回滚 → 读取
${SKILL_BASE}/phases/phase4-archive.md 的「回滚」节执行
explore / verify
直接使用 OpenSpec 原生命令处理，不需要额外的 Superpowers 集成。
完整流程全景
用户：我要做一个新功能 / 提供 TAPD 链接
Phase 0：需求输入
├── 自动检测输入（TAPD URL/ID vs 描述 vs 空）
├── 无输入 → AskQuestion 让用户选择「直接描述」或「从 TAPD 获取」
├── TAPD 模式：通过 tapd-manager MCP 获取单据详情
├── 展示并确认需求信息
└── 携带需求上下文（tapd_context 或 user_description）进入 Phase 1
Phase 1：设计讨论
├── 调用 superpowers:brainstorming 进行设计探索（携带 Phase 0 上下文）
├── 逐一提问 → 提出 2-3 个方案 → 分节呈现设计
├── 用户确认完整设计
└── ⛔ 此阶段禁止：创建任何文件、调用 writing-plans
Phase 1.5：环境检查
├── 检测是否在 Git worktree 中
├── 不在 → 选项：创建 worktree / 当前目录继续 / 取消
└── 就绪 → 进入 Phase 2
Phase 2：文档生成
├── 重新读取 tasks-template.md 模板（强制，防止遗忘）
├── 生成 openspec/changes/<name>/ 目录：
│ ├── proposal.md （Why + What Changes + Impact）
│ ├── specs/*.md （功能需求规格 + Delta Specs → 归档后同步到 openspec/specs/）
│ ├── design.md （Context + Goals + Decisions + Risks → 归档后同步到 openspec/specs/）
│ └── tasks.md （TDD/非TDD 子任务 + 代码审查 + 变更文档定稿）
└── ⛔ 禁止：调用 writing-plans、写入 docs/plans/
用户：/opsx:apply
Phase 3：实施
├── 前置检查（分支、worktree、tasks.md 存在性）
├── 读取 tasks.md → 生成 TODO 列表 → 选择执行模式
├── 逐任务执行：
│ ├── TDD 任务：写失败测试 → 验证失败 → 最小实现 → 验证通过 → 重构
│ │ └── 意外失败 → 调用 superpowers:systematic-debugging
│ ├── 非 TDD 任务：执行变更 → 验证无回归 → 检查完整性
│ └── 任务组代码审查：
│ ├── 先调用 superpowers:verification-before-completion 确认测试通过
│ ├── 再调用 superpowers:requesting-code-review 执行审查
│ └── 用户选择处理 → 调用 superpowers:receiving-code-review 验证后实施
├── 变更文档定稿（校验变更级别文档与实际实现一致）
└── 调用 superpowers:finishing-a-development-branch 引导分支决策
用户：/opsx:archive
Phase 4：归档
├── 选择变更（自动检测或询问）
├── 完整性检查（任务完成度、必要文件）
├── 功能文档同步（openspec/specs/）：
│ ├── 扫描 openspec/changes/<name>/specs/ 下的 delta specs
│ ├── 分析类型（新建 / 追加 / 替换 / 删除）
│ ├── 同步 design.md 到 openspec/specs/<capability>/design.md
│ ├── 生成同步预览 → 用户确认
│ └── 执行同步 spec.md + design.md 到 openspec/specs/
├── 服务设计文档更新（docs/services/）：
│ ├── 识别受影响的服务（从代码变更和设计文档推导）
│ ├── 确定更新内容（追加/修改章节）
│ ├── 生成更新预览 → 用户确认
│ └── 执行更新到 docs/services/<service>.md
├── 归档：mv openspec/changes/<name> → archive/YYYY-MM-DD-<name>
└── 输出归档摘要
Superpowers 技能调用矩阵
| 阶段 | Superpowers 技能 | 调用时机 |
|---|
| Phase 0 | tapd-manager | TAPD 模式时获取单据（条件触发） |
| Phase 1 | brainstorming | 设计讨论开始时（强制） |
| Phase 1.5 | using-git-worktrees | 需要创建 worktree 时（可选） |
| Phase 3 | test-driven-development | 执行 TDD 任务时（隐式遵循） |
| Phase 3 | systematic-debugging | 测试结果与预期不符时（强制） |
| Phase 3 | verification-before-completion | 代码审查前（强制） |
| Phase 3 | requesting-code-review | 每个任务组完成后（强制） |
| Phase 3 | receiving-code-review | 用户选择处理审查意见后（强制） |
| Phase 3 | finishing-a-development-branch | 所有任务完成后（强制） |
| Phase 4 | — | 不依赖 Superpowers 技能，独立执行 delta spec 同步与归档 |
HARD STOPS
违反以下任何规则必须立即停止并向用户报错：
| ID | Phase | 规则 |
|---|
| H1 | 1 | 禁止在 Phase 1 创建任何文件 |
| H2 | 1 | 禁止跳过 brainstorming 技能调用 |
| H3 | 1 | 禁止在用户明确确认完整设计前进入 Phase 1.5 |
| H4 | 2 | 禁止调用 writing-plans 技能 |
| H5 | 2 | 禁止在 docs/plans/ 下创建文件 |
| H6 | 2 | 禁止凭记忆生成 tasks.md，必须先重新读取模板 |
| H7 | 3 | 禁止跳过 execution_mode 询问 |
| H8 | 3 | 禁止跳过任务执行子步骤 |
| H9 | 3 | 禁止跳过代码审查 |
| H10 | 3 | 禁止在测试结果异常时跳过 systematic-debugging |
| H11 | 3 | 禁止在完成后跳过 finishing-a-development-branch |
| H12 | 4 | 禁止在用户未确认同步预览前修改主 specs |
| H13 | 4 | 禁止在主 spec 中留下 TBD/TODO 占位符 |
| H14 | 4 | 禁止在主 spec 中残留 ADDED/MODIFIED/REMOVED 标记 |
| H17 | 4 | 禁止在用户未确认更新预览前修改 docs/services/ 下的文件 |
| H18 | 4 | 禁止在 docs/services/ 更新时修改变更范围之外的内容 |
| H15 | 回滚 | 禁止在未展示状态诊断和用户选择前执行任何回滚操作 |
| H16 | 回滚 | 禁止对已推送到远程的提交使用 git reset（必须用 git revert） |
配置
execution_mode: agent
review_mode: per_task
review_action: confirm
skip_worktree_check: false
tdd_strict: true
execution_mode 选择指南
| 模式 | 适用场景 | 特点 |
|---|
agent | 任务 ≤5 个或逻辑简单、任务间有强依赖 | 主代理顺序执行，上下文连续 |
subagent | 任务多（>5）或功能复杂、任务组内可并行 | 每任务派独立子代理，并行执行同组独立任务 |
Phase 3 启动时会根据 tasks.md 中的任务数量，向用户询问执行模式。
跳过已完成任务
Phase 3 执行前会检查每个任务的前置条件。如果目标文件已满足要求（如 proto 文件已有完整注释），应直接标记为已完成并跳过，避免重复工作。
项目可通过 alwaysApply 规则文件覆盖以上默认值。
执行时，会话上下文中的配置值优先于默认值。
阶段间数据契约
| 数据 | 产生阶段 | 消费阶段 | 传递方式 |
|---|
| 需求上下文（tapd_context / user_description） | Phase 0 | Phase 1, 2 | 会话上下文传递；TAPD 模式下包含 source、type、id、url、title、description、priority、owner、time_constraint |
| 设计方案 | Phase 1 | Phase 2 | 写入 design.md 的 Context 和 Decisions 节 |
| worktree 路径 | Phase 1.5 | Phase 2, 3 | pwd 动态获取 |
| change name | Phase 0/2 | Phase 2, 3, 4 | Phase 0 从用户描述或 TAPD 标题推导；Phase 2 用于创建目录；Phase 4 用于定位变更 |
| tasks.md | Phase 2 | Phase 3, 4 | read_file 读取 |
| delta specs | Phase 2 | Phase 4 (Step 3) | openspec/changes/<name>/specs/<capability>/spec.md 文件 |
| design.md | Phase 2 | Phase 4 (Step 3, 4) | openspec/changes/<name>/design.md → 同步到 openspec/specs/ 和 docs/services/ |
| proposal.md | Phase 2 | Phase 4 (Step 3) | 新建主 spec 时提取 Purpose 描述 |
跨会话恢复：Phase 3 通过 /opsx:apply 独立触发时，前置检查覆盖必要的恢复步骤。Phase 4 通过 /opsx:archive 独立触发时，从文件系统重新读取所有上下文。AI 不应假设前置阶段的上下文仍在内存中。
上下文刷新检查点
长对话中 AI 可能遗忘早期指令。以下检查点处必须重新读取对应内容：
| 检查点 | 重新加载内容 |
|---|
| 每 5 个顶层任务完成后 | 本文件 HARD STOPS 表格 |
| 每次代码审查前 | phase3-implement.md 的「代码审查」节 |
| 每次派发子代理前 | phase3-implement.md 的「subagent 模式」节 |
| 变更文档定稿前 | phase3-implement.md 的「禁止行为」节 |
| 功能文档同步前 | phase4-archive.md 的「3.5 执行同步」节和「禁止行为」节 |
| 服务文档更新前 | phase4-archive.md 的「Step 4：同步更新 docs/services/」节和「禁止行为」节 |
