Comet

What It Does

Comet (npm package @rpamis/comet, repo rpamis/comet) is a TypeScript CLI that acts as a "skill harness" for AI coding agents. It does not replace your skills. It chains two existing ones, OpenSpec and Superpowers, into a single five-phase pipeline: open (define the change), design (technical design doc), build (execute tasks), verify (prove it works), archive (close the spec). The differentiator is that Comet refuses to let an agent advance phases on its own word. Shell scripts (comet-guard.sh, comet-state.sh, comet-yaml-validate.sh) check that tasks are actually checked off, that state fields in .comet.yaml are valid, and that verification evidence exists before a transition is allowed. A .comet.yaml state file records phase, execution mode, verification result, and archive status so a session can resume after interruption instead of re-reading documents and guessing progress. The intended user is a developer or team that already uses (or wants to use) OpenSpec and Superpowers together and is tired of agents skipping the design step or forgetting to sync and archive specs.

The Good

The engineering rigor is well above the average agent-skill repo, and it is verifiable. The TypeScript source is 6,270 lines across a clean src/ tree (cli, commands, core, dashboard, utils). The test suite is real: 422 vitest tests across 24 files plus 29 bats shell tests, all passing in 21 seconds. The tests are not smoke. They assert phase-guard behavior directly, with names like "blocks build completion until isolation and build mode are selected", "rejects subagent build mode without confirmed background dispatch", and "blocks verify guard when verification evidence is missing". The shell tests cover comet-state.sh get/set/check/scale semantics including enum validation (phase, verify_mode, archived, branch_status) and rejection of unknown fields. CI run #215 is green as of today, and there have been 100 commits in the last 30 days. This is a maintained, tested codebase, not a README with ambitions.

The phase-guard state machine is the genuine technical contribution, and it is implemented in testable shell rather than fragile prompt prose. Comet's central claim is that agents lie at phase exits ("done", "all tasks complete") and that you should not trust them. The seven shell scripts (3,628 lines total) implement the guards: comet-guard.sh checks open/design/build/verify/archive exit conditions, comet-state.sh is a CRUD interface over .comet.yaml with strict field validation, comet-yaml-validate.sh validates the state file structure, and comet-hook-guard.sh is a PreToolUse hook that blocks file writes during the wrong phase (open, design, archive). The scripts are explicitly written for cross-platform compatibility: the contributing guide forbids sed -i (GNU/BSD incompatibility), handles both sha256sum and shasum -a 256, and requires || true on optional greps to survive pipefail. That level of shell discipline is rare in this ecosystem.

The platform surface is the widest I have measured in a single skill installer. src/core/platforms.ts defines 30 supported AI coding platforms, each with its own skills directory, rules directory, rules format (plain markdown, Cursor MDC, GitHub Copilot instructions, GEMINI.md), and hook format where supported. The list includes Claude Code, Cursor, Codex, OpenCode, Windsurf, Cline, RooCode, Continue, GitHub Copilot, Gemini CLI, Amazon Q, Qwen Code, Kilo Code, Auggie, Kiro, Kimi Code, Lingma, Junie, CodeBuddy, CoStrict, Crush, Factory Droid, iFlow, Pi, Qoder, Antigravity (both versions), Bob Shell, ForgeCode, and Trae. The code even handles platform-specific quirks correctly, for example Cline rules going to .clinerules/ at project root instead of inside .cline/, and Antigravity using different project-level and global paths.

Functional verification of the install claim succeeded with concrete artifacts on disk. Running comet init --yes --language en in a throwaway project with a .claude/skills/ marker produced exactly the expected tree: all eight skills (comet, comet-open, comet-design, comet-build, comet-verify, comet-archive, comet-hotfix, comet-tweak) deployed to .claude/skills/, the eight reference docs deployed under comet/reference/, the seven scripts deployed under comet/scripts/, and a package.json created that declared @fission-ai/openspec as a dependency. The deployed skill line counts (1,787 total) matched the source asset tree line for line. Comet then cloned obra/superpowers and began installing its 14 skills. The deployment path works.

The skill content itself is detailed and references real mechanisms, not vibes. The main comet SKILL.md (282 lines) specifies automatic phase detection with an explicit decision table (active changes by count versus user input), preset upgrade criteria with hard thresholds (hotfix upgrades to full if the change touches 3 or more files, involves architecture changes, or introduces a new public API), and resume rules that re-run detection on every context resume rather than trusting conversation history. There is a full English and Chinese parity: every one of the eight skills exists in both assets/skills/ and assets/skills-zh/, and the CLI lets you pick artifact language at init.

The Bad

