16 KiB

Raw Blame History Unescape Escape

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

name	description
comet	Comet — OpenSpec + Superpowers 双星开发流程。用 /comet 启动，自动检测阶段并分发到子命令。五阶段：开启 → 深度设计 → 计划与构建 → 验证与收尾 → 归档。

Comet — OpenSpec + Superpowers 双星开发流程

OpenSpec 与 Superpowers 如双星系统围绕同一目标运转。

OpenSpec 负责 WHAT  — 大纲、提案、spec 生命周期、归档
Superpowers 负责 HOW — 技术设计、计划、执行、收尾

核心原则：brainstorming 必不可跳过。每次变更都必须经过深度设计（hotfix 和 tweak preset 除外）。

决策核心（Decision Core）

agent 做决策只需读本节，参考附录按需查阅。

输出语言规则

以触发本次工作流的用户请求语言作为默认输出语言。恢复已有 change 时，如果现有产物有明确主语言，除非用户明确要求切换，否则保持该语言。

阶段自动检测

Step 0: 活跃 Change 发现与意图判定

先做 Preset 检测；命中 hotfix/tweak 时直接调用对应 preset skill，不进入普通 open 分支
未命中 preset 时，运行 openspec list --json 获取所有活跃 change

Preset 检测优先级最高：

用户明确描述为 bug fix / 热修复 + 满足 hotfix 条件 → 直接 /comet-hotfix
用户明确描述为文案/配置/文档/prompt 小调整 + 满足 tweak 条件 → 直接 /comet-tweak
未命中 preset → 按下表处理

活跃 change	用户输入	行为
无	非 preset 输入	→ 调用 `/comet-open`
恰好 1 个	`/comet <描述>`	→ 询问：继续该变更 or 创建新变更
多个	`/comet <描述>`	→ 询问：继续现有变更 or 创建新变更；若选继续 → 列出清单让用户选择
恰好 1 个	`/comet`（无描述）	→ 自动选中，进入 Step 1
多个	`/comet`（无描述）	→ 列出清单让用户选择

当用户选择「创建新变更」时，**必须调用 `/comet-open`**（禁止直接调用 `/opsx:new`）。 `/comet-open` 负责完整双初始化OpenSpec artifacts由内部 `/opsx:new` 创建）+ `.comet.yaml` 状态文件。直接调用 `/opsx:new` 会缺失 `.comet.yaml`，导致后续阶段判定失败。

Step 1: 读取 .comet.yaml 状态元数据

优先读取 openspec/changes/<name>/.comet.yaml。不存在时回退到 openspec status --change "<name>" --json、tasks.md 和 docs/superpowers/ 文件检查。

断点恢复规则：

每次恢复上下文时，先重新执行 Step 0 和 Step 1，不依赖对话历史判断阶段
只要存在 active change 且工作区有未提交改动，必须按 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 恢复点，提示用户继续选择隔离方式和执行方式，不重新生成 plan
- 若 build_pause: plan-ready 但 plan 文件缺失，回到 /comet-build 处理状态损坏或重新生成 plan
- 若 build_mode、isolation 或 tdd_mode 未设置，回到 /comet-build 对应步骤补充后再执行
- 若均已设置，读取 tasks.md 的下一个未勾选任务，并按 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-build
若 phase: open 但 proposal/design/tasks 已完整，先运行 "$COMET_BASH" "$COMET_GUARD" <change-name> open --apply 修正状态，再继续判定
若 phase: archive，只允许调用 /comet-archive；/comet-archive 必须先等待归档前最终确认，归档成功后 change 会移动到 archive 目录，不再对原活跃目录运行 guard

Step 2: 阶段判定（按顺序，命中即停）

archived: true 或 change 已移入 archive → 流程已完成
verify_result: pass 且 archived 不是 true → /comet-archive（先进行归档前最终确认）
verify_result: fail → 进入验证失败决策阻塞点（暂停询问修复或接受偏差；用户选择修复后才 verify-fail 并 /comet-build）
phase: verify 或 tasks.md 全部勾选 → /comet-verify
phase: build 或已有 Design Doc 但计划/执行未完成 → 优先按 workflow 路由：hotfix → /comet-hotfix，tweak → /comet-tweak，full → /comet-build
phase: design 或有 change 但无 Design Doc → /comet-design
phase: open 或有活跃 change 但 .comet.yaml 缺失 → /comet-open
无活跃 change → /comet-open

