Skip to content

SKILL.md

Latest commit

 

History

History
242 lines (159 loc) · 14.3 KB

SKILL.md

File metadata and controls

242 lines (159 loc) · 14.3 KB
Raw
name comet-open
description Use when Comet 需要创建新的 OpenSpec change，或 active change 缺少 proposal/design/tasks/.comet.yaml 初始化产物。

Comet 阶段 1：开启（Open）

前置条件

  • 无活跃 change，或用户希望创建新 change

步骤

0. 输出语言约束

传递给 OpenSpec 的所有提问和产物要求都必须包含解析后的 Comet 产物语言，并使用 en、zh-CN 这类规范化 ID。.comet.yaml 尚不存在时依次读取项目 .comet/config.yaml 和全局 ~/.comet/config.yaml 的 language；change 初始化后使用 "$COMET_BASH" "$COMET_STATE" get <name> language 读取。没有配置语言时才回退到当前用户请求语言。生成的 proposal.md、design.md、tasks.md 必须以该语言为主语言。

0a. 当前 change 绑定

恢复已有 change 时，第一项状态操作必须是：

comet state select <change-name>

创建新 change 时，必须先完成 .comet.yaml 初始化，再立即运行同一命令；状态文件不存在前不得伪造选择。

1. 探索想法与需求澄清

立即执行： 使用 Skill 工具加载 openspec-explore 技能。禁止跳过此步骤。

技能加载后，按其指引探索问题空间，但不得把一次问答视为足够澄清。必须围绕下列内容继续提问、对齐并形成澄清摘要：

  • 目标：用户真正要解决的问题和期望结果
  • 非目标：本次明确不做的内容
  • 范围边界：涉及/不涉及的模块、用户、平台或数据
  • 关键未知项：仍不确定的假设、风险或依赖
  • 验收场景草案：至少覆盖核心成功场景和关键边界场景

澄清摘要必须包含：目标、非目标、范围边界、关键未知项、验收场景草案。

1a. PRD 拆分预检（阻塞点）

当用户输入是大型 PRD、路线图、完整产品方案，或澄清摘要显示包含多个独立能力、模块、用户路径或里程碑时，必须在创建 OpenSpec artifacts 前评估是否需要拆分为多个 change。

拆分预检必须基于已澄清的信息，输出候选拆分清单。每个候选拆分项必须包含：

  • 建议 change 名称
  • 目标与范围边界
  • 明确非目标
  • 依赖关系或推荐执行顺序
  • 对应的核心验收场景

满足任一条件时，应推荐拆分：

  • PRD 包含多个可独立设计、构建、验证、归档的 capability
  • 涉及多个模块或用户路径，且其中一部分可独立交付
  • 存在明显分阶段里程碑
  • 预计会产生多个 delta spec 或超过 3 个大任务
  • 任一部分失败或延期不应阻塞其他部分进入后续阶段

如推荐拆分，必须按 comet/reference/decision-point.md 的协议暂停并等待用户选择。

用户选择必须包含：

  • 「创建多个 OpenSpec changes」— 按候选拆分逐个创建独立 change
  • 「保持为一个 change」— 继续单 change 流程，并在 proposal/design/tasks 中记录不拆分原因
  • 「调整拆分方案后继续」— 用户说明调整方向后，重新输出候选拆分清单并再次确认

每个被接受的拆分项都必须通过 /comet-open 创建独立 change，不得直接调用 /opsx:new。/comet-open 负责同时创建 OpenSpec artifacts 和 .comet.yaml，确保每个 change 都进入 Comet 状态机。

不得在用户完成 PRD 拆分选择前创建 proposal.md、design.md 或 tasks.md。若用户选择创建多个 change，当前 /comet-open 调用只负责完成拆分确认与调度，随后按用户确认的顺序分别进入每个拆分项的 /comet-open。

批量拆分模式下，进入每个拆分项的 /comet-open 时必须明确标注「已确认拆分项」并携带该拆分项的目标、范围、非目标和验收场景。已确认拆分项默认跳过 PRD 拆分预检，除非该拆分项本身仍明显包含多个独立 capability。

批量拆分模式下，单个拆分项完成 open 阶段后不得自动流转到 /comet-design。

批量完成硬性检查（不得跳过）：全部拆分项完成各自的 open 阶段后，对用户确认清单中的每个 <name> 逐个运行：

openspec status --change "<name>" --json
comet state check <name> design

解析 OpenSpec JSON 时必须同时确认：

  • isComplete 必须为 true
  • artifacts 中每一项的 status 必须为 done
  • artifactPaths 中 CLI 返回的已有输出路径必须存在且非空；不得用固定文件名清单代替 CLI 状态

