rpamis/comet: a resumable, phase-guarded workflow harness for coding agents

What Comet actually is, and the problem it targets

Comet is a resumable long-running task workflow and Skill platform for coding, distributed as the npm package @rpamis/comet with a comet binary. The problem it addresses is specific: a coding agent doing a multi-step change loses its place. A session ends, context is dropped, and the next session re-derives what was already decided. Comet's answer is to keep task state in the project so work can resume after interruptions or session changes, and to have the CLI output identify the next step and the decisions that need your input.

It is aimed at people who already drive an agent such as Claude Code or Codex through real changes and want governance around that loop, not at people looking for a chat interface. The repository topics name the concerns directly: eval, harness-engineering, phase-guarded, sdd, skill-creator. Two independent requirements workflows exist. Native is powered only by Comet's own runtime and is for strong models that can plan and verify autonomously. Classic preserves the OpenSpec + Superpowers phase-governance model. The README is explicit that these are not lightweight and heavyweight tiers and that neither upgrades into the other.

A naming warning belongs here, because the related searches for this project are dominated by unrelated things: Comet the browser, Comet by Perplexity, Comet cleaning powder, Comet the car. Those are different products. Search results for "how to use comet powder in toilet" have nothing to do with this repository.

How the two workflows share one runtime

The architecture visible in the repository is a Node.js runtime plus a set of agent-facing Skills. The build scripts confirm the split: build:classic-runtime, build:native-runtime and build:entry-runtime each produce a runtime, and check:generated reruns all three with a --check flag, which implies generated runtime artifacts are committed and verified rather than produced on the fly. The top-level layout carries .claude/ and .codex/ directories alongside .comet/, platform/, domains/ and eval/, so the agent integration surface and the product code are separated.

In Native, after requirements are confirmed the agent chooses how to plan, implement, test and review, while Comet handles state checks, acceptance and resumable archive. User-readable artifacts live under docs/comet/ by default, fully separate from Classic. The archive is described as one-way and resumable: it first returns a single dry-run continuation command, offers explicit isolated-workspace finish choices and blocker paths, and continuing the workflow lets the Runtime own the archive commit without repeated status queries or manual runtime-file commits.

For complex requirements there is a Supervisor Change mechanism. A goal is split into dependency-aware child changes; independent Codex sessions or Claude Code Agent Teams implement and verify them in isolated worktrees, then integrate them in dependency order before the parent change's final acceptance. That is the most structurally interesting part of the design, and also the part with the least documentation in the README: it names the mechanism and the isolation unit, but the failure modes of a partially integrated dependency graph are not described there.

Installing Comet and running a first change

The package is published to npm as @rpamis/comet with a comet binary, so installation is a global npm install. The package.json declares bin as bin/comet.js and lists a postinstall script under scripts/install/postinstall.js, which means the install step does more than drop files on disk.

npm install -g @rpamis/comet
comet --help

After the global install, comet --help should print the CLI entry points. The README does not reproduce the full flag list, so treat the help output as the authoritative surface rather than any command transcribed from a blog post.

From there the documented entry point for the model-driven path is the /comet-native skill. The README describes it as using a detailed brief, complete target specifications, phase checks and a recoverable archive to constrain outcomes while leaving planning, implementation, testing and review methods to the model.

/comet-native

That is a skill invocation inside the agent session, not a shell command, which is why it appears without a preceding binary. The same README points to a Native workflow quickstart at docs.comet.rpamis.com/en/native/quickstart for the full sequence. Evaluation is a separate CLI surface, comet eval, which the release notes tie to Rubric, Pass@k, Pass^k and LangSmith for comparing results and guiding Skill improvements. A three-pane Dashboard can be started to inspect Native and Classic progress, Git worktrees, acceptance results and archives in a browser; the repository exposes dev:dashboard and build:dashboard scripts for it, and the README does not spell out the exact command to launch it from the installed CLI.

The eval numbers, and what they do not cover

The 0.4.0 release notes cite an aligned Native versus 0.4.0 Classic experiment: 16 tasks, 48 runs per treatment. In the 41 paired samples where both passed, Native showed 76.8% fewer total tokens, 57.4% fewer agent rounds and 47.4% less time. Across the full sample, Native reached 87.5% pass^3, a 12.5 percentage point gain, while both treatments reached 100% pass@3.

Read that carefully before repeating it. The token, round and time reductions are computed on the subset where both treatments passed, so they describe efficiency on tasks both could already solve, not on tasks Classic failed. The pass^3 gap is the more interesting number, because pass@3 at 100% for both means neither treatment failed outright within three attempts, while pass^3 measures consistency. A 16-task sample is small, and the release notes themselves point to an evaluation report for conditions and limitations. The README does not state who ran the experiment or on which models, and the Classic arm is pinned to 0.4.0, so the comparison is against a specific version rather than Classic in general.

