Back to Details

comet

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Comet — OpenSpec + Superpowers 双星开发流程

Comet — OpenSpec + Superpowers Binary Star Development Workflow

OpenSpec 与 Superpowers 如双星系统围绕同一目标运转。
OpenSpec 负责 WHAT  — 大纲、提案、spec 生命周期、归档
Superpowers 负责 HOW — 技术设计、计划、执行、收尾
核心原则：brainstorming 必不可跳过。每次变更都必须经过深度设计（hotfix 和 tweak preset 除外）。
OpenSpec and Superpowers operate like a binary star system revolving around the same goal.
OpenSpec is responsible for WHAT  — outlines, proposals, spec lifecycle, archiving
Superpowers is responsible for HOW — technical design, planning, execution, finalization
Core Principle: Brainstorming cannot be skipped. Every change must undergo deep design (except for hotfix and tweak presets).

决策核心（Decision Core）

Decision Core

agent 做决策只需读本节，参考附录按需查阅。
Agents only need to read this section for decision-making, and refer to the appendix as needed.

阶段自动检测

Automatic Phase Detection

Step 0: 活跃 Change 发现与意图判定
  1. 先做 Preset 检测；命中 hotfix/tweak 时直接调用对应 preset skill，不进入普通 open 分支
  2. 未命中 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
（无描述）		→ 列出清单让用户选择
<IMPORTANT> 当用户选择「创建新变更」时，**必须调用 `/comet-open`**（禁止直接调用 `/opsx:new`）。 `/comet-open` 负责完整双初始化：OpenSpec artifacts（由内部 `/opsx:new` 创建）+ `.comet.yaml` 状态文件。 直接调用 `/opsx:new` 会缺失 `.comet.yaml`，导致后续阶段判定失败。 </IMPORTANT>
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_mode
    和 
    isolation
    是否已设置；若有未设置的字段，回到 
    /comet-build
    对应步骤补充后再执行；若均已设置，读取 tasks.md 的下一个未勾选任务继续
  • 若 
    phase: verify
    且 
    verify_result: fail
    ，进入验证失败决策阻塞点：暂停并询问用户修复或接受偏差；用户选择修复后才运行 
    bash "$COMET_STATE" transition <name> verify-fail
    并调用 
    /comet-build
  • 若 
    phase: open
    但 proposal/design/tasks 已完整，先运行 
    bash "$COMET_GUARD" <change-name> open --apply
    修正状态，再继续判定
  • 若 
    phase: archive
    ，只允许调用 
    /comet-archive
    ；归档成功后 change 会移动到 archive 目录，不再对原活跃目录运行 guard
Step 2: 阶段判定（按顺序，命中即停）
  1. archived: true
    或 change 已移入 archive → 流程已完成
  2. verify_result: pass
    且 
    archived
    不是 
    true
    → 
    /comet-archive
  3. verify_result: fail
    → 进入验证失败决策阻塞点（暂停询问修复或接受偏差；用户选择修复后才 
    verify-fail
    并 
    /comet-build
    ）
  4. phase: verify
    或 tasks.md 全部勾选 → 
    /comet-verify
  5. phase: build
    或已有 Design Doc 但计划/执行未完成 → 优先按 workflow 路由：
    hotfix
    → 
    /comet-hotfix
    ，
    tweak
    → 
    /comet-tweak
    ，
    full
    → 
    /comet-build
  6. phase: design
    或有 change 但无 Design Doc → 
    /comet-design
  7. phase: open
    或有活跃 change 但 
    .comet.yaml
    缺失 → 
    /comet-open
  8. 无活跃 change → 
    /comet-open
如果元数据与文件状态冲突，以文件状态为准，修正 
.comet.yaml
后继续。
Step 0: Active Change Discovery and Intent Determination
  1. First perform preset detection; if hotfix/tweak is hit, directly call the corresponding preset skill without entering the normal open branch
  2. If no preset is hit, run 
    openspec list --json
    to get all active changes
Preset detection has the highest priority:
  • User explicitly describes as bug fix / hotfix + meets hotfix conditions → directly 
    /comet-hotfix
  • User explicitly describes as minor adjustment to copy/config/docs/prompt + meets tweak conditions → directly 
    /comet-tweak
  • No preset hit → handle according to the table below
