@rpamis/comet 0.1.4 → 0.1.6

package/assets/skills-zh/comet/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: comet
+description: "Comet — OpenSpec + Superpowers 双星开发流程。用 /comet 启动，自动检测阶段并分发到子命令。五阶段：开启 → 深度设计 → 计划与构建 → 验证与收尾 → 归档。"
+---
+
+# Comet — OpenSpec + Superpowers 双星开发流程
+
+OpenSpec 与 Superpowers 如双星系统围绕同一目标运转。OpenSpec 负责 WHAT，Superpowers 负责 HOW。
+
+```
+OpenSpec 负责 WHAT  — 大纲、提案、spec 生命周期、归档
+Superpowers 负责 HOW — 技术设计、计划、执行、收尾
+```
+
+**核心原则：brainstorming 必不可跳过。每次变更都必须经过深度设计（hotfix 和 tweak preset 除外）。**
+
+<IMPORTANT>
+## 阶段衔接
+
+单次 `/comet` 调用会从检测到的阶段开始执行，并在每个阶段退出条件满足后提示或进入下一阶段。
+
+流转链：open → design → build → verify → archive
+
+需要用户参与的节点：
+1. brainstorming 过程中确认设计方案
+2. build 阶段选择执行方式
+3. verify 不通过时决定修复或接受偏差
+4. finishing-branch 选择分支处理方式
+5. 遇到升级条件（hotfix/tweak → 完整流程）
+
+agent 不应跳过这些决策点；其他明确无歧义的阶段衔接可以继续推进。
+</IMPORTANT>
+
+## 阶段自动检测
+
+### Step 0: 活跃 Change 发现
+
+**立即执行：**
+
+1. 运行 `openspec list --json` 获取所有活跃 change
+2. 对每个 change，检查 `docs/superpowers/specs/` 和 `docs/superpowers/plans/` 匹配关联文件，判断阶段和进度
+
+**分支逻辑：**
+
+| 情况 | 行为 |
+|------|------|
+| 无活跃 change | → 调用 `/comet-open` |
+| 恰好 1 个活跃 change | → 自动选中，进入阶段判定（Step 1） |
+| 多个活跃 change | → 列出清单让用户选择 |
+
+**多 change 选择**：使用 AskUserQuestion 展示，格式示例：
+
+```
+| # | Change 名称 | 当前阶段 | 任务进度 |
+|---|------------|---------|---------|
+| 1 | xxx-feature | Build | 3/5 tasks |
+| 2 | yyy-fix | Design | No design doc |
+```
+
+用户选择后，对选中的 change 进入阶段判定。
+
+**Preset 检测**：
+- 如用户明确描述为 bug fix / 热修复，且满足 hotfix 适用条件，直接调用 `/comet-hotfix`（跳过选择）。
+- 如用户明确描述为文案、配置、文档、prompt 或小范围非 bug 调整，且满足 tweak 适用条件，直接调用 `/comet-tweak`（跳过选择）。
+
+### Step 1: Comet 状态元数据读取
+
+优先读取 `openspec/changes/<name>/.comet.yaml`。若该文件不存在，再回退到 `openspec status --change "<name>" --json`、`tasks.md` 和 `docs/superpowers/` 文件检查。
+
+推荐元数据结构：
+
+```yaml
+workflow: full
+phase: build
+design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
+build_mode: subagent-driven-development
+isolation: branch
+verify_mode: light
+verify_result: pending
+verified_at: null
+archived: false
+```
+
+字段含义：
+
+| 字段 | 含义 |
+|------|------|
+| `workflow` | `full`、`hotfix` 或 `tweak` |
+| `phase` | 当前阶段：`open`、`design`、`build`、`verify`、`archive` |
+| `design_doc` | 关联的 Superpowers Design Doc 路径，可为空 |
+| `plan` | 关联的 Superpowers Plan 路径，可为空 |
+| `build_mode` | 已选择的执行方式，可为空 |
+| `isolation` | `branch` 或 `worktree`，工作区隔离方式，默认 `branch` |
+| `verify_mode` | `light` 或 `full`，可为空 |
+| `verify_result` | `pending`、`pass` 或 `fail` |
+| `verified_at` | 验证通过时间，可为空 |
+| `archived` | change 是否已归档 |
+
+### Step 2: 阶段判定
+
+对选中的 change，按以下顺序判断当前状态：
+
+1. **`archived: true` 或 change 已移入 archive** → 流程已完成
+2. **`verify_result: pass` 且 `archived` 不是 `true`** → 调用 `/comet-archive`
+3. **`phase: verify` 或 tasks.md 全部勾选** → 调用 `/comet-verify`
+4. **`phase: build` 或已有 Design Doc 但计划/执行未完成** → 调用 `/comet-build`
+5. **`phase: design` 或有 change 但无 Design Doc** → 调用 `/comet-design`
+6. **无活跃 change 或状态无法判定** → 调用 `/comet-open`
+
+如果元数据与文件状态冲突，以可验证的文件状态为准，并在继续阶段前修正 `.comet.yaml`。
+
+---
+
+## 子命令
+
+| 命令 | 阶段 | 归属 | 产物 |
+|------|------|------|------|
+| `/comet-open` | 1. 开启 | OpenSpec | proposal.md、design.md、tasks.md |
+| `/comet-design` | 2. 深度设计 | Superpowers | Design Doc、delta spec |
+| `/comet-build` | 3. 计划与构建 | Superpowers | 实施计划、代码提交 |
+| `/comet-verify` | 4. 验证与收尾 | Both | 验证报告、分支处理 |
+| `/comet-archive` | 5. 归档 | OpenSpec | delta→main spec 同步、design doc 标注、归档 |
+| `/comet-hotfix` | 预设路径 | Both | 快速修复（跳过 brainstorming） |
+| `/comet-tweak` | 预设路径 | Both | 小改动（跳过 brainstorming 和完整 plan） |
+
+---
+
+## 流程图
+
+```
+/comet
+  ↓ 自动检测
+/comet-open ──→ /comet-design ──→ /comet-build ──→ /comet-verify ──→ /comet-archive
+  (OpenSpec)      (Superpowers)     (Superpowers)     (Both)          (OpenSpec)
+
+/comet-hotfix（预设路径，跳过 brainstorming）
+  open ──→ build ──→ verify ──→ archive
+    ↑ 如触发升级条件 → 补充 Design Doc → 回到完整流程
+
+/comet-tweak（预设路径，跳过 brainstorming 和完整 plan）
+  open ──→ lightweight build ──→ light verify ──→ archive
+    ↑ 如触发升级条件 → 补充 Design Doc → 回到完整流程
+```
+
+---
+
+## 错误处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| `openspec list --json` 失败 | 检查 openspec 是否已安装，提示用户运行 `openspec init` |
+| 子 skill 不可用（如 `superpowers:brainstorming`） | 停止流程，提示安装或启用对应 skill |
+| `.comet.yaml` 格式异常或缺失 | 以文件状态为准（tasks.md、docs/superpowers/），修正元数据后继续 |
+| Maven 编译/测试失败 | 返回 build 阶段修复，不进入 verify |
+| change 目录结构不完整 | 按 `comet-open` 的产物要求补齐缺失文件 |
+
+---
+
+## 快速参考
+
+### 脚本定位
+
+Comet 阶段守卫脚本 `comet-guard.sh` 随 skill 包分发，位于 `comet/scripts/` 目录。
+**不硬编码平台路径**，运行时通过以下命令自定位：
+
+```bash
+COMET_GUARD=$(find . -path '*/comet/scripts/comet-guard.sh' -type f -print -quit)
+bash "$COMET_GUARD" <change-name> <phase>
+```
+
+后续文档中 `bash $COMET_GUARD <change> <phase>` 均指此命令。加载 comet 后，agent 应在 shell 环境中缓存 `COMET_GUARD` 路径，避免重复 `find`。
+
+### 文件结构
+
+```
+openspec/                              # OpenSpec — WHAT
+├── config.yaml
+├── changes/
+│   ├── <name>/                        # 活跃 change
+│   │   ├── .openspec.yaml
+│   │   ├── .comet.yaml
+│   │   ├── proposal.md                # Why + What
+│   │   ├── design.md                  # 高层架构决策
+│   │   ├── specs/<capability>/spec.md # Delta 能力规格
+│   │   └── tasks.md                   # 任务清单
+│   └── archive/YYYY-MM-DD-<name>/     # 已归档
+└── specs/<capability>/spec.md         # 主 specs（归档时从 delta 同步）
+
+docs/superpowers/                      # Superpowers — HOW
+├── specs/YYYY-MM-DD-<topic>-design.md # 设计文档（技术 RFC，归档时标注状态）
+└── plans/YYYY-MM-DD-<feature>.md      # 实施计划（文件头含 change 关联元数据）
+```
+
+### 最佳实践
+
+1. **brainstorming 不可跳过** — 每次变更必须经过深度设计（hotfix 和 tweak 除外）
+2. **delta spec 是活文档** — 阶段 3 期间可自由修改，归档时同步
+3. **保持 tasks.md 同步** — 完成一个勾一个
+4. **频繁提交** — 每个任务一次提交，message 体现设计意图
+5. **先验证再归档** — `/comet-verify` 通过后才执行 `/comet-archive`
+6. **增量更新分级** — 小编辑、中重 brainstorming、大新 change
+7. **Plan 必须关联 change** — 文件头包含 `change:` 和 `design-doc:` 元数据
+8. **归档闭环** — design doc 和 plan 必须标注 `archived-with` 状态
+9. **增量修改已有功能** — 基于 main spec 创建 delta spec 基线，不从零编写
+10. **Preset 有上限** — hotfix/tweak 满足升级条件时及时切换到完整流程

