Initializes OpenSpec, Superpowers, and Comet skills for selected AI coding platforms.

When multiple existing components are found on the same platform, interactive init offers one bulk choice: overwrite all, skip all, or choose per component.

Displays active changes, task progress, the recommended next Comet workflow command, the current step, runtime mode, and diagnostic recovery hints when a change is malformed or missing required evidence.

Starts a local HTTP server that displays a visual dashboard with active changes, phase status, task progress, and archive history. Auto-opens in your browser by default.

Active change overview with phase indicators, task progress, and archive history

Checks project/global installation health, working directories, installed skills, scripts, and active change diagnostics. comet doctor reports diagnostic status for malformed .comet.yaml files, current step / runtime mode for valid changes, and runtime evidence gaps that block safe resume.

Updates the npm package and refreshes installed Comet skills in detected project/global targets.

Safely removes Comet-distributed skills, rules, and hooks from all detected platforms. Preserves user-defined hooks and non-Comet configuration.

comet uninstall              # Interactive — shows targets, asks for confirmation
comet uninstall --force      # Non-interactive — removes everything immediately
comet uninstall --scope project  # Only remove project-level installations

comet eval answers a simple question: does this Skill actually work reliably on standard tasks?

The most common case is evaluating a Skill generated by /comet-any. Generated packages usually include comet/eval.yaml; pass that file to comet eval first:

comet eval ./generated-skill/comet/eval.yaml --collect
comet eval ./generated-skill/comet/eval.yaml --html

The first command only performs discovery and preflight checks, confirming that the manifest, tasks, and dependency paths can be found before any expensive evaluation work runs. The second command runs local evaluation and writes a browsable report suitable for publish-readiness evidence. The report path is printed by the command and is usually under eval/local/logs/experiments/<experiment-id>/summary.html.

If you do not have comet/eval.yaml yet and only have a local Skill directory, start with a low-cost smoke run:

comet eval ./my-skill --quick --html

That path is useful early on: it checks that the Skill directory can be read, injected into the eval harness, and run against the generic smoke task. For release evidence, prefer generating comet/eval.yaml through /comet-any and using the manifest path.

Local eval is the normal path for day-to-day development and pre-release checks. In the HTML report, look first at:

• whether pass/fail and rubric scores match expectations
• whether failures are attributed to the Skill, workflow, task, model, or environment/harness
• whether expected artifacts are missing
• whether token use, cost, or duration look unusual
• whether the result is clean enough, or a specific task/treatment should be rerun

If the report says Insufficient clean data or Inconclusive due to data quality, check auth, rate limits, Docker/container setup, network, and other environment issues before treating the run as a Skill-quality verdict.

Use the LangSmith suite when you want to sync eval results to LangSmith, or when your team wants to inspect runs, rubric feedback, costs, and Claude Code trajectories together. It reuses the same tasks, treatments, rubric, and comet/eval.yaml; the difference is that results are uploaded to LangSmith.

Prepare dependencies and environment variables once:

cd eval
uv sync --extra langsmith

LANGSMITH_API_KEY=lsv2_pt_...
LANGSMITH_PROJECT=comet-skill-eval
LANGSMITH_TRACING=true

Then run the same manifest:

cd eval
uv run pytest langsmith/tests/tasks/test_tasks.py \
  --eval-manifest=/absolute/path/to/generated-skill/comet/eval.yaml -v

In PowerShell, set $env:LANGSMITH_API_KEY, $env:LANGSMITH_PROJECT, and $env:LANGSMITH_TRACING, or place them in eval/.env. See eval/langsmith/README.md for plugin cache and trajectory tracing details.

• Day-to-day development: comet eval ./my-skill --quick --html
• /comet-any output: comet eval ./generated-skill/comet/eval.yaml --collect, then rerun with --html
• Publish evidence: prefer the local HTML report from comet/eval.yaml
• Team tracing and side-by-side comparison: run the same comet/eval.yaml through the LangSmith suite

For full task, treatment, report, and troubleshooting details, see the Eval usage guide.

/comet-any is the main user path: Create or optimize a reusable Skill → validate it with comet eval → review and distribute it, until it becomes a stable composed Skill. For resume and release, use comet creator, comet creator status / comet creator next, comet publish, and comet publish distribute --preview. The README does not expand the backend command list; see the Skill creation guide for Advanced Bundle backend and Advanced Engine Run details, including comet skill run / comet skill continue.

Classic automation ships as independent Node.js command scripts generated from TypeScript. They run through node on every platform, so Comet requires only Node.js — no Bash, Git Bash, or WSL.

Each change-level .comet.yaml stores Classic workflow state and only keeps run_id as the link to the Engine Run. Machine-owned Engine state lives in the change's .comet/run-state.json with camelCase fields such as currentStep, status, and iteration. Legacy Run fields left in YAML are migrated after compatibility reads, and skill is no longer a valid current .comet.yaml field. Project defaults live in .comet/config.yaml.

Phase progression is handled consistently by the TypeScript transition table, comet-state transition, comet-guard --apply, and archive commands. Each successful progression appends an audit event to .comet/state-events.jsonl with the source, before/after state, and actual field changes.

This keeps Skill text focused on guiding the agent while scripts own state writes, phase checks, auditability, and breakpoint recovery. Agents can use Comet commands to know which phase the current Spec is in.