Active ChangesUser InputAction
NoneNon-preset input→ Call 
/comet-open
Exactly 1
/comet <description>
→ Ask: Continue this change or create a new change
Multiple
/comet <description>
→ Ask: Continue existing change or create a new change; if continue is selected → list options for user to choose
Exactly 1
/comet
(no description)		→ Automatically select and proceed to Step 1
Multiple
/comet
(no description)		→ List options for user to choose
<IMPORTANT> When the user selects "Create new change", **must call `/comet-open`** (direct calling of `/opsx:new` is prohibited). `/comet-open` is responsible for complete dual initialization: OpenSpec artifacts (created by internal `/opsx:new`) + `.comet.yaml` state file. Directly calling `/opsx:new` will result in missing `.comet.yaml`, leading to subsequent phase determination failure. </IMPORTANT>
Step 1: Read 
.comet.yaml
state metadata
Prioritize reading 
openspec/changes/<name>/.comet.yaml
. If it does not exist, fall back to checking 
openspec status --change "<name>" --json
, 
tasks.md
and 
docs/superpowers/
files.
Breakpoint Recovery Rules:
  • When restoring context each time, re-execute Step 0 and Step 1 first, do not rely on conversation history to determine phases
  • As long as there is an active change and uncommitted changes in the workspace, must handle according to the 
    comet/reference/dirty-worktree.md
    protocol. This protocol defines inspection steps, attribution classification and prohibitions, which are not repeated in this document
  • If 
    phase: build
    , first check if 
    build_mode
    and 
    isolation
    are set; if any fields are not set, return to the corresponding step in 
    /comet-build
    to supplement before execution; if all are set, read the next unchecked task in tasks.md to continue
  • If 
    phase: verify
    and 
    verify_result: fail
    , enter the verification failure decision blocking point: pause and ask the user to fix or accept deviations; only after the user chooses to fix, run 
    bash "$COMET_STATE" transition <name> verify-fail
    and call 
    /comet-build
  • If 
    phase: open
    but proposal/design/tasks are complete, first run 
    bash "$COMET_GUARD" <change-name> open --apply
    to correct the state, then continue determination
  • If 
    phase: archive
    , only 
    /comet-archive
    is allowed; after successful archiving, the change will be moved to the archive directory, and no longer run guard on the original active directory
Step 2: Phase Determination (in order, stop when hit)
  1. archived: true
    or change has been moved to archive → workflow completed
  2. verify_result: pass
    and 
    archived
    is not 
    true
    → 
    /comet-archive
  3. verify_result: fail
    → enter verification failure decision blocking point (pause to ask user to fix or accept deviations; only after user chooses to fix, execute 
    verify-fail
    and 
    /comet-build
    )
  4. phase: verify
    or all tasks in tasks.md are checked → 
    /comet-verify
  5. phase: build
    or Design Doc exists but planning/execution is not completed → prioritize routing by workflow: 
    hotfix
    → 
    /comet-hotfix
    , 
    tweak
    → 
    /comet-tweak
    , 
    full
    → 
    /comet-build
  6. phase: design
    or change exists but no Design Doc → 
    /comet-design
  7. phase: open
    or active change exists but 
    .comet.yaml
    is missing → 
    /comet-open
  8. No active changes → 
    /comet-open
If metadata conflicts with file status, take file status as the standard, correct 
.comet.yaml
and continue.

预设升级条件

Preset Upgrade Conditions

hotfix → full（满足任一即升级）：
  • 改动涉及 3+ 文件
  • 涉及架构变更（新模块、新接口、新依赖）
  • 涉及数据库 schema 变更
  • 修复引入新的 public API
  • 修复范围超出单一函数/模块
tweak → full（满足任一即升级）：
  • 改动涉及 5+ 文件
  • 涉及多个模块的协调修改
  • 需要新增测试用例 5+
  • 涉及配置项的新增或删除（非值修改）
hotfix → full (upgrade if any condition is met):
  • Changes involve 3+ files
  • Involves architectural changes (new modules, new interfaces, new dependencies)
  • Involves database schema changes
  • Fix introduces new public APIs
  • Fix scope exceeds a single function/module