package/assets/skills-zh/comet-archive/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: comet-archive
+description: "Comet 阶段 5：归档。用 /comet-archive 调用。同步 delta spec 到主 spec，归档 change。"
+---
+
+# Comet 阶段 5：归档（Archive）
+
+## 前置条件
+
+- 验证已通过（阶段 4 完成）
+- 分支已处理
+- `openspec/changes/<name>/.comet.yaml` 中 `verify_result: pass`
+
+## 步骤
+
+### 0. 入口状态验证（Entry Check）
+
+在执行任何操作之前，读取并验证当前状态：
+
+**检查清单：**
+1. `openspec/changes/<name>/.comet.yaml` 存在
+2. `phase` 字段的值为 `"archive"`
+3. `verify_result` 字段的值为 `"pass"`
+4. `archived` 字段为 `"false"` 或 null（尚未归档）
+
+**验证方式：**
+- `cat openspec/changes/<name>/.comet.yaml` 读取全部字段
+- 如 `verify_result` 不是 `"pass"`，必须先完成验证
+
+**失败输出：**
+```
+[HARD STOP] Entry check failed for comet-archive
+  Expected: phase=archive, verify_result=pass, archived=false|null
+  Actual:   phase=<实际值>, verify_result=<实际值>, archived=<实际值>
+  Suggestion: Run comet-verify first, or this change was already archived.
+```
+
+验证通过后才进入步骤 1。
+
+### 1. 执行归档
+
+归档前如 `verify_result` 不是 `pass`，停止归档并返回 `/comet-verify`。
+
+**立即执行：** 使用 Skill 工具加载 `openspec-archive-change` 技能。禁止跳过此步骤。
+
+技能加载后，按其指引归档。自动检查：
+1. artifact 完成状态（proposal、design、specs、tasks）
+2. 所有任务已标记 `[x]`
+3. delta specs 同步状态
+
+### 1b. 移动 Comet 状态文件
+
+`openspec-archive-change` 不感知 `.comet.yaml`，因此 Comet 需要在 OpenSpec 归档完成后自行移动该文件：
+
+```bash
+mv openspec/changes/<name>/.comet.yaml openspec/changes/archive/YYYY-MM-DD-<name>/.comet.yaml
+```
+
+【写入验证】移动完成后必须验证：
+  test -f openspec/changes/archive/YYYY-MM-DD-<name>/.comet.yaml
+  确认归档目录中 .comet.yaml 存在
+  如文件不在预期位置，检查 mv 命令是否成功执行。
+
+### 2. Delta Spec 同步
+
+归档时将 delta specs 同步到主 specs：
+
+```
+openspec/changes/<name>/specs/<capability>/spec.md
+       ↓ 同步
+openspec/specs/<capability>/spec.md  ← 主 spec（持久化）
+```
+
+### 3. Design Doc & Plan 处理
+
+归档时同步处理 `docs/superpowers/` 下的关联文件。若目标文件已有 YAML frontmatter，将归档字段合并到现有 frontmatter；若没有 frontmatter，才新建一组 frontmatter。
+
+**3a. Design Doc 一致性标注**
+
+查找 `docs/superpowers/specs/` 中与当前 change 关联的设计文档：
+- 对比 delta spec 最终版与 design doc 内容
+- 如有偏差（实施过程中 spec 发生了增量修改），在 design doc 的 YAML frontmatter 中设置以下元数据：
+
+```yaml
+---
+archived-with: YYYY-MM-DD-<name>
+status: superseded-by-main-spec
+implementation-notes: |
+  <简述实施过程中偏离原设计的关键变化>
+---
+```
+
+- 如完全一致，仅设置：
+
+```yaml
+---
+archived-with: YYYY-MM-DD-<name>
+status: final
+---
+```
+
+**3b. Plan 关联标注**
+
+查找 `docs/superpowers/plans/` 中与当前 change 关联的实施计划，在 YAML frontmatter 中设置相同的 `archived-with` 元数据。
+
+### 4. 归档目录
+
+change 移入归档目录：
+
+```
+openspec/changes/archive/YYYY-MM-DD-<name>/
+├── .openspec.yaml
+├── .comet.yaml
+├── proposal.md
+├── design.md
+├── specs/<capability>/spec.md
+└── tasks.md
+```
+
+### 5. 生命周期闭环
+
+Spec 生命周期在此完成：
+```
+brainstorming → delta spec → 实施（增量修改）→ 验证 → 主 spec 同步 → design doc 标注 → 归档
+```
+
+## 退出条件
+
+- change 已归档（从活跃列表移除）
+- 主 specs 已更新（delta → main 同步完成）
+- 关联 design doc 已标注归档状态
+- 关联 plan 已标注归档状态
+- `.comet.yaml` 中 `archived` 已记录为 `true`
+- **阶段守卫**：运行 `bash $COMET_GUARD <change-name> archive`，全部 PASS 后确认归档完整
+
+归档完成后，在归档目录的 `.comet.yaml` 中更新：
+
+```yaml
+phase: archive
+archived: true
+```
+
+【写入验证】更新完成后必须验证：
+  cat openspec/changes/archive/YYYY-MM-DD-<name>/.comet.yaml
+  确认 phase 行的值为 "archive"
+  确认 archived 行的值为 "true"
+  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+
+## 完成
+
+Comet 流程全部完成。如需开始新工作，调用 `/comet` 或 `/comet-open`。

