Skip to main content
You only need to call /comet. It reads the project configuration in .comet/config.yaml; when default_workflow is classic, it forwards the call to the permanent internal entry /comet-classic, which splits one change into five stages: open, design, build, verify, and archive. Classic and the Native workflow are two independent workflows, and each keeps its own changes, state, and artifacts. Classic chains OpenSpec and Superpowers into one recoverable flow. OpenSpec owns the WHAT — requirements, proposals, the spec lifecycle, and archiving — while Superpowers owns the HOW — brainstorming, technical design, planning, execution, and verification — and Comet saves the phase and handoff state. Stage Skills do not depend on conversation history: every invocation re-reads the active change, .comet.yaml, and the actual file state to decide the current stage, so you do not need to figure out for yourself whether you are in open, design, build, verify, or archive. Classic primarily targets models in the capability tier below Fable 5 and GPT-5.6. For these models, explicit spec, design, planning, TDD, debugging, and review stages reduce omissions and process drift. Comet’s existing real-world baseline evaluations confirm that this structure keeps task coverage and completion quality on lower-capability models. Fable 5, GPT-5.6, and similarly stronger models are often better served by the Native workflow, which executes more lightly. The rest of this page uses <classic-root> for the current Classic OpenSpec root directory: docs/openspec/ by default for new projects, and openspec/ for projects that keep the legacy layout. The actual location is decided by classic.artifact_layout; see Project file structure.

​
Who should use Classic

The full five stages fit changes that introduce new capabilities, change a public API or schema, or span multiple modules. For small, well-scoped changes, prefer the lightweight presets: fix bugs with /comet-hotfix, and handle light-to-medium changes to configuration, documentation, or prompts with /comet-tweak; both skip design. When a preset hits an escalation signal mid-run, Comet stops and lets you choose between staying on the preset and escalating to full — see “Lightweight presets and escalation” below. If you want a documented record of requirements, design, and verification, Classic’s five stages and archived artifacts leave a reviewable trail. If your model is already at the Fable 5 / GPT-5.6 tier and you want it to decide its own implementation and testing approach, the Native workflow is the lighter choice.

​
What a change looks like end to end

The walkthrough below follows one complete full change from entry to archive. Every place where you must stop and decide is numbered: routing is 1, open is 2/3/4, design is 5, build is 6/7, verify is 8, archive is 9, and the hotfix/tweak escalation review is 10. For the complete list, see Five-stage pause points and user selection points. /comet-classic chains the stages automatically; with auto_transition: false, advance stage by stage manually instead (see Auto-transition).

​
Entry: say what you want, and routing picks the flow

Type /comet followed by what you want to do. Based on your words, the list of active changes, and the risk signals, /comet-classic routes the call to one of six outcomes: full (the complete five stages), hotfix, tweak, resume (continue an existing change), ask_user, or out_of_scope (you are only asking a question). A few common directions:
  • New capability, public API, schema, or cross-module work normally routes to full, which opens /comet-open;
  • Fixing an existing bug with no new capability or interface change routes to hotfix, which opens /comet-hotfix;
  • A contained light-to-medium change routes to tweak, which opens /comet-tweak;
  • Explicitly continuing some active change routes to resume, and the next step depends on which stage that change is currently paused at.
full, hotfix, tweak, and resume start right away; ask_user pauses at the entry only when the evidence is thin, several active changes exist, or the flow you stated conflicts with the risk signals. How routing decides, which risk signals affect the result, and typical scenarios are covered in Intent Recognition and Routing.

​
open: turn an idea into an OpenSpec change

When the route is full and there is no active change to resume, /comet-classic calls /comet-open. Comet loads openspec-explore to clarify the requirements iteratively, then generates proposal → design → tasks one by one, following the project’s template, instruction, and dependencies. Along the way you meet the pause points in order:
  • When the input is a large PRD or holds several independent capabilities, pause point 2 lets you split it into multiple changes, keep one change, or adjust the split;
  • Pause point 3 picks the workspace isolation — current (current branch), branch (a new branch), or worktree (an isolated workspace; choose it directly when you clearly want parallelism);
  • Pause point 4 reviews the output: confirm the change name and scope, and that proposal/design/tasks match expectations.
The artifacts land in <classic-root>/changes/<name>/, including .comet.yaml, proposal.md, design.md, and tasks.md, plus the delta spec (specs/<capability>/spec.md) when the change touches a capability. The full flow forbids one-shot proposal generation and forbids skipping brainstorming. When scope and naming are clear, requirement clarification and naming do not block by default — pause points appear only where you actually need to choose. The step-by-step open operations and artifact layout are in open stage.
Create changes only with /comet-open. Calling /opsx:new directly only generates OpenSpec artifacts; it does not create .comet.yaml, and the change ends up outside the Comet state machine.

​
design: confirm the technical approach (full only)

After open completes, the full flow automatically chains to /comet-design. Comet first turns the open-phase artifacts into a handoff package with a script — the agent may not hand-write a summary in its place — then loads brainstorming to discuss the implementation approach, risks, and test strategy with you against the real context. Pause point 5 asks you to confirm the technical approach; the Design Doc (docs/superpowers/specs/...-design.md) is generated after confirmation, and only then does the guard advance to build. The design stage does not allow the agent to write a second requirements spec. When the delta spec lacks acceptance scenarios, the only legal move is a Spec Patch written back to OpenSpec; when a change exceeds the Spec Patch boundary (interface change, new component, data-flow change, and so on), return to brainstorming to realign or open a new change. Design details are in design stage.

​
build: write a plan and implement task by task

