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。