package/assets/skills-zh/comet-build/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: comet-build
+description: "Comet 阶段 3：计划与构建。用 /comet-build 调用。制定计划并通过 subagent-driven-development 执行实施。"
+---
+
+# Comet 阶段 3：计划与构建（Build）
+
+## 前置条件
+
+- Design Doc 已创建（阶段 2 完成）
+- 活跃 change 存在
+
+## 步骤
+
+### 0. 入口状态验证（Entry Check）
+
+在执行任何操作之前，读取并验证当前状态：
+
+**检查清单：**
+1. `openspec/changes/<name>/.comet.yaml` 存在
+2. `phase` 字段的值为 `"build"`
+3. `design_doc` 字段非 null 且非空
+4. `design_doc` 引用的文件存在（例如 `docs/superpowers/specs/YYYY-MM-DD-topic-design.md`）
+5. `openspec/changes/<name>/proposal.md` 存在且非空
+6. `openspec/changes/<name>/tasks.md` 存在且非空
+
+**验证方式：**
+- `cat openspec/changes/<name>/.comet.yaml` 读取全部字段
+- 用 `ls` 或 `test -f` 确认 design_doc 文件存在
+
+**失败输出：**
+```
+[HARD STOP] Entry check failed for comet-build
+  Expected: phase=build, design_doc=<path> exists
+  Actual:   phase=<实际值>, design_doc=<实际值或文件不存在>
+  Suggestion: Run comet-design first, or verify design_doc file exists.
+```
+
+验证通过后才进入步骤 1。
+
+### 1. 制定计划
+
+**立即执行：** 使用 Skill 工具加载 `superpowers:writing-plans` 技能。禁止跳过此步骤。
+
+技能加载后，按其指引制定计划。计划要求：
+- 保存至 `docs/superpowers/plans/YYYY-MM-DD-<feature>.md`
+- 引用设计文档，拆分为可执行任务
+- **Plan 文件头必须包含关联元数据**：
+
+```yaml
+---
+change: <openspec-change-name>
+design-doc: docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
+---
+```
+
+### 2. 更新计划状态
+
+在 `openspec/changes/<name>/.comet.yaml` 中合并更新以下字段（保留其他字段不变）：
+
+```yaml
+phase: build
+plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
+```
+
+【写入验证】更新完成后必须验证：
+  cat openspec/changes/<name>/.comet.yaml
+  确认 plan 行的值为 "docs/superpowers/plans/YYYY-MM-DD-feature.md"
+  如不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+
+### 3. 工作区隔离
+
+计划已写入当前分支。在开始执行前，选择工作区隔离方式：
+
+| 选项 | 方式 | 说明 |
+|------|------|------|
+| A | 创建分支 | 在当前仓库创建新分支，简单快速 |
+| B | 创建 Worktree | 隔离工作区，完全独立，适合并行开发 |
+
+**推荐规则**：
+- 变更涉及 ≤ 3 个文件 → 推荐 A
+- 需要并行开发、当前分支有未提交工作 → 推荐 B
+
+用户选择后，在 `openspec/changes/<name>/.comet.yaml` 中合并更新 `isolation`（保留其他字段不变）。`isolation` 只允许以下值之一：
+
+- `branch`
+- `worktree`
+
+Few-shot 示例：
+
+```yaml
+# 用户选择创建分支 / A
+isolation: branch
+```
+
+```yaml
+# 用户选择创建 worktree / B
+isolation: worktree
+```
+
+【写入验证】更新完成后必须验证：
+  cat openspec/changes/<name>/.comet.yaml
+  确认 isolation 行的值为 "<branch 或 worktree>"
+  如不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+
+**执行隔离**：
+
+- **branch**：执行 `git checkout -b <change-name>`，后续工作在新分支上进行
+- **worktree**：调用 `superpowers:using-git-worktrees` 技能或使用原生 `EnterWorktree` 工具创建隔离工作区
+
+创建隔离后，确认计划文件可访问（分支方式天然可访问；worktree 方式需确认计划已提交）。
+
+### 4. 选择执行方式
+
+向用户展示计划摘要（任务数、涉及模块），然后询问执行方式：
+
+| 选项 | 技能 | 适用场景 |
+|------|------|---------|
+| A | `superpowers:subagent-driven-development` | 任务独立、复杂度高、需要双阶段审查 |
+| B | `superpowers:executing-plans` | 任务简单、无子agent环境、轻量快速 |
+
+**推荐规则**：
+- 任务数 ≥ 3 → 推荐 A
+- 任务数 ≤ 2 且无跨模块依赖 → 推荐 B
+- 来自 hotfix 路径 → 推荐 B
+
+用户选择后，在 `openspec/changes/<name>/.comet.yaml` 中合并更新 `build_mode`（保留其他字段不变）。`build_mode` 只允许以下值之一：
+
+- `subagent-driven-development`
+- `executing-plans`
+- `direct`（仅 hotfix preset 使用）
+
+Few-shot 示例：
+
+```yaml
+# 用户选择稳健模式 / A
+build_mode: subagent-driven-development
+```
+
+```yaml
+# 用户选择快速模式 / B
+build_mode: executing-plans
+```
+
+【写入验证】更新完成后必须验证：
+  cat openspec/changes/<name>/.comet.yaml
+  确认 build_mode 行的值为 "<subagent-driven-development 或 executing-plans 或 direct>"
+  如不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+
+然后，**立即执行：** 使用 Skill 工具加载对应技能。禁止跳过此步骤。
+
+如所选 Superpowers 技能不可用，停止流程并提示安装或启用对应技能，不要用普通对话替代该步骤。
+
+技能加载后，按其指引执行：
+- 按计划执行任务
+- 完成 tasks.md 勾选（`- [ ]` → `- [x]`）
+- 每个任务完成后提交代码
+
+### 5. Spec 增量更新
+
+实施过程中发现初版 spec 不完整时，按变更规模分级处理：
+
+| 规模 | 触发条件 | 做法 |
+|------|---------|------|
+| 小 | 遗漏验收场景、边界条件 | 直接编辑 delta spec + design.md，追加 tasks.md 任务 |
+| 中 | 接口变更、新增组件、数据流变化 | 重新 `superpowers:brainstorming` 更新 Design Doc + delta spec |
+| 大 | 全新 capability 需求 | `/opsx:new` 创建独立 change |
+
+**50% 阈值判定**：以 tasks.md 初始任务总数为基准，若新增任务数超过该总数的一半，视为超出原计划范围，应考虑拆分为新 change。
+
+**原则**：
+- delta spec 是活文档，本阶段期间随时可修改
+- 每次更新应提交，commit message 说明变更原因
+- 不提前同步到 main spec，归档时统一同步
+- 如增量任务超过原 tasks.md 初始任务总数 50%，考虑拆分为新 change
+- 小规模增量直接改 delta spec 时，应在 commit message 中注明，便于归档时判断 design doc 漂移
+
+## 退出条件
+
+- tasks.md 全部勾选
+- 代码已提交
+- 测试通过
+- `.comet.yaml` 中 `phase` 已更新为 `verify`
+- **阶段守卫**：运行 `bash $COMET_GUARD <change-name> build`，全部 PASS 后才允许流转
+
+退出前在 `.comet.yaml` 中合并更新以下字段（保留其他字段不变）：
+
+```yaml
+phase: verify
+verify_result: pending
+```
+
+【写入验证】更新完成后必须验证：
+  cat openspec/changes/<name>/.comet.yaml
+  确认 phase 行的值为 "verify"
+  确认 verify_result 行的值为 "pending"
+  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+
+## 自动流转
+
+退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段：
+
+> **REQUIRED NEXT SKILL:** 调用 `comet-verify` skill 进入验证与收尾阶段。