/comet-build first dispatches a sub-agent that loads writing-plans to produce the implementation plan, then pause point 6 (the build joint decision) lets you decide in one go: continue executing immediately or pause and resume with a stronger model, and select the execution mode, TDD mode, and review mode. After that, tasks are implemented in the mode you chose:
  • subagent-driven-development: the main session only coordinates while background sub-agents implement tasks one by one; task-level reviews and fixes run per review_mode, and when a task passes, the main session checks it off in tasks.md and commits;
  • executing-plans: a lighter path where the main session executes directly;
  • On a crash, test failure, or build failure, execution is forced through systematic-debugging to find the root cause before fixing.
If execution turns up new tasks exceeding half of the initial tasks.md (pause point 7), Comet stops and asks whether to split them into a new change or keep them in the current one. For a comparison of the three execution modes, review modes, and the debugging protocol, see build stage.

​
verify: validate the implementation against the spec

/comet-verify runs a light or full check depending on task size and saves the conclusion as a verification report. Failures that can be fixed objectively go back to build automatically, and the first three times do not interrupt you. What needs you converges on pause point 8: the fourth failure, accepting a WARNING/SUGGESTION deviation with trade-offs, or a full check finding drift between the delta spec and the Design Doc. On drift, choose one of three: append an Implementation Divergence entry to the Design Doc to record the deviation, run verify-fail to go back to build and realign, or accept the deviation and keep verifying. Once verification passes, the guard advances to archive while branch_status stays pending; whether to push or open a PR is confirmed right before archiving. Verification depth and failure handling are in verify stage.

​
archive: confirm the delivery and archive

On entering archive, pause point 9 is the final confirmation, with five options: archive locally only, archive and push, archive and push with a PR, go back and adjust (return to verify for another round), or do not archive yet. Choosing “do not archive yet” keeps the change active in the archive stage and writes no archive state. If you are unsure, preview first with comet archive --dry-run, which only reports the outcome and merges nothing. After you confirm, comet archive delegates to the OpenSpec CLI to merge the delta spec into the main spec, moves the change directory to <classic-root>/changes/archive/YYYY-MM-DD-<name>/, stamps the Design Doc and plan as archived, then creates a single archive commit and pushes or opens a PR the way you chose. Once archived, the change is no longer active and comet status stops listing it. Archive steps are in archive stage; command details are in comet archive.

​
Five stages at a glance

Write release: by default, writes inside the project but outside the artifact area are subject to the Classic stage guard. To keep an implementation directory writable in any stage, configure the shared hook.allow_paths in .comet/config.yaml. See Classic configuration — Hook write release.
Classic’s handoff, spec handling, routing, archiving, and recovery each have a dedicated page. For everyday use, the two sections above are enough; when you need to chase down a mechanism, jump from here to the authoritative page:
  • Handoff and context compression: how the handoff package and handoff_hash are computed and what each stage does with them is in comet handoff; the two handoff formats, off and beta, and when to enable compression are in Context compression mechanism. What the intermediate artifacts — the handoff package, brainstorm-summary, subagent-progress, the verification report, and so on — are each for is in Workflow intermediate products.
  • Spec scope and drift: the delta spec’s ADDED/MODIFIED/REMOVED/RENAMED are native OpenSpec concepts; Comet uses them and does not deduplicate. How build handles a delta spec by size — small edits applied directly, medium ones realigned, large ones opened as a new change — is in build stage and Change Spec or roll back mid-workflow. The three-way choice when verify finds spec drift belongs to pause point 8, in Five-stage pause points and user selection points and verify stage.
  • Archive flow: the step-by-step delta merge, directory move, and artifact annotation are in archive stage; the comet archive command and its --dry-run preview are in comet archive.
  • Routing and stage detection: how the six routing outcomes are decided and how risk signals affect the result is in Intent Recognition and Routing; stage advancement, automatic chaining, and auto_transition are in Auto-transition.
  • Where you participate: the complete list of pause points 1–10, their options, and rules is in Five-stage pause points and user selection points.
  • Stage Skills: the five stages are driven by /comet-open, /comet-design, /comet-build, /comet-verify, and /comet-archive, all routed from /comet-classic; the lightweight presets run /comet-hotfix and /comet-tweak. For normal use, call only /comet; when you may call these entries manually and how to recover from them is in the phases pages and Resuming interrupted work.

​
Lightweight presets and escalation

hotfix and tweak both run open → build → verify → archive (skipping design) and keep the OpenSpec state, verification, and archiving. Their shared precondition is that the change fits into a single OpenSpec change and does not need in-depth Superpowers design. /comet-hotfix suits quick bug fixes that need no Design Doc; /comet-tweak suits configuration adjustments, documentation or prompt refinements, and delta-spec-driven medium changes — in tweak the delta spec is a first-class artifact, so needing a delta spec alone is not a reason to escalate. Each preset’s preconditions, flow, and limits are in the hotfix preset and the tweak preset. The preset walkthrough is the same flow minus design: once the open guard completes, the change goes straight into build, and verify’s failure handling and the pre-archive confirmation stay in place. The two differ only in how each builds — hotfix fixes tasks one by one manually (build_mode defaults to direct), while tweak executes through OpenSpec’s native apply path. When a change no longer fits into a single change, or execution hits an escalation signal such as cross-module coordination, a new public API, a schema change, or a deep architectural issue, Comet pauses (pause point 10) and asks whether to stay on the preset or escalate to full; escalation goes through the preset-escalate channel only. The operations for escalation and mid-run rollback are in Change Spec or roll back mid-workflow.

​
Next steps

Last modified on September 4, 2026