tweak → full (upgrade if any condition is met):
  • Changes involve 5+ files
  • Involves coordinated modifications across multiple modules
  • Requires adding 5+ test cases
  • Involves adding or deleting configuration items (not value modifications)

错误处理速查

Error Handling Quick Reference

场景处理方式
openspec list --json
失败		检查 openspec 是否已安装，提示 
openspec init
子 skill 不可用停止流程，提示安装或启用对应 skill
.comet.yaml
格式异常或缺失		以文件状态为准，用 
bash $COMET_STATE set
修正后继续
构建/测试失败返回 build 阶段修复，不进入 verify
change 目录结构不完整按 
comet-open
产物要求补齐
ScenarioHandling Method
openspec list --json
fails		Check if openspec is installed, prompt 
openspec init
Sub-skill unavailableStop workflow, prompt to install or enable the corresponding skill
.comet.yaml
format exception or missing		Take file status as the standard, correct with 
bash $COMET_STATE set
before continuing
Build/test failureReturn to build phase for repair, do not enter verify
Change directory structure incompleteComply with 
/comet-open
product requirements to complete

阶段衔接

Phase Transition

<IMPORTANT> 单次 `/comet` 调用从检测到的阶段开始，退出条件满足后进入下一阶段。
流转链：open → design → build → verify → archive
连续执行要求：从检测到的阶段开始，agent 自动推进后续阶段。但自动推进仅适用于没有用户决策的衔接点。遇到用户决策点时，必须使用 AskUserQuestion 工具暂停并等待用户明确回复，不得用推荐规则、默认值或历史偏好代替用户确认，也不得仅输出文字提示后继续执行。
决策点是阻塞点：只要到达下列任一节点，当前 
/comet
调用必须停住，使用 AskUserQuestion 工具等待用户选择。用户明确选择后才能写入对应状态字段、执行对应操作，随后再继续自动流转。
需要用户参与的节点（仅在这些节点暂停）：
  1. open 阶段 proposal/design/tasks 审视确认
  2. brainstorming 确认设计方案
  3. build 阶段选择工作方式（隔离方式 + 执行方式，一次交互完成）
  4. verify 不通过时决定修复或接受偏差（含 Spec 漂移处理方式选择）
  5. finishing-branch 选择分支处理方式
  6. 遇到升级条件（hotfix/tweak → 完整流程）
  7. build 阶段范围扩张需重新设计或拆分新 change
agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须自动继续推进，不得中途退出。到达决策点时，禁止以文字输出代替工具等待——必须通过 AskUserQuestion 明确获取用户选择后才能继续。
红旗清单 — 以下想法出现时立即停止并检查：
Agent 心理实际风险
"用户应该会同意这个方案"不能替用户决策，用 AskUserQuestion
"这只是个小改动，不需要确认"决策点无大小之分，阻塞点必须等待
"用户之前选过 A，这次也选 A"历史偏好不能替代当前确认
"我已经解释了方案，用户没反对"没反对 ≠ 同意，必须用工具获取明确选择
"流程走到这里应该没问题了"验证不通过 ≠ 通过，检查 verify_result
</IMPORTANT>
<IMPORTANT> A single `/comet` call starts from the detected phase, and proceeds to the next phase after exit conditions are met.
Flow chain: open → design → build → verify → archive
Continuous Execution Requirement: Start from the detected phase, the agent automatically advances subsequent phases. But automatic advancement only applies to transition points without user decisions. When encountering a user decision point, must use the AskUserQuestion tool to pause and wait for the user's explicit reply, and cannot replace user confirmation with recommendation rules, default values or historical preferences, nor continue execution after only outputting text prompts.
Decision points are blocking points: As long as any of the following nodes is reached, the current 
/comet
call must stop, wait for the user's selection using the AskUserQuestion tool. Only after the user explicitly selects, can the corresponding state field be written, corresponding operations executed, and then continue automatic flow.
Nodes requiring user participation (only pause at these nodes):
  1. Proposal/design/tasks review confirmation in open phase
  2. Design plan confirmation during brainstorming
  3. Selection of working method in build phase (isolation method + execution method, completed in one interaction)
  4. Decide to fix or accept deviations when verification fails (including selection of Spec drift handling method)
  5. Branch handling method selection in finishing-branch
  6. Encounter upgrade conditions (hotfix/tweak → full workflow)
  7. Scope expansion in build phase requires re-design or splitting new change
Agents should not skip these decision points; other unambiguous phase transitions must continue automatically without exiting midway. When reaching a decision point, prohibited to replace tool waiting with text output — must explicitly obtain user selection via AskUserQuestion before continuing.
Red Flag List — Stop and check immediately when any of the following thoughts occur:
Agent MindsetActual Risk
"The user should agree to this plan"Cannot make decisions for the user, use AskUserQuestion
"This is just a small change, no need for confirmation"Decision points have no size distinction, blocking points must wait
"The user chose A before, so choose A this time"Historical preferences cannot replace current confirmation
"I have explained the plan, the user did not object"No objection ≠ agreement, must obtain explicit selection via tool
"The workflow should be fine here"Verification failure ≠ pass, check verify_result
</IMPORTANT>

子命令速查

Subcommand Quick Reference

命令阶段归属产物
/comet-open
1. 开启OpenSpecproposal.md、design.md、tasks.md
/comet-design
2. 深度设计SuperpowersDesign Doc、delta spec
/comet-build
3. 计划与构建Superpowers实施计划、代码提交
/comet-verify
4. 验证与收尾Both验证报告、分支处理
/comet-archive
5. 归档OpenSpecdelta→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 → 回到完整流程
CommandPhaseOwnerOutput
/comet-open
1. OpenOpenSpecproposal.md, design.md, tasks.md
/comet-design
2. Deep DesignSuperpowersDesign Doc, delta spec
/comet-build
3. Plan & BuildSuperpowersImplementation plan, code commits
/comet-verify
4. Verify & FinalizeBothVerification report, branch handling
/comet-archive
5. ArchiveOpenSpecdelta→main spec sync, design doc annotation, archiving
/comet-hotfix
Preset PathBothQuick fix (skips brainstorming)
/comet-tweak
Preset PathBothMinor changes (skips brainstorming and full plan)
/comet
  ↓ Auto-detect
/comet-open ──→ /comet-design ──→ /comet-build ──→ /comet-verify ──→ /comet-archive
  (OpenSpec)      (Superpowers)     (Superpowers)     (Both)          (OpenSpec)

/comet-hotfix (preset path, skips brainstorming)
  open ──→ build ──→ verify ──→ archive
    ↑ If upgrade condition is triggered → block to confirm upgrade → supplement Design Doc → return to full workflow

/comet-tweak (preset path, skips brainstorming and full plan)
  open ──→ lightweight build ──→ light verify ──→ archive
    ↑ If upgrade condition is triggered → block to confirm upgrade → supplement Design Doc → return to full workflow

参考附录（Reference Appendix）

Reference Appendix

.comet.yaml 字段说明