Key Fields in change .comet.yaml:

workflow: full                                           # Workflow type: full | tweak | hotfix
phase: build                                             # Current phase: open | design | build | verify | archive
context_compression: off                                 # Context compression: off | beta
auto_transition: true                                    # Auto-invoke the next Skill after phase completion
base_ref: <git-sha-or-null>                              # Baseline commit captured at init; may be null
created_at: YYYY-MM-DD                                   # Creation date written by comet-state.mjs init
run_id: <uuid>                                           # Links to .comet/run-state.json only; Run details stay out of YAML
review_mode: standard                                    # Automatic review strength: off | standard | thorough
build_mode: subagent-driven-development                  # Build mode: subagent-driven-development | executing-plans | direct
build_pause: null                                        # `build_pause` records an internal build-phase pause point: null none, `plan-ready` means the plan has been generated
subagent_dispatch: null                                  # Dispatch confirmation; confirm before verify
tdd_mode: null                                           # Full-workflow build choice: tdd | direct
isolation: branch                                        # Isolation mode: branch | worktree
verify_mode: null                                        # Verification mode: light | full
design_doc: docs/superpowers/specs/<design-doc>.md       # Design doc path
plan: docs/superpowers/plans/YYYY-MM-DD-feature.md       # Implementation plan path
verify_result: pending                                   # Verification result: pending | pass | fail
verification_report: null                                # Verification report path; must exist before verify-pass
branch_status: pending                                   # Branch handling status: pending | handled
verified_at: null                                        # Verification timestamp; null before verification passes
archived: false                                          # Archived changes are blocked from further mutation
direct_override: null                                    # Must be true when a full workflow chooses direct build
handoff_context: null                                    # Design handoff context path written by comet-handoff.mjs
handoff_hash: null                                       # SHA256 for handoff_context; 64 hex chars when present
classic_profile: full                                    # Machine-maintained Classic profile
classic_migration: 1                                     # Machine-maintained migration version

Current change .comet.yaml no longer contains skill; legacy Run fields in YAML are migrated to .comet/run-state.json.

1. Entry Verification — Each phase validates preconditions before execution

   • Checks file existence, state consistency, and phase transitions
   • Outputs [HARD STOP] with actionable suggestions if validation fails

2. Automated State Transitions — comet-guard.mjs --apply updates .comet.yaml automatically

   • All phase transitions (open → design/build → verify → archive) use guard --apply
   • No manual state editing required — eliminates write-verification errors
   • comet-state.mjs is the agents' exclusive interface for state operations
   • Guard and archive scripts use comet-state.mjs internally for state management

3. Schema Validation — comet-yaml-validate.mjs ensures data integrity

   • Validates required and optional fields
   • Validates enum values, including direct_override
   • Validates design_doc, plan, and handoff_context paths exist, plus handoff_hash format
   • Detects unknown/typos fields

4. Build Decision Enforcement — Guard and state transitions both block skipped build choices

   • isolation must be branch or worktree
   • build_mode must be selected before leaving build
   • build_pause: plan-ready is a recoverable pause after plan generation, not a build_mode
   • Full workflow build_mode: direct requires direct_override: true

5. Verification Evidence — Guard enforces proof before phase advance

   • verify-pass transition requires verification_report pointing to an existing report file
   • branch_status must be handled before verify can pass
   • Guard checks verification_report exists and branch_status=handled as hard prerequisites
   • Prevents false phase advances when verification or branch handling was skipped

6. Archive Automation — comet-archive.mjs handles the full archive flow in one command

   • Validates entry state, merges delta specs into main specs through OpenSpec
   • Annotates design doc and plan frontmatter
   • Moves change to archive directory and updates archived: true
   • Supports --dry-run for preview

7. Anti-drift Phase Guards — Phase awareness for long-context sessions

   • Rule layer: comet-phase-guard.md injects phase awareness, Skill invocation rules, and context recovery guidance each turn across platforms
   • Hook layer: comet-hook-guard.mjs hard-blocks file writes during open/design/archive phases on platforms that support hooks, such as Claude Code
   • Allowlisted paths: openspec/*, docs/superpowers/*, .superpowers/*, .claude/*, and .comet/*

Comet supports context compression at the Design → Build handoff. When enabled, comet-handoff.mjs generates a compact context package that reduces Build-phase input tokens by 25–30% without affecting implementation correctness.

Key findings from benchmark testing:

• Test pass rate: 100% across all tiers (compression does not affect correctness)
• Spec coverage: 100% (off) vs 95% (beta) — minor edge-case detail loss
• Scaling: Larger tasks yield higher absolute savings (up to 15,000 tokens for large-tier tasks)

Enable in .comet/config.yaml: context_compression: beta

See CONTEXT-COMPRESSION.md for the full benchmark report, compression principles, and reproduction steps.

auto_transition controls whether Comet automatically invokes the next skill after a phase completes, or pauses for manual handoff. Phase advancement itself always happens — this setting only affects skill invocation.

Three-layer configuration with precedence: COMET_AUTO_TRANSITION env var > .comet/config.yaml (project) > change .comet.yaml.

See AUTO-TRANSITION.md for configuration details, workflow mapping, and FAQ.