The external-dependency story is the biggest source of friction, and the --yes flag makes a quiet decision about it. Comet is an orchestrator that depends on two other skills (OpenSpec, Superpowers) and one indexing tool (CodeGraph) to do anything useful. comet init tries to install all of them: OpenSpec via npm install -g @fission-ai/openspec@latest, Superpowers via npx skills add obra/superpowers (which clones the repo), and CodeGraph via another global npm install. In my test the skill deployment succeeded but the process exited with code 1 because the OpenSpec global install step could not finish in the sandbox. Worse, the --yes flag (line 226 of src/commands/init.ts) silently selects every not-yet-installed dependency and triggers all of this. A user running comet init --yes for the first time will get global npm installs, a git clone of a large external repo, and potentially sudo prompts, with no upfront warning. This is the difference between "one command from idea to archive" (the tagline) and "one command that does a lot of global mutation" (the reality).

The version drift between the repository and the published npm package is currently a full minor version. The repo package.json and assets/manifest.json both declare 0.4.0-beta.1, but npm view @rpamis/comet version returns 0.3.9 (last published 2026-06-18, 18 days before this review). A user who installs from npm gets 0.3.9 and its feature set (review mode, Kimi Code support, CodeGraph indexing), while the README documents 0.4.0-beta behavior. Anyone following the README against the npm install will hit small mismatches. The beta is unreleased on the registry, which is normal, but the gap is worth knowing about before you depend on documented behavior.

The whole value proposition collapses if you do not want both OpenSpec and Superpowers. Comet is not a general-purpose workflow engine. It is a harness for two specific skills with specific artifact conventions (OpenSpec proposals/tasks, Superpowers design docs and plans). If you use only OpenSpec, or only Superpowers, or a different spec-driven stack entirely, most of Comet's state machine and artifact linking is dead weight. The "What You'll Learn" section of the README frames Comet as a reference implementation for skill-chaining patterns, which is honest, but the practical value is concentrated in the intersection of those two tools' users.

