comet-classic

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Comet Classic — OpenSpec + Superpowers 双星开发流程

Comet Classic — OpenSpec + Superpowers Dual-Star Development Workflow

开始或恢复前必须先读取并执行

comet-classic/reference/classic-layout.md

；本文件中的 OpenSpec CLI 调用必须使用 adapter，文件路径必须使用该协议绑定的

<classic-*>

逻辑根。

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

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

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

Before starting or resuming, you must first read and execute

comet-classic/reference/classic-layout.md

; all OpenSpec CLI calls in this document must use an adapter, and file paths must use the

<classic-*>

logical root bound by this protocol.

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, wrap-up

Core Principle: Brainstorming cannot be skipped. Every change must undergo in-depth 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.

输出语言规则

Output Language Rules

所有 OpenSpec 和 Superpowers 产物都必须使用 Comet 配置的产物语言。配置值是规范化语言 ID，

en

或

zh-CN

。已有 change 优先通过

comet state get <name> language

读取

<classic-change-dir>/.comet.yaml

中的

language

；

.comet.yaml

尚不存在时依次读取项目

.comet/config.yaml

和全局

~/.comet/config.yaml

的

classic.language

；都不存在时才回退到当前用户请求语言。调用外部 OpenSpec/Superpowers skill 时，必须把解析后的语言显式写入 prompt 或 ARGUMENTS。

All OpenSpec and Superpowers artifacts must use the product language configured in Comet. The configuration value is a standardized language ID,

en

zh-CN

. For existing changes, prioritize reading the

language

field in

<classic-change-dir>/.comet.yaml

via

comet state get <name> language

; if

.comet.yaml

does not exist, read

classic.language

from the project

.comet/config.yaml

and global

~/.comet/config.yaml

in sequence; if neither exists, fall back to the current user request language. When calling external OpenSpec/Superpowers skills, the resolved language must be explicitly written into the prompt or ARGUMENTS.

阶段自动检测

Automatic Phase Detection

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

先按
```
comet-classic/reference/scripts.md
```
直接运行公开 Comet CLI 命令。
运行
```
comet classic openspec -- list --json
```
获取所有活跃 change。
根据用户请求、active change 列表和必要仓库状态填写
```
CometIntentFrame
```
。
优先用
```
comet classic intent route --stdin
```
传入 frame JSON，获取 runtime 规范化路由。
```
CometIntentFrame + runtime scorer
```
是事实源；本节自然语言规则只用于意图识别槽位提取。
按 runtime route 处理：
- ```
hotfix
```
  → 直接调用
```
/comet-hotfix
```
- ```
tweak
```
  → 直接调用
```
/comet-tweak
```
- ```
full
```
  → 按活跃 change 表决定
```
/comet-open
```
  或用户确认
- ```
resume
```
  → 进入 Step 1 读取对应 change 的
```
.comet.yaml
```
- ```
ask_user
```
  → 按
```
comet-classic/reference/decision-point.md
```
  暂停并等待用户选择
- ```
out_of_scope
```
  → 说明本次输入不是 Comet workflow 启动/恢复请求，不初始化 change

当 runtime route、Ambient Resume 或用户选择已经解析出明确 change 后，进入对应阶段 Skill 前必须先绑定当前执行上下文：

bash

comet state select <change-name>

多个 active change 且用户尚未明确选择时，不得提前绑定；继续按

ask_user

决策点等待选择。

Step 0: Active Change Discovery and Intent Determination

Directly run public Comet CLI commands as specified in
```
comet-classic/reference/scripts.md
```
.
Run
```
comet classic openspec -- list --json
```
to get all active changes.
Fill in the
```
CometIntentFrame
```
based on user requests, active change list, and necessary repository status.
Prioritize passing the frame JSON via
```
comet classic intent route --stdin
```
to get the runtime standardized route.
```
CometIntentFrame + runtime scorer
```
is the source of truth; the natural language rules in this section are only used for intent recognition slot extraction.
Process according to the runtime route:
- ```
hotfix
```
  → directly call
```
/comet-hotfix
```
- ```
tweak
```
  → directly call
```
/comet-tweak
```
- ```
full
```
  → decide between
```
/comet-open
```
  or user confirmation based on the active change table
- ```
resume
```
  → proceed to Step 1 to read the
