Comet

Comet — OpenSpec + Superpowers Dual-Star Development Workflow

OpenSpec and Superpowers orbit the same goal like a binary star system.

OpenSpec handles WHAT  — outline, proposal, spec lifecycle, archive
Superpowers handles HOW — technical design, planning, execution, closing

Core principle: brainstorming cannot be skipped. Every change must undergo deep design (except hotfix and tweak presets).

Decision Core

Agents need only read this section for decision-making. Refer to the Reference Appendix as needed.

Output Language Rule

Use the language of the user request that triggered this workflow as the default output language. When resuming an existing change with a clear dominant artifact language, preserve that language unless the user explicitly asks to switch.

Automatic Phase Detection

Step 0: Active Change Discovery and Intent Detection

1. Detect presets first; if hotfix/tweak matches, invoke the corresponding preset skill directly and do not enter the normal open branch
2. When no preset matches, run openspec list --json to get all active changes

Preset detection has highest priority:

• User explicitly describes a bug fix / hotfix + meets hotfix conditions → directly invoke /comet-hotfix
• User explicitly describes copy/config/docs/prompt small adjustment + meets tweak conditions → directly invoke /comet-tweak
• No preset match → follow the table below

<IMPORTANT>
When the user chooses "create a new change", **must invoke `/comet-open`**. Do not call `/opsx:new` directly.
`/comet-open` performs dual initialization: OpenSpec artifacts (created by internal `/opsx:new`) plus `.comet.yaml` state file.
Calling `/opsx:new` directly leaves `.comet.yaml` missing and breaks later phase detection.
</IMPORTANT>

Step 1: Read .comet.yaml state metadata

Prefer reading openspec/changes/<name>/.comet.yaml. If not available, fall back to openspec status --change "<name>" --json, tasks.md, and docs/superpowers/ file checks.

Resume rules:

• On every context resume, rerun Step 0 and Step 1; do not trust conversation history for phase detection
• If there is an active change and the worktree has uncommitted changes, handle them through comet/reference/dirty-worktree.md. That protocol defines checks, attribution, and prohibitions; this file does not repeat them
• If phase: build, first check build_pause, plan, build_mode, and isolation (see details below):
  • If build_pause: plan-ready but isolation and build_mode are already set, treat as stale pause: first output [COMET] Detected stale pause (build_pause=plan-ready but isolation/build_mode already set), auto-clearing and continuing, then run "$COMET_BASH" "$COMET_STATE" set <name> build_pause null, then read the next unchecked task from tasks.md and resume execution per build_mode
  • If build_pause: plan-ready and the plan file exists, but isolation or build_mode is not yet set, return to the /comet-build plan-ready resume point, prompt the user to choose isolation and execution method, and do not regenerate the plan
  • If build_pause: plan-ready but the plan file is missing, return to /comet-build to handle corrupted state or regenerate the plan
  • If build_mode, isolation, or tdd_mode is unset, return to the corresponding /comet-build step to supplement before executing
  • If all are set, read the next unchecked task from tasks.md and continue:
    • If build_mode: subagent-driven-development, do not execute tasks directly in the main window; return to /comet-build's background subagent dispatch rules, main window only coordinates
    • Other execution modes follow /comet-build's corresponding rules
• If phase: verify and verify_result: fail, enter the verification failure decision blocking point: pause and ask the user to fix or accept deviation; only after the user chooses fix, run "$COMET_BASH" "$COMET_STATE" transition <name> verify-fail and invoke /comet-build
• If phase: open but proposal/design/tasks are complete, first run "$COMET_BASH" "$COMET_GUARD" <change-name> open --apply to repair state, then continue detection
• If phase: archive, only invoke /comet-archive; /comet-archive must first wait for final archive confirmation. After archive succeeds, the change moves to the archive directory, so do not run guard against the old active directory

Step 2: Phase Determination (check in order, first match wins)

1. archived: true or change moved to archive → Workflow complete
2. verify_result: pass and archived is not true → Invoke /comet-archive (first perform final archive confirmation)
3. verify_result: fail → Enter verification failure decision blocking point (pause and ask fix or accept deviation; only after user chooses fix, run verify-fail then /comet-build)
4. phase: verify or tasks.md all checked → Invoke /comet-verify
5. phase: build or has Design Doc but plan/execution incomplete → Route by workflow: hotfix → /comet-hotfix, tweak → /comet-tweak, full → /comet-build
6. phase: design or has change but no Design Doc → Invoke /comet-design
7. phase: open or active change exists but .comet.yaml is missing → Invoke /comet-open
8. No active change → Invoke /comet-open

If metadata conflicts with file state, use verifiable file state as source of truth and correct .comet.yaml before continuing.

Preset Upgrade Criteria

hotfix → full (upgrade if any condition met):

• Change involves 3+ files
• Architecture changes (new modules, new interfaces, new dependencies)
• Database schema changes
• Fix introduces new public API
• Fix scope exceeds a single function/module

tweak → full (upgrade if any condition met):

• Change involves 5+ files
• Cross-module coordination required
• 5+ new test cases needed
• Config item additions or deletions (not value changes)
• New capability needed
• Delta spec needed (existing spec affected)

Error Handling Quick Reference

Phase Transitions

<IMPORTANT>
A single `/comet` invocation starts from the detected phase and advances to the next phase when exit conditions are met.

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

Continuous execution requirement: starting from the detected phase, the agent automatically continues through all later phases. But auto-advancing only applies at transition points without user decisions. When encountering user decision points, must use the current platform's available user input/confirmation mechanism to pause and wait for the user's explicit response. Must not use recommendation rules, defaults, or historical preferences to substitute for user confirmation, and must not just output a text prompt and then continue executing.

Distinguish phase advancement vs automatic handoff: each sub-skill runs phase guard --apply before exit to advance the .comet.yaml phase field. This step always happens and is not controlled by auto_transition. After that, the sub-skill runs "$COMET_BASH" "$COMET_STATE" next <name> to resolve the next action: when auto_transition is not false, output is NEXT: auto (auto-invoke next skill); when auto_transition is false, output is NEXT: manual (do not invoke next skill, show a manual run hint). Therefore auto_transition only controls next skill invocation, not phase advancement. Regardless of auto_transition, user decision points below remain blocking.

Decision points are blocking points: whenever reaching any of the following nodes, the current /comet invocation must stop, and follow the comet/reference/decision-point.md protocol to obtain the user's explicit choice. Only after the user explicitly chooses can the corresponding state fields be written and operations executed, then auto-advance resumes.

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

1. Open phase proposal/design/tasks review and confirmation
2. Confirm design approach during brainstorming
3. Plan-ready pause choice during build phase, followed by workflow configuration selection (isolation + execution method + TDD mode)
4. Decide to fix or accept deviation when verify fails (including Spec drift handling)
5. Choose branch handling method for finishing-branch
6. Archive phase final confirmation before running the archive script
7. Encounter upgrade conditions (hotfix/tweak → full workflow)
8. Build phase scope expansion requiring redesign or new change split
9. Open phase large PRD requiring confirmation to split into multiple changes

Agents should not skip these decision points; other unambiguous phase transitions must proceed automatically, must not exit midway. At decision points, must not skip user confirmation or choose automatically — must explicitly obtain the user's choice through the current platform's available user input/confirmation mechanism before continuing.

Red Flags — when these thoughts appear, STOP and check: