Skip to main content
Comet installs in seconds and gets your AI coding tool running a structured five-phase workflow with a single command. This guide walks you from zero to your first /comet invocation.

​
Prerequisites

Make sure the following are available on your machine before installing Comet.
  • Node.js 20+ — Comet requires Node 20 or later (node --version to check)
  • npm / npx — bundled with Node.js; used to install and run the CLI
  • Git — required for branch/worktree isolation during the build phase
  • Bash-compatible shell — macOS and Linux are supported natively; Windows users should use Git Bash or an equivalent bash environment for the workflow scripts
  • An AI coding tool — Claude Code, Cursor, Windsurf, GitHub Copilot, Gemini CLI, or any of the 28 supported platforms

​
Step 1: Install Comet Globally

Install the Comet CLI from npm so the comet command is available anywhere on your system. 
npm install -g @rpamis/comet
Verify the installation: 
comet --version

​
Step 2: Navigate to Your Project Directory

Comet installs skills relative to your project root (or to your home directory for a global install). Change into the project you want to use Comet with: 
cd your-project
If you haven’t started a project yet, create a new directory and initialise a Git repository first: mkdir my-app && cd my-app && git init.

​
Step 3: Run comet init

The interactive initialiser installs OpenSpec skills, Superpowers skills, and Comet skills to your chosen AI coding platforms. 
comet init
comet init guides you through the following prompts in order:
PromptWhat to choose
Install scopeproject installs skills into the current directory (committed with your repo). global installs to your home directory for all projects.
LanguageChoose English or 中文 for the Comet skill text. OpenSpec and Superpowers skills use their own language settings.
Platform selectionPick the AI coding tools you use. Comet auto-detects existing platform config directories (e.g. .claude/, .cursor/) and pre-selects them.
Conflict handlingIf skills already exist, choose to overwrite all, skip all, or decide per component.

​
Example comet init Output

$ comet init

   ██████╗ ██████╗ ███╗   ███╗███████╗████████╗
  ██╔════╝██╔═══██╗████╗ ████║██╔════╝╚══██╔══╝
  ██║     ██║   ██║██╔████╔██║█████╗     ██║
  ██║     ██║   ██║██║╚██╔╝██║██╔══╝     ██║
  ╚██████╗╚██████╔╝██║ ╚═╝ ██║███████╗   ██║
   ╚═════╝ ╚═════╝ ╚═╝     ╚═╝╚══════╝   ╚═╝
             OpenSpec + Superpowers Workflow

? Install scope:
  ● Project (current directory)
  ○ Global (home directory)

? Language for Comet skills:
  ● English
  ○ 中文

? Select platforms to set up:
  ◉ Claude Code  (detected)
  ◯ Cursor
  ◯ Windsurf
  ◯ GitHub Copilot

  Installing OpenSpec for: claude
  OpenSpec: installed
  Installing Superpowers for: claude
  Superpowers: installed
  Comet -> Claude Code: installed (12 files) -> .claude/skills/

  Comet setup complete! (scope: project)

  Installed:
    Claude Code -> .claude/skills/

  Working directories: docs/superpowers/specs/  docs/superpowers/plans/

  Get started:
    /comet "your idea"  — Start a new change with full workflow
    /comet-hotfix       — Quick bug fix (skip brainstorming)
    /comet-tweak        — Small change (skip brainstorming and plan)
After comet init completes, your project will contain a skills directory for each selected platform (e.g. .claude/skills/) containing the full Comet, OpenSpec, and Superpowers skill files and automation scripts.

​
Step 4: Verify with comet doctor

Run the built-in health check to confirm everything is wired up correctly: 
comet doctor

​
Expected Healthy Output

$ comet doctor

Comet Doctor — project scope
────────────────────────────────────────────────
✔ Node.js           v22.4.0  (>=20 required)
✔ Git               available
✔ Bash              available
✔ Platform          Claude Code (.claude/)
✔ Skills installed  comet, comet-open, comet-design, comet-build,
                    comet-verify, comet-archive, comet-hotfix, comet-tweak
✔ OpenSpec skills   installed
✔ Superpowers skills installed
✔ Scripts           comet-guard.sh, comet-env.sh, comet-handoff.sh,
                    comet-archive.sh, comet-yaml-validate.sh, comet-state.sh
✔ Working dirs      docs/superpowers/specs/  docs/superpowers/plans/

All checks passed. Comet is ready.
If any check shows ✗, the output includes a suggested fix. Re-run comet init or consult the CLI Reference for remediation options.

​
Step 5: Open Your AI Coding Tool and Type /comet

Launch your AI coding tool (Claude Code, Cursor, Windsurf, etc.), open the project, and enter: 
/comet
Comet’s main entry skill runs automatically. It:
  1. Scans for active specs — looks for in-progress changes in openspec/changes/.
  2. Reads .comet.yaml — determines the current workflow phase (open, design, build, verify, or archive).
  3. Dispatches to the correct sub-skill — /comet-open if no spec exists yet, or the appropriate phase skill to resume an interrupted workflow.
  4. Presents a selection list if multiple active specs are found, so you choose which to continue.
For a brand-new project with no active spec, /comet starts Phase 1 (/comet-open) and asks you to describe the change you want to make.
You can also invoke phases directly — /comet-open, /comet-design, /comet-build, /comet-verify, /comet-archive — but /comet is the recommended entry point because it validates phase preconditions and prevents out-of-order execution.

​
Using OpenClaw, Hermes, or Other Generic Platforms

For platforms that use the generic skills CLI directly (such as OpenClaw and Hermes), install the Comet skill package with: 
npx skills add rpamis/comet
npx skills add rpamis/comet uses the generic skills registry and does not require a global Comet install. It installs the Comet skill bundle directly into the platform’s skills directory.

​
Keeping Comet Up to Date

To get the latest features and fixes: 
comet update
Or update the npm package directly: 
npm install -g @rpamis/comet@latest
comet update refreshes both the npm package and the installed skill files across all detected project and global targets.

​
Next Steps

Workflow Deep Dive

Understand the five phases, guard conditions, state machine, and preset paths.

Platforms

See all 28 supported AI coding platforms and their skills directory paths.

CLI Reference

Full options for comet init, comet doctor, comet status, and comet update.

Scripts Overview

Learn how the guard, handoff, state, and archive scripts protect your workflow.