Comet is a five-phase development workflow that chains two complementary AI skill sets — OpenSpec and Superpowers — into a single automated pipeline. Each phase has a clear owner, well-defined entry conditions, scripted exit guards, and a fixed set of artifacts. You start a change with /comet, walk through design, implementation, and verification, then close it with archive. If your session ends mid-way, running /comet again picks up exactly where you left off.
The Two-Star Model
Comet is built on what the project calls a dual-star model: two skill sets that orbit the same goal.
| Star | Handles | Responsibilities |
|---|
| OpenSpec | WHAT | Requirements, proposals, spec lifecycle, delta-to-main sync, archiving |
| Superpowers | HOW | Technical design, brainstorming, planning, TDD-driven execution, code review |
Five Phases
Each phase maps to a slash command, an owner, and a concrete set of output artifacts.
| # | Phase | Command | Owner | Artifacts |
|---|
| 1 | Open | /comet-open | OpenSpec | proposal.md, design.md, tasks.md |
| 2 | Deep Design | /comet-design | Superpowers | Design Doc, delta spec |
| 3 | Plan & Build | /comet-build | Superpowers | Implementation plan, code commits |
| 4 | Verify & Finish | /comet-verify | Both | Verification report, branch handling |
| 5 | Archive | /comet-archive | OpenSpec | delta→main spec sync, archive |
.comet.yaml here to begin tracking state.
Phase 2 — Deep Design runs Superpowers brainstorming to produce a Design Doc (a technical RFC) and writes or updates the delta capability spec. This is the phase where architectural decisions are locked in before any code is written.
Phase 3 — Plan & Build generates a detailed implementation plan tied to the change and Design Doc, then executes task by task — one commit per task, commit messages reflecting design intent.
Phase 4 — Verify & Finish runs project tests and writes a verification report. It also handles branch operations (merge, close, or carry forward), updating branch_status to handled before the phase can close.
Phase 5 — Archive syncs the delta spec into the main spec tree, annotates the Design Doc and plan with archived-with status, and moves the change directory to openspec/changes/archive/. This is the only phase that cannot be retried after completion.
Workflow Diagram
/comet
↓ auto-detect phase from .comet.yaml + openspec list --json
/comet-open ──→ /comet-design ──→ /comet-build ──→ /comet-verify ──→ /comet-archive
(OpenSpec) (Superpowers) (Superpowers) (Both) (OpenSpec)
Preset: /comet-hotfix (skips brainstorming)
open ──→ build ──→ verify ──→ archive
↑ upgrade triggered → pause for confirmation → supplement Design Doc → return to full workflow
Preset: /comet-tweak (skips brainstorming + full plan)
open ──→ lightweight build ──→ light verify ──→ archive
↑ upgrade triggered → pause for confirmation → supplement Design Doc → return to full workflow
Preset Paths
Two preset commands streamline common low-complexity changes by skipping phases that would add more overhead than value.
/comet-hotfix — Quick Bug Fix
Skips the brainstorming-driven deep design phase. Suitable when the root cause is already understood and the fix is self-contained (a single function or module). The full Phase 1 (Open) still runs to create proper change artifacts.
Upgrade to full workflow if any of these conditions are met:
- Change touches 3 or more files
- Architecture changes involved (new modules, interfaces, or dependencies)
- Database schema changes required
- Fix introduces a new public API surface
- Scope exceeds a single function or module
/comet-tweak — Small Adjustment
Skips brainstorming and the full implementation plan. Suitable for copy changes, configuration value edits, documentation updates, or prompt text adjustments.
Upgrade to full workflow if any of these conditions are met:
- Change touches 5 or more files
- Cross-module coordination required
- 5 or more new test cases needed
- Config items are added or removed (not just value changes)
When an upgrade condition is met, Comet pauses, asks the user to confirm the switch, supplements the Design Doc, and then re-enters the full workflow at the appropriate phase.
Automatic Phase Detection
Running /comet with no arguments triggers automatic detection. The agent reads .comet.yaml and runs openspec list --json to determine the exact state of all active changes, then dispatches to the correct phase without requiring you to remember where you left off.
Step 0 — Preset and active-change discovery:
Preset detection runs first. If the user’s input matches hotfix or tweak criteria, the corresponding preset is invoked directly and the table below is skipped.
| Active changes | User input | Behavior |
|---|
| None | non-preset input | → Invoke /comet-open to create a new change |
| Exactly 1 | /comet <description> | → Ask: continue this change or create a new one |
| Multiple | /comet <description> | → Ask: continue existing or create new; list for selection if continuing |
| Exactly 1 | /comet (no description) | → Auto-select, enter Step 1 |
| Multiple | /comet (no description) | → List active changes for user selection |
.comet.yaml for phase, workflow, build_pause, build_mode, isolation, and verify_result.
Step 2 — Phase determination (first match wins):
archived: true or change moved to archive directory → Workflow completeverify_result: pass and not yet archived → Invoke /comet-archiveverify_result: fail → Enter verification failure decision point (blocking pause)phase: verify or all tasks checked → Invoke /comet-verifyphase: build or Design Doc exists but build/plan incomplete → Route by workflow (full → /comet-build, hotfix → /comet-hotfix, tweak → /comet-tweak)phase: design or change exists but no Design Doc → Invoke /comet-designphase: open or active change exists but .comet.yaml is missing → Invoke /comet-open- No active change → Invoke
/comet-open
On every context resume, phase detection reruns from Step 0. Comet never trusts conversation history for phase state — only .comet.yaml and verifiable file state.
Decision Points
Certain nodes in the workflow require explicit user input before the agent can continue. These are blocking pauses — the agent must use an interactive tool (such as AskUserQuestion in Claude Code) to wait for your response. Text output alone does not count as a user decision.
| Phase | Blocking decision |
|---|
| Open | Review and confirm the proposal, design, and task breakdown |
| Design | Confirm the technical approach during brainstorming |
| Build | After the plan is generated, choose whether to pause (e.g., to switch models) or continue; if continuing, select workspace isolation method (branch or worktree) and execution mode |
| Build | Confirm scope expansion that requires redesign or splitting into a new change |
| Verify | Decide to fix or accept deviation when verification fails |
| Verify | Choose branch handling method (merge, close, or carry forward) |
| Any | Confirm upgrade from hotfix/tweak to full workflow when upgrade conditions are triggered |
Core Principles
Core principles that apply across all phases:
- Brainstorming is non-skippable — every change must go through deep design (Phases 1–2) before writing code, except for the
hotfix and tweak presets where complexity criteria are met.
- Delta specs are living documents — the delta capability spec can be freely edited during Phase 3 (Plan & Build) and is only synced to the main spec tree at archive time.
- Keep tasks.md in sync — check off each task in
tasks.md as it is completed; one commit per task.
- Commit frequently — one commit per task in
tasks.md; commit messages must reflect design intent from the Design Doc.
- Verify before archive —
/comet-verify must produce a passing verification report before /comet-archive is allowed to run. Guard scripts enforce this as a hard constraint.