@rpamis/comet 0.3.5 → 0.3.7

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

@@ -23,7 +23,7 @@ if [ -z "$COMET_ENV" ]; then
   return 1
 fi
 . "$COMET_ENV"
-bash "$COMET_STATE" check <name> design
+"$COMET_BASH" "$COMET_STATE" check <name> design
 ```
 
 验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
@@ -35,16 +35,25 @@ bash "$COMET_STATE" check <name> design
 **必须由脚本生成，不允许 agent 临场手写 summary 代替。**
 
 ```bash
-bash "$COMET_HANDOFF" <change-name> design --write
+"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write
 ```
 
-脚本会生成并记录：
+脚本会根据 change `.comet.yaml` 的 `context_compression` 快照生成并记录交接包。
 
-```
+默认 `context_compression: off` 时生成：
+
+```text
 openspec/changes/<name>/.comet/handoff/design-context.json
 openspec/changes/<name>/.comet/handoff/design-context.md
 ```
 
+启用 beta（项目 `.comet/config.yaml` 中 `context_compression: beta`，创建 change 时快照进入 `.comet.yaml`）时生成：
+
+```text
+openspec/changes/<name>/.comet/handoff/spec-context.json
+openspec/changes/<name>/.comet/handoff/spec-context.md
+```
+
 并在 `.comet.yaml` 写入：
 
 ```yaml
@@ -57,10 +66,15 @@ handoff_hash: <sha256>
 - `design-context.md`：供 Superpowers 阅读的上下文，包含脚本标记、source path、line range、sha256、确定性摘录
 - 超出摘录预算时标记 `[TRUNCATED]`，并保留 Full source 路径
 
+beta 交接包是 **结构化 spec projection**，用于减少 OpenSpec 原文 token 占用但避免实现漂移：
+- `spec-context.json`：机器索引，包含 change、phase、mode=beta、source paths、context_hash、files 角色
+- `spec-context.md`：供 Superpowers 阅读的紧凑上下文，verbatim 投影 delta spec 文件并按 hash 引用支撑产物
+- OpenSpec delta spec 仍是 canonical spec；projection 缺失或过期时必须重新生成或读取源 spec，不得用 agent summary 替代
+
 如确实需要全文上下文，可显式运行：
 
 ```bash
-bash "$COMET_HANDOFF" <change-name> design --write --full
+"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write --full
 ```
 
 交接包来源来自 OpenSpec open 阶段产物：
@@ -71,16 +85,29 @@ bash "$COMET_HANDOFF" <change-name> design --write --full
 
 ### 1b. 执行 Brainstorming（带上下文）
 
-**立即执行：** 使用 Skill 工具加载 `superpowers:brainstorming` 技能，ARGUMENTS 包含：
+**立即执行：** 使用 Skill 工具加载 Superpowers `brainstorming` 技能。禁止跳过此步骤。
+
+技能加载时，ARGUMENTS 必须包含：
 
+```text
+Language: 使用触发本次工作流的用户请求语言输出
 ```
+
+技能加载后，按其指引使用以下上下文：
+
+```text
 Change: <change-name>
 OpenSpec Context Pack: openspec/changes/<name>/.comet/handoff/design-context.md
 Machine handoff: openspec/changes/<name>/.comet/handoff/design-context.json
 
-OpenSpec 产物是上游事实源，不要重新定义需求，不要重写 proposal/spec。
+如 context_compression: beta，则使用：
+OpenSpec Context Pack: openspec/changes/<name>/.comet/handoff/spec-context.md
+Machine handoff: openspec/changes/<name>/.comet/handoff/spec-context.json
+
+OpenSpec 产物是上游事实源，但不得用“跳过重复上下文探索”削弱 Superpowers `brainstorming` 的澄清流程。
 你的任务是基于交接包做深度技术设计：实现方案、技术风险、测试策略、边界条件。
-如发现 OpenSpec delta spec 缺少验收场景，只能提出 Spec Patch，并回写 OpenSpec delta spec；不要在 Design Doc 中创建第二份需求 spec。
+如发现目标、范围、非目标、验收场景或关键约束仍不清楚，必须先继续提问并形成设计方案，不得只进行一轮问答就创建 Design Doc。
+不要重写 proposal/spec；如发现 OpenSpec delta spec 缺少验收场景，只能提出 Spec Patch，并回写 OpenSpec delta spec；不要在 Design Doc 中创建第二份需求 spec。Spec Patch 仅限于补充验收场景、修正歧义描述或添加边界条件，不得大幅重写 delta spec 的结构或范围——如需大幅修改，应标记为设计发现并回到 brainstorming 确认。
 
 Design Doc frontmatter 必须最小化，只包含：
 ---
