superpowers-openspec

name superpowers-openspec description 用于：用户明确要求按 OpenSpec / OPSX 分析需求、写 spec、做详细设计、写方案或方案文档、制定计划；或新功能、功能变更、流程变更、接口变更、数据模型变更、状态流转、角色流程、模块边界调整会改变对外行为；或同一请求包含设计与实现混合意图。 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 完成以下事项后即停止： 用户要求编写、更新或转换产物时，已实际创建或更新当前阶段允许的文件；用户只询问路径、阶段或命令时，已给出唯一入口 已说明当前阶段是什么、下一步只做什么，以及当前应生成或更新哪些产物 已声明当前处于规范阶段，不进入实现 如有必要，已点出未决项、图示建议、来源关系或可选的 source-notes.md / transcript.md 停止后由 OpenSpec / OPSX 承接。各参考文件已在对应章节内引用，使用顺序见 references/skill-usage-sequence.md 。