Skip to main content
Frequently asked questions about the Classic Spec Mode /comet five-phase workflow, state, guards, and presets.

​
Basic Concepts

Comet does not replace either of them. OpenSpec is responsible for WHAT (requirements, proposals, spec lifecycle, archiving), while Superpowers is responsible for HOW (brainstorming, technical design, planning, execution, verification). Comet strings the two together into a single resumable five-phase workflow, and uses a state machine and guards to ensure reliable handoffs. See Workflow Concepts.
/comet is the entry point for Classic Spec Mode. It drives the five-phase open/design/build/verify/archive flow, suitable for project changes. /comet-any is the Skill Creator, used to create, optimize, and compose reusable Skills. They are different entry points and do not conflict with each other.
Classic Spec Mode depends on both — OpenSpec records the requirements spec, and Superpowers provides the design/execution methodology. comet init will install both for you. If you only want to use Comet’s Skill platform capabilities through /comet-any to compose arbitrary Skills into a verifiable, reviewable, and distributable Skill Bundle, you can start from Compose Any Skill Quickstart without going through the five phases.

​
Differences from Similar Products

Both aim to combine OpenSpec (the WHAT) and Superpowers (the HOW) into a single workflow, but their form factor and level of enforcement are completely different.superpowers-bridge is an OpenSpec native schema bundle: you copy it into your project’s openspec/schemas/ and select it per change with --schema superpowers-bridge. It is a pure prompt-layer integration — it does not modify the Superpowers source or the OpenSpec CLI, and relies on the artifact DAG in schema.yaml (brainstorm → proposal → design → specs → tasks → plan → verify → retrospective) plus prose PRECHECKs to enforce ordering. It also adds an evidence-first retrospective artifact that Superpowers does not natively cover.Comet is a standalone npm package (@rpamis/comet) with a cross-platform Node runtime, a .comet.yaml state machine, hard hook interception, diagnostics, and recovery. The core differences:
Dimensionsuperpowers-bridgeComet
Form factorOpenSpec schema bundle copied into openspec/schemas/Standalone npm package + CLI + Node runtime
Integration layerPure prompt layer, no source/CLI changesPrompt layer + engineered runtime (state machine, hook, guard)
OrchestrationArtifact DAG + prose, relies on model/human invoking /opsx:* in orderFive-phase state machine with script-driven auto-transition
State/RecoveryOnly the artifact files themselves, no explicit phase state.comet.yaml state machine + compaction recovery
EnforcementProse PRECHECK (read but not enforced)phase-guard rules injected every round + hard hook interception
Platform requirementRequires a subagent-capable platform, else falls back to spec-drivenCross-platform, no subagent requirement, has fallback paths
Entry pointOnly fires via /opsx:* commands; verbal triggers leakIntent routing routes from any input to a phase
TieringManual judgment of “do I need a change”Built-in hotfix/tweak presets
ScopeA single development workflow schemaWorkflow + Skill platform (compose/eval/visualize)
Relative to pure-schema integrations like superpowers-bridge, Comet’s advantages concentrate on four points:
  1. Resumable state machine: .comet.yaml explicitly records phase, build_mode, tdd_mode, and review_mode, so long-running tasks or context compaction can resume precisely from a checkpoint rather than inferring from “which artifact files already exist.”
  2. Hard enforcement line: Comet has comet-hook-guard.mjs (a PreToolUse hook) doing hard interception, plus phase-guard rules injected every round — e.g., writing source code is blocked in the design phase, and illegal phase jumps are caught. A pure-schema PRECHECK is only prose, which the model may “read but not execute.”
  3. Robust entry + cross-platform: Intent routing routes any user input to the right phase, avoiding the front-door problem where “it only works via /opsx:* and leaks on verbal triggers”; and it does not require a subagent-capable platform.
  4. Not just a workflow, a Skill platform: /comet-any composes arbitrary Skills, comet eval evaluates local Skills, and comet dashboard visualizes each change — a scope beyond a single development workflow.
The trade-off is that Comet is heavier (you install an npm package and maintain a runtime). If you only want to layer Superpowers onto OpenSpec and don’t mind driving it manually, superpowers-bridge is lighter; if you want long-task resumability, strong anti-drift enforcement, multi-platform support, and Skill platform capabilities, Comet is the better fit. To learn which industry practices Comet’s runtime, workflow, evaluation, and Skill authoring correspond to, read on in Comet vs Industry Practices.