任一拆分项未通过检查时，不得宣告拆分完成，也不得询问用户开始哪个 change；必须停止并从该 change 的第一个 ready 或 blocked artifact 恢复 /comet-open。OpenSpec 检查通过但 Comet state 检查失败时，必须先修复 .comet.yaml 初始化或 phase，再重新执行整批检查。

只有所有拆分项都通过两项 CLI 检查后，才暂停询问用户开始哪一个 change；用户选择后，只推进该 change 进入 /comet-design，其他 change 保持 active，稍后通过 /comet 恢复。

最小断点恢复规则：不新增专用批量状态文件。若批量拆分过程中断，恢复时先对已创建的 active changes 运行上述 CLI 检查；已完整通过的拆分项不得重复创建，未通过的拆分项从 OpenSpec 返回的第一个未完成 artifact 继续。未创建的拆分项按用户已确认的拆分清单继续通过 /comet-open 创建。若对话中已确认的拆分清单不可恢复，必须重新向用户确认拆分清单后再继续。

1b. 需求澄清完成确认（阻塞点）

创建 OpenSpec artifacts 前，必须按 comet/reference/decision-point.md 的协议暂停并等待用户确认需求澄清完成。

暂停时必须展示澄清摘要：目标、非目标、范围边界、关键未知项、验收场景草案。

不得在用户确认需求澄清完成前创建 proposal.md、design.md 或 tasks.md，也不得使用 Skill 工具加载 openspec-propose 技能一次性生成全部 artifacts。

1c. Change 名称确认（阻塞点）

创建 change 目录（openspec new change）前，必须按 comet/reference/decision-point.md 的协议暂停，让用户决定 change 名称。不得自动生成或静默推断 change 名称。

OpenSpec change 名称必须是 kebab-case 英文（小写字母、数字、连字符；如 refine-requirements-doc）。中文或其他不合规名称无效。

暂停时必须展示：

  • 基于已确认澄清摘要派生的 2-3 个推荐 kebab-case 英文名，每个附一行说明其隐含范围
  • 一个让用户 自行输入名称 的明确选项
  • 提示：若用户输入中文（或任何非 kebab-case 文本），会被转换为合规的 kebab-case 英文名，转换结果必须回显给用户确认后才能使用

决策选项必须包含：

  • 选择某个推荐名称
  • 「自行输入名称」——接收用户输入；若已是合规 kebab-case 英文则直接使用；若为中文或其他不合规形式，则转换为合规 kebab-case 英文并回显转换后的名称，确认后再继续

不得在用户确认最终 change 名称前运行 openspec new change 或创建 .comet.yaml。若选定/转换后的名称与已有 change 冲突，必须报告冲突并请用户另选名称。

2. 创建 Change 结构 + 初始化状态

立即执行： 使用 Skill 工具加载 openspec-new-change 技能。禁止跳过此步骤。

完整 /comet 流程默认不得使用 Skill 工具加载 openspec-propose 技能；只有用户明确要求一次性生成提案和 artifacts 时才允许加载。

技能加载后，按其指引创建 change 骨架，但当 Step 1b 的已确认澄清摘要已存在于对话上下文时，覆盖其"STOP and wait for user direction"行为。

如果用户已确认澄清摘要（Step 1b），直接使用该摘要填充产物内容。如果不存在澄清摘要（边缘情况），回退到技能的默认行为，询问用户。

change 骨架创建后，必须按 OpenSpec CLI 返回的 schema 和依赖图生成全部 artifacts，直到 CLI 明确报告完成：

OpenSpec 状态驱动产物循环：

  1. 运行 openspec status --change "<name>" --json 并解析完整 JSON。

  2. 若 isComplete: true，退出循环并进入 .comet.yaml 初始化；否则继续。

  3. 从 artifacts 中选择所有 status: "ready" 的项，按 CLI 返回顺序逐个处理。不得硬编码 artifact 顺序，也不得假设 schema 只有 proposal/design/tasks。

  4. 对每个 ready 的 <artifact-id> 获取实时指令：

    openspec instructions <artifact-id> --change "<name>" --json

  5. 对返回的 JSON 指令载荷，必须：

    • 读取 dependencies 中列出的每个已完成依赖产物
    • 以 template 作为产物结构
    • 遵循 instruction 的指引
    • 将 context 和 rules 作为约束条件应用，不得复制到 artifact 内容中
    • 写入 resolvedOutputPath；通配输出必须按 instruction 创建每个实际文件
    • 验证 CLI 返回的实际输出文件存在且非空

  6. 每创建一个 artifact 后，重新运行 status。已经变为 done 的项不得重复生成；新变为 ready 的项进入下一轮。

阻塞与失败处理：isComplete: false 时若没有任何 ready artifact，必须报告每个 blocked artifact 的 missingDeps 并停止，不得猜测顺序或跳过依赖。如果 openspec status / openspec instructions 失败、返回无效 JSON、或未提供可用的 resolvedOutputPath，也必须立即停止并报告 OpenSpec 错误。不得回退为硬编码文档结构。

