@rpamis/comet
Advanced tools
██████╗ ██████╗ ███╗ ███╗███████╗████████╗
██╔════╝██╔═══██╗████╗ ████║██╔════╝╚══██╔══╝
██║ ██║ ██║██╔████╔██║█████╗ ██║
██║ ██║ ██║██║╚██╔╝██║██╔══╝ ██║
╚██████╗╚██████╔╝██║ ╚═╝ ██║███████╗ ██║
╚═════╝ ╚═════╝ ╚═╝ ╚═╝╚══════╝ ╚═╝
Comet is a resumable long-running task workflow and Skill platform for coding.
It provides two independent requirements workflows: Native for strong models, powered only by Comet's own runtime, and Classic, which preserves the full OpenSpec + Superpowers phase-governance model. Comet also covers Skill creation, evaluation, and release.
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.7 — A new high-performance, native and recoverable Native workflow has been added. Native and Classic work independently through unified configuration, status, Guard, Dashboard, and Eval entry points. Eval alignment of experiments (16 tasks × 48 runs, selecting 41 pairs of samples that both passed) shows that total Token has decreased by 76.8%, Agent rounds have dropped by 57.4%, time consumption has shrunk by 47.4%, pass^3 reaches 87.5% (+12.5pp) and pass@3 is 100%. For more details, please refer to Native vs. 0.4.0 Classic Real Evaluation.
0.4.0-beta.1 — Upgrades Comet to a pure Node runtime without Bash/WSL and adds three core capabilities: compose any Skill through
/comet-any, evaluate any Skill throughcomet evalwith LangSmith integration, and visualize every change throughcomet dashboard.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.See the website Changelog for details.
Native and Classic are not lightweight and heavyweight tiers, and neither upgrades into the other. Native is for strong models that can plan and verify autonomously; Classic is for scenarios that benefit from a complete phased methodology and stronger constraints.
/comet-native uses a detailed brief, complete target specifications, phase checks, and recoverable archive to constrain outcomes while leaving planning, implementation, testing, and review methods to the model. It uses a configurable comet/ artifact root and remains fully separate from Classic. See the Native workflow guide./comet-classic./comet reads only the project's .comet/config.yaml and deterministically forwards to /comet-native or /comet-classic. It does not guess from task size or mix changes, state, or directories across workflows. comet resume-probe uses the same configuration to resume through the correct permanent entry point./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 to enter the project's configured Native or Classic workflow/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
A single global initialization makes /comet available through the selected hosts in every project:
comet init --scope global
cd your-project
# Invoke /comet in the host
The first /comet invocation in an unconfigured project snapshots the defaults from ~/.comet/config.yaml into the project's .comet/config.yaml and creates artifacts only inside that project. Later global-default changes do not rewrite activated projects. Hooks then recognize the project config and .comet/current-change.json; Hook events, comet status, and ordinary read-only resolution never initialize a project by themselves.
Run project initialization only when you want project-local copies of Skills, Rules, and Hooks, or explicit project overrides:
cd your-project
comet init
Interactive setup explains and offers Native, Classic, or both. Native is for strong models that can implement and verify autonomously; Classic is for tasks that need full Spec/TDD phase constraints; Both installs two independent entries while keeping /comet on Native by default. Non-interactive new projects default to Native, and project configuration is unified at .comet/config.yaml:
comet init --workflow classic
comet init --workflow both
Generated configuration comments follow the language selected during installation. Ambient Resume is a shared project setting for Native and Classic; disable the read-only probe with:
# Enables the read-only Ambient Resume probe for both Native and Classic
ambient_resume: false
If an agent must write project-local shared rules or team notes during a non-coding phase, declare those directories in the same project configuration. Paths are project-relative; paths outside the project retain the existing scope behavior, and this setting cannot bypass .comet or workflow artifact directories:
hook:
allow_paths:
- .agents/rules
- docs/team-notes
Classic-specific defaults live under classic:. The next comet init or comet update migrates legacy top-level fields:
classic:
artifact_layout: docs
language: en
context_compression: off
review_mode: standard
auto_transition: true
Native stores user-readable artifacts under docs/comet/ by default, while machine Runtime is fixed under the project-local .comet/runtime/native/. To use another project-relative artifact root, specify it explicitly; for example, this uses artifacts/comet/:
comet init --workflow native --root artifacts
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 Comet for selected AI coding platforms. Interactive setup selects Native, Classic, or both; new non-interactive projects default to self-contained Native, while projects with existing Classic state remain Classic. Pass --platform to initialize only that platform; unknown but valid platform ids are treated as project-scoped custom platforms installed under .<platform>/ with the selected workflow's skills, scripts, rules, and hooks. The workflows keep independent entries, state, artifacts, and Guards. Each platform installs one comet-workflow-guard Rule, and platforms with Hook support install only comet-hook-router.mjs. The Router uses .comet/current-change.json to send each write to exactly one current Native or Classic Guard. Only Classic installs OpenSpec and Superpowers; Native depends on no external Skill.
| 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) |
--platform <platform> | Initialize only this platform; project scope accepts custom platform ids |
--workflow <mode> | Workflows to initialize: native, classic, or both |
--root <path> | Project-relative Native artifact root; global scope stores it as a project default |
--codegraph <action> | Non-interactive project index action: explicitly choose init or skip |
--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 the configured default entry point and separate Native, Classic, and unmanaged OpenSpec sections. Native entries include phase, approval, verification, selection, and next-step data; Classic entries retain workflow, phase, runtime mode, current step, evidence, and recovery diagnostics.
| Option | Description |
|---|---|
--json | Output active changes with nextCommand, currentStep, and runtime data |
comet resume-probe [path] — Decide whether an active Comet workflow should resumeRead-only probe that resolves the configured default workflow and inspects only that side. It returns auto_resume, ask_user, out_of_scope, or none, and routes Native to /comet-native or Classic to /comet-classic. A malformed root configuration stops recovery instead of falling back or scanning the other workflow. comet init/update still merges a <comet-ambient-resume> managed block into AGENTS.md and CLAUDE.md while preserving user-authored rules.
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, CodeGraph indexes, 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. In a Git secondary worktree, it separately reports
the current worktree, primary worktree, and global fallback installation state. Ignored assets in the primary worktree
are inspected only for classification and are never executed across worktrees.
| Option | Description |
|---|---|
--json | Output structured diagnostics, including CodeGraph state and the effective runtime source |
--scope <scope> | Diagnose auto, project, or global scope (default: auto) |
--repair | Repair deterministic managed-install and state problems |
--yes | Use with --repair to authorize potentially expensive CodeGraph initialization, rebuild, or sync |
comet update [path] — Update Comet package and skillsRefreshes installed Comet skills in detected project/global targets. Pass --platform to refresh only that platform, including project-scoped custom platforms. A current-project refresh does not mutate any npm installation, whether global or project-local, by default; pass --self-update explicitly when the CLI should be upgraded too. Explicit --scope global deterministically uses the current-project asset scope, never opens the all-projects selector, and still does not update the npm package implicitly. Self-update compares full semver values, including prereleases, refuses downgrades, and validates the candidate package's version, Workflow command, and Native command in isolation before installation. A failed install attempts to restore the exact installed version.
| Option | Description |
|---|---|
--json | Output npm and skill update results as JSON |
--language <lang> | Override detected skill language (en, zh) |
--platform <platform> | Refresh only this platform; project scope accepts custom platform ids |
--scope <scope> | Update only the global or project install scope |
--current-project | Refresh only the current project |
--all-projects | Refresh all registered project installations |
--self-update | Explicitly update the Comet npm package first |
--skip-self-update | Explicitly skip Comet npm package self-update |
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 primary path is evaluating a local Skill that you already own. You do not need to run
/comet-any first or create comet/eval.yaml:
comet eval ./my-skill --collect
comet eval ./my-skill --html
comet eval ./my-skill --quick --html
--collect performs static discovery and configuration checks without starting an Agent, Docker, plugins,
credential checks, or network requests. A normal run generates and caches 2–4 tasks when the Skill has no
comet/eval.yaml; --quick uses the fixed generic-skill-smoke task. The report path is printed by the command
and is written under .comet/eval/runs/<experiment-id>/ in the Skill or the project passed with --project.
If the Skill contains comet/eval.yaml, passing its directory discovers it automatically. You can also pass a
manifest or SKILL.md directly:
comet eval ./my-skill/comet/eval.yaml --collect
comet eval ./my-skill/SKILL.md --html
Configure the main Agent, model, and API URL directly. LLM-as-Judge has an independent Agent, model, API URL, and credential boundary:
execution:
agent: codex
model: subject-model
baseUrl: https://subject.example/v1
judge:
agent: claude-code
model: judge-model
baseUrl: https://judge.example/v1
/comet-any may still produce a compatible manifest, but it is an optional Skill producer, never a prerequisite
for comet eval.
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 select the LangSmith suite through the same comet eval entry point:
comet eval ./my-skill --suite langsmith --html
--suite defaults to local. With langsmith, the CLI starts the LangSmith runner, prints Suite: langsmith in its
launch details, and writes reports under the project's .comet/eval/runs/. 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 --collect, then comet eval ./my-skill --htmlcomet eval ./my-skill --quick --html/comet-any output: pass its directory for automatic manifest discovery, or pass comet/eval.yaml directlycomet eval ./my-skill --suite langsmith --htmlFor 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 an optional Skill creation and composition 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 34 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/ | WorkBuddy | .workbuddy/ |
| 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/ | CoStrict | .cospec/ |
comet init installs skills for the selected workflow. Native depends only on Comet-owned skills; Classic additionally installs OpenSpec and Superpowers.
| Skill | Description |
|---|---|
/comet | Shared entry — routes to the configured Native or Classic workflow from .comet/config.yaml |
/comet-native | Permanent Native entry — self-contained, recoverable Shape, Build, Verify, and Archive |
/comet-classic | Permanent Classic entry — the five-phase OpenSpec + Superpowers workflow |
/comet-open | Classic phase 1: Open a change (proposal, design, task breakdown) |
/comet-design | Classic phase 2: Deep design (brainstorming, Design Doc) |
/comet-build | Classic phase 3: Plan and build (implementation plan, code commits) |
/comet-verify | Classic phase 4: Verify and finish (testing, verification report) |
/comet-archive | Classic phase 5: Archive (delta spec sync, status annotation) |
/comet-hotfix | Classic preset: Quick bug fix |
/comet-tweak | Classic preset: OpenSpec-chained medium change |
/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-router.mjs | The platform's only Hook entry — routes by current ownership to one workflow Guard |
comet-hook-guard.mjs | Classic Guard launcher — calls Classic runtime when selected by the Router |
comet-native-runtime.mjs | Native state, checks, archive, and recovery runtime |
comet-native-hook-guard.mjs | Native Guard launcher — calls Native runtime when selected by the Router |
Both Native and Classic runtimes are generated from TypeScript and run through node on every platform. Native does
not depend on OpenSpec, Superpowers, Bash, Git Bash, or WSL.
/comet-native uses Shape → Build → Verify → Archive. Shape owns clarification, the brief, complete target specs, and
user approval; the agent chooses its own planning and implementation methods. User-readable state, specifications, and
verification material live under docs/comet/ by default; machine Runtime, locks, transactions, and recovery data live
under the project-local .comet/runtime/native/.
/comet-native (or /comet when default_workflow: native)
Shape ──confirm requirements──> Build ──Builder handoff──> Verify ──pass──> Archive
^ │
└────────── fail ──────────────┘
| Phase | Main work | Required result |
|---|---|---|
| Shape | Inspect the environment, clarify in rounds, and write the brief plus complete target specs | No blocking questions; the user confirms the current outcome |
| Build | The agent plans, implements, self-tests, and submits a concise Builder handoff | Every acceptance item is addressed; ordinary source writes occur in Build |
| Verify | Runtime runs necessary checks and dispatches a fresh read-only Verifier | Pass advances to Archive; failure returns to Build with specific gaps |
| Archive | Sync complete target specs and move the change without rerunning Build or Verify checks | The recoverable archive transaction commits |
Shape supports clarification_mode: sequential and clarification_mode: batch. Sequential asks one upstream question per round; Batch asks every currently answerable question whose prerequisites are settled and is the default for new projects. In both modes, the agent investigates discoverable facts and writes user decisions back into the brief and complete target specs.
| File or directory | Purpose |
|---|---|
.comet/config.yaml | Select workflows, artifact root, language, clarification mode, and project-local Hook write allow paths |
.comet/current-change.json | Shared Native/Classic ownership; each write routes to one workflow |
docs/comet/changes/<name>/comet-state.yaml | Portable phase, Loop, acceptance results, blockers, and next action |
docs/comet/changes/<name>/brief.md | Outcome, scope, non-goals, examples, constraints, decisions, and open questions |
docs/comet/changes/<name>/specs/ | Complete target behavior for each capability after archive |
docs/comet/changes/<name>/verification.md | Human-readable Runtime checks, acceptance results, risks, and conclusion |
.comet/runtime/native/changes/<name>/ | Local state.json execution overlay and on-demand logs; rebuildable from portable state |
.comet/runtime/native/locks/ / transactions/ | Project-local locks and recoverable transactions |
docs/comet/specs/ / archive/ | Applied specs, archived changes, and user-readable verification material |
Native can keep multiple active changes at the same time. comet status lists the candidates, while .comet/current-change.json selects ownership for the current request; it does not limit the project to one change. Missing, stale, or ambiguous selection stops resume and writes for an explicit choice instead of guessing another change or switching to Classic.
Runtime owns comet-state.yaml and machine state under .comet/runtime/native/. Requirement edits return the change to Shape; implementation edits return it to Build before a fresh Verifier reviews the candidate. Do not hand-edit state to skip a phase.
comet-state.yaml keeps the stable phase, Loop, and next action. Interrupted local work reruns only necessary checks, not Shape, Build, or an already completed matching check./comet-classic (or /comet when default_workflow: classic)
↓
/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 |
Classic uses a decoupled state architecture with separate files:
| File | Owner | Purpose |
|---|---|---|
.openspec.yaml | OpenSpec | Spec lifecycle, change metadata |
<classic-change-dir>/.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 |
Each change-level .comet.yaml stores Classic workflow state and only keeps run_id as the link to the Engine Run.
<classic-change-dir> is resolved from the project's classic.artifact_layout; use comet classic root show to inspect the current OpenSpec root.
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: current | branch | worktree
bound_branch: null # Git branch bound by current/branch/worktree isolation; branch drift blocks progress
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.
The first six items below describe Classic phase automation; the final item covers the Router/Rule boundary shared by Native and Classic:
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 current, branch, or worktreeisolation: current, branch, and worktree bind the current Git branch, and later entry checks block accidental branch driftbuild_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-workflow-guard, resolves enabled, default, and current ownership
from .comet/current-change.json, and applies only one phase modelcomet-hook-router.mjs; one write reaches at most one Guard,
and ambiguous or stale selection fails closeddocs/comet/)your-project/
├── .comet/
│ ├── config.yaml # Shared config and Native artifact_root
│ ├── current-change.json # Optional current ownership shared by Native and Classic
│ └── runtime/native/ # Git-ignored Native machine Runtime
│ ├── changes/<name>/ # Local state.json and on-demand logs
│ ├── locks/ # Project-local locks
│ └── transactions/ # Recoverable transactions
├── .claude/skills/ # Claude Code shown as the platform example
│ ├── comet/SKILL.md # Configuration-driven shared entry
│ └── comet-native/
│ ├── SKILL.md # Permanent Native entry
│ ├── reference/ # Artifact, command, and recovery contracts
│ └── scripts/ # Native runtime and Guard launcher
└── docs/comet/ # native.artifact_root: docs
├── specs/<capability>/spec.md # Archived canonical specs
├── changes/<name>/
│ ├── comet-state.yaml # Native change state
│ ├── brief.md # Outcome, scope, decisions, and acceptance
│ ├── specs/<capability>/spec.md # Complete target specification
│ ├── verification.md # Verification report
└── archive/YYYY-MM-DD-<name>/ # Archived changes
your-project/
├── .comet/
│ └── config.yaml # Shared project config (workflows, Ambient Resume, language, Classic defaults)
├── .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-router.mjs # The platform's only Hook entry (routes the current workflow Guard)
│ │ ├── comet-hook-guard.mjs # Classic Guard (not installed as a separate platform Hook)
│ │ └── comet-state.mjs # Unified state management (init/set/get/check/scale)
│ ├── comet-*/SKILL.md
│ ├── openspec-*/SKILL.md
│ └── brainstorming/SKILL.md
└── docs/
├── openspec/ # OpenSpec — WHAT (classic.artifact_layout: docs)
│ ├── config.yaml
│ ├── specs/<capability>/spec.md # Main specs after archive
│ └── changes/
│ ├── archive/YYYY-MM-DD-<name>/ # Archived 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
└── superpowers/ # Superpowers — HOW
├── specs/ # Design documents
├── plans/ # Implementation plans
└── reports/ # Verification reports
New Classic and dual-workflow projects default to classic.artifact_layout: docs. Projects that retain the legacy layout keep the OpenSpec root at repository-level openspec/, while Superpowers artifacts remain under docs/superpowers/. Use comet classic root show to inspect the current layout. To migrate, run comet classic root move docs --dry-run first and then apply the returned plan with --apply; do not edit the configuration field by itself.
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 context_compression: beta under the classic: block in .comet/config.yaml.
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 > classic.auto_transition in
.comet/config.yaml (project) > change .comet.yaml.
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,319 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.
Research
/Security News
A Twitch browser extension on Chrome and Firefox forwards users’ live OAuth session tokens through proxies controlled by a Russian bot service.
Security News
Anthropic found biased reasoning and recklessness drove Claude Mythos 5 to publish malware on PyPI and compromise a security vendor.
Research
/Security News
Malicious Chrome and Firefox extensions target Axiom Trade and Padre users, stealing session tokens and wallet data.