> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Classic Spec Mode FAQ

> Answers to common questions about the /comet five-phase workflow, state recovery, phase guards, and lightweight presets.

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

## Basic Concepts

<AccordionGroup>
  <Accordion title="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](/en/concepts/workflow).
  </Accordion>

  <Accordion title="What is the difference between /comet and /comet-any">
    `/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.
  </Accordion>

  <Accordion title="Do I have to use OpenSpec and Superpowers">
    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](/en/skill-creator/getting-started) without going through the five phases.
  </Accordion>
</AccordionGroup>

## Differences from Similar Products

<AccordionGroup>
  <Accordion title="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](https://github.com/JiangWay/openspec-schemas): 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 `PRECHECK`s 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 `openspec/schemas/`                  | 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](/en/concepts/auto-transition)                                  |
    | State/Recovery       | Only the artifact files themselves, no explicit phase state             | [`.comet.yaml` state machine](/en/concepts/state-management) + [compaction recovery](/en/concepts/context-compression)       |
    | Enforcement          | Prose `PRECHECK` (read but not enforced)                                | [phase-guard rules injected every round + hard hook interception](/en/concepts/decision-points)                              |
    | 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](/en/concepts/intent-routing) routes from any input to a phase                                               |
    | Tiering              | Manual judgment of "do I need a change"                                 | Built-in [hotfix](/en/presets/hotfix)/[tweak](/en/presets/tweak) presets                                                     |
    | Scope                | A single development workflow schema                                    | Workflow + Skill platform ([compose](/en/skill-creator/getting-started)/[eval](/en/cli/eval)/[visualize](/en/cli/dashboard)) |
  </Accordion>

  <Accordion title="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:

    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](/en/tech-blog/comet-vs-industry).
  </Accordion>
</AccordionGroup>

## State and Recovery

<AccordionGroup>
  <Accordion title="When I come back after an interruption, how does the Agent know where it left off">
    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](/en/concepts/workflow).
  </Accordion>

  <Accordion title="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 to let it take over and backfill the state file. See "Orphan changes" in [Existing Project Onboarding](/en/guides/existing-project).
  </Accordion>

  <Accordion title="Can I edit .comet.yaml by hand">
    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](/en/concepts/state-management).
  </Accordion>

  <Accordion title="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` and it will recover from file state rather than from memory. See [Resuming an Interrupted Workflow](/en/guides/resuming-workflow).
  </Accordion>
</AccordionGroup>

## Phases and Guards

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/en/concepts/workflow).
  </Accordion>
</AccordionGroup>

## Lightweight Presets and Large Requirements

<AccordionGroup>
  <Accordion title="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](/en/presets/hotfix).
  </Accordion>

  <Accordion title="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](/en/guides/prd-splitting).
  </Accordion>

  <Accordion title="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 a project default in `.comet/config.yaml`.
  </Accordion>
</AccordionGroup>

## Common Issues

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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**: 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](/en/guides/mid-workflow-changes) and [State and Configuration](/en/concepts/state-management).
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>