The eval tooling is the part most likely to be undervalued. comet eval with Rubric, Pass@k and Pass^k turns "is this Skill getting better" into a scored question, and the repository ships an eval/ tree with langfuse, langsmith, local, scaffold and schemas directories plus a report-html-config.json. That is an unusual amount of evaluation scaffolding for a workflow tool, and it is the strongest evidence that the project treats Skill quality as measurable rather than vibes-based.

Where Comet is the wrong tool

Comet writes into your repository. Runtime files, agent configuration under .claude/ and .codex/, artifacts under docs/comet/, and a .comet/ directory all become part of the working tree. If your constraint is a clean diff, or if your team reviews agent output as a single patch, that footprint is friction you will be fighting rather than using.

The two-workflow design is a real cost. Native and Classic share configuration, status, Dashboard and Eval entry points, but they do not share methodology, and the README states plainly that neither upgrades into the other. A team has to decide which one it is on. Choosing Native means accepting that the model decides how to plan, implement, test and review, which is exactly what you do not want if your organisation requires a fixed phase sequence with named gates. Choosing Classic means carrying the OpenSpec + Superpowers methodology, which is heavier by design.

There is also a model assumption baked in. Native is described as being for strong models that can plan and verify autonomously. On a weaker model, the freedom Native grants is a liability, and Classic's constraints are the point. The README does not offer guidance on where the boundary between strong and weak sits, so that judgement is yours. Finally, the package is JavaScript and TypeScript with a pure Node.js runtime and no Bash or WSL requirement on Windows, macOS or Linux, but the agent integration targets Claude Code and Codex specifically. If your agent runtime is something else, the .claude/ and .codex/ directories tell you what is supported.

Comet versus plain spec-driven development

The obvious alternative is a spec-driven development loop with no harness: write a spec file, point the agent at it, review the diff, repeat. Tools in that space keep the agent's context in the conversation and the spec in a markdown file. The difference in approach is where state lives and who owns the transitions. A plain spec loop has no runtime that knows a phase completed, no acceptance step that produces a record, and no archive that can be resumed. Comet moves those into a runtime with phase checks and a one-way archive, at the cost of a larger repository footprint and a CLI to learn.

The second alternative is the OpenSpec + Superpowers methodology on its own. Comet's Classic workflow preserves that phase-governance model, so if you already run it directly, Comet's contribution is the surrounding runtime: shared configuration, status, Dashboard, Eval entry points, and the ability to package composed Skills with /comet-any for distribution. The release notes also mention Personal Memory and Project Knowledge, which retain collaboration preferences and reusable experience across tasks and can be inspected, corrected, forgotten or paused, with new lessons starting in trial and gaining supporting evidence through actual adoption and verification. That trial-then-promote behaviour is a design choice worth noting: memory does not become trusted on first write.

If your work is a single-file change, none of this pays for itself. The harness earns its keep on long-running, multi-step changes where losing state is expensive.

Maintenance, licence and upgrade cost

The repository is not archived. The last push was on 2026-09-15, and the most recent release is 0.4.0 from 2026-09-08, preceded by 0.4.0-rc.6 and 0.4.0-rc.5 in the days before. The package.json version is 0.4.1, ahead of the published release listed, which is normal for a repository between a release and the next one. Release cadence has been fast, and the changelog is hosted at docs.comet.rpamis.com/en/changelog rather than inlined in the README.

Fast cadence cuts both ways. The 0.4.0 notes describe adding Native workflows, multi-agent collaboration, memory and knowledge management, and a full Skill toolchain on top of 0.3.9. A release of that size means upgrade cost is not just running a new npm install: if you adopted Classic on 0.3.x, the methodology you standardised on is now one of two, and the experiment in the release notes pins Classic at 0.4.0. Existing docs/comet/ artifacts and runtime files are the things to check against the changelog before upgrading, because the archive is described as one-way.

The licence is MIT, declared in both the LICENSE file and package.json. That permits commercial use, modification and redistribution with the copyright notice retained. It is a permissive licence with no copyleft obligation and no patent grant language beyond what MIT contains; as always, that is a description of the licence text, not legal advice for your situation.

Editorial conclusion

Adopt Comet if you already run Claude Code or Codex on multi-step work and want task state, phase checks and an archive that survive a lost session, and if you are willing to keep two workflows in your head or pick one deliberately. Do not adopt it if you want a single prompt-level tool with no repository footprint, or if you cannot accept that your agent's planning freedom differs sharply between Native and Classic. Verify two things first: that the phase guards fire on your own task shape rather than only on the 16-task experiment described in the docs, and which workflow your team will standardise on, because the README is explicit that Native and Classic are not tiers and neither upgrades into the other.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. rpamis/comet on GitHub