```
.comet.yaml
```
  of the corresponding change
- ```
ask_user
```
  → pause and wait for user selection according to
```
comet-classic/reference/decision-point.md
```
- ```
out_of_scope
```
  → indicate that this input is not a Comet workflow start/resume request, do not initialize a change

After the runtime route, Ambient Resume, or user selection has resolved an explicit change, you must bind the current execution context before entering the corresponding phase skill:

bash

comet state select <change-name>

Do not bind in advance when there are multiple active changes and the user has not made an explicit choice; continue waiting for selection according to the

ask_user

decision point.

Comet Ambient Resume

当用户未显式输入

/comet-classic

，但当前仓库可能已有 active Comet change 时，开始处理需要改动或调查的任务前先运行只读探针：

bash

comet resume-probe . --stdin --json

探针只读仓库状态，不修改文件。按返回值处理：

auto_resume

：输出一行

[COMET] 检测到 active change <name>，按 <nextCommand> 恢复。

，然后进入

nextCommand

。

```
ask_user
```
：只问一个短问题并等待用户回复。
```
out_of_scope
```
或
```
none
```
：不要进入 Comet workflow。

原则：不把无关任务挂到 active Comet change，尤其不能只因为存在

.comet.yaml

就这样做。

CometIntentFrame 最小骨架：

json

{
  "schema_version": "comet.intent.v1",
  "utterance": "<用户原话>",
  "intent": { "name": "start_change", "confidence": 0.8 },
  "slots": {
    "requested_action": "start",
    "workflow_candidate": "full",
    "user_explicit_workflow": null,
    "change_id": null,
    "existing_behavior": null,
    "new_capability": null,
    "public_api_change": null,
    "schema_change": null,
    "cross_module_change": null
  },
  "context": {
    "active_changes_count": 0,
    "active_change_names": []
  },
  "evidence": [],
  "proposed_route": {
    "name": "ask_user",
    "confidence": 0.5
  }
}

意图识别槽位提取：字段完整含义见

comet-classic/reference/intent-frame.md

；正常路由只需按上方最小骨架填写。

```
fix_bug
```
+
```
existing_behavior: true
```
+ 无新增 capability/public API/schema/cross-module 信号 → 倾向
```
hotfix
```
用户明确描述为可收敛为单一 OpenSpec change 的轻量/中等变更，需通过 OpenSpec apply 执行，且不需要完整
```
/comet-classic
```
深度设计/plan → 倾向
```
tweak
```
文案、配置、文档、prompt 或单一 OpenSpec change 的轻中量修改 → 倾向
```
tweak
```
新增 capability、public API、schema 变更、跨模块协调或架构调整 → 倾向
```
full
```
多个 active change 且用户未明确 change →
```
ask_user
```
置信度不足、关键 evidence 缺失或用户显式 workflow 与风险信号冲突 →
```
ask_user
```

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

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

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

优先读取

<classic-change-dir>/.comet.yaml

。不存在时回退到

comet classic openspec -- status --change "<name>" --json

、

<classic-change-dir>/tasks.md

和

<classic-superpowers-root>/

文件检查。

断点恢复规则：

每次恢复上下文时，先重新执行 Step 0 和 Step 1，不依赖对话历史判断阶段
只要存在 active change 且工作区有未提交改动，必须按
```
comet-classic/reference/dirty-worktree.md
```
协议处理。该协议定义了检查步骤、归因分类和禁令，本文件不重复
若
```
phase: build
```
，先检查
```
build_pause
```
、
```
plan
```
、
```
isolation
```
、
```
build_mode
```
、
```
tdd_mode
```
和
```
review_mode
```
（详见下方）：
- 若
```
build_pause: plan-ready
```
  但
```
isolation
```
  、
```
build_mode
```
  、
```
tdd_mode
```
  和
```
review_mode
```
  都已经设置，则视为 stale pause：先输出
```
[COMET] 检测到 stale pause（build_pause=plan-ready 但 isolation/build_mode/tdd_mode/review_mode 已设置），自动清除并继续
```
  ，再运行
```
comet state set <name> build_pause null
```
  ，然后读取 tasks.md 的下一个未勾选任务并按
```
build_mode
```
  恢复执行
- 若
```
build_pause: plan-ready
```
  且 plan 文件存在，但
```
isolation
```
  、
```
build_mode
```
  、