package/assets/skills-zh/comet-design/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: comet-design
+description: "Comet 阶段 2：深度设计。用 /comet-design 调用。通过 brainstorming 产出 Design Doc 和 delta spec。"
+---
+
+# Comet 阶段 2：深度设计（Design）
+
+## 前置条件
+
+- 活跃 change 已存在（proposal.md、design.md、tasks.md）
+- 无 Design Doc（`docs/superpowers/specs/` 下无对应文件）
+
+## 步骤
+
+### 0. 入口状态验证（Entry Check）
+
+在执行任何操作之前，读取并验证当前状态：
+
+**检查清单：**
+1. `openspec/changes/<name>/.comet.yaml` 存在
+2. `phase` 字段的值为 `"design"`
+3. `workflow` 字段的值为 `"full"`
+4. `design_doc` 字段为 `null` 或空
+5. `openspec/changes/<name>/proposal.md` 存在且非空
+6. `openspec/changes/<name>/design.md` 存在且非空
+7. `openspec/changes/<name>/tasks.md` 存在且非空
+
+**验证方式：**
+- `cat openspec/changes/<name>/.comet.yaml` 读取全部字段
+- 逐条比对检查清单
+
+**失败输出：**
+```
+[HARD STOP] Entry check failed for comet-design
+  Expected: phase=design, design_doc=<empty/null>, workflow=full
+  Actual:   phase=<实际值>, design_doc=<实际值>, workflow=<实际值>
+  Suggestion: Run comet-open first, or check if .comet.yaml was modified out of sequence.
+```
+
+验证通过后才进入步骤 1。
+
+### 1a. 读取已有上下文
+
+读取活跃 change 下的 `proposal.md` 和 `design.md`，将核心内容整理为摘要：
+- **proposal 摘要**：目标、动机、范围
+- **design 摘要**：架构决策、高层设计
+
+### 1b. 执行 Brainstorming（带上下文）
+
+**立即执行：** 使用 Skill 工具加载 `superpowers:brainstorming` 技能，ARGUMENTS 包含：
+
+```
+Change: <change-name>
+Proposal 摘要: <proposal 核心内容>
+Design 摘要: <design.md 架构决策>
+跳过上下文探索，直接进入设计提问。
+```
+
+禁止跳过此步骤，禁止在未加载该技能的情况下继续。
+
+如 `superpowers:brainstorming` 不可用，停止流程并提示安装或启用 Superpowers 技能，不要用普通对话替代该步骤。
+
+技能加载后，按其指引产出：
+- `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` — 设计文档（技术 RFC）
+- `openspec/changes/<name>/specs/<capability>/spec.md` — 能力规格（delta）
+
+### 2. 更新 Comet 状态
+
+在 `openspec/changes/<name>/.comet.yaml` 中合并更新以下字段（保留其他字段不变）：
+
+```yaml
+phase: build
+design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+```
+
+【写入验证】更新完成后必须验证：
+  cat openspec/changes/<name>/.comet.yaml
+  确认 phase 行的值为 "build"
+  确认 design_doc 行的值为 "docs/superpowers/specs/YYYY-MM-DD-topic-design.md"
+  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+
+### 3. 双 Spec 分工
+
+| Spec 类型 | 归属 | 存放位置 | 定义 |
+|-----------|------|---------|------|
+| 能力规格 | OpenSpec | `openspec/changes/<name>/specs/` | 系统应该做什么（需求 + 验收场景） |
+| 设计文档 | Superpowers | `docs/superpowers/specs/` | 怎么构建（技术架构 + 实现细节） |
+
+### 4. 文档层级确认
+
+```
+proposal.md（阶段 1）              → Why + What
+design.md（阶段 1，OpenSpec）      → 高层架构决策
+设计文档（阶段 2，Superpowers）     → 深度技术设计
+能力规格（阶段 2，delta）           → 需求 + 验收场景
+```
+
+## 退出条件
+
+- Design Doc 已创建并保存
+- 如有新能力则 delta spec 已创建
+- **阶段守卫**：运行 `bash $COMET_GUARD <change-name> design`，全部 PASS 后才允许流转
+
+## 自动流转
+
+退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段：
+
+> **REQUIRED NEXT SKILL:** 调用 `comet-build` skill 进入计划与构建阶段。