命名与范围守卫：change name 必须使用 Step 1c 中用户确认的 kebab-case 英文名，不得自动生成、推断或使用非 kebab-case（如中文）名称。变更范围必须与用户描述一致，不得自行扩大或缩小。

确认以下产物已创建：

openspec/changes/<name>/
├── .openspec.yaml
├── .comet.yaml
├── proposal.md       # Why + What：问题、目标、范围
├── design.md         # How（高层框架）：架构决策、方案选型（深度技术设计在 design 阶段 Design Doc 细化）
└── tasks.md          # 任务清单（勾选框）

创建 .comet.yaml 状态文件：

先按 comet/reference/scripts.md 定位脚本（定位 comet-env.mjs），然后初始化状态：

node "$COMET_STATE" init <name> full

3. 入口状态验证

验证状态机已正确初始化：

node "$COMET_STATE" check <name> open

验证通过后继续 Step 4。验证失败时脚本会输出具体失败原因。

幂等恢复算法：open 阶段所有操作可安全重复执行。恢复时按以下顺序处理：

  1. 运行 openspec status --change "<name>" --json，读取最新的 isComplete、artifacts 和 missingDeps。
  2. done：该 artifact 已完成，保持原文件不变，不重复生成。
  3. ready：依赖已经满足，可以立即生成。先运行该 artifact 的 openspec instructions，按返回内容写入；写完后立刻重新运行 status，再决定下一步。
  4. blocked：当前不可生成，不是等待用户或等待时间。读取它的 missingDeps，在 artifacts 中找到对应依赖，先完成 missingDeps 列出的依赖 artifact；每完成一个依赖都重新运行 status，不能直接生成 blocked artifact。
  5. 重复上述处理，直到 status 返回 isComplete: true。

如果 isComplete: false 且没有任何 ready artifact，说明依赖图当前无法推进；必须列出每个 blocked artifact 及其 missingDeps 后停止并报告，不得猜测顺序或跳过依赖。只有 isComplete: true 才表示 OpenSpec open 产物全部完成；目录、.comet.yaml 或固定三个文件存在都不能替代这一判定。

4. 内容完整性检查

再次运行 openspec status --change "<name>" --json，确认 isComplete: true，artifacts 每项均为 done，且 artifactPaths 返回的实际输出文件存在且非空。任一条件不满足时，不得进入 Step 5 或执行阶段守卫。

随后检查关键 artifact 内容：proposal 覆盖问题、目标、范围和非目标；design 覆盖高层决策与数据流；tasks 包含明确任务；schema 返回 specs 等其他 artifact 时，也必须按其 instructions 检查内容，不能因固定三件套存在而跳过。

5. 用户审视确认（阻塞点）

全部 OpenSpec artifacts 完成且内容完整性检查通过后，必须按 comet/reference/decision-point.md 的协议暂停并等待用户确认。不得在用户确认前执行阶段守卫或自动流转。

用户确认问题必须以单选题形式呈现，包含以下摘要和选项：

摘要内容：

  • proposal.md：问题背景、目标、范围
  • specs 等 schema artifacts：能力、需求和关键验收场景
  • design.md：高层架构决策、方案选型
  • tasks.md：任务数量和关键任务描述

选项：

  • 「确认，继续下一阶段」— 产物符合预期，执行阶段守卫流转
  • 「需要调整」— 附带调整说明，修改后重新请求确认

用户选择「确认」后继续执行退出条件。用户选择「需要调整」时，按其说明修改对应文件，然后重新请求确认。

退出条件

  • openspec status --change "<name>" --json 返回 isComplete: true，全部 artifacts 均为 done 且实际输出非空
  • 用户已确认 全部 OpenSpec artifacts 内容符合预期
  • 阶段守卫：运行 node "$COMET_GUARD" <change-name> open --apply，全部 PASS 后由守卫推进到下一阶段（此步骤更新 phase 字段，与 auto_transition 无关）

退出前必须使用 --apply，否则 .comet.yaml 仍停留在 phase: open，下一阶段入口检查会失败。

node "$COMET_GUARD" <change-name> open --apply

完整流程会自动更新为 phase: design；hotfix/tweak 预设会自动更新为 phase: build。

自动衔接下一阶段

按 comet/reference/auto-transition.md 执行。关键命令：

node "$COMET_STATE" next <change-name>
  • NEXT: auto → 调用 SKILL 指向的 skill 进入下一阶段
  • NEXT: manual → 不要调用下一 skill，按 HINT 提示用户手动运行 /<SKILL>
  • NEXT: done → 流程已完成，无需继续

hotfix/tweak 预设由对应预设 Skill 控制后续流转（phase 直接进入 build），其 next 会返回对应预设 Skill。