# Superpowers Openspec

> 用于：用户明确要求按 OpenSpec / OPSX 分析需求、写 spec、做详细设计、写方案或方案文档、制定计划；或新功能、功能变更、流程变更、接口变更、数据模型变更、状态流转、角色流程、模块边界调整会改变对外行为；或同一请求包含设计与实现混合意图。

- Skill: `tielei60/superpowers-openspec` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add tielei60/superpowers-openspec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tielei60/superpowers-openspec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tielei60 (https://skillmd.com/u/tielei60)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tielei60/superpowers-openspec

---


# superpowers-openspec

面向 OpenSpec 的方案、规范与计划工作流 skill。
职责：帮助用户把方案、规范和计划的阶段边界说清楚。需要业务评审或完整方案沉淀时，先写 `docs/solutions/*.md`，由用户确认后，再将已确认内容落到官方 OpenSpec / OPSX 工作流。

## 快速执行路径

先判断当前阶段，再只推进下一步；不要把方案确认、OpenSpec 生成和实现落地混在一次响应里完成。

| 用户场景 | 当前阶段 | 下一步只做 | 暂不做 |
|----------|----------|------------|--------|
| 用户要求先写方案、方案文档、详细设计文档、业务评审材料，或要求确认后再生成 OpenSpec | 方案确认前 | 先写方案文档：创建或更新 `docs/solutions/<主题>.md` | 不创建 `openspec/changes/`，不写 OpenSpec artifact，不进入实现 |
| 用户明确要求不要方案文档，直接按 OpenSpec 走，且输入边界清楚 | OpenSpec 准备 | 直接进入 OpenSpec：选择唯一 `/opsx:*` 入口，并说明要生成或更新的 artifact | 不同时给多个命令，不跳到实现 |
| 用户已确认 `docs/solutions/<主题>.md`，并要求转成 OpenSpec | OpenSpec 转换 | 已确认方案转 OpenSpec：先输出方案提取摘要，再创建或更新 `proposal.md`、`spec.md`、`design.md`、`tasks.md` | 未确认事项未清空前，不直接生成完整 `tasks.md` |
| OpenSpec 规范已经完成，用户要求开发落地 | 实现准备 | 已完成规范进入实现：交给实现入口或 `/opsx:apply` 承接 | 不在本 skill 内继续写实现代码 |

按用户请求的动作决定本轮产出：

- 用户要求编写、更新或转换产物时，在工作区实际创建或更新当前阶段允许的文件，并报告结果；不要只说明应该写哪个路径。
- 用户只询问路径、阶段或命令时，只返回路由判断，不擅自创建产物。

响应时必须明确：当前阶段是什么；本轮已完成或将执行什么；下一步只做什么。

## 权威来源

以下内容以上游 OpenSpec / OPSX 为准，不由本 skill 重定义：

- 目录结构：`openspec/specs/` 与 `openspec/changes/`
- 命令体系：`openspec init`、`openspec update` 与 `/opsx:*`
- 变更产物：`proposal.md`、`spec.md`、`design.md`、`tasks.md`
- 本 skill 只规定进入顺序、来源引用、中文表达和质量门禁

## 触发边界

满足任一即触发：

- 用户要求先分析、先整理需求、先写 spec、先做详细设计、先写方案、方案文档或计划
- 用户要求先写完整 markdown 方案、先确认完整方案文档，或给产品、运营、业务团队、技术评审会准备材料
- 任务属于新功能、功能改造、功能优化、流程优化、模块重构、能力升级
- 任务涉及业务规则、接口、交互、数据结构、状态流转、角色流程或模块边界变更
- 用户把"设计/方案/计划"和"实现/开发/落地"混在一起表达

不触发：

- 纯 bug 修复，且不涉及新规则、流程、接口或状态
- 纯文案、样式、配置值调整
- 局部性能优化，影响范围明确且无需新增规范
- 用户只要求快速定位问题或直接给出修复建议

混合意图优先级：先判断是否涉及新功能、规则、接口、数据结构、状态或角色变化；如果是，优先进入 `superpowers-openspec`。`帮我设计并实现短信发送功能`、`先沟通需求，再把功能做出来` 都是带实现诉求的规范阶段入口。

## 阶段门禁

核心边界：**方案文档确认前不进 OpenSpec，规范完成前不进实现。**

- 一句话规则：**先写方案文档，确认后再进 OpenSpec。**
- `docs/solutions/*.md` 是进入 OpenSpec 前的业务方案确认层；它不替代官方 artifact，但在用户需要完整方案、业务评审或先确认文档时，优先级高于 `/opsx:propose`、`/opsx:ff` 和其他 `/opsx:*`。
- 用户说"先写方案"、"先写文档"、"先确认方案"、"给业务评审"时，先创建或更新 `docs/solutions/<主题>.md`；用户确认前，不应创建或更新 OpenSpec change，不进入 `/opsx:*`。
- 方案文档至少覆盖：背景、目标、非目标、已确认决策、关键取舍、方案设计、风险、待确认问题、验收标准；正文和文件名必须使用中文。
- 请求确认前，询问用户是否需要"方案文档自我闭环验证"；该验证由用户决定，不是强制门禁。若用户选择验证，完成后再询问是否需要创建 `docs/solutions/references/<主题>-OpenSpec-拆分设计.md`。
- 确认后，`proposal.md` 必须靠前包含"来源方案文档"章节；多方案来源时全部列出，不新增 `sources.md` 或 `source-docs.md`。
- 已确认方案转 OpenSpec 时，必须先输出"方案提取摘要"，再生成产物；存在关键未决项时，不直接生成完整 `tasks.md`，等待用户明确确认。
- 方案文档与 OpenSpec 产物发生实质变化时，检查并同步另一侧。模板见 `references/planning-workflow.md`，方案转 OpenSpec 流程见 `references/solution-to-openspec-workflow.md`。

## 命令映射

给出唯一推荐入口；完整映射见 `references/intent-to-openspec-mapping.md`。

| 场景 | 推荐入口 | 重点产物 |
|------|----------|----------|
| 直接按 OpenSpec 推进，输入完整 | `/opsx:propose` | proposal + spec + design + tasks |
| 输入零散或关键边界不清 | `/opsx:explore` | 先收敛假设、范围、待确认问题 |
| 已有方案但未确认 | 先 `docs/solutions/*.md` | 确认后再进 `/opsx:*` |
| 用户要求一次全出 | `/opsx:ff` | 全部 OpenSpec 产物 |
| 用户要求分步补齐 | `/opsx:new` + `/opsx:continue` | 逐步补齐 |
| 规范已完成，准备实现 | `/opsx:apply` | 进入实现入口 |
| 变更完成 | `/opsx:archive` | 归档 |
| 验证或同步 | `/opsx:verify` / `/opsx:sync`（profile 支持时） | 一致性检查或同步回主规范 |

## 产物质量要求

- 语言要求：默认工作语言必须中文；工作流判断、命令建议、产物说明、门禁提示，以及 `docs/solutions/*.md`、`proposal.md`、`spec.md`、`design.md`、`tasks.md` 的文档内容本身也必须使用中文。只有当用户明确要求其他语言时，才可以切换。
- 确定性语言：规则、行为、任务、验收标准要可执行、可验证；未确认内容只放入"待确认问题"章节并暂停确认，不用"可能、也许、大概、或许、暂定"承载规范结论。
- 业务化表达要求：文档必须写成业务系统设计文档，不写成 AI 技术说明书。总原则是先讲业务场景，再讲系统处理，最后讲技术支撑。
- 每个功能点都写明：解决什么业务问题、系统怎么处理、异常情况怎么处理、业务价值是什么；优先使用"用户/业务人员……时，系统会……"的句式。
- 技术词可以出现，但必须放在业务解释之后。技术词不是禁用词；不要逐词列禁用清单，应通过写法规则约束文档质量。"事实、召回、向量、实体、关系、切片、上下文、模型"只是示例，不是穷举；同类技术词出现时，先解释业务含义和用户可见结果，再说明技术实现。
- DTO、MQ、Job、状态机、唯一键、缓存、锁、回调等实现词不能替代业务说明；出现这些词时，先说明它解决的业务问题。表名、字段名、枚举、接口字段要先说明业务语义；唯一性优先使用稳定、非空、不可变的业务字段或字段组合并建立唯一索引，不默认新增单独请求唯一键。
- 行为描述必须具备 WHO + TRIGGER + OUTCOME：具名角色、触发动作、可观测业务结果。缺 WHO 或缺 TRIGGER 的陈述要改写；数据迁移、字段映射、底层存储模型和非功能性指标可用系统术语。
- 文档可读性要求：使用人类易读语义，避免 AI 式套话和内部缩写；术语首次出现需解释，优先短句先说结论，对比枚举状态映射优先用表格。
- 为什么有时必须补图：复杂架构、流程、状态、时序或页面结构只靠文字容易产生歧义。架构图、流程图、时序图优先 Mermaid；页面、表单、列表、弹窗布局用 ASCII 文本布局图。优先 Mermaid，页面布局退化为 ASCII；如果输出 Mermaid 图，最后必须做一次自检。
- 图示是 `design.md` 的组成部分，不是独立强制文件；不要在明明需要图示时只给纯文字总结。
- 减少返工的完整性要求：进入 OpenSpec 前必须检查关键假设、待确认问题、外部依赖、兼容性、迁移、状态延续、回滚规则、验收标准和验证方式。信息不完整时，优先 `/opsx:explore` 收敛，或 `/opsx:new` + `/opsx:continue` 分步补齐。

详细模板、示例和检查项见 `references/spec-template.md`、`references/spec-checklist.md`、`references/output-example.md`。

## 常见错误

| 错误 | 正确做法 |
|------|----------|
| 把 Mermaid 文件列为独立强制产物 | 图示放在 `design.md` 内 |
| 跳过 `docs/solutions/*.md` 直接生成 OpenSpec change | 先写方案文档，确认后再进 OpenSpec |
| 用户要业务评审材料时直接 `/opsx:propose` | 先生成可完整评审的 `docs/solutions/<主题>.md` |
| 未决项明显时仍给完整 tasks | 先 `/opsx:explore` 收敛 |
| 同时推荐多个 `/opsx:*` 不做取舍 | 给出唯一推荐命令 |
| 用"系统 / 数据 / 状态 / 事实"做主语描述行为 | 改写为 WHO + TRIGGER + OUTCOME |
| 用技术术语替代业务解释 | 先写业务人员能看懂的场景和系统处理，再补技术支撑；技术词本身可以保留 |
| 默认新增 `unique_key` / `request_key` / `idempotency` 字段 | 先判断业务字段或字段组合能否表达唯一性；不能覆盖请求级去重时再新增请求唯一键并说明原因 |

## 停止条件

本 skill 完成以下事项后即停止：

1. 用户要求编写、更新或转换产物时，已实际创建或更新当前阶段允许的文件；用户只询问路径、阶段或命令时，已给出唯一入口
2. 已说明当前阶段是什么、下一步只做什么，以及当前应生成或更新哪些产物
3. 已声明当前处于规范阶段，不进入实现
4. 如有必要，已点出未决项、图示建议、来源关系或可选的 `source-notes.md` / `transcript.md`

停止后由 OpenSpec / OPSX 承接。各参考文件已在对应章节内引用，使用顺序见 `references/skill-usage-sequence.md`。