comet

name: comet description: "Comet — OpenSpec + Superpowers 双星开发工作流。使用 /comet 启动，自动检测阶段并分发到子命令。五个阶段：open → design → build → verify → archive。" argument-hint: "[--ralph] [--auto] [--subagent_limit=N] [--no-deslop] [--critic=architect|critic|codex] <任务描述>"

Comet — OpenSpec + Superpowers 双星开发工作流

OpenSpec 和 Superpowers 围绕同一个目标运行，如同双星系统。

OpenSpec 处理 WHAT — 大纲、提案、规格生命周期、归档
Superpowers 处理 HOW — 技术设计、计划、执行、收尾

核心原则：头脑风暴不可跳过。每个变更都必须经过深度设计（hotfix 和 tweak 预设除外）。

Subagent Limit

当传入 --subagent_limit 参数时，控制任务数阈值：tasks ≥ N 时使用子 agent 执行。

检测方式： 检查 {{PROMPT}} 是否包含 --subagent_limit=N。如果存在：

1. 从工作提示中移除参数
2. 存储参数值（默认 1）
3. 传递给子技能

参数值：

传递规则： 分发到子技能时原样传递 --subagent_limit={value}。

Ralph 模式

当传入 --ralph 标志（例如 /comet --ralph <任务描述>）时，Comet 将其工作流包裹在 Ralph 的 PRD 驱动持久循环中：

检测方式： 检查 {{PROMPT}} 是否包含 --ralph。如果存在：

1. 从工作提示中移除 --ralph
2. 创建 PRD，包含以下源自 Comet 各阶段的用户故事：
   • US-001: Open 阶段完成（proposal.md、design.md、tasks.md 创建并确认）
   • US-002: Design 阶段完成（设计文档创建并确认）
   • US-003: Build 阶段完成（实现完成，tasks.md 全部勾选）
   • US-004: Verify 阶段完成（验证通过，分支处理完成）
   • US-005: 用户需求验证（提供实际测试/证据证明原始用户需求已满足）
   • US-006: Archive 阶段完成（变更归档）
3. 执行标准 Ralph 迭代循环（Ralph SKILL.md 的步骤 2-9）
4. 每个故事的验收标准包含对应 Comet 阶段的退出条件
5. US-005 验收标准必须包含证明用户原始需求已满足的具体证据（例如：修复 bug 时需有实际测试显示 bug 已修复；新增功能时需演示功能按预期工作）
6. 在第 7 步审批后运行强制 deslop 清理（除非指定 --no-deslop）
7. 如提供 --critic 则使用其选择（默认：architect）

Ralph 模式流程：

/comet --ralph <任务>
  ↓ 移除 --ralph，创建 PRD
  ↓ Ralph 迭代循环
  ├── US-001: Open 阶段 → 验证 → passes: true
  ├── US-002: Design 阶段 → 验证 → passes: true
  ├── US-003: Build 阶段 → 验证 → passes: true
  ├── US-004: Verify 阶段 → 验证 → passes: true
  ├── US-005: 用户需求验证 → 实际测试/证据 → passes: true
  └── US-006: Archive 阶段 → 验证 → passes: true
  ↓ 所有故事通过 → architect/critic 验证
  ↓ Deslop 清理
  ↓ /oh-my-claudecode:cancel

Ralph 模式优势：

• 阶段失败时自动重试
• PRD 驱动的进度跟踪
• 完成前强制验证
• 强制用户需求验证（US-005）— 不仅是流程完成
• 跨迭代持久状态
• 通过 deslop 清理干净完成

Auto 模式

当传入 --auto 标志（例如 /comet --auto <任务描述>）时，Comet 跳过所有用户确认提示，在每个决策点自动选择推荐/合理的默认选项。

检测方式： 检查 {{PROMPT}} 是否包含 --auto。如果存在：

1. 从工作提示中移除 --auto
2. 继续执行所有阶段，无需请求用户确认
3. 在每个 AskUserQuestion 阻塞点，自动选择推荐选项

Auto 模式决策默认值：

Auto 模式 + Ralph 模式： 当同时使用 --auto 和 --ralph（例如 /comet --ralph --auto <任务>）时：

• Ralph 包裹 Comet 工作流
• Auto 模式应用于每个 Comet 阶段内部
• 任何阻塞点都无需用户确认
• 从开始到归档完全自主执行

Auto 模式流程：

/comet --auto <任务>
  ↓ 移除 --auto
  ↓ Open 阶段 → 自动确认 → 继续
  ↓ Design 阶段 → 自动确认 → 继续
  ↓ Build 阶段 → 自动选择分支 + subagent → 执行
  ↓ Verify 阶段 → 自动合并到主分支 → 继续
  ↓ Archive 阶段 → 完成

Auto 模式优势：

• 完全自主执行
• 无需手动干预
• 更快完成简单变更
• 适合 CI/CD 集成或批量处理

Auto 模式注意事项：

• 无法在执行中途回滚决策
• 可能选择不符合用户偏好的选项
• 仅在默认值可接受时使用

决策核心

代理只需阅读本节即可进行决策。需要时参考参考附录。

自动阶段检测

步骤 0：活跃变更发现与意图检测

1. 首先检测预设；如果 hotfix/tweak 匹配，直接调用对应的预设技能，不进入正常 open 分支
2. 当没有预设匹配时，运行 openspec list --json 获取所有活跃变更

预设检测具有最高优先级：

