Comet — OpenSpec + Superpowers Binary Star Development Workflow

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

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

Automatic Phase Detection

Step 0: Active Change Discovery and Intent Determination

First perform preset detection; if hotfix/tweak is hit, directly call the corresponding preset skill without entering the normal open branch
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 Changes	User Input	Action
None	Non-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)

```
archived: true
```
or change has been moved to archive → workflow completed

verify_result: pass

and

archived

is not

true

→

/comet-archive

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

and continue.

Preset Upgrade Conditions

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

Scenario	Handling Method
`openspec list --json` fails	Check if openspec is installed, prompt `openspec init`
Sub-skill unavailable	Stop 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 failure	Return to build phase for repair, do not enter verify
Change directory structure incomplete	Comply with `/comet-open` product requirements to complete

Phase Transition

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

Proposal/design/tasks review confirmation in open phase
Design plan confirmation during brainstorming
Selection of working method in build phase (isolation method + execution method, completed in one interaction)
Decide to fix or accept deviations when verification fails (including selection of Spec drift handling method)
Branch handling method selection in finishing-branch
Encounter upgrade conditions (hotfix/tweak → full workflow)
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 Mindset	Actual 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

Command	Phase	Owner	Output
`/comet-open`	1. Open	OpenSpec	proposal.md, design.md, tasks.md
`/comet-design`	2. Deep Design	Superpowers	Design Doc, delta spec
`/comet-build`	3. Plan & Build	Superpowers	Implementation plan, code commits
`/comet-verify`	4. Verify & Finalize	Both	Verification report, branch handling
`/comet-archive`	5. Archive	OpenSpec	delta→main spec sync, design doc annotation, archiving
`/comet-hotfix`	Preset Path	Both	Quick fix (skips brainstorming)
`/comet-tweak`	Preset Path	Both	Minor 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

.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

Field	Meaning
`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:

Field	Meaning
`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 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

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

Brainstorming cannot be skipped — Every change must undergo deep design (except hotfix and tweak)
Delta spec is a living document — Can be freely modified during Phase 3, synchronized during archiving
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
Keep tasks.md synchronized — Check off one task after completion
Commit frequently — One commit per task, message reflects design intent
Verify before archiving — Execute
```
/comet-archive
```
only after
```
/comet-verify
```
passes
Incremental update grading — Minor edits, medium brainstorming, major new changes
Plan must be associated with change — File header contains
```
change:
```
and
```
design-doc:
```
metadata
Archiving closed loop — Design doc and plan must be annotated with
```
archived-with
```
state
Modify existing features — Simply open a new change
Presets have limits — Switch to full workflow promptly when hotfix/tweak meets upgrade conditions

comet

NPX Install

Tags

SKILL.md Content (Chinese)

Comet — OpenSpec + Superpowers Binary Star Development Workflow

Decision Core

Automatic Phase Detection

Preset Upgrade Conditions

Error Handling Quick Reference

Phase Transition

Subcommand Quick Reference

Reference Appendix

.comet.yaml Field Description

Script Location

File Structure

Best Practices