```
tdd_mode
```
  或
```
review_mode
```
  尚未设置，回到
```
/comet-build
```
  的 plan-ready 恢复点，提示用户继续补齐/确认工作区隔离、执行方式、TDD 模式和代码审查模式，不重新生成 plan
- 若
```
build_pause: plan-ready
```
  但 plan 文件缺失，回到
```
/comet-build
```
  处理状态损坏或重新生成 plan
- 若
```
isolation
```
  、
```
build_mode
```
  、
```
tdd_mode
```
  或
```
review_mode
```
  未设置，回到
```
/comet-build
```
  对应步骤补充后再执行
- 若均已设置，读取 tasks.md 的下一个未勾选任务，并按
```
build_mode
```
  恢复执行：
  - 若
```
build_mode: subagent-driven-development
```
    ，不得在主窗口直接执行任务；必须回到
```
/comet-build
```
    的后台 subagent 调度规则，由主窗口只做协调
  - 其他执行方式按
```
/comet-build
```
    的对应规则继续
若
```
verify_result: fail
```
，读取
```
verify_failures
```
：未超过 3 次时直接调用
```
/comet-build
```
继续已记录的修复循环，不重复询问；超过自动修复上限时回到
```
/comet-verify
```
的例外决策点。只有接受 WARNING/SUGGESTION 偏差或超限后的继续/停止策略需要用户选择
若
```
phase: open
```
但 OpenSpec
```
applyRequires
```
已完整，先运行
```
comet guard <change-name> open --apply
```
修正状态，再继续判定
若
```
phase: archive
```
，只允许调用
```
/comet-archive
```
；归档前先等待最终确认，归档后精确提交归档改动，再处理分支并运行 archive guard

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

```
archived: true
```
或 change 已移入 archive → 流程已完成
```
verify_result: pass
```
且
```
archived
```
不是
```
true
```
→
```
/comet-archive
```
（先进行归档前最终确认）
```
verify_result: fail
```
→ 自动调用
```
/comet-build
```
继续修复；若
```
verify_failures
```
已超过自动修复上限，则进入
```
/comet-verify
```
的超限策略决策点
```
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

后继续。

When the user does not explicitly input

/comet-classic

, but there may be active Comet changes in the current repository, run a read-only probe before starting tasks that require modification or investigation:

bash

comet resume-probe . --stdin --json

The probe only reads the repository status and does not modify files. Process according to the return value:

auto_resume

: Output a line

[COMET] Detected active change <name>, resuming with <nextCommand>.

, then proceed to

nextCommand

```
ask_user
```
: Ask only one short question and wait for the user's reply.
```
out_of_scope
```
or
```
none
```
: Do not enter the Comet workflow.

Principle: Do not attach unrelated tasks to active Comet changes, especially not just because

.comet.yaml

exists.

Minimum CometIntentFrame Skeleton:

json

{
  "schema_version": "comet.intent.v1",
  "utterance": "<user's original input>",
  "intent": { "name": "start_change", "confidence": 0.8 },
  "slots": {
    "requested_action": "start",
    "workflow_candidate": "full",
    "user_explicit_workflow": null,
    "change_id": null,
    "existing_behavior": null,
    "new_capability": null,
    "public_api_change": null,
    "schema_change": null,
    "cross_module_change": null
  },
  "context": {
    "active_changes_count": 0,
    "active_change_names": []
  },
  "evidence": [],
  "proposed_route": {
    "name": "ask_user",
    "confidence": 0.5
  }
}

Intent Recognition Slot Extraction: The complete meaning of fields can be found in

comet-classic/reference/intent-frame.md

; normal routing only requires filling in the minimum skeleton above.

```
fix_bug
```
+
```
existing_behavior: true
```
+ no signals of new capability/public API/schema/cross-module changes → tend to
```
hotfix
```
User explicitly describes a light/medium change that can be converged into a single OpenSpec change, needs to be executed via OpenSpec apply, and does not require complete
```
/comet-classic
```
in-depth design/plan → tend to
```
tweak
```
Light/medium modifications to copy, configuration, documents, prompts, or a single OpenSpec change → tend to
```
tweak
```
New capability, public API, schema change, cross-module coordination, or architecture adjustment → tend to
```
full
```
Multiple active changes and user has not specified a change →
```
ask_user
```
Insufficient confidence, missing key evidence, or conflict between user's explicit workflow and risk signals →
```
ask_user
```

Active Change	User Input	Action
None	`full` route	→ Call `/comet-open`
Exactly 1	`/comet-classic <description>`	→ Ask: Continue this change or create a new one
Multiple	`/comet-classic <description>`	→ Ask: Continue existing changes or create a new one; if continue is selected → list options for user to choose
Exactly 1	`/comet-classic` (no description)	→ Automatically select and enter Step 1
Multiple	`/comet-classic` (no description)	→ List options for user to choose

<IMPORTANT> When the user selects "Create new change", **must call `/comet-open`** (prohibit direct call to `/opsx:new`). `/comet-open` is responsible for complete dual initialization: OpenSpec artifacts (created by internal `/opsx:new`) + `.comet.yaml` status file. Directly calling `/opsx:new` will result in missing `.comet.yaml`, leading to failure in subsequent phase determination. </IMPORTANT>

Step 1: Read
.comet.yaml
Status Metadata

Prioritize reading

<classic-change-dir>/.comet.yaml

. If it does not exist, fall back to checking

comet classic openspec -- status --change "<name>" --json

<classic-change-dir>/tasks.md

, and files in

<classic-superpowers-root>/

Breakpoint Resume Rules:

When resuming context each time, re-execute Step 0 and Step 1 first, do not rely on conversation history to determine the phase
As long as there is an active change and uncommitted changes in the workspace, must handle according to the
```
comet-classic/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
```
build_pause
```
,
```
plan
```
,
```
isolation
```
,
```
build_mode
```
,
```
tdd_mode
```
, and
```
review_mode
```
(see details below):
- If
```
build_pause: plan-ready
```
  but