The open-issue backlog shows the automation is still being debugged in the wild. There are 44 open issues, several of which are real defects in core behavior: "Unknown skill: openspec-new-change" (#155), the hook guard intercepting a legitimate brainstorming path (#154), the hook guard failing open on invalid state (#151), and "comet dashboard: unknown command 'dashboard'" (#148). Issues are bilingual (English and Chinese), which is good for the community but means triage spans two languages. None of these are fatal, and the maintainers are clearly active, but a tool whose central promise is reliable phase enforcement has open issues about its enforcement hooks misbehaving.

Smoke Test Results

Tested on macOS host (aarch64), Node v24.13.1, npm. The repo was shallow-cloned to 8.7 MB. Dependencies were installed with npm install --ignore-scripts (the prepare hook hard-codes pnpm run build, and pnpm is not installed on this host, so a plain npm install would fail at the prepare step). The TypeScript build was run directly with node build.js. A custom npm cache (/tmp/comet-npm-cache) was used to avoid a pre-existing root-owned-file EACCES error in the default cache, a known macOS pitfall unrelated to Comet.

Run A. Fresh sandbox, no deps preinstalled

$ git clone --depth 1 https://github.com/rpamis/comet.git

Cloning into 'comet-review-17357'... (8.7 MB)

$ ls package.json assets/skills/ src/ test/ .github/workflows/

package.json present (v0.4.0-beta.1, MIT, Node >=20, bin: ./bin/comet.js)

assets/skills/ has 8 skill dirs (comet + 7 subcommands) plus assets/skills-zh/ parity

src/ has 56 TypeScript files across cli/commands/core/dashboard/utils

test/ has 26 .test.ts files + 1 .bats shell suite

.github/workflows/ has ci, greeting, pr-title-lint, stale-prs

$ find . -name "SKILL.md" -not -path './node_modules/*'

16 files: 8 English + 8 Chinese (full parity)

PASS (structure matches README, license present, 30-platform matrix in platforms.ts)

Pass rate: 1 of 1. The repository is well-organized and self-describing. The only surprise is the prepare lifecycle hook depending on pnpm, which trips a plain npm install.

Run B. Sandbox with deps preinstalled

$ npm install --ignore-scripts --no-audit --no-fund

added 203 packages in 3s

$ node build.js

Building Comet...

Compiling TypeScript... Version 5.9.3

Build completed successfully!

$ CI=true npx vitest run

Test Files 24 passed (24)

Tests 422 passed (422)

Duration 20.91s

$ CI=true node scripts/run-bats.js test/shell/*.bats

ok 1 - init creates .comet.yaml with required fields

... (29 tests)

ok 29 - scale missing args shows usage

All 29 shell tests pass

$ node bin/comet.js --version

0.4.0-beta.1

$ node bin/comet.js --help

Usage: comet [options] [command]

Commands: init, status, dashboard, doctor, update, uninstall

PASS (build, unit tests, shell tests, and CLI all green)

Pass rate: 6 of 6. The badge number is 6 of 6. Build is clean, both test suites pass, and the CLI is responsive. This is the canonical "does it install and self-check correctly" verdict.

Run C. Functional verification (does it do what it claims?)

$ mkdir /tmp/probe/.claude/skills && cd /tmp/probe

$ node bin/comet.js doctor --json

{

"scope": "auto",

"results": [

{ "check": "openspec CLI", "status": "warn", "message": "not installed" },

{ "check": "working directories", "status": "fail", "message": "missing - run: comet init" },

{ "check": "skills", "status": "warn", "message": "no platforms detected" },

{ "check": "scripts executable", "status": "pass", "message": "OK (7 scripts)" },

{ "check": "CodeGraph CLI", "status": "warn", "message": "not installed" }

]

}

PASS (doctor correctly reports missing deps instead of claiming success)

$ node bin/comet.js status --json

{ "changes": [] }

PASS (empty project handled cleanly)

$ node bin/comet.js dashboard --json

{ "project": {...}, "summary": {"activeChanges":0,"archivedChanges":0,...}, "git": {...} }

PASS (snapshot mode produces structured JSON without starting a server)

$ cd /tmp/init2 && node bin/comet.js init --yes --language en

(detected Claude Code, deployed 8 Comet skills to .claude/skills/, cloned obra/superpowers, installed 14 skills)

$ wc -l .claude/skills/comet*/SKILL.md

1787 total (exact match to source assets)

$ ls .claude/skills/comet/reference/ | wc -l

8 reference docs deployed

$ cat package.json

{ "dependencies": { "@fission-ai/openspec": "^1.5.0" } }

(exit code 1 from the OpenSpec global install step; skill deployment already complete)

PASS (core skill-deployment claim verified; external-dep orchestration partial)

Functional pass rate: 4 of 4 exercised. The install claim is verified with real files on disk. The dashboard snapshot, status, and doctor commands all return correct structured output. What remains unverified is the live-agent workflow loop, which requires a cooperating AI coding agent that a headless sandbox cannot provide.

What the runs tell you

Comet installs cleanly once you work around the pnpm prepare hook and any npm cache permission issues, and its test suite is strong. The skill-deployment path works and produces exact-copy artifacts on the target platform. The friction is concentrated entirely in the external-dependency orchestration: OpenSpec, Superpowers, and CodeGraph are heavy, the install mutates globally, and the --yes flag does not warn before doing it. The live workflow itself (the five-phase automation) could not be exercised without a real AI agent, so the deepest claim, that the phase guards actually hold during agentic execution, is taken on the strength of the 422 unit tests rather than a live run.

Setup Walkthrough

1. Install Node 20 or later and a bash-compatible shell. On Windows, use Git Bash.
2. npm install -g @rpamis/comet. This gets you npm version 0.3.9. The repository is ahead at 0.4.0-beta.1, which is not yet on the registry.
3. cd your-project && comet init. This is interactive by default and will prompt for platform, scope, language, and which npm dependencies to install. If you accept all dependencies, expect a global npm install of OpenSpec, a git clone of Superpowers, and a global install of CodeGraph.
4. For a non-interactive CI-style install, comet init --yes auto-detects platforms and selects all missing dependencies, but be aware it triggers the same global installs with no confirmation.
5. To run from source instead, git clone https://github.com/rpamis/comet.git, then npm install --ignore-scripts (to avoid the pnpm-only prepare hook), then node build.js, then invoke node bin/comet.js.
6. After install, comet doctor reports what is healthy and what is missing, comet status shows active changes, and comet dashboard opens a local read-only web view of phase progress.

Gotcha: on macOS with a stale npm cache, npm install can fail with EACCES on root-owned cache files. Point npm at a fresh cache (npm_config_cache=/tmp/...) rather than trying to fix permissions.

Alternatives

1. OpenSpec (Fission-AI/OpenSpec) and Superpowers (obra/superpowers), used separately - what Comet chains together. Prefer them directly if you only need spec lifecycle management or only need brainstorming-driven execution, and you do not mind driving the handoffs yourself.
2. planning-with-files (OthmanAdi/planning-with-files) - a lighter, file-based plan-state skill without the OpenSpec/Superpowers coupling or the multi-platform installer. Prefer it if you want resumable task state without committing to a specific spec framework.
3. A custom PreToolUse hook plus a markdown state file - the do-it-yourself version of Comet's core idea. Prefer it if you want phase guards but not the eight-skill opinionated workflow, and you are comfortable writing the hook yourself.