@rpamis/comet
Advanced tools
██████╗ ██████╗ ███╗ ███╗███████╗████████╗
██╔════╝██╔═══██╗████╗ ████║██╔════╝╚══██╔══╝
██║ ██║ ██║██╔████╔██║█████╗ ██║
██║ ██║ ██║██║╚██╔╝██║██╔══╝ ██║
╚██████╗╚██████╔╝██║ ╚═╝ ██║███████╗ ██║
╚═════╝ ╚═════╝ ╚═╝ ╚═╝╚══════╝ ╚═╝
Comet is a resumable long-running task workflow and Skill platform for coding.
It uses a unified cross-platform runtime to connect OpenSpec artifacts, Superpowers execution methodology, Skill creation, evaluation, and release into a closed-loop workflow.
It allows you to use a toolchain to handle everything from requirements to archiving, combine any skill to make it like Comet, evolving your skills based on scientific Rubric, Pass@k, and Pass^k scoring.
[!IMPORTANT] 0.4.0-beta.1 — Comet has been upgraded to a pure Node runtime (no longer dependent on Bash/WSL) and brings three core capabilities: use
/comet-anyto combine any skill into a custom workflow, usecomet evalto evaluate any skill and integrate it into the LangSmith system, and usecomet dashboardto visualize each change in the browser.0.3.9 — Review mode (
off|standard|thorough) controls Build/Verify code review with project defaults; init/update now use optional dependency prompts, broader CLI i18n, stronger phase guards, and macOS executable bits.0.3.8 — Adds Kimi Code support, safe multi-platform
comet uninstall, extended subagent dispatch, shared progressive-loading references, update checks, and pre-commit formatting.0.3.7 — Adds CodeGraph semantic indexing, Beta context compression, active context compression, token optimizations,
auto_transition, phase guards, optional TDD, and safer archive/verification flow.See NEWS.md for details.
Combining OpenSpec and Superpowers is not Comet's ultimate goal. We hope to track long-running skills like these and find the Harness capabilities that enable stable execution of long-running skills. If you are interested in participating, you are welcome to contribute to our project or learn from our source code.
/comet remembers where a change stopped, supports zero-context recovery across devices, and removes the need
to memorize long Skill command names: use /comet to advance or resume your work./comet-any to organize them into distributable
Bundles, so Skills you create can be distributed to coding platforms with one command, much like comet init.With Comet, you only need to remember two skills and one command, covering coding, creation, and evaluation with an extremely low barrier to entry：
/comet for coding tasks/comet-any to compose any Skillscomet eval to evaluate any SkillThe following charts are from 16 Comet workflow tasks, with 5 samples per treatment, comparing no Comet, Comet 0.3.9, and Comet 0.4.0.
The core observations were the differences in Pass@5, Pass^5, and Rubric scores. The baseline without Comet Skills only validated business behavior.
Many Comet capabilities have parallels in current industry practice.
To compare Comet with those patterns, see Comet Docs.
.comet.yaml, so an
agent can continue after interruption instead of rereading documents and guessing progress.comet-guard.mjs, comet-yaml-validate.mjs, and comet-state.mjs check tasks, state fields, verification
evidence, and archive conditions before the workflow advances./comet-any composes arbitrary Skills. You describe your Skill
preferences, and the agent handles stability-related hooks, rules, scripts, and referenced Skill files for you.Requirements:
npm install -g @rpamis/comet
cd your-project
comet init
For platforms that use the generic skills CLI directly, you can install the Comet skill package with:
npx skills add rpamis/comet
Auto-install OpenSpec & Superpowers, one-click dev environment setup
Multi-phase Skill entry, auto-detects current Spec stage, auto-triggers core flow, manual review at key nodes
Comet Eval's automated dual-agent architecture can integrate online with LangSmith/LangFuse environments, making experiments traceable and skills evolvable.
Manage your Skill baseline in LangSmith and view detailed performance metrics, latency, and token consumption
Trace your Claude Code in LangSmith
Trace custom Rubric metrics with Pytest in LangSmith
comet init [path] — Initialize Comet workflowInitializes OpenSpec, Superpowers, and Comet skills for selected AI coding platforms.
| Option | Description |
|---|---|
--yes | Non-interactive mode, auto-select detected platforms (or all if none detected) |
--scope <scope> | Install scope: project or global |
--language <lang> | Skill language: en or zh (skips interactive language prompt) |
--skip-existing | Skip already installed components |
--overwrite | Overwrite already installed components |
--json | Output structured JSON |
When multiple existing components are found on the same platform, interactive init offers one bulk choice: overwrite all, skip all, or choose per component.
comet status [path] — Show active changes and next workflow commandDisplays 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.
| Option | Description |
|---|---|
--json | Output active changes with nextCommand, currentStep, and runtime data |
comet dashboard [path] — Launch local read-only dashboard serverStarts 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
| Option | Description |
|---|---|
--port | Server port (default: auto-selects available port) |
--no-open | Don't auto-open the dashboard in browser |
--json | Collect single snapshot and print JSON to stdout (for scripting/inspection) |
comet doctor [path] — Diagnose Comet installation healthChecks 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.
| Option | Description |
|---|---|
--json | Output structured diagnostic results |
--scope <scope> | Diagnose auto, project, or global scope (default: auto) |
comet update [path] — Update Comet package and skillsUpdates the npm package and refreshes installed Comet skills in detected project/global targets.
| Option | Description |
|---|---|
--json | Output npm and skill update results as JSON |
--language <lang> | Override detected skill language (en, zh) |
--scope <scope> | Update only global or project scope |
comet uninstall [path] — Remove Comet skills, rules, and hooksSafely removes Comet-distributed skills, rules, and hooks from all detected platforms. Preserves user-defined hooks and non-Comet configuration.
| Option | Description |
|---|---|
--force | Skip confirmation prompt |
--scope <scope> | Uninstall only global or project scope |
--json | Output removal results as JSON |
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 [target] — Evaluate Skills through the shared eval harnesscomet 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:
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.
comet eval ./my-skill --quick --html/comet-any output: comet eval ./generated-skill/comet/eval.yaml --collect, then rerun with --htmlcomet/eval.yamlcomet/eval.yaml through the LangSmith suiteFor full task, treatment, report, and troubleshooting details, see the Eval usage guide.
/comet-any / comet creator / comet publish — Create, evaluate, and publish Skills/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.
comet --help / comet --version — Basic information| Command | Description |
|---|---|
comet --help | Show help |
comet --version | Show version |
comet init supports 33 AI coding platforms:
| Platform | Skills Dir | Platform | Skills Dir |
|---|---|---|---|
| Claude Code | .claude/ | Cursor | .cursor/ |
| Codex | .codex/ | OpenCode | .opencode/ |
| Windsurf | .windsurf/ | Cline | .cline/ |
| RooCode | .roo/ | Continue | .continue/ |
| GitHub Copilot | .github/ | Gemini CLI | .gemini/ |
| Amazon Q Developer | .amazonq/ | Qwen Code | .qwen/ |
| Kilo Code | .kilocode/ | Auggie | .augment/ |
| Kimi Code | .kimi-code/ | Kiro | .kiro/ |
| Lingma | .lingma/ | Junie | .junie/ |
| CodeBuddy | .codebuddy/ | CoStrict | .cospec/ |
| Crush | .crush/ | Factory Droid | .factory/ |
| iFlow | .iflow/ | Pi | .pi/ |
| Qoder | .qoder/ | Antigravity | .agents/ |
| Antigravity 2.0 | .agents/ | Bob Shell | .bob/ |
| ForgeCode | .forge/ | Trae | .trae/ |
| Trae CN | .trae-cn/ | ZCode | .zcode/ |
| MimoCode | .mimocode/ |
After comet init, three groups of skills are installed to the selected platform's skills/ directory:
| Skill | Description |
|---|---|
/comet | Main entry — auto-detects phase and dispatches to sub-commands |
/comet-open | Phase 1: Open a change (proposal, design, task breakdown) |
/comet-design | Phase 2: Deep design (brainstorming, Design Doc) |
/comet-build | Phase 3: Plan and build (implementation plan, code commits) |
/comet-verify | Phase 4: Verify and finish (testing, verification report) |
/comet-archive | Phase 5: Archive (delta spec sync, status annotation) |
/comet-hotfix | Preset: Quick bug fix (skips brainstorming) |
/comet-tweak | Preset: OpenSpec-chained medium change (delta spec is first-class, skips brainstorming and full plan) |
/comet-any | Comet Skill Creator — Create or optimize a reusable Skill |
| Script | Purpose |
|---|---|
comet-env.mjs | Script discovery helper — prints the bundled scripts directory so skills can resolve sibling command paths |
comet-guard.mjs | Phase transition guard — validates exit conditions, --apply auto-updates .comet.yaml |
comet-handoff.mjs | Design handoff — generates deterministic context packages from OpenSpec artifacts with SHA256 tracing |
comet-archive.mjs | One-command archive — validates state, syncs specs, moves to archive, updates status |
comet-yaml-validate.mjs | Schema validator — validates .comet.yaml structure and field values |
comet-state.mjs | Unified state management — init/set/get/check/scale, agents' exclusive YAML interface |
comet-hook-guard.mjs | Phase write guard — PreToolUse hook, blocks file writes during open/design/archive phases |
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.
/comet
↓ auto-detect
/comet-open --> /comet-design --> /comet-build --> /comet-verify --> /comet-archive
(OpenSpec) (Superpowers) (Superpowers) (Both) (OpenSpec)
/comet-hotfix (preset path, skips brainstorming)
open --> build --> verify --> archive
/comet-tweak (lightweight preset, chains OpenSpec)
open --> build --> verify --> archive
| Phase | Command | Owner | Artifacts |
|---|---|---|---|
| 1. Open | /comet-open | OpenSpec | proposal.md, design.md, tasks.md |
| 2. Deep Design | /comet-design | Superpowers | Design Doc, delta spec |
| 3. Plan & Build | /comet-build | Superpowers | Implementation plan, code commits |
| 4. Verify & Finish | /comet-verify | Both | Verification report, branch handling |
| 5. Archive | /comet-archive | OpenSpec | delta→main spec sync, archive |
Comet uses a decoupled state architecture with separate files
| File | Owner | Purpose |
|---|---|---|
.openspec.yaml | OpenSpec | Spec lifecycle, change metadata |
.comet.yaml | Comet | Workflow phase, execution mode, verification status |
.comet/run-state.json | Engine | Run identity and execution state (machine-owned) |
.comet/state-events.jsonl | Comet | Append-only state transition audit log |
.comet.yaml stores Classic workflow state and only keeps run_id as the link to the Engine Run. Machine-owned Engine
state lives in .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.
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 .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
build_command: null # Optional build command; may also live in repo-root config
verify_command: null # Optional verify command; may also live in repo-root config
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 .comet.yaml no longer contains skill; legacy Run fields in YAML are migrated to .comet/run-state.json.
Comet ensures agent execution reliability through automated state transitions:
Entry Verification — Each phase validates preconditions before execution
[HARD STOP] with actionable suggestions if validation failsAutomated State Transitions — comet-guard.mjs --apply updates .comet.yaml automatically
guard --applycomet-state.mjs is the agents' exclusive interface for state operationscomet-state.mjs internally for state managementSchema Validation — comet-yaml-validate.mjs ensures data integrity
direct_overridedesign_doc, plan, and handoff_context paths exist, plus handoff_hash formatBuild Decision Enforcement — Guard and state transitions both block skipped build choices
isolation must be branch or worktreebuild_mode must be selected before leaving buildbuild_pause: plan-ready is a recoverable pause after plan generation, not a build_modebuild_mode: direct requires direct_override: trueVerification Evidence — Guard enforces proof before phase advance
verify-pass transition requires verification_report pointing to an existing report filebranch_status must be handled before verify can passverification_report exists and branch_status=handled as hard prerequisitesArchive Automation — comet-archive.mjs handles the full archive flow in one command
archived: true--dry-run for previewAnti-drift Phase Guards — Phase awareness for long-context sessions
comet-phase-guard.md injects phase awareness, Skill invocation rules, and context recovery guidance
each turn across platformscomet-hook-guard.mjs hard-blocks file writes during open/design/archive phases on platforms that
support hooks, such as Claude Codeopenspec/*, docs/superpowers/*, .superpowers/*, .claude/*, and .comet/*your-project/
├── .comet/
│ └── config.yaml # Project-level global config (context_compression, review_mode, auto_transition)
├── .claude/skills/ # Platform skills dir (Comet + OpenSpec + Superpowers)
│ ├── comet/SKILL.md
│ │ └── scripts/
│ │ ├── comet-guard.mjs # Phase transition guard (--apply auto-updates state)
│ │ ├── comet-env.mjs # Script discovery helper
│ │ ├── comet-handoff.mjs # Design handoff (OpenSpec → Superpowers context tracing)
│ │ ├── comet-archive.mjs # One-command archive automation
│ │ ├── comet-yaml-validate.mjs # Schema validator
│ │ ├── comet-hook-guard.mjs # Phase write guard (PreToolUse hook)
│ │ └── comet-state.mjs # Unified state management (init/set/get/check/scale)
│ ├── comet-*/SKILL.md
│ ├── openspec-*/SKILL.md
│ └── brainstorming/SKILL.md
├── openspec/ # OpenSpec — WHAT
│ ├── config.yaml
│ └── changes/
│ └── <name>/
│ ├── .openspec.yaml # OpenSpec state
│ ├── .comet.yaml # Comet workflow state (Classic fields + run_id link)
│ ├── .comet/
│ │ ├── run-state.json # Engine Run state (machine-owned, auto-migrated)
│ │ └── state-events.jsonl # State transition audit log (append-only)
│ ├── proposal.md
│ ├── design.md
│ ├── specs/<capability>/spec.md
│ └── tasks.md
└── docs/superpowers/ # Superpowers — HOW
├── specs/ # Design documents
└── plans/ # Implementation plans
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.
| Mode | Behavior | Token Savings |
|---|---|---|
off | Full Spec excerpts in handoff context | Baseline |
beta | Design Doc + SHA256 hash references only | ~25–30% |
Key findings from benchmark testing:
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.
| Value | Behavior |
|---|---|
true | Auto-invoke the next skill after each phase (default) |
false | Pause after each phase; user manually triggers the next skill |
Three-layer configuration with precedence: COMET_AUTO_TRANSITION env var > .comet/config.yaml (project) > .comet.yaml (change).
See AUTO-TRANSITION.md for configuration details, workflow mapping, and FAQ.
See CONTRIBUTING.md | 中文版 for development setup, commit conventions, PR process, branch workflow, and guidance for adding platforms, skills, scripts, or changelog entries.
See CHANGELOG.md for version history and updates.
Track our development progress and upcoming features on the Comet Roadmap.
 DouYin (Recommended) |
 |
 |
FAQs
Agent Skill Harness For Turning Ideas Into Evaluated Workflows
The npm package @rpamis/comet receives a total of 1,574 weekly downloads. As such, @rpamis/comet popularity was classified as popular.
We found that @rpamis/comet demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Threat Research
/Security News
Cursor removed a malicious Claude Code 2.1.313 extension from its marketplace. Socket examines registry records and the initial claims about its distribution.
Security News
An OpenCode user faced harassment after reporting a free AI usage loophole, drawing a bitter backlash in a GitHub thread that has since been deleted.
Threat Research
/Security News
319 browser extensions installed by 13.4 million users hijack searches, capture queries, and collect referral payments from Yahoo and Bing.