Comet Classic — OpenSpec + Superpowers Dual-Star Development Workflow

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

Agents only need to read this section for decision-making, and refer to the appendix as needed.

Output Language Rules

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: 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

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

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

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

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

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

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

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

Consult

comet-classic/reference/file-structure.md

for the complete directory structure.

comet-classic

NPX Install

Tags

SKILL.md Content (Chinese)

Comet Classic — OpenSpec + Superpowers Dual-Star Development Workflow

Decision Core

Output Language Rules

Automatic Phase Detection

Comet Ambient Resume

Preset Upgrade Determination

Error Handling Quick Reference

Phase Transition

Subcommand Quick Reference

Reference Appendix

State Machine Hard Constraints

Script Location

File Structure