```
isolation
```
  ,
```
build_mode
```
  ,
```
tdd_mode
```
  , and
```
review_mode
```
  are already set, it is considered a stale pause: first output
```
[COMET] Detected stale pause (build_pause=plan-ready but isolation/build_mode/tdd_mode/review_mode are set), automatically clearing and continuing
```
  , then run
```
comet state set <name> build_pause null
```
  , then read the next unchecked task in tasks.md and resume execution according to
```
build_mode
```
- If
```
build_pause: plan-ready
```
  and the plan file exists, but
```
isolation
```
  ,
```
build_mode
```
  ,
```
tdd_mode
```
  , or
```
review_mode
```
  are not set yet, return to the plan-ready resume point of
```
/comet-build
```
  , prompt the user to continue completing/confirming workspace isolation, execution method, TDD mode, and code review mode, do not regenerate the plan
- If
```
build_pause: plan-ready
```
  but the plan file is missing, return to
```
/comet-build
```
  to handle status corruption or regenerate the plan
- If
```
isolation
```
  ,
```
build_mode
```
  ,
```
tdd_mode
```
  , or
```
review_mode
```
  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 and resume execution according to
```
build_mode
```
  :
  - If
```
build_mode: subagent-driven-development
```
    , do not execute tasks directly in the main window; must return to the background subagent scheduling rules of
```
/comet-build
```
    , with the main window only responsible for coordination
  - Other execution methods continue according to the corresponding rules of
```
/comet-build
```
If
```
verify_result: fail
```
, read
```
verify_failures
```
: if it does not exceed 3 times, directly call
```
/comet-build
```
to continue the recorded repair loop without repeated inquiries; if it exceeds the automatic repair limit, return to the exception decision point of
```
/comet-verify
```
. Only the strategy of accepting WARNING/SUGGESTION deviations or continuing/stopping after exceeding the limit requires user selection
If
```
phase: open
```
but OpenSpec
```
applyRequires
```
is complete, first run
```
comet guard <change-name> open --apply
```
to correct the status, then continue determination
If
```
phase: archive
```
, only allow calling
```
/comet-archive
```
; wait for final confirmation before archiving, accurately commit the archive changes, then process the branch and run the archive guard

Step 2: Phase Determination (in order, stop when hit)