@@ -89,23 +116,26 @@ role: technical-design
 canonical_spec: openspec
 ---
 
-跳过重复上下文探索，直接进入设计提问。
+按 Superpowers `brainstorming` 技能原流程推进：澄清问题、2-3 个方案、分段确认设计。不得提前写入 Design Doc。
 ```
 
-禁止跳过此步骤，禁止在未加载该技能的情况下继续。
+禁止在未加载该技能的情况下继续。
 
-如 `superpowers:brainstorming` 不可用，停止流程并提示安装或启用 Superpowers 技能，不要用普通对话替代该步骤。
+如 Superpowers `brainstorming` 技能不可用，停止流程并提示安装或启用 Superpowers 技能，不要用普通对话替代该步骤。
 
 技能加载后，按其指引产出设计方案（以对话形式呈现）：
 - 技术方案：架构、数据流、关键技术选型与风险
 - 测试策略
+- 需求/范围缺口与需回写的 Spec Patch
 - 如需补充验收场景，标明将回写的 delta spec 变更
 
 brainstorming 阶段不写入 Design Doc 文件，仅产出设计方案供 Step 1c 用户确认。确认后才创建 `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` 并回写 delta spec。
 
+但为了上下文压缩恢复，brainstorming 过程中必须增量更新 `brainstorm-summary.md`。每轮澄清或方案迭代后，只要产生新的已确认事实、关键约束、候选方案、取舍/风险、测试策略或 Spec Patch 候选，就更新该文件；未确认内容必须标注为“待确认”或“候选”。该文件是恢复检查点，不是 Design Doc，也不得替代 Step 1c 的用户确认。
+
 ### 1c. 用户确认设计方案（阻塞点）
 
-brainstorming 产出设计方案后，**必须使用 AskUserQuestion 工具暂停并等待用户明确确认设计方案**。不得在用户确认前创建最终 Design Doc、写入 `design_doc`、运行 design guard，或进入 `/comet-build`。也不得仅输出文字提示后继续执行。
+brainstorming 产出设计方案后，**必须使用当前平台可用的用户输入/确认机制暂停并等待用户明确确认设计方案**。不得在用户确认前创建最终 Design Doc、写入 `design_doc`、运行 design guard，或进入 `/comet-build`。若当前平台没有结构化提问工具，则在对话中提出确认问题并停止流程，等待用户回复后才能继续。
 
 暂停时只展示必要摘要：
 - 采用的技术方案
@@ -115,19 +145,86 @@ brainstorming 产出设计方案后，**必须使用 AskUserQuestion 工具暂
 
 用户明确确认后，才继续 Step 2。若用户要求调整，继续 brainstorming 迭代，直到用户确认。
 
-### 2. 更新 Comet 状态
 
-先记录 design_doc 路径。如果 Step 1c 回写了 delta spec（新增或修改了 `specs/*/spec.md`），必须重新生成 handoff 以更新 hash：
+### 1d. Brainstorming 检查点定稿
+
+用户确认设计方案后，在创建 Design Doc 前，创建或更新已增量维护的检查点文件，将其定稿为确认后的设计方案摘要：
+
+```bash
+mkdir -p openspec/changes/<name>/.comet/handoff
+```
+
+`openspec/changes/<name>/.comet/handoff/brainstorm-summary.md` 结构：
+
+```markdown
+# Brainstorm Summary
+
+- Change: <change-name>
+- Date: <YYYY-MM-DD>
+
+## 确认的技术方案
+
+<用户确认的方案摘要>
+
+## 关键取舍与风险
+
+<主要取舍和风险>
+
+## 测试策略
+
+<测试方法概述>
+
+## Spec Patch
+
+<将回写的 delta spec 变更，无则写"无">
+```
+
+**上下文压缩说明**：每次增量更新 `brainstorm-summary.md` 后，都是相对安全的压缩恢复点。Brainstorming 完成后，如上下文窗口紧张，应优先在此处进行压缩。压缩后重新加载以下文件继续 Step 2：
+- `openspec/changes/<name>/.comet/handoff/brainstorm-summary.md`
+- `openspec/changes/<name>/.comet/handoff/design-context.md`（或 beta 模式的 `spec-context.md`）
+- `openspec/changes/<name>/.comet/handoff/design-context.json`（或 beta 模式的 `spec-context.json`）
+
+### 1e. 主动上下文压缩门
+
+完成 Step 1d 并确认 `brainstorm-summary.md` 已写入后，进入 Design Doc 创建前的主动压缩门。此时 OpenSpec 交接包、brainstorming 决策和待确认项都已落盘，应主动释放前面读取 Spec 和 brainstorming 消耗的上下文，为 Step 2 及后续 Build 阶段保留窗口。
+
+执行规则：
+- 如果当前平台提供原生上下文压缩/清理机制（例如宿主 Agent 的 compact/compaction 命令、工具或 UI 操作），必须在这里触发一次主动压缩；不要尝试用 shell 脚本伪造压缩命令。
+- 压缩恢复提示必须包含 change 名称、当前步骤（Design Step 2）、以及上方三类需重新加载的 handoff 文件。
+- 如果当前平台无法由 agent 程序化触发压缩，必须暂停并提示用户在宿主平台执行手动压缩；用户确认无法压缩或要求继续时，才继续 Step 2。
+
+### 2. 创建 Design Doc
+
+基于 brainstorming 对话的完整上下文（仍在主 session 中），创建 Design Doc。
+
+Design Doc frontmatter 必须最小化：
+
+```yaml
+---
+comet_change: <change-name>
+role: technical-design
+canonical_spec: openspec
+---
+```
+
+将 Design Doc 写入 `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`。
+如需回写 delta spec（Spec Patch），同时编辑对应的 `specs/*/spec.md`。
+
+**上下文压缩恢复**：若上下文已被压缩，从 `brainstorm-summary.md` + handoff 上下文恢复。若用户尚未确认设计方案，回到 Step 1b/1c 继续 brainstorming；若用户已确认，继续创建 Design Doc。brainstorm-summary.md 是压缩恢复的落盘点，不是 Design Doc 的唯一输入——创建时应尽可能利用恢复后的完整上下文。
+
+### 3. 更新 Comet 状态
+
+先记录 design_doc 路径。如果 Spec Patch 回写了 delta spec（新增或修改了 `specs/*/spec.md`），必须重新生成 handoff 以更新 hash：
 
 ```bash
 # 记录 design_doc 路径
-bash "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+"$COMET_BASH" "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
 
 # 如有 delta spec 变更，重新生成 handoff（更新 hash）
-bash "$COMET_HANDOFF" <change-name> design --write
+"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write
 
-# 自动流转到下一阶段
-bash "$COMET_GUARD" <change-name> design --apply
+# 阶段守卫推进 phase 到下一阶段
+"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply
 ```
 
 如果没有 delta spec 变更，跳过 handoff 重新生成步骤。状态文件自动更新，无需手动编辑其他字段。
@@ -138,15 +235,16 @@ bash "$COMET_GUARD" <change-name> design --apply
 - Design Doc frontmatter 包含 `comet_change`、`role: technical-design`、`canonical_spec: openspec`
 - `handoff_context` 和 `handoff_hash` 已写入 `.comet.yaml`（由 guard 强制校验）
 - `handoff_hash` 与当前 OpenSpec open 阶段产物一致（由 guard 强制校验）
-- `design-context.md` 必须是脚本生成，且包含 source path、mode、sha256 等可追溯标记（由 guard 强制校验）
+- `design-context.md` 或 beta `spec-context.md` 必须是脚本生成，且包含 source path、mode、sha256 等可追溯标记（由 guard 强制校验）
+- beta 模式下，`spec-context.json` 必须结构合法且引用当前源文件（由 guard 强制校验）
 - 如有新能力或补充验收场景，OpenSpec delta spec 已创建/更新
 - `design_doc` 已写入 `.comet.yaml`
-- **阶段守卫**：运行 `bash "$COMET_GUARD" <change-name> design --apply`，全部 PASS 后自动流转到 `phase: build`
+- **阶段守卫**：运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply`，全部 PASS 后由守卫推进到 `phase: build`（此步骤更新 `phase` 字段，与 `auto_transition` 无关）
 
 退出前必须使用 `--apply`：
 
 ```bash
-bash "$COMET_GUARD" <change-name> design --apply
+"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply
 ```
 
 ## 上下文压缩恢复
@@ -154,13 +252,22 @@ bash "$COMET_GUARD" <change-name> design --apply
 design 阶段在 brainstorming 过程中可能触发上下文压缩。恢复时先运行：
 
 ```bash
-bash "$COMET_STATE" check <change-name> design --recover
+"$COMET_BASH" "$COMET_STATE" check <change-name> design --recover
 ```
 
 脚本输出结构化恢复上下文（阶段、已完成字段、待完成字段、恢复动作）。按 Recovery action 判断下一步。
 
-## 自动流转
+## 自动衔接下一阶段
+
+> **术语区分**：上面的「阶段守卫推进」由 guard `--apply` 完成，更新 `.comet.yaml` 的 `phase` 字段——这一步**始终发生**，与 `auto_transition` 无关。本节的「自动衔接」只决定**是否自动调用下一个 skill**，由 `auto_transition` 控制。
 
-退出条件满足后（包括用户确认设计方案），自动流转到下一阶段：
+阶段守卫推进 phase 后，运行：
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <change-name>
+```
 
-> **REQUIRED NEXT SKILL:** 调用 `comet-build` skill 进入计划与构建阶段。
+脚本根据 `phase`、`workflow`、`auto_transition` 输出确定性的下一步：
+- `NEXT: auto` → 调用 `SKILL` 指向的 skill 进入下一阶段
+- `NEXT: manual` → 不要调用下一 skill，按 `HINT` 提示用户手动运行 `/<SKILL>`
+- `NEXT: done` → 流程已完成，无需继续

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

@@ -16,9 +16,13 @@ description: "Comet 预设路径：Bug fix / 热修复。跳过 brainstorming，
 
 ---
 
-## 流程（preset workflow，5 阶段）
+## 流程（preset workflow，6 步）
 
-执行链路：open → build → verify → archive。Hotfix 为每个阶段提供默认决策：精简开启、直接构建、按规模验证、验证通过后归档。
+### 0. 输出语言约束
+
+精简版 OpenSpec 产物必须使用触发本次工作流的用户请求语言。
+
+执行链路：open → build → verify → archive。Hotfix 为每个阶段提供默认决策：精简开启、直接构建、按规模验证、验证通过后进入归档前最终确认。
 
 开始前先定位 Comet 脚本：
 
@@ -46,24 +50,33 @@ fi
 初始化 Comet 状态文件：
 
 ```bash
-bash "$COMET_STATE" init <name> hotfix
+"$COMET_BASH" "$COMET_STATE" init <name> hotfix
 ```
 
 初始化后验证状态：
 
 ```bash
-bash "$COMET_STATE" check <name> open
+"$COMET_BASH" "$COMET_STATE" check <name> open
 ```
 
 阶段守卫完成 open → build 过渡：
 
 ```bash
-bash "$COMET_GUARD" <change-name> open --apply
+"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
+```
+
+检查 `auto_transition` 决定是否继续：
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <name>
 ```
 
+- `NEXT: auto` → 继续 Step 2
+- `NEXT: manual` → 暂停，按 `HINT` 提示用户手动运行 `/<SKILL>`
+
 ### 2. 直接构建（preset build）
 
-使用 hotfix 默认值：`build_mode: direct`。跳过 `superpowers:brainstorming` 和 `superpowers:writing-plans`（除非任务 > 3 个；若超过 3 个任务，转入 `/comet-build` 的计划与执行方式选择）。
+使用 hotfix 默认值：`build_mode: direct`。跳过 Superpowers `brainstorming` 和 `writing-plans`（除非任务 > 3 个；若超过 3 个任务，转入 `/comet-build` 的计划与执行方式选择——注意这不触发 full workflow 升级，仅切换执行方式）。
 
 继续或开始修改前，按 `comet/reference/dirty-worktree.md` 协议处理未提交改动。若归因后发现修复范围超出 hotfix，按本文件“升级条件”处理。
 
@@ -78,6 +91,14 @@ bash "$COMET_GUARD" <change-name> open --apply
    - 提交代码，commit message 格式：`fix: <简述修复>`
 3. 全部任务完成后，显式运行项目相关测试和构建命令
 
+执行 hotfix 期间，只要运行程序、测试、构建或手动验证时出现崩溃、异常行为、测试失败或构建失败，必须使用 Skill 工具加载 Superpowers `systematic-debugging` 技能。在完成根因调查前，不得提出或实施源码修复。
+
+按 `systematic-debugging` 的四阶段流程处理：
+- 先复现并定位根因，读取完整错误、检查近期变更、追踪数据流
+- 若根因指向源码 bug，先补充能复现该崩溃/异常的最小失败测试，再修改源码
+- 修复后运行该失败测试、相关测试和项目构建/验证命令，确认全部通过
+- 将测试、源码修复和 tasks.md 勾选保留在当前 change 内；不得通过另起一个“写测试用例”的 change 来替代当前 change 的验证闭环
+
 **如修复影响已有 spec 验收场景**：
 - 在 `openspec/changes/<name>/specs/<capability>/spec.md` 创建 delta spec
 - 仅包含 `## MODIFIED Requirements` 部分
@@ -97,7 +118,7 @@ bash "$COMET_GUARD" <change-name> open --apply
 根因确认消除后，运行阶段守卫完成 build → verify 过渡：
 
 ```bash
-bash "$COMET_GUARD" <change-name> build --apply
+"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply
 ```
 
 状态文件自动更新为 `phase: verify`、`verify_result: pending`，然后进入验证。
@@ -110,11 +131,11 @@ bash "$COMET_GUARD" <change-name> build --apply
 
 无 delta spec 的小范围 hotfix 通常满足轻量验证条件（≤ 3 tasks、≤ 2 files），comet-verify 的规模评估会选择轻量验证路径（5 项快速检查）。若 hotfix 创建了 delta spec，则根据 comet-verify 的规模评估规则进入完整验证路径。
 
-验证通过后，按 `/comet-verify` 的规则将 `.comet.yaml` 的 `verify_result` 记录为 `pass`，归档前不得跳过该状态。
+验证通过后，按 `/comet-verify` 的规则将 `.comet.yaml` 的 `verify_result` 记录为 `pass`，归档前不得跳过该状态。验证通过后仍必须进入 `/comet-archive` 的归档前最终确认，不得自动运行归档脚本。
 
 ### 5. 归档（preset archive）
 
-复用 `/comet-archive`。归档前必须满足 `.comet.yaml` 中 `verify_result: pass`。
+复用 `/comet-archive`。归档前必须满足 `.comet.yaml` 中 `verify_result: pass`，并等待 `/comet-archive` 的归档前最终确认。
 
 **立即执行：** 使用 Skill 工具加载 `comet-archive` 技能进行归档。禁止跳过此步骤。
 如有 delta spec，按 comet-archive 规则同步到 main spec，并处理关联 Design Doc 与 Plan 的归档标注。
@@ -124,11 +145,12 @@ bash "$COMET_GUARD" <change-name> build --apply
 ## 连续执行模式
 
 <IMPORTANT>
-Hotfix 流程为 **一次性连续执行**。调用 `/comet-hotfix` 后，agent 在 hotfix 自有步骤间自动推进，不主动停顿。但以下情况必须暂停等待用户确认：
+Hotfix 流程默认 **一次性连续执行**。调用 `/comet-hotfix` 后，agent 在 hotfix 自有步骤间自动推进，不主动停顿。**例外**：若 `auto_transition: false`，则在每个 phase 边界（build/verify/archive 之间）停下，由用户手动运行下一阶段命令——此时连续执行降级为逐阶段手动推进，详见下方「自动衔接下一阶段」。但无论 `auto_transition` 取何值，以下情况都必须暂停等待用户确认：
 
-1. 遇到升级条件（见"升级条件"章节），**必须使用 AskUserQuestion 工具暂停并等待用户明确确认**升级为完整流程
+1. 遇到升级条件（见"升级条件"章节），**必须使用当前平台可用的用户输入/确认机制暂停并等待用户明确确认**升级为完整流程
 2. 任务超过 3 个转入 `/comet-build` 时的工作区隔离和执行方式选择
 3. 验证阶段（comet-verify）的验证失败决策和分支处理决策
+4. 归档前最终确认（comet-archive 执行归档脚本前）
 
 执行顺序：快速开启 → 直接构建 → 根因消除检查 → 验证 → 归档 → 完成
 
@@ -149,12 +171,13 @@ Hotfix 流程为 **一次性连续执行**。调用 `/comet-hotfix` 后，agent
 | 引入新的 public API | 修复产生了新的对外接口 |
 | 修复范围超出单一函数/模块 | 需要多处协调修改 |
 
-满足升级条件时**必须使用 AskUserQuestion 工具暂停并等待用户明确确认**升级为完整 `/comet` 流程。不得直接进入 `/comet-design`，不得自动补充 Design Doc。不得仅输出文字提示后继续执行。
+满足升级条件时**必须使用当前平台可用的用户输入/确认机制暂停并等待用户明确确认**升级为完整 `/comet` 流程。不得直接进入 `/comet-design`，不得自动补充 Design Doc。若当前平台没有结构化提问工具，则在对话中提出升级确认问题并停止流程，等待用户回复后才能继续。
 
-用户确认升级后，**必须先更新 workflow 字段**再进入完整流程：
+用户确认升级后，**必须先更新 workflow 和 phase 字段**再进入完整流程：
 
 ```bash
-bash "$COMET_STATE" set <name> workflow full
+"$COMET_BASH" "$COMET_STATE" set <name> workflow full
+"$COMET_BASH" "$COMET_STATE" set <name> phase design
 ```
 
 然后在当前 change 基础上补充 Design Doc：**立即使用 Skill 工具加载 `comet-design` skill**，后续正常走完整流程。若用户不确认升级，停止 hotfix 并报告当前变更已超出 hotfix 适用范围。
@@ -166,4 +189,19 @@ bash "$COMET_STATE" set <name> workflow full
 - Bug 已修复，测试通过
 - change 已归档
 - 如有 spec 变更，已同步到 main spec
-- **阶段守卫**：build → verify 前运行 `bash "$COMET_GUARD" <change-name> build --apply`，verify → archive 前按 `/comet-verify` 规则运行 `bash "$COMET_GUARD" <change-name> verify --apply`
+- **阶段守卫**：build → verify 前运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`，verify → archive 前按 `/comet-verify` 规则运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply`
+
+## 自动衔接下一阶段
+
+> **术语区分**：阶段守卫 `--apply` 推进 `.comet.yaml` 的 `phase` 字段——这一步**始终发生**，与 `auto_transition` 无关。本节的「自动衔接」只决定**是否自动调用下一个 skill**。
+
+每次阶段守卫或状态转换推进 phase 后，运行：
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <name>
+```
+
+脚本根据 `phase`、`workflow`、`auto_transition` 输出确定性的下一步：
+- `NEXT: auto` → 调用 `SKILL` 指向的 skill 继续 hotfix 流程（`phase: build` 返回 `comet-hotfix`，`verify` 返回 `comet-verify`，`archive` 返回 `comet-archive`）
+- `NEXT: manual` → 不要调用下一 skill，按 `HINT` 提示用户手动运行 `/<SKILL>`
+- `NEXT: done` → 流程已完成，无需继续

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

@@ -1,6 +1,6 @@
 ---
 name: comet-open
-description: "Comet 阶段 1：开启。用 /comet-open 调用。通过 OpenSpec 探索想法、创建 change 结构（proposal + design + tasks）。"
+description: "Comet 阶段 1：开启。用 /comet-open 调用。通过 OpenSpec 探索想法、确认需求澄清，再创建 change 结构（proposal + design + tasks）。"
 ---
 
 # Comet 阶段 1：开启（Open）
@@ -11,17 +11,81 @@ description: "Comet 阶段 1：开启。用 /comet-open 调用。通过 OpenSpec
 
 ## 步骤
 
-### 1. 探索想法
+### 0. 输出语言约束
+
+传递给 OpenSpec 的所有提问和产物要求都必须包含输出语言约束：使用触发本次工作流的用户请求语言。恢复已有 change 且产物已有明确主语言时，除非用户明确要求切换，否则保持该语言。
+
+### 1. 探索想法与需求澄清
 
 **立即执行：** 使用 Skill 工具加载 `openspec-explore` 技能。禁止跳过此步骤。
 
-技能加载后，按其指引自由探索问题空间。
+技能加载后，按其指引探索问题空间，但不得把一次问答视为足够澄清。必须围绕下列内容继续提问、对齐并形成澄清摘要：
+- 目标：用户真正要解决的问题和期望结果
+- 非目标：本次明确不做的内容
+- 范围边界：涉及/不涉及的模块、用户、平台或数据
+- 关键未知项：仍不确定的假设、风险或依赖
+- 验收场景草案：至少覆盖核心成功场景和关键边界场景
+
+澄清摘要必须包含：目标、非目标、范围边界、关键未知项、验收场景草案。
+
+### 1a. PRD 拆分预检（阻塞点）
+
+当用户输入是大型 PRD、路线图、完整产品方案，或澄清摘要显示包含多个独立能力、模块、用户路径或里程碑时，必须在创建 OpenSpec artifacts 前评估是否需要拆分为多个 change。
+
+拆分预检必须基于已澄清的信息，输出候选拆分清单。每个候选拆分项必须包含：
+- 建议 change 名称
+- 目标与范围边界
+- 明确非目标
+- 依赖关系或推荐执行顺序
+- 对应的核心验收场景
+
+满足任一条件时，应推荐拆分：
+- PRD 包含多个可独立设计、构建、验证、归档的 capability
+- 涉及多个模块或用户路径，且其中一部分可独立交付
+- 存在明显分阶段里程碑
+- 预计会产生多个 delta spec 或超过 3 个大任务
+- 任一部分失败或延期不应阻塞其他部分进入后续阶段
+
+如推荐拆分，必须使用当前平台可用的用户输入/确认机制暂停并等待用户选择。若当前平台没有结构化提问工具，则在对话中提出同等单选问题并停止流程，等待用户回复后才能继续。
+
+用户选择必须包含：
+- 「创建多个 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`。拆分完毕后必须暂停询问用户开始哪一个 change；用户选择后，只推进该 change 进入 `/comet-design`，其他 change 保持 active，稍后通过 `/comet` 恢复。
+
+最小断点恢复规则：不新增专用批量状态文件。若批量拆分过程中断，恢复时先检查已创建的 active changes；已存在且包含 `.comet.yaml` 的拆分项不得重复创建，未创建的拆分项按用户已确认的拆分清单继续通过 `/comet-open` 创建。若对话中已确认的拆分清单不可恢复，必须重新向用户确认拆分清单后再继续。
+
+### 1b. 需求澄清完成确认（阻塞点）
+
+创建 OpenSpec artifacts 前，必须使用当前平台可用的用户输入/确认机制暂停并等待用户确认需求澄清完成。若当前平台没有结构化提问工具，则在对话中展示澄清摘要并提出确认问题，停止流程，等待用户回复后才能继续。
+
+暂停时必须展示澄清摘要：目标、非目标、范围边界、关键未知项、验收场景草案。
+
+不得在用户确认需求澄清完成前创建 proposal.md、design.md 或 tasks.md，也不得使用 Skill 工具加载 `openspec-propose` 技能一次性生成全部 artifacts。
 
 ### 2. 创建 Change 结构 + 初始化状态
 
-**立即执行：** 使用 Skill 工具加载 `openspec-new-change` 技能。若用户意图未明确、需要先形成建议，改为加载 `openspec-propose`。禁止跳过此步骤。
+**立即执行：** 使用 Skill 工具加载 `openspec-new-change` 技能。禁止跳过此步骤。
+
+完整 `/comet` 流程默认不得使用 Skill 工具加载 `openspec-propose` 技能；只有用户明确要求一次性生成提案和 artifacts 时才允许加载。
+
+技能加载后，按其指引创建 change 骨架，但当 Step 1b 的已确认澄清摘要已存在于对话上下文时，覆盖其"STOP and wait for user direction"行为。具体如下：
+
+1. 按技能指引执行 `openspec new change`、`openspec status`、`openspec instructions`
+2. 如果用户已确认澄清摘要（Step 1b），直接使用该摘要起草 proposal.md —— 不得再要求用户重新描述变更内容
+3. 如果不存在澄清摘要（边缘情况），回退到技能的默认行为，询问用户
 
-**命名与范围守卫**：change name 必须使用用户指定或通过 AskUserQuestion 确认的名称，不得自动生成或推断。变更范围必须与用户描述一致，不得自行扩大或缩小。
+然后逐个补齐 design.md、tasks.md；每个文档都必须基于已确认的澄清摘要。
+
+**命名与范围守卫**：change name 必须使用用户指定或通过当前平台可用的用户输入/确认机制确认的名称，不得自动生成或推断。变更范围必须与用户描述一致，不得自行扩大或缩小。
 
 确认以下产物已创建：
 
@@ -49,7 +113,7 @@ if [ -z "$COMET_STATE" ] || [ -z "$COMET_GUARD" ]; then
   return 1
 fi
 
-bash "$COMET_STATE" init <name> full
+"$COMET_BASH" "$COMET_STATE" init <name> full
 ```
 
 ### 3. 入口状态验证
@@ -57,7 +121,7 @@ bash "$COMET_STATE" init <name> full
 验证状态机已正确初始化：
 
 ```bash
-bash "$COMET_STATE" check <name> open
+"$COMET_BASH" "$COMET_STATE" check <name> open
 ```
 
 验证通过后继续 Step 4。验证失败时脚本会输出具体失败原因。
@@ -75,9 +139,9 @@ bash "$COMET_STATE" check <name> open
 
 ### 5. 用户审视确认（阻塞点）
 
-三个文档创建完成且内容完整性检查通过后，**必须使用 AskUserQuestion 工具暂停并等待用户确认**。不得在用户确认前执行阶段守卫或自动流转。
+三个文档创建完成且内容完整性检查通过后，**必须使用当前平台可用的用户输入/确认机制暂停并等待用户确认**。不得在用户确认前执行阶段守卫或自动流转。若当前平台没有结构化提问工具，则在对话中提出同等单选问题并停止流程，等待用户回复后才能继续。
 
-AskUserQuestion 必须以单选题形式呈现，包含以下摘要和选项：
+用户确认问题必须以单选题形式呈现，包含以下摘要和选项：
 
 **摘要内容**：
 - **proposal.md**：问题背景、目标、范围
@@ -88,26 +152,35 @@ AskUserQuestion 必须以单选题形式呈现，包含以下摘要和选项：
 - 「确认，继续下一阶段」— 产物符合预期，执行阶段守卫流转
 - 「需要调整」— 附带调整说明，修改后重新请求确认
 
-用户选择「确认」后继续执行退出条件。用户选择「需要调整」时，按其说明修改对应文件，然后重新使用 AskUserQuestion 请求确认。
+用户选择「确认」后继续执行退出条件。用户选择「需要调整」时，按其说明修改对应文件，然后重新请求确认。
 
 ## 退出条件
 
 - proposal.md、design.md、tasks.md 均已创建且内容完整
 - **用户已确认** proposal、design、tasks 内容符合预期
-- **阶段守卫**：运行 `bash "$COMET_GUARD" <change-name> open --apply`，全部 PASS 后自动流转到下一阶段
+- **阶段守卫**：运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply`，全部 PASS 后由守卫推进到下一阶段（此步骤更新 `phase` 字段，与 `auto_transition` 无关）
 
 退出前必须使用 `--apply`，否则 `.comet.yaml` 仍停留在 `phase: open`，下一阶段入口检查会失败。
 
 ```bash
-bash "$COMET_GUARD" <change-name> open --apply
+"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
 ```
 
 完整流程会自动更新为 `phase: design`；hotfix/tweak preset 会自动更新为 `phase: build`。
 
-## 自动流转
+## 自动衔接下一阶段
+
+> **术语区分**：上面的「阶段守卫推进」由 guard `--apply` 完成，更新 `.comet.yaml` 的 `phase` 字段——这一步**始终发生**，与 `auto_transition` 无关。本节的「自动衔接」只决定**是否自动调用下一个 skill**，由 `auto_transition` 控制。
+
+用户确认且阶段守卫推进 phase 后，运行：
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <change-name>
+```
 
-用户确认后，退出条件满足，自动流转到下一阶段：
+脚本根据 `phase`、`workflow`、`auto_transition` 输出确定性的下一步：
+- `NEXT: auto` → 调用 `SKILL` 指向的 skill 进入下一阶段
+- `NEXT: manual` → 不要调用下一 skill，按 `HINT` 提示用户手动运行 `/<SKILL>`
+- `NEXT: done` → 流程已完成，无需继续
 
-> **REQUIRED NEXT SKILL（完整流程）:** 调用 `comet-design` skill 进入深度设计阶段。
->
-> hotfix/tweak preset 由对应 preset skill 控制后续流转（phase 直接进入 build），不经过本节。
+hotfix/tweak preset 由对应 preset skill 控制后续流转（phase 直接进入 build），其 `next` 会返回对应 preset skill。