如果元数据与文件状态冲突，以文件状态为准，修正 .comet.yaml 后继续。

预设升级条件

hotfix → full（满足任一即升级）：

改动涉及 3+ 文件
涉及架构变更（新模块、新接口、新依赖）
涉及数据库 schema 变更
修复引入新的 public API
修复范围超出单一函数/模块

tweak → full（满足任一即升级）：

改动涉及 5+ 文件
涉及多个模块的协调修改
需要新增测试用例 5+
涉及配置项的新增或删除（非值修改）
需要新增 capability
需要 delta spec（影响了已有规格）

错误处理速查

场景	处理方式
`openspec list --json` 失败	检查 openspec 是否已安装，提示 `openspec init`
子 skill 不可用	停止流程，提示安装或启用对应 skill
`.comet.yaml` 格式异常或缺失	以文件状态为准，用 `"$COMET_BASH" "$COMET_STATE" set` 修正后继续
构建/测试失败	返回 build 阶段修复，不进入 verify
change 目录结构不完整	按 `comet-open` 产物要求补齐

阶段衔接

单次 `/comet` 调用从检测到的阶段开始，退出条件满足后进入下一阶段。

流转链：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 的协议获取用户明确选择。用户明确选择后才能写入对应状态字段、执行对应操作，随后再继续自动流转。

需要用户参与的节点（仅在这些节点暂停）：

open 阶段 proposal/design/tasks 审视确认
brainstorming 确认设计方案
build 阶段 plan-ready 暂停选择，以及随后选择工作方式（隔离方式 + 执行方式）
verify 不通过时决定修复或接受偏差（含 Spec 漂移处理方式选择）
finishing-branch 选择分支处理方式
archive 阶段执行归档脚本前的最终确认
遇到升级条件（hotfix/tweak → 完整流程）
build 阶段范围扩张需重新设计或拆分新 change
open 阶段大型 PRD 需确认拆分为多个 change

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 → 回到完整流程

参考附录（Reference Appendix）

字段说明、文件结构和自动衔接协议已提取为渐进式加载参考文档，按需查阅：

.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 或 worktree
build → verify 前，build_mode 必须已选择
build_mode: subagent-driven-development 必须同时有 subagent_dispatch: confirmed
full workflow 离开 build 阶段前 tdd_mode 必须已选择为 tdd 或 direct
build_mode: direct 默认只允许 hotfix / tweak；full workflow 需要 direct_override: true
build_pause 不是执行方式，不得写入 build_mode
这些约束同时存在于 comet-guard.sh build --apply 和 comet-state.sh transition <name> build-complete

脚本定位

Comet 脚本随 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 查阅完整目录结构。

最佳实践

brainstorming 不可跳过 — 每次变更必须经过深度设计（hotfix 和 tweak 除外）
delta spec 是活文档 — 阶段 3 期间可自由修改，归档时同步
交接包由脚本生成 — OpenSpec → Superpowers 的上下文必须通过 comet-handoff.sh 生成 compact 可追溯摘录（需要全文时用 --full），并由 guard 校验 source/hash/mode
保持 tasks.md 同步 — 完成一个勾一个
频繁提交 — 每个任务一次提交，message 体现设计意图
先验证再确认归档 — /comet-verify 通过后进入 /comet-archive，但运行归档脚本前必须等待用户最终确认
增量更新分级 — 小编辑、中重 brainstorming、大新 change
Plan 必须关联 change — 文件头包含 change: 和 design-doc: 元数据
归档闭环 — design doc 和 plan 必须标注 archived-with 状态
修改已有功能 — 直接 open 新 change 即可
Preset 有上限 — hotfix/tweak 满足升级条件时及时切换到完整流程

16 KiB Raw Blame History Unescape Escape