```
archived: true
```
or change has been moved to archive → workflow completed
```
verify_result: pass
```
and
```
archived
```
is not
```
true
```
→
```
/comet-archive
```
(first conduct final confirmation before archiving)
```
verify_result: fail
```
→ automatically call
```
/comet-build
```
to continue repair; if
```
verify_failures
```
has exceeded the automatic repair limit, enter the over-limit strategy decision point of
```
/comet-verify
```
```
phase: verify
```
or all tasks in tasks.md are checked →
```
/comet-verify
```
```
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
```
```
phase: design
```
or change exists but no Design Doc →
```
/comet-design
```
```
phase: open
```
or active change exists but
```
.comet.yaml
```
is missing →
```
/comet-open
```
No active changes →
```
/comet-open
```

If metadata conflicts with file status, take file status as the standard, correct

.comet.yaml

, then continue.

预设升级判定

Preset Upgrade Determination

hotfix/tweak 的范围判定采用三层分工，避免「用纯文件数当硬性升级条件」误杀正常小改动：

质变信号（agent 语义识别，命中任一即暂停交用户二选一）：跨模块协调修改、需要新增 capability、数据库 schema 变更、引入新的 public API、触及深层架构问题（各预设沿用这套核心信号，并可追加自身语境的特有信号，如 tweak 的「需要拆分为多个 OpenSpec changes」）
文件数 tripwire（用户拍板，非自动升级）：改动文件数超提示阈值时，暂停交用户决定继续预设流程还是升级 full，不自动踢
验证级别（scale 脚本判定）：
```
comet state scale
```
仅决定
```
verify_mode
```
（验证轻重），不卡流程、不触发升级

升级决策点（用户二选一）：

继续预设轻量流程（用户确认范围可控）
升级为完整
```
/comet-classic
```
（使用
```
comet state transition <name> preset-escalate
```
合法回退到 design 阶段，同时清除预设专属的 build 配置；补 Design Doc 后重新联合选择完整工作方式）

详细判定规则见

comet-hotfix

comet-tweak

各自的「升级判定」章节。

The scope determination for hotfix/tweak adopts a three-layer division of labor to avoid mistakenly killing normal small changes by "using pure file count as a hard upgrade condition":

