Classic Spec Mode FAQ

Frequently asked questions about the five-phase Classic Spec Mode selected by /comet, including state, guards, and presets.

Basic Concepts

What is the relationship between Comet, OpenSpec, and Superpowers

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.

What is the difference between /comet and /comet-any

Users invoke /comet; when project configuration selects Classic, the permanent internal /comet-classic entry drives the five-phase open/design/build/verify/archive flow. /comet is the shared alias controlled by project configuration, so it may enter Native or Classic. /comet-any is the Skill Creator for creating, optimizing, and composing reusable Skills. The three entry points have distinct responsibilities.

Do I have to use OpenSpec and Superpowers

Classic Spec Mode depends on both—OpenSpec records requirements specifications, and Superpowers provides the design and execution methodology. comet init --workflow classic installs both. A new project-scope comet init defaults to Native, which does not depend on them. If you only want Comet’s Skill-platform capabilities through /comet-any, start with Compose Any Skill Quickstart.

Differences from Similar Products

What is the difference between Comet and superpowers-bridge

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 schemas/ under the current OpenSpec root (docs/openspec/schemas/ for new Classic projects or openspec/schemas/ for retained legacy layouts) 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:

Dimension	superpowers-bridge	Comet
Form factor	OpenSpec schema bundle copied into `schemas/` under the current OpenSpec root	Standalone npm package + CLI + Node runtime
Integration layer	Pure prompt layer, no source/CLI changes	Prompt layer + engineered runtime (state machine, hook, guard)
Orchestration	Artifact DAG + prose, relies on model/human invoking `/opsx:*` in order	Five-phase state machine with script-driven auto-transition
State/Recovery	Only the artifact files themselves, no explicit phase state	`.comet.yaml` state machine + compaction recovery
Enforcement	Prose `PRECHECK` (read but not enforced)	phase-guard rules injected every round + hard hook interception
Platform requirement	Requires a subagent-capable platform, else falls back to spec-driven	Cross-platform, no subagent requirement, has fallback paths
Entry point	Only fires via `/opsx:*` commands; verbal triggers leak	Intent routing routes from any input to a phase
Tiering	Manual judgment of “do I need a change”	Built-in hotfix/tweak presets
Scope	A single development workflow schema	Workflow + Skill platform (compose/eval/visualize)

Since both are OpenSpec + Superpowers, where is Comet's advantage

Relative to pure-schema integrations like superpowers-bridge, Comet’s advantages concentrate on four points:

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

When I come back after an interruption, how does the Agent know where it left off

Comet does not rely on chat history. Each time you invoke /comet and configuration selects Classic, the internal /comet-classic entry rereads .comet.yaml and OpenSpec artifacts, checks phase and evidence consistency, and routes to the correct phase Skill.

comet status doesn't show my change

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 and let configuration route to Classic so it can take over and backfill the state file. See “Orphan changes” in Existing Project Onboarding.

Can I edit .comet.yaml by hand

User-visible fields (workflow, phase, build_mode, etc.) should in principle flow through /comet-classic 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 management.

What if I lose context after context compaction

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; after configuration selects Classic, the internal router recovers from file state rather than memory. See Resuming an Interrupted Workflow.

Phases and Guards

Why can't I skip design and go straight to build

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.

What should I do if verify fails

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.

How do phases advance — do I need to do anything manually

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.

What does a handoff hash mismatch error mean

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

What is the difference between hotfix and tweak

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.

How should I handle large requirements

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

What is review_mode for

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 the project default at classic.review_mode in .comet/config.yaml.

Common Issues

What if code keeps getting auto-committed

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.

What if I'm halfway through writing code and I'm not happy with the approach

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: Invoke /comet again. After configuration selects Classic, Comet rereads .comet.yaml and OpenSpec artifacts and resumes at the correct phase.
You modified the code yourself: Invoke /comet again and tell the Agent that code changed. Comet inspects and attributes uncommitted work through the dirty-worktree protocol.

If both the spec and code changed, recover through /comet first. Explain whether the changes represent a new approach; do not hand-edit phase in .comet.yaml or .comet/run-state.json. Comet relies on current file state and persisted artifacts rather than chat memory.

Token consumption increased and time got longer after using Comet

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.

Install and update