.comet.yaml Field Description

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
base_ref: a1b2c3d4e5f6...
build_mode: subagent-driven-development
isolation: branch
verify_mode: light
verify_result: pending
verification_report: null
branch_status: pending
created_at: 2026-05-26
verified_at: null
archived: false
字段含义
workflow
full
、
hotfix
或 
tweak
phase
当前阶段：
open
、
design
、
build
、
verify
、
archive
（init 统一设为 
open
，guard 负责过渡）
design_doc
关联的 Superpowers Design Doc 路径，可为空
plan
关联的 Superpowers Plan 路径，可为空
base_ref
init 时记录的 git commit SHA，用于 scale 评估。无 plan 时作为改动文件数统计基准
build_mode
已选择的执行方式，可为空
isolation
branch
或 
worktree
，工作区隔离方式。full 初始化可为 
null
，但只允许持续到 
/comet-build
Step 3 前；hotfix/tweak 默认 
branch
verify_mode
light
或 
full
，可为空
verify_result
pending
、
pass
或 
fail
verification_report
验证报告文件路径，verify 通过前必须指向已存在文件
branch_status
pending
或 
handled
，分支处理完成后设为 
handled
created_at
change 创建日期（init 时自动写入），格式 
YYYY-MM-DD
verified_at
验证通过时间，可为空
archived
change 是否已归档
可选字段：
字段含义
direct_override
true
/
false
。full workflow 如需使用 
build_mode: direct
，必须显式设为 
true
build_command
项目构建命令。guard 优先运行该命令，失败时打印命令输出
verify_command
项目验证命令。verify guard 优先运行该命令，未配置时回退到构建命令
状态机硬约束：
  • build → verify
    前，
    isolation
    必须是 
    branch
    或 
    worktree
  • build → verify
    前，
    build_mode
    必须已选择
  • build_mode: direct
    默认只允许 
    hotfix
    / 
    tweak
    ；full workflow 需要 
    direct_override: true
  • 这些约束同时存在于 
    comet-guard.sh build --apply
    和 
    comet-state.sh transition <name> build-complete
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
base_ref: a1b2c3d4e5f6...
build_mode: subagent-driven-development
isolation: branch
verify_mode: light
verify_result: pending
verification_report: null
branch_status: pending
created_at: 2026-05-26
verified_at: null
archived: false
FieldMeaning
workflow
full
, 
hotfix
or 
tweak
phase
Current phase: 
open
, 
design
, 
build
, 
verify
, 
archive
(initially set to 
open
uniformly, guard is responsible for transition)
design_doc
Path to associated Superpowers Design Doc, can be empty
plan
Path to associated Superpowers Plan, can be empty
base_ref
git commit SHA recorded during init, used for scale evaluation. Serves as the benchmark for counting changed files when there is no plan
build_mode
Selected execution mode, can be empty
isolation
branch
or 
worktree
, workspace isolation method. Can be 
null
during full initialization, but only allowed until before 
/comet-build
Step 3; hotfix/tweak defaults to 
branch
verify_mode
light
or 
full
, can be empty
verify_result
pending
, 
pass
or 
fail
verification_report
Path to verification report file, must point to an existing file before verify passes
branch_status
pending
or 
handled
, set to 
handled
after branch handling is completed
created_at
Change creation date (automatically written during init), format 
YYYY-MM-DD
verified_at
Verification pass time, can be empty
archived
Whether the change has been archived
Optional Fields:
FieldMeaning
direct_override
true
/
false
. If 
build_mode: direct
is needed for full workflow, must be explicitly set to 
true
build_command
Project build command. Guard runs this command first, prints command output on failure
verify_command
Project verification command. Verify guard runs this command first, falls back to build command if not configured
State Machine Hard Constraints:
  • Before 
    build → verify
    , 
    isolation
    must be 
    branch
    or 
    worktree
  • Before 
    build → verify
    , 
    build_mode
    must be selected
  • build_mode: direct
    is only allowed for 
    hotfix
    / 
    tweak
    by default; full workflow requires 
    direct_override: true
  • These constraints exist in both 
    comet-guard.sh build --apply
    and 
    comet-state.sh transition <name> build-complete

脚本定位

Script Location

Comet 脚本随 skill 包分发在 
comet/scripts/
下。不硬编码路径 — 定位一次，缓存到环境变量：
bash
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"
Comet scripts are distributed with the skill package under 
comet/scripts/
. Do not hardcode paths — locate once and cache to environment variables:
bash
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"

脚本定位失败时停止流程

Stop the workflow if script location fails

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` 状态字段：

```bash
bash "$COMET_GUARD" <change-name> <phase> --apply
--apply
内部委托给 
comet-state transition
。需要直接表达状态事件时使用：
bash
bash "$COMET_STATE" transition <change-name> open-complete
bash "$COMET_STATE" transition <change-name> design-complete
bash "$COMET_STATE" transition <change-name> build-complete
bash "$COMET_STATE" transition <change-name> verify-pass
bash "$COMET_STATE" transition <change-name> verify-fail
bash "$COMET_STATE" transition <archive-name> archived
归档脚本：一键完成归档全部步骤：
bash
bash "$COMET_ARCHIVE" <change-name>
加载 comet 后，agent 应执行以上变量赋值一次，后续全程复用 
$COMET_GUARD
、
$COMET_STATE
、
$COMET_HANDOFF
、
$COMET_ARCHIVE
。
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

**Automatic State Update**: Guard supports the `--apply` parameter, which automatically updates `.comet.yaml` state fields after verification passes:

```bash
bash "$COMET_GUARD" <change-name> <phase> --apply
--apply
internally delegates to 
comet-state transition
. Use when directly expressing state events:
bash
bash "$COMET_STATE" transition <change-name> open-complete
bash "$COMET_STATE" transition <change-name> design-complete
bash "$COMET_STATE" transition <change-name> build-complete
bash "$COMET_STATE" transition <change-name> verify-pass
bash "$COMET_STATE" transition <change-name> verify-fail
bash "$COMET_STATE" transition <archive-name> archived
Archive Script: Complete all archiving steps with one click:
bash
bash "$COMET_ARCHIVE" <change-name>
After loading comet, the agent should perform the above variable assignment once, and reuse 
$COMET_GUARD
, 
$COMET_STATE
, 
$COMET_HANDOFF
, 
$COMET_ARCHIVE
throughout the process.

文件结构

File Structure

openspec/                              # OpenSpec — WHAT
├── config.yaml
├── changes/
│   ├── <name>/                        # 活跃 change
│   │   ├── .openspec.yaml
│   │   ├── .comet.yaml
│   │   ├── proposal.md                # Why + What
│   │   ├── design.md                  # 高层架构决策
│   │   ├── specs/<capability>/spec.md # Delta 能力规格
│   │   ├── .comet/handoff/            # 脚本生成的阶段交接包
│   │   └── 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 关联元数据）
openspec/                              # OpenSpec — WHAT
├── config.yaml
├── changes/
│   ├── <name>/                        # Active change
│   │   ├── .openspec.yaml
│   │   ├── .comet.yaml
│   │   ├── proposal.md                # Why + What
│   │   ├── design.md                  # High-level architecture decisions
│   │   ├── specs/<capability>/spec.md # Delta capability specification
│   │   ├── .comet/handoff/            # Phase handoff package generated by script
│   │   └── tasks.md                   # Task list
│   └── archive/YYYY-MM-DD-<name>/     # Archived
└── specs/<capability>/spec.md         # Main specs (overwritten from delta during archiving)

docs/superpowers/                      # Superpowers — HOW
├── specs/YYYY-MM-DD-<topic>-design.md # Design document (technical RFC, state annotated during archiving)
└── plans/YYYY-MM-DD-<feature>.md      # Implementation plan (contains change association metadata in file header)

最佳实践

Best Practices

  1. brainstorming 不可跳过 — 每次变更必须经过深度设计（hotfix 和 tweak 除外）
  2. delta spec 是活文档 — 阶段 3 期间可自由修改，归档时同步
  3. 交接包由脚本生成 — OpenSpec → Superpowers 的上下文必须通过 
    comet-handoff.sh
    生成 compact 可追溯摘录（必要时 
    --full
    ），并由 guard 校验 source/hash/mode
  4. 保持 tasks.md 同步 — 完成一个勾一个
  5. 频繁提交 — 每个任务一次提交，message 体现设计意图
  6. 先验证再归档 — 
    /comet-verify
    通过后才执行 
    /comet-archive
  7. 增量更新分级 — 小编辑、中重 brainstorming、大新 change
  8. Plan 必须关联 change — 文件头包含 
    change:
    和 
    design-doc:
    元数据
  9. 归档闭环 — design doc 和 plan 必须标注 
    archived-with
    状态
  10. 修改已有功能 — 直接 open 新 change 即可
  11. Preset 有上限 — hotfix/tweak 满足升级条件时及时切换到完整流程
  1. Brainstorming cannot be skipped — Every change must undergo deep design (except hotfix and tweak)
  2. Delta spec is a living document — Can be freely modified during Phase 3, synchronized during archiving
  3. Handoff packages are generated by scripts — Context from OpenSpec → Superpowers must be generated as compact, traceable excerpts via 
    comet-handoff.sh
    (use 
    --full
    if necessary), and validated by guard for source/hash/mode
  4. Keep tasks.md synchronized — Check off one task after completion
  5. Commit frequently — One commit per task, message reflects design intent
  6. Verify before archiving — Execute 
    /comet-archive
    only after 
    /comet-verify
    passes
  7. Incremental update grading — Minor edits, medium brainstorming, major new changes
  8. Plan must be associated with change — File header contains 
    change:
    and 
    design-doc:
    metadata
  9. Archiving closed loop — Design doc and plan must be annotated with 
    archived-with
    state
  10. Modify existing features — Simply open a new change
  11. Presets have limits — Switch to full workflow promptly when hotfix/tweak meets upgrade conditions