Qualitative Change Signals (agent semantic recognition, pause and ask user to choose one if any are hit): cross-module coordinated modifications, need to add new capabilities, database schema changes, introduce new public APIs, touch deep architecture issues (each preset follows this set of core signals and can add its own context-specific signals, such as tweak's "needs to be split into multiple OpenSpec changes")
File Count Tripwire (user decides, no automatic upgrade): when the number of modified files exceeds the prompt threshold, pause and ask the user to decide whether to continue the preset workflow or upgrade to full, do not automatically kick out
Verification Level (determined by scale script):
```
comet state scale
```
only determines
```
verify_mode
```
(light/heavy verification), does not block the workflow or trigger upgrade

Upgrade Decision Point (user chooses one):

Continue the preset lightweight workflow (user confirms the scope is controllable)
Upgrade to complete
```
/comet-classic
```
(use
```
comet state transition <name> preset-escalate
```
to legally roll back to the design phase, clear preset-specific build configuration at the same time; supplement the Design Doc and then re-select the complete working method)

Detailed determination rules can be found in the "Upgrade Determination" sections of

comet-hotfix

comet-tweak

respectively.

错误处理速查

Error Handling Quick Reference

场景	处理方式
`comet classic openspec -- list --json` 失败	检查 OpenSpec 是否已安装；若 artifact root 缺失或损坏，提示运行 `comet update --scope project` 或重新运行 `comet init --scope project`
子 skill 不可用	停止流程，提示安装或启用对应 skill
`.comet.yaml` 缺失	进入对应 preset 的 `/comet-open` 初始化状态，再运行 `comet state select` ；不得跳过初始化
`.comet.yaml` 格式异常	停止并报告解析错误；从版本控制、备份或可验证产物人工修复，不能用 `comet state set` 覆盖损坏文件
构建/测试失败	返回 build 阶段修复，不进入 verify
change 目录结构不完整	按 `comet-open` 产物要求补齐

Scenario	Handling Method
`comet classic openspec -- list --json` fails	Check if OpenSpec is installed; if the artifact root is missing or damaged, prompt to run `comet update --scope project` or re-run `comet init --scope project`
Sub-skill unavailable	Stop the workflow, prompt to install or enable the corresponding skill
`.comet.yaml` missing	Enter the initialization state of `/comet-open` for the corresponding preset, then run `comet state select` ; do not skip initialization
`.comet.yaml` format exception	Stop and report parsing error; manually repair from version control, backup, or verifiable artifacts, do not overwrite damaged files with `comet state set`
Build/test failure	Return to the build phase for repair, do not enter verify
Change directory structure incomplete	Supplement according to the product requirements of `comet-open`

阶段衔接

Phase Transition

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

流转链：open → design → build → verify → archive

连续执行要求：从检测到的阶段开始，agent 自动推进后续阶段。但自动推进仅适用于没有用户决策的衔接点。遇到用户决策点时，必须提出明确选项并暂停等待用户回复，不得用推荐规则、默认值或历史偏好代替用户确认，也不得仅输出文字提示后继续执行。

阶段推进与自动衔接的区分：每个子 skill 退出前都会运行阶段守卫

--apply

推进

.comet.yaml

的

phase

字段——这一步始终发生，与

auto_transition

无关。之后子 skill 运行

comet state next <name>

解析下一步：

auto_transition

不为

false

时输出

NEXT: auto

（自动调用下一 skill），为

false

时输出

NEXT: manual

（不调用下一 skill，按

HINT

交还控制权）。

NEXT: manual

不是用户决策点，不得再询问“是否继续”。因此

auto_transition

只控制是否自动调用下一个 skill，不影响 phase 推进。无论

auto_transition

取何值，下方真正的用户决策点都必须阻塞等待。

决策点是阻塞点：只要到达下列任一节点，当前

/comet-classic

调用必须停住，并按

comet-classic/reference/decision-point.md

的协议获取用户明确选择。用户明确选择后才能写入对应状态字段、执行对应操作，随后再继续自动流转。

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

workflow 目标选择：多个 active changes、继续现有 change/创建新 change、或批量拆分完成后选择先启动哪一个
open 阶段 proposal/design/tasks 最终审视确认（同时确认 change 名称与范围；清晰请求不做前置摘要/命名确认）
brainstorming 确认设计方案
build 阶段一次性联合选择 plan-ready 暂停或完整工作方式（工作区隔离 + 执行方式 + TDD 模式 + 代码审查模式；选择 branch 时同时确认分支名）
verify 阶段接受 WARNING/SUGGESTION 偏差、处理 Spec 漂移，或第 4 次失败后选择继续修复/停止；前 3 次明确可修复失败自动闭环
archive 阶段执行归档脚本前的最终确认
归档改动精确提交后选择 finishing-branch 分支处理方式
遇到升级判定信号（hotfix/tweak → 用户二选一：继续预设流程 / 升级完整流程）
build 阶段范围扩张需重新设计或拆分新 change
open 阶段大型 PRD 是否拆分为多个 changes

agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须自动继续推进，不得中途退出。到达决策点时，禁止跳过用户确认或自动选择——必须提出明确选项并获取用户选择后才能继续。

红旗清单 — 以下想法出现时立即停止并检查：

Agent 心理	实际风险
"用户应该会同意这个方案"	不能替用户决策，必须等待用户明确选择
"这只是个小改动，不需要确认"	决策点无大小之分，阻塞点必须等待
"用户之前选过 A，这次也选 A"	历史偏好不能替代当前确认
"我已经解释了方案，用户没反对"	没反对 ≠ 同意，必须用工具获取明确选择
"流程走到这里应该没问题了"	验证不通过 ≠ 通过，检查 verify_result

</IMPORTANT>

<IMPORTANT> A single `/comet-classic` call starts from the detected phase and proceeds to the next phase when the exit condition is met.

Flow chain: open → design → build → verify → archive

Continuous Execution Requirement: Start from the detected phase, the agent automatically advances subsequent phases. However, automatic advancement only applies to transition points without user decisions. When encountering user decision points, must present clear options and pause to wait for the user's reply, do not use recommendation rules, default values, or historical preferences to replace user confirmation, and do not continue execution only after outputting text prompts.

Distinction between Phase Advancement and Automatic Transition: Before exiting, each sub-skill runs the phase guard

--apply

to advance the

phase

field of

.comet.yaml

— this step always occurs, regardless of

auto_transition

. Then the sub-skill runs

comet state next <name>

to parse the next step: when

auto_transition

is not

false

, output

NEXT: auto

(automatically call the next skill); when it is

false

, output

NEXT: manual

(do not call the next skill, return control according to

HINT

NEXT: manual

is not a user decision point, do not ask "whether to continue" again. Therefore,

auto_transition

only controls whether to automatically call the next skill, and does not affect phase advancement. Regardless of the value of

auto_transition

, the following real user decision points must block and wait.

Decision Points are Blocking Points: As long as any of the following nodes are reached, the current

/comet-classic

call must stop, and obtain the user's explicit selection according to the protocol in

comet-classic/reference/decision-point.md

. Only after the user makes an explicit selection can the corresponding status field be written, the corresponding operation be executed, and then automatic flow continue.

Nodes requiring user participation (only pause at these nodes):

Workflow target selection: multiple active changes, continue existing change/create new change, or select which one to start first after batch splitting is completed
Final review confirmation of proposal/design/tasks in the open phase (confirm change name and scope at the same time; do not pre-confirm summary/naming for clear requests)
Confirm design plan during brainstorming
One-time joint selection of plan-ready pause or complete working method in the build phase (workspace isolation + execution method + TDD mode + code review mode; confirm branch name when selecting branch)
Accept WARNING/SUGGESTION deviations, handle Spec drift, or choose to continue repair/stop after the 4th failure in the verify phase; the first 3 clearly repairable failures are automatically closed-loop
Final confirmation before executing the archive script in the archive phase
Choose the finishing-branch handling method after accurately committing archive changes
Encounter upgrade determination signals (hotfix/tweak → user chooses one: continue preset workflow / upgrade to complete workflow)
Scope expansion in the build phase requires re-design or splitting new changes
Whether to split large PRDs into multiple changes in the open phase

Agents should not skip these decision points; other clear and unambiguous phase transitions must continue automatically, and must not exit midway. When reaching a decision point, prohibit skipping user confirmation or automatic selection — must present clear options and obtain user selection before continuing.

Red Flag List — Stop and check immediately when the following thoughts occur:

Agent's Mindset	Actual Risk
"The user should agree to this plan"	Cannot make decisions for the user, must wait for the user's explicit selection
"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, and the user did not object"	No objection ≠ agreement, must use tools to obtain explicit selection
"The process should be fine here"	Verification failed ≠ passed, check verify_result

</IMPORTANT>

子命令速查

Subcommand Quick Reference

命令	阶段	归属	产物
`/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	串联 OpenSpec 的中等改动（delta spec 为一等公民，跳过 brainstorming 和完整 plan）

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

/comet-hotfix（预设路径，跳过 brainstorming）
  open ──→ build ──→ verify ──→ archive
    ↑ 命中升级判定信号 → 用户二选一（继续预设流程 / 升级 full）→ 升级则 transition preset-escalate → 补 Design Doc → 回到完整流程

/comet-tweak（轻量预设路径，串联 OpenSpec，delta spec 为一等公民）
  open ──→ build ──→ verify ──→ archive
    ↑ 命中升级判定信号 → 用户二选一（继续预设流程 / 升级 full）→ 升级则 transition preset-escalate → 补 Design Doc → 回到完整流程

Command	Phase	Ownership	Artifacts
`/comet-open`	1. Initiate	OpenSpec	proposal.md, design.md, tasks.md
`/comet-design`	2. In-depth Design	Superpowers	Design Doc, delta spec
`/comet-build`	3. Planning & Construction	Superpowers	Implementation plan, code commits
`/comet-verify`	4. Verification	Both	Verification report
`/comet-archive`	5. Archiving & Wrap-up	OpenSpec	delta→main spec synchronization, design doc annotation, archive commit, branch handling
`/comet-hotfix`	Preset Path	Both	Quick fix (skips brainstorming)
`/comet-tweak`	Preset Path	Both	Moderate changes linked with OpenSpec (delta spec as first-class citizen, skips brainstorming and complete plan)

/comet-classic
  ↓ Auto-detection
/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
    ↑ Hit upgrade determination signal → user chooses one (continue preset workflow / upgrade to full) → if upgrade, transition preset-escalate → supplement Design Doc → return to complete workflow

/comet-tweak (lightweight preset path, linked with OpenSpec, delta spec as first-class citizen)
  open ──→ build ──→ verify ──→ archive
    ↑ Hit upgrade determination signal → user chooses one (continue preset workflow / upgrade to full) → if upgrade, transition preset-escalate → supplement Design Doc → return to complete workflow

参考附录（Reference Appendix）

Reference Appendix

字段说明、文件结构和自动衔接协议已提取为渐进式加载参考文档，按需查阅：
.comet.yaml
完整字段表：按
comet-classic/reference/comet-yaml-fields.md
查阅（含必需字段、可选字段和完整示例）
文件结构：按
comet-classic/reference/file-structure.md
查阅
自动衔接协议：按
comet-classic/reference/auto-transition.md
查阅
上下文压缩恢复：按
comet-classic/reference/context-recovery.md
查阅
用户决策点协议：按
comet-classic/reference/decision-point.md
查阅
异常调试协议：按
comet-classic/reference/debug-gate.md
查阅

Field descriptions, file structures, and automatic transition protocols have been extracted into progressively loaded reference documents, which can be consulted as needed:
Complete
.comet.yaml
Field Table: Consult
comet-classic/reference/comet-yaml-fields.md
(includes required fields, optional fields, and complete examples)
File Structure: Consult
comet-classic/reference/file-structure.md
Automatic Transition Protocol: Consult
comet-classic/reference/auto-transition.md
Context Compression & Recovery: Consult
comet-classic/reference/context-recovery.md
User Decision Point Protocol: Consult
comet-classic/reference/decision-point.md
Exception Debugging Protocol: Consult
comet-classic/reference/debug-gate.md

状态机硬约束

State Machine Hard Constraints

full workflow 的
```
build → verify
```
前，
```
isolation
```
必须是
```
branch
```
或
```
worktree
```
；hotfix/tweak 可如实使用
```
current
```
```
build → verify
```
前，
```
build_mode
```
必须已选择

build_mode: subagent-driven-development

必须同时有

subagent_dispatch: confirmed

full workflow 离开 build 阶段前
```
tdd_mode
```
必须已选择为
```
tdd
```
或
```
direct
```
full workflow 离开 build 阶段前
```
review_mode
```
必须已选择为
```
off
```
、
```
standard
```
或
```
thorough
```

build_mode: direct

默认只允许

hotfix

tweak

；full workflow 需要

direct_override: true

```
build_pause
```
不是执行方式，不得写入
```
build_mode
```

这些约束同时由

comet guard <name> build --apply

和

comet state transition <name> build-complete

执行

Before
```
build → verify
```
in the full workflow,
```
isolation
```
must be
```
branch
```
or
```
worktree
```
; hotfix/tweak can use
```
current
```
as is
Before
```
build → verify
```
,
```
build_mode
```
must be selected

build_mode: subagent-driven-development

must have

subagent_dispatch: confirmed

at the same time

Before leaving the build phase in the full workflow,
```
tdd_mode
```
must be selected as
```
tdd
```
or
```
direct
```
Before leaving the build phase in the full workflow,
```
review_mode
```
must be selected as
```
off
```
,
```
standard
```
, or
```
thorough
```
```
build_mode: direct
```
is only allowed for
```
hotfix
```
/
```
tweak
```
by default; full workflow requires
```
direct_override: true
```
```
build_pause
```
is not an execution method, must not be written into
```
build_mode
```

These constraints are enforced by both

comet guard <change-name> build --apply

and

comet state transition <change-name> build-complete

脚本定位

Script Location

每个会话按

comet-classic/reference/scripts.md

直接运行公开 CLI 命令。关键入口：

bash

comet guard <change-name> <phase> --apply             # 阶段守卫 + 自动状态更新
comet state transition <change-name> <event>          # open-complete | design-complete | build-complete | verify-pass | verify-fail
comet state next <change-name>                        # NEXT: auto|manual|done + SKILL: <skill-name>
comet archive <change-name>                           # 一键完成归档

Each session directly runs public CLI commands as specified in

comet-classic/reference/scripts.md

. Key entry points:

bash

comet guard <change-name> <phase> --apply             # Phase guard + automatic status update
comet state transition <change-name> <event>          # open-complete | design-complete | build-complete | verify-pass | verify-fail
comet state next <change-name>                        # NEXT: auto|manual|done + SKILL: <skill-name>
comet archive <change-name>                           # One-click archiving

文件结构

File Structure

按

comet-classic/reference/file-structure.md

查阅完整目录结构。

Consult

comet-classic/reference/file-structure.md

for the complete directory structure.