Comet — OpenSpec + Superpowers Dual-Star AI Workflow
Comet combines OpenSpec’s spec lifecycle management with Superpowers’ TDD-driven development into a five-phase AI-assisted workflow for software projects.
Comet (@rpamis/comet) is an npm CLI tool that installs AI coding Skills and chains two best-in-class skill sets — OpenSpec and Superpowers — into a single, fully automated five-phase development pipeline. Install it once and every AI coding session gains a structured, stateful workflow from idea to archived spec.
OpenSpec handles the WHAT: requirements proposals, spec lifecycle management, delta-spec tracking, and archival.
Superpowers handles the HOW: brainstorming, TDD-driven coding, subagent-driven development, code review, and plan writing.
Comet chains both, wiring their skills together with guard scripts, a YAML state machine, and a smart main entry (/comet) that auto-detects where you are in the workflow and resumes from that exact point — no token-wasting re-reads of documents or manual phase tracking required.
AI coding workflows break down in two common ways:
Problem
Root Cause
Agents re-examine all documents on resume, wasting tokens
No stateful record of which phase completed and what remains
Spec documents fall out of sync with code changes
Document synchronisation depends on manual reminders to the Agent
Phase transitions happen prematurely (“done” without evidence)
No guard conditions enforcing real exit criteria
Skills trigger “look-alike” operations instead of real skill calls
Nested skill invocation is poorly understood
Comet fixes all of these by:
Recording phase, execution mode, verification results, and archive status in .comet.yaml — a dedicated Comet workflow state file decoupled from OpenSpec’s own .openspec.yaml.
Running guard scripts (comet-guard.sh) at every phase boundary to check tasks, YAML fields, verification evidence, and archive conditions before allowing the workflow to advance.
Automating handoff, state updates, validation, and archive sync inside scripted flows so users never have to remind the Agent to “update the design doc” or “sync the spec”.
Comet does not simply trust the Agent saying “done”. Each phase exit is validated by scripts that check real evidence — file existence, field values, SHA256 hashes, and task completion — before advancing state.
Comet organises every piece of work into five sequential phases. The main entry /comet dispatches to the correct phase automatically by reading the active spec’s state from .comet.yaml.
For smaller changes, Comet ships two preset paths that skip phases where full design overhead isn’t warranted:
Preset
Path
Skips
/comet-hotfix
open → build → verify → archive
Brainstorming/deep design
/comet-tweak
open → lightweight build → light verify → archive
Brainstorming and full plan
Brainstorming is non-skippable in the full workflow. Every substantive change must pass through deep design before implementation. This is a deliberate guard, not an oversight.
Close your AI coding session mid-way through Phase 3? Just type /comet when you return. Comet reads the active spec from .comet.yaml, dynamically identifies which phase was executing, and continues — without re-reading every document or guessing progress.If multiple active specs exist, Comet presents a selection list so you choose which one to resume.
Two decoupled state files track the full lifecycle:
File
Owner
Purpose
.openspec.yaml
OpenSpec
Spec lifecycle, change metadata
.comet.yaml
Comet
Workflow phase, execution mode, verification status
This separation means Comet can be upgraded or replaced without affecting OpenSpec’s data, and agents have a clean, well-defined interface to query state via comet-state.sh.
comet init installs skills to 28 AI coding platforms — from Claude Code and Cursor to GitHub Copilot, Gemini CLI, Amazon Q Developer, and many more. The interactive installer auto-detects which platforms you already have configured in your project and pre-selects them.See the full Platforms list.
Beyond the workflow itself, the Comet project is a working reference implementation for advanced AI coding patterns:
How to reliably trigger nested Skills — ensuring the Agent truly invokes a skill (with visible print output) rather than performing a “look-alike” operation based on a description.
How to make combined Skills flow automatically across phases — wiring multiple skill sets into a single coherent pipeline without manual intervention at each handoff.
How to turn the Spec lifecycle into a resumable workflow — linking OpenSpec and Superpowers artifacts with stateful YAML so agents can resume mid-task correctly.
How to turn document synchronisation into automation — scripting handoff, state updates, validation, and archive sync so users never need to remind the Agent.
How to design guard conditions that Agents can execute — replacing “the agent says done” with script-checked evidence.
How to distribute and install Skills across platforms — handling project vs global scopes, language selection, and platform-specific directory differences in a CLI installer.
How to turn shell scripts into Agent workflow infrastructure — writing cross-platform scripts (macOS, Linux, Windows Git Bash) that move fragile workflow control out of Prompt text and into testable, reusable tools.