comet init is the setup and onboarding entry for Comet.
It detects the current project environment, installs required Skills and runtime assets, and writes the default workflow used by /comet.
Basic usage
Common options:
Native and Classic initialization
Interactive initialization supports Native, Classic, or both at project and global scope. At project scope, non-interactive initialization chooses the default workflow in this order:
- Read valid
.comet/config.yaml first. It is the source of truth.
- If
--workflow native|classic|both is provided, honor the explicit choice. Under both, /comet defaults to Native.
- If workflow config is missing but Classic
.comet.yaml state or legacy Ambient Resume evidence exists, keep Classic.
- In all other cases, default to Native. Existing code,
openspec/, or docs/superpowers/ does not change that default.
Native initialization installs Comet-owned Skills and runtime, one shared workflow Rule, and one Hook Router where the platform supports Hooks. It creates:
It does not install OpenSpec, Superpowers, or CodeGraph and does not create Classic/OpenSpec changes or docs/superpowers/. The shared Rule and Router use .comet/current-change.json to send each write to one workflow Guard, never both Native and Classic. Classic initialization preserves its complete dependency set and phase governance.
Comet writes and activates .comet/config.yaml only after required assets succeed on every selected platform and any existing /comet entry is compatible with the bundled routing contract. If an incompatible custom /comet entry exists, initialization preserves it and reports the run as incomplete. Re-run comet init --workflow native --overwrite only when you intend to replace that custom entry.
At global scope, --workflow selects which capabilities are installed globally. On the first explicit /comet invocation in an unconfigured project, Comet snapshots those defaults into the project’s .comet/config.yaml; later global-default changes do not rewrite an activated project. Use project initialization when you want project-local Skill, Rule, and Hook copies or explicit overrides. Non-interactive global initialization keeps Classic as the default when --workflow is omitted. --root remains valid only for project-scope Native initialization.
When a project defines several platforms but this run should install or repair only one, pass --platform:
The value may be a Comet-supported platform ID or a custom platform defined by the project. With the option, initialization touches only that target. Without it, Comet continues to use automatic platform detection and the existing fallback rules.
Non-interactive project initialization can also use --codegraph init to create or refresh the CodeGraph index, or --codegraph skip to skip it explicitly. Ordinary diagnostics never mutate the index. Run comet doctor first when you need to inspect its current state.
Project installation registry
Starting in 0.4.0-beta.4, a successful project-scope installation is recorded in a user-level project registry. The registry stores only the project location and installed platforms needed for later updates and uninstallation. It neither copies project content nor uploads usage data.
After registration, interactive comet update and comet uninstall can offer the current project or every registered project. --json and explicit --current-project remain limited to the current project, and comet uninstall --force does too. Batch operations require an explicit --all-projects. Automation should pass one of these scope options instead of relying on terminal detection.
Installation mode: copy or symlink
Classic or both initialization asks for an installation mode after platform selection, including at global scope. Native-only initialization always uses Copy. Project-scope Native avoids .comet/skills/; Native change state stays under <artifact-root>/comet/, while shared project configuration and selection live under .comet/. Symlink mode was added in 0.4.0-beta.1:
- Copy: copy an independent set of Skill files to each platform.
- Symlink: create links in each platform directory that point to the shared
.comet/skills/ store, saving space and making one update apply everywhere.
If a platform already has its own skills/ directory, Comet preserves it and adds links only for Comet-managed Skills. Existing local and third-party Skills are not deleted or replaced when you choose Symlink.
See Supported platforms · Installation mode for details and guidance.
Shared project configuration merge
Native and Classic now share .comet/config.yaml. Initialization merges managed fields for the enabled workflows:
- preserves existing values such as
native.artifact_root and classic.review_mode;
- adds defaults for missing managed fields;
- refreshes comments to match the current version;
- preserves extra custom fields;
- keeps shared
default_workflow, workflows, and ambient_resume semantics separate from native.* and classic.* settings;
- fails closed when workflow configuration cannot be parsed safely instead of guessing defaults and overwriting it.
The terminal reports Project config merged (.comet/config.yaml).
OpenSpec CLI installation scope
OpenSpec CLI is a cross-project tool used by Classic. Even for project-scope Classic initialization, Comet installs or upgrades OpenSpec CLI globally, so this dependency does not create a project node_modules/ directory. Native neither checks nor installs it.
Check after initialization
If platform directories, Skill files, or scripts are missing, repair them before starting /comet.
Reading the installation summary
comet init and comet update report each component’s installation status per platform. Skill and script copies look like this:
Since 0.4.0-beta.1,
a partially failed installation is no longer reported as success. When any file
copy fails on a platform, that platform is marked failed with a failure count.
Missing comet-hook-guard.mjs breaks Classic phase checks; a missing Native entry
point or runtime likewise prevents project default configuration from being written. Re-run
comet init or comet update to install the missing files.
