Basic concepts
What is the relationship between Comet, OpenSpec and Superpowers
What is the relationship between Comet, OpenSpec and Superpowers
Comet does not replace either party. OpenSpec is responsible for WHAT (requirements, proposals, spec lifecycle, and archiving), while Superpowers is responsible for HOW (brainstorming, technical design, planning, execution, and verification). Comet links the two into a recoverable five-stage workflow and ensures reliable handover with state machines and guards. For details, please refer to Workflow Concept
What's the difference between /comet and/Comet-any
What's the difference between /comet and/Comet-any
Users uniformly call
/comet; After selecting Classic for the project configuration, the internal permanent entry /comet-classic driver is selected
The open/design/build/verify/archive five-phase process. /comet is the project-configured unified entry point and may enter Native or
Classic. /comet-any is Skill Creator, used to create, optimize, and compose reusable Skills. Each has a different responsibility.Must I use OpenSpec and Superpowers
Must I use OpenSpec and Superpowers
Classic Spec mode relies on both: OpenSpec records requirement specifications, while Superpowers provides the design and execution methodology.
comet init --workflow classic installs both. New project-level comet init runs use Native by default, which does not depend on them.
If you only want Comet’s Skill platform capabilities—using /comet-any to compose Skills into verifiable, reviewable, and distributable Skill Bundles—start with Compose any Skill.The differences from similar products
What are the differences between Comet and superpowers bridge
What are the differences between Comet and superpowers bridge
Both aim to integrate OpenSpec and Superpowers into a single workflow, but their implementation forms and guarantee levels are completely different.superpowers-bridge is an OpenSpec native schema bundle Copy it to the current OpenSpec root directory of the project’s
schemas/ (the default for Classic new projects is docs/openspec/schemas/, and for projects that retain the old layout, it is openspec/schemas/), and select it by pressing change with --schema superpowers-bridge. It is a ** pure prompt layer integration ** - without modifying the source code of Superpowers or the OpenSpec CLI, the order is constrained by the artifact DAG (brainstorm → proposal → design → specs → tasks → plan → verify → retrospective) and prose PRECHECK in schema.yaml. It also fills in a retrospective artifact that was natively missing from Superpowers and prioritized evidence.Comet is an independent npm package (@rpamis/comet), featuring cross-platform Node runtime, .comet.yaml state machine, hook hard interception, diagnosis and recovery. The core difference between the two:Since both are OpenSpec and Superpowers, what are the advantages of Comet
Since both are OpenSpec and Superpowers, what are the advantages of Comet
Compared with pure schema integrations like superpowers-bridge, Comet’s advantages are concentrated in four points:
- ** Recoverable State Machine ** :
.comet.yamlexplicitly recordsphase,build_mode,tdd_mode, andreview_mode. After compressing long tasks or contexts, breakpoints can be precisely restored directly from these states. - ** Hard execution Defense line ** : Comet has
comet-hook-guard.mjs(PreToolUse hook) for hard interception, along with phase-guard rules for each round of injection - for instance, source code writing is prohibited during the design phase, and illegal jump phases will be blocked. Pure schemaPRECHECKis just prose, and the model can “read but not execute”. - Stable entry across platforms: intent routing can map natural-language requests directly to the right phase, without relying on a fixed
/opsx:*trigger path, and without requiring a subagent-only platform. - Other product entry points:
/comet-anycreates and combines Skills,comet evalevaluates a local Skill, andcomet dashboarddisplays changes.
Status and Recovery
How does the Agent know where it has reached when it comes back after an interruption
How does the Agent know where it has reached when it comes back after an interruption
Comet does not rely on chat history. Each time
/comet is called and the configuration enters Classic, the internal /comet-classic will re-read the .comet.yaml and OpenSpec artifacts of the active change, determine whether the current stage and evidence are consistent, and then route to the correct stage Skill.comet status can't see my change
comet status can't see my change
This change might have been created with the original
/opsx:new. If .comet.yaml is missing, it will be silently skipped by comet status. in
The Agent platform calls /comet and enters Classic through configuration
Let it take over and fill in the status file. For details, please refer to the “Orphan change” of existing projects connected to ](/en/guides/existing-project).Can.comet.yaml be edited manually
Can.comet.yaml be edited manually
User-visible fields (workflow, phase, build_mode, etc.) should, in principle, flow through
/comet-classic and phase guards. Do not manually modify phase. Run-state fields maintained automatically by Comet (machine-owned, in .comet/run-state.json or .comet/runs/<run-id>) must never be modified manually. When troubleshooting, you can use the comet-state command. For more details, please refer to Status Management What should I do if the context is lost after context compression
What should I do if the context is lost after context compression
In the design stage,
brainstorm-summary.md was written as the recovery checkpoint. In the build stage, the sub-agent has a persistent checkpoint. When restoring, call /comet; After the configuration enters Classic, the internal route will directly read the file status and locate the breakpoint. For details, please refer to Restoring Interrupted Work Stages and Guards
Why can't we skip design and build directly
Why can't we skip design and build directly
The core principle of Comet is that brainstorming cannot be skipped (except for hotfix/tweak presets). The guard of the complete workflow will check whether
design_doc exists. If it is missing, it will be FATAL. Skipping the design will lead to a lack of technical basis in the subsequent stages.What should I do if the verification fails
What should I do if the verification fails
Don’t file directly. The first 3 fixable failures automatically return to Build for repair without asking you. Only on the 4th failure, or when accepting a WARNING/SUGGESTION deviation requires a trade-off, does Comet pause for your choice: keep repairing, accept the deviation (record the reason and impact), or go back and restart
“brainstorming. When
verify_result: fail is used, archiving will be blocked by guard.How does the stage progress? Do I need to operate it manually
How does the stage progress? Do I need to operate it manually
The guard script
comet-guard.mjs --apply advances phases. With auto_transition: true (the default), completing one phase automatically invokes the next phase Skill. With auto_transition: false, the workflow pauses and you run the HINT manually. Phase advancement still occurs; this setting only controls whether the next Skill is invoked automatically.What does a handoff hash mismatch mean?
What does a handoff hash mismatch mean?
After the design stage to generate handoff, OpenSpec artifacts (proposal/design/tasks/spec) is modified. The solution is to re-run
comet-handoff to enable Superpowers to obtain the current OpenSpec context. For details, please refer to “How to Hand Over Products” in the Workflow concept ](/en/concepts/workflow).Lightweight presets and high demand
What's the difference between hotfix and tweak
What's the difference between hotfix and tweak
Both skip the full brainstorming process and retain the OpenSpec status, verification, and archiving. hotfix is suitable for reproducing bug fixes with clear paths. tweak is suitable for minor changes with a clear scope. When cross-module coordination, new public apis, or schema changes occur, full should be upgraded. For details, please refer to hotfix preset
How should large demands be handled
How should large demands be handled
/comet-open will trigger a PRD split pre-check before creating artifacts, breaking down large requirements into multiple independently designed, delivered, and archived ones
“change. For details, please refer to Large PRD Split What is the use of review_mode
What is the use of review_mode
review_mode (off/standard/thorough) controls the intensity of automatic code review in the build and verify phases. The full workflow must be selected before leaving the build; hotfix is off by default. The default values of the project can be set in classic.review_mode of .comet/config.yaml.Q&A
What should I do if the code keeps submitting automatically
What should I do if the code keeps submitting automatically
Auto-commit is Superpowers’ own behavior. You can have the AI generate a hook or rule that blocks
git commit to stop it.I'm halfway through writing the code and I'm not satisfied with the solution. What should I do
I'm halfway through writing the code and I'm not satisfied with the solution. What should I do
First, stop the Agent and don’t continue writing the code. Then handle it according to what you have actually done:
- ** You have changed the spec, design or tasks** : Directly call
/cometagain. After entering the Classic configuration, Comet will re-read.comet.yamland OpenSpec artifacts and restore to the correct phase according to the current phase. - ** You have modified the code yourself ** : Call
/cometagain and tell the Agent: “I have modified the code. Please restore it to the current workspace.” Comet will inspect the uncommitted changes in the workspace and determine which phase they belong to.
/comet. You need to explain whether these changes represent the new plan; Do not manually modify the phase or .comet/run-state.json of .comet.yaml. Comet will recover from the current file state and persistent artifacts.After using Comet, the Token consumption increases and the time becomes longer
After using Comet, the Token consumption increases and the time becomes longer
The Comet Full workflow targets complex requirements and features: it goes through multiple rounds of clarification plus optional TDD execution and review, so the process is strict and token consumption is higher. When you need lightweight and fast delivery, use the comet-tweak and comet-hotfix presets. Small requirements can also be handled directly with Plan or /loop.