• 用户明确描述 bug 修复 / hotfix + 满足 hotfix 条件 → 直接调用 /comet-hotfix
• 用户明确描述文案/配置/文档/prompt 小调整 + 满足 tweak 条件 → 直接调用 /comet-tweak
• 无预设匹配 → 按下表处理

步骤 1：读取 .comet.yaml 状态元数据

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

恢复规则：

• 每次上下文恢复时，重新运行步骤 0 和步骤 1；不要信任对话历史进行阶段检测
• 如果有活跃变更且工作区有未提交更改，通过 comet/reference/dirty-worktree.md 处理。该协议定义了检查、归属和禁止事项；本文件不重复
• 如果 phase: build，首先检查 build_pause、plan、build_mode 和 isolation：
  • 如果 build_pause: plan-ready 且计划文件存在，返回 /comet-build 的 plan-ready 恢复点，提示用户继续选择隔离和执行方法，不要重新生成计划
  • 如果 build_pause: plan-ready 但计划文件缺失，返回 /comet-build 处理损坏状态或重新生成计划
  • 如果 build_mode 或 isolation 未设置，返回对应的 /comet-build 步骤补充后再执行
  • 如果都已设置，从 tasks.md 读取下一个未勾选任务并继续
• 如果 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；归档成功后，变更移动到归档目录，所以不要对旧的活跃目录运行 guard

步骤 2：阶段判定（按顺序检查，首次匹配生效）

Subagent Limit 参数传递：

• 在调用任何子技能前，将 --subagent_limit 参数值传递给子技能
• 子技能（comet-build、comet-hotfix、comet-tweak）根据此参数决定执行模式

1. archived: true 或变更已移动到归档 → 工作流完成

2. verify_result: pass 且 archived 不是 true → 调用 /comet-archive 技能

   **禁止手动归档操作！**
   • ❌ 不要执行 mv openspec/changes/<name> openspec/changes/archive/
   • ❌ 不要手动创建归档目录或移动文件
   • ✅ 必须调用 /comet-archive 技能或 "$COMET_BASH" "$COMET_ARCHIVE" <name>

   归档脚本会自动：

   • 从 proposal.md 第一行提取中文标题
   • 生成 0001-中文标题 格式的归档目录
   • 同步 delta spec → 主 spec
   • 标注设计文档和计划的 archived-with 状态
   • 更新 .comet.yaml 的 archived: true

3. verify_result: fail → 进入验证失败决策阻塞点（暂停并询问修复或接受偏差；只有用户选择修复后，运行 verify-fail 然后 /comet-build）

4. phase: verify 或 tasks.md 全部勾选 → 调用 /comet-verify

5. phase: build 或有设计文档但计划/执行未完成 → 按工作流路由：hotfix → /comet-hotfix，tweak → /comet-tweak，full → /comet-build

6. phase: design 或有变更但无设计文档 → 调用 /comet-design

7. phase: open 或存在活跃变更但 .comet.yaml 缺失 → 调用 /comet-open

8. 无活跃变更 → 调用 /comet-open

如果元数据与文件状态冲突，以可验证的文件状态为真实来源，并在继续前修正 .comet.yaml。

预设升级条件

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

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

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

• 变更涉及 5+ 文件
• 需要跨模块协调
• 需要 5+ 新测试用例
• 配置项新增或删除（非值修改）

错误处理快速参考

阶段转换

/comet
  ↓ 自动检测
/comet-open ──→ /comet-design ──→ /comet-build ──→ /comet-verify ──→ /comet-archive
  (OpenSpec)      (Superpowers)     (Superpowers)     (双方)          (OpenSpec)

/comet-hotfix (预设，跳过头脑风暴)
  open ──→ build ──→ verify ──→ archive
    ↑ 如触发升级 → 阻塞确认 → 补充设计文档 → 返回完整工作流

/comet-tweak (预设，跳过头脑风暴和完整计划)
  open ──→ 轻量 build ──→ 轻量 verify ──→ archive
    ↑ 如触发升级 → 阻塞确认 → 补充设计文档 → 返回完整工作流

workflow: full
phase: build
design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
base_ref: a1b2c3d4e5f6...
build_mode: subagent-driven-development
build_pause: null
isolation: branch
verify_mode: light
verify_result: pending
verification_report: null
branch_status: pending
created_at: 2026-05-26
verified_at: null
archived: false

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

"$COMET_BASH" "$COMET_GUARD" <change-name> <phase> --apply

"$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

"$COMET_BASH" "$COMET_ARCHIVE" <change-name>

openspec/                              # OpenSpec — WHAT
├── config.yaml
├── changes/
│   ├── <name>/                        # 活跃变更
│   │   ├── .openspec.yaml
│   │   ├── .comet.yaml
│   │   ├── proposal.md                # Why + What
│   │   ├── design.md                  # 高层架构决策
│   │   ├── specs/<capability>/spec.md # Delta 能力规格
│   │   ├── .comet/handoff/            # 脚本生成的阶段交接包
│   │   └── tasks.md                   # 任务清单
│   └── archive/0001<name>/            # 已归档（序号前缀）
└── specs/<capability>/spec.md         # 主规格（归档时从 delta 覆盖）

docs/superpowers/                      # Superpowers — HOW
├── specs/YYYY-MM-DD-<topic>-design.md # 设计文档（技术 RFC，归档时标记状态）
└── plans/YYYY-MM-DD-<feature>.md      # 实现计划（文件头包含变更关联元数据）