Menu
Comet — OpenSpec + Superpowers 双星开发流程。用 /comet 启动，自动检测阶段并分发到子命令。五阶段：开启 → 深度设计 → 计划与构建 → 验证与收尾 → 归档。
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
Comet 阶段 5：归档。用 /comet-archive 调用。按 OpenSpec delta 语义合并主 spec，归档 change。
Comet 阶段 3：计划与构建。用 /comet-build 调用。制定计划并选择执行方式（subagent 或直接执行）实施。
Comet 阶段 2：深度设计。用 /comet-design 调用。通过 brainstorming 产出 Design Doc 和 delta spec。
Comet 预设路径：Bug fix / 热修复。跳过 brainstorming，直接 open → build → verify → archive。适用于行为修复、不涉及新 capability 设计的场景。
Comet 阶段 1：开启。用 /comet-open 调用。通过 OpenSpec 探索想法、确认需求澄清，再创建 change 结构（proposal + design + tasks）。
Comet 预设路径：非 bug 的小改动（tweak）。跳过 brainstorming 和完整 plan，直接 open → lightweight build → light verify → archive。适用于文案、配置、文档或 prompt 的局部优化。
| name | comet |
| description | Comet — OpenSpec + Superpowers 双星开发流程。用 /comet 启动，自动检测阶段并分发到子命令。五阶段：开启 → 深度设计 → 计划与构建 → 验证与收尾 → 归档。 |
OpenSpec 与 Superpowers 如双星系统围绕同一目标运转。
OpenSpec 负责 WHAT — 大纲、提案、spec 生命周期、归档
Superpowers 负责 HOW — 技术设计、计划、执行、收尾
核心原则：brainstorming 必不可跳过。每次变更都必须经过深度设计（hotfix 和 tweak preset 除外）。
agent 做决策只需读本节，参考附录按需查阅。
以触发本次工作流的用户请求语言作为默认输出语言。恢复已有 change 时，如果现有产物有明确主语言，除非用户明确要求切换，否则保持该语言。
Step 0: 活跃 Change 发现与意图判定
openspec list --json 获取所有活跃 changePreset 检测优先级最高：
/comet-hotfix/comet-tweak| 活跃 change | 用户输入 | 行为 |
|---|---|---|
| 无 | 非 preset 输入 | → 调用 /comet-open |
| 恰好 1 个 | /comet <描述> | → 询问：继续该变更 or 创建新变更 |
| 多个 | /comet <描述> | → 询问：继续现有变更 or 创建新变更；若选继续 → 列出清单让用户选择 |
| 恰好 1 个 | /comet（无描述） | → 自动选中，进入 Step 1 |
| 多个 | /comet（无描述） | → 列出清单让用户选择 |
Step 1: 读取 .comet.yaml 状态元数据
优先读取 openspec/changes/<name>/.comet.yaml。不存在时回退到 openspec status --change "<name>" --json、tasks.md 和 docs/superpowers/ 文件检查。
断点恢复规则：
comet/reference/dirty-worktree.md 协议处理。该协议定义了检查步骤、归因分类和禁令，本文件不重复phase: build，先检查 build_pause、plan、build_mode 和 isolation（详见下方）：
build_pause: plan-ready 但 isolation 和 build_mode 已经设置，则视为 stale pause：先输出 [COMET] 检测到 stale pause（build_pause=plan-ready 但 isolation/build_mode 已设置），自动清除并继续，再运行 "$COMET_BASH" "$COMET_STATE" set <name> build_pause null，然后读取 tasks.md 的下一个未勾选任务并按 build_mode 恢复执行build_pause: plan-ready 且 plan 文件存在，但 isolation 或 build_mode 尚未设置，回到 /comet-build 的 plan-ready 恢复点，提示用户继续选择隔离方式和执行方式，不重新生成 planbuild_pause: plan-ready 但 plan 文件缺失，回到 /comet-build 处理状态损坏或重新生成 planbuild_mode、isolation 或 tdd_mode 未设置，回到 /comet-build 对应步骤补充后再执行build_mode 恢复执行：
build_mode: subagent-driven-development，不得在主窗口直接执行任务；必须回到 /comet-build 的后台 subagent 调度规则，由主窗口只做协调/comet-build 的对应规则继续phase: verify 且 verify_result: fail，进入验证失败决策阻塞点：暂停并询问用户修复或接受偏差；用户选择修复后才运行 "$COMET_BASH" "$COMET_STATE" transition <name> verify-fail 并调用 /comet-buildphase: open 但 proposal/design/tasks 已完整，先运行 "$COMET_BASH" "$COMET_GUARD" <change-name> open --apply 修正状态，再继续判定phase: archive，只允许调用 /comet-archive；/comet-archive 必须先等待归档前最终确认，归档成功后 change 会移动到 archive 目录，不再对原活跃目录运行 guardStep 2: 阶段判定（按顺序，命中即停）
archived: true 或 change 已移入 archive → 流程已完成verify_result: pass 且 archived 不是 true → /comet-archive（先进行归档前最终确认）verify_result: fail → 进入验证失败决策阻塞点（暂停询问修复或接受偏差；用户选择修复后才 verify-fail 并 /comet-build）phase: verify 或 tasks.md 全部勾选 → /comet-verifyphase: build 或已有 Design Doc 但计划/执行未完成 → 优先按 workflow 路由：hotfix → /comet-hotfix，tweak → /comet-tweak，full → /comet-buildphase: design 或有 change 但无 Design Doc → /comet-designphase: open 或有活跃 change 但 .comet.yaml 缺失 → /comet-open/comet-open如果元数据与文件状态冲突，以文件状态为准，修正 .comet.yaml 后继续。
hotfix → full（满足任一即升级）：
tweak → full（满足任一即升级）：
| 场景 | 处理方式 |
|---|---|
openspec list --json 失败 | 检查 openspec 是否已安装，提示 openspec init |
| 子 skill 不可用 | 停止流程，提示安装或启用对应 skill |
.comet.yaml 格式异常或缺失 | 以文件状态为准，用 "$COMET_BASH" "$COMET_STATE" set 修正后继续 |
| 构建/测试失败 | 返回 build 阶段修复，不进入 verify |
| change 目录结构不完整 | 按 comet-open 产物要求补齐 |
流转链：open → design → build → verify → archive
连续执行要求：从检测到的阶段开始，agent 自动推进后续阶段。但自动推进仅适用于没有用户决策的衔接点。遇到用户决策点时，必须使用当前平台可用的用户输入/确认机制暂停并等待用户明确回复，不得用推荐规则、默认值或历史偏好代替用户确认，也不得仅输出文字提示后继续执行。
阶段推进与自动衔接的区分：每个子 skill 退出前都会运行阶段守卫 --apply 推进 .comet.yaml 的 phase 字段——这一步始终发生，与 auto_transition 无关。之后子 skill 运行 "$COMET_BASH" "$COMET_STATE" next <name> 解析下一步：auto_transition 不为 false 时输出 NEXT: auto（自动调用下一 skill），为 false 时输出 NEXT: manual（不调用下一 skill，提示用户手动运行）。因此 auto_transition 只控制是否自动调用下一个 skill，不影响 phase 推进。无论 auto_transition 取何值，下方的用户决策点都必须阻塞等待。
决策点是阻塞点：只要到达下列任一节点，当前 /comet 调用必须停住，并按 comet/reference/decision-point.md 的协议获取用户明确选择。用户明确选择后才能写入对应状态字段、执行对应操作，随后再继续自动流转。
需要用户参与的节点（仅在这些节点暂停）：
agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须自动继续推进，不得中途退出。到达决策点时，禁止跳过用户确认或自动选择——必须通过当前平台可用的用户输入/确认机制明确获取用户选择后才能继续。
红旗清单 — 以下想法出现时立即停止并检查：
| Agent 心理 | 实际风险 |
|---|---|
| "用户应该会同意这个方案" | 不能替用户决策，必须等待用户明确选择 |
| "这只是个小改动，不需要确认" | 决策点无大小之分，阻塞点必须等待 |
| "用户之前选过 A，这次也选 A" | 历史偏好不能替代当前确认 |
| "我已经解释了方案，用户没反对" | 没反对 ≠ 同意，必须用工具获取明确选择 |
| "流程走到这里应该没问题了" | 验证不通过 ≠ 通过，检查 verify_result |
| 命令 | 阶段 | 归属 | 产物 |
|---|---|---|---|
/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 → 回到完整流程
字段说明、文件结构和自动衔接协议已提取为渐进式加载参考文档，按需查阅：
.comet.yaml完整字段表：按comet/reference/comet-yaml-fields.md查阅（含必需字段、可选字段和完整示例）- 文件结构：按
comet/reference/file-structure.md查阅- 自动衔接协议：按
comet/reference/auto-transition.md查阅- 上下文压缩恢复：按
comet/reference/context-recovery.md查阅- 用户决策点协议：按
comet/reference/decision-point.md查阅- 异常调试协议：按
comet/reference/debug-gate.md查阅
build → verify 前，isolation 必须是 branch 或 worktreebuild → verify 前，build_mode 必须已选择build_mode: subagent-driven-development 必须同时有 subagent_dispatch: confirmedtdd_mode 必须已选择为 tdd 或 directbuild_mode: direct 默认只允许 hotfix / tweak；full workflow 需要 direct_override: truebuild_pause 不是执行方式，不得写入 build_modecomet-guard.sh build --apply 和 comet-state.sh transition <name> build-completeComet 脚本随 skill 包分发在 comet/scripts/ 下。不硬编码路径 — 定位一次，缓存到环境变量。此块为标准样板，在每个子 skill 中独立重复以确保可独立加载；修改时必须保持所有文件同步（样板版本: v2，变更时更新此版本号便于定位需要同步的文件）：
COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
if [ -z "$COMET_ENV" ]; then
echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
return 1
fi
. "$COMET_ENV"
# 脚本定位失败时停止流程
if [ -z "$COMET_GUARD" ] || [ -z "$COMET_STATE" ] || [ -z "$COMET_HANDOFF" ] || [ -z "$COMET_ARCHIVE" ]; then
echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2
echo "Expected path pattern: */comet/scripts/comet-*.sh under project or platform skill directories" >&2
return 1
fi
自动状态更新：guard 支持 --apply 参数，验证通过后自动更新 .comet.yaml 状态字段：
"$COMET_BASH" "$COMET_GUARD" <change-name> <phase> --apply
--apply 内部委托给 comet-state transition。需要直接表达状态事件时使用：
"$COMET_BASH" "$COMET_STATE" transition <change-name> open-complete
"$COMET_BASH" "$COMET_STATE" transition <change-name> design-complete
"$COMET_BASH" "$COMET_STATE" transition <change-name> build-complete
"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-pass
"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
"$COMET_BASH" "$COMET_STATE" transition <archive-name> archived
解析下一步：阶段守卫推进 phase 后，用 next 子命令解析是否自动调用下一个 skill：
"$COMET_BASH" "$COMET_STATE" next <change-name>
输出 NEXT: auto|manual|done + SKILL: <skill-name>（done 时省略）+ HINT（仅 manual 时）。auto_transition: false 时输出 manual，只暂停下一 skill 调用，不影响已发生的 phase 推进。
归档脚本：一键完成归档全部步骤：
"$COMET_BASH" "$COMET_ARCHIVE" <change-name>
加载 comet 后，agent 应执行以上变量赋值一次，后续全程复用 $COMET_GUARD、$COMET_STATE、$COMET_HANDOFF、$COMET_ARCHIVE。
按 comet/reference/file-structure.md 查阅完整目录结构。
comet-handoff.sh 生成 compact 可追溯摘录（需要全文时用 --full），并由 guard 校验 source/hash/mode/comet-verify 通过后进入 /comet-archive，但运行归档脚本前必须等待用户最终确认change: 和 design-doc: 元数据archived-with 状态