​
State and Recovery

Comet does not rely on chat history. Every time you invoke /comet, it re-reads the active change’s .comet.yaml and OpenSpec artifacts, determines whether the current phase and evidence are consistent, and then routes to the correct phase Skill. See “How auto-detection works” in Workflow Concepts.
This change may have been created with the original /opsx:new and is missing .comet.yaml, so it will be silently skipped by comet status. Invoke /comet on the Agent platform to let it take over and backfill the state file. See “Orphan changes” in Existing Project Onboarding.
User-visible fields (workflow, phase, build_mode, etc.) should in principle flow through /comet and the phase guards — do not hand-edit phase. Machine-owned Run fields (in .comet/run-state.json or .comet/runs/<run-id>) must never be hand-edited. For troubleshooting you can use the comet-state command. See State and Configuration.
The design phase writes a brainstorm-summary.md as a recovery checkpoint, and the build phase’s sub-agents have persisted checkpoints. When resuming, invoke /comet and it will recover from file state rather than from memory. See Resuming an Interrupted Workflow.

​
Phases and Guards

A core principle of Comet is that brainstorming cannot be skipped (except for the hotfix/tweak presets). The guard in the full workflow checks whether design_doc exists, and its absence is treated as FATAL. Skipping design means subsequent phases lack a technical basis.
Do not archive directly. Comet will let you choose: go back to build after fixing, accept the deviation (append an explanation to the design doc), or return to re-brainstorming. When verify_result: fail, archiving is blocked by the guard.
Phase advancement is performed by the guard script comet-guard.mjs --apply. When auto_transition: true (the default), the next phase Skill is invoked automatically after a phase completes; when auto_transition: false, it pauses and you run it manually following the HINT. The phase always advances — this setting only affects whether the next Skill is invoked automatically.
It means that after the design phase generated a handoff, the OpenSpec artifacts (proposal/design/tasks/spec) were modified. The fix is to re-run comet-handoff so Superpowers gets the current OpenSpec context. See “How artifacts are handed off” in Workflow Concepts.

​
Lightweight Presets and Large Requirements

Both skip the full brainstorming flow but preserve OpenSpec state, verification, and archiving. hotfix is suited for bug fixes with a clear reproduction path; tweak is suited for small changes with a well-defined scope. When cross-module coordination, new public APIs, or schema changes arise, you should escalate to full. See hotfix Preset.
/comet-open triggers a PRD split pre-check before creating artifacts, breaking a large requirement into multiple changes that can be designed, delivered, and archived independently. See Large PRD Splitting.
review_mode (off/standard/thorough) controls the intensity of automatic code review in the build and verify phases. The full workflow requires you to choose one before leaving build; hotfix defaults to off. You can set a project default in .comet/config.yaml.

​
Common Issues

Auto-committing is a behavior of the Superpowers source. You can have the AI generate a hook or rule that intercepts git commit to prevent this from happening.
First, have the Agent stop — do not keep writing code. Then handle it based on what you actually did:
  • You modified the spec, design, or tasks: Just invoke /comet again. Comet will re-read .comet.yaml and the OpenSpec artifacts and resume at the correct phase based on the current phase. When the build phase detects that the spec has changed, it follows the incremental update rules: small changes directly update the delta spec and tasks; medium-sized design changes trigger re-brainstorming; when it becomes a new requirement, it asks you to split it into a new change.
  • You modified the code yourself: Also just invoke /comet again and tell the Agent: “I changed the code, please resume from the current workspace.” As long as there are uncommitted changes, Comet follows the dirty-worktree protocol: it first looks at git status and the diff, attributes the changes to the current change, another change, or an uncertain source, and then decides whether to continue, merge in, split, or ask you to confirm.
If both the spec and the code changed, still let /comet recover first. What you need to do is explain whether these changes represent a new approach; do not hand-edit phase in .comet.yaml or .comet/run-state.json. Comet’s principle is to rely on the current file state and persisted artifacts rather than continuing from chat memory. See Modifying Specs Mid-Workflow or Rolling Back and State and Configuration.
The Comet Full workflow is designed for complex requirements/features. It goes through multiple rounds of clarification, optional TDD execution, and Review, so the process is stricter and therefore consumes tokens faster. For lightweight, fast delivery, use the comet-tweak and comet-hotfix presets. For small requirements/features, you can also use Plan or /loop as an alternative.
Last modified on July 3, 2026