The OpenSpec integration in Comet serves as the foundational layer for managing AI-native development workflows. It bridges the gap between Comet's state machine and the underlying @fission-ai/openspec CLI, which handles the lifecycle of feature specifications, task tracking, and change verification.
The integration is primarily managed in src/core/openspec.ts, which handles the installation, configuration, and invocation of the OpenSpec CLI.
The system ensures that the OpenSpec CLI is available before attempting any operations. The isCommandAvailable() function checks for the openspec binary on the system PATH using platform-specific lookups (where for Windows, which for Unix) src/core/openspec.ts148-156
The ensureOpenSpecCli() function orchestrates the check and potential installation src/core/openspec.ts158-185 If the CLI is missing, Comet attempts an automatic installation via npm:
npm install -g @fission-ai/openspec@latest src/core/openspec.ts165npm install @fission-ai/openspec@latest src/core/openspec.ts166Comet forces OpenSpec to support a comprehensive set of workflows by defining ALL_OPENSPEC_WORKFLOWS. This list includes essential operations like propose, explore, new, continue, apply, ff, sync, archive, bulk-archive, verify, and onboard src/core/openspec.ts11-23
The integration uses a custom profile with delivery: both to ensure that OpenSpec generates both human-readable and machine-parsable artifacts src/core/openspec.ts44-54
installOpenSpec() Entry PointThis is the primary orchestrator for setting up OpenSpec for a given project or global environment.
| Step | Action | Description |
|---|---|---|
| 1 | ensureOpenSpecCli | Verifies or installs the @fission-ai/openspec package src/core/openspec.ts235 |
| 2 | Backup Config | Backs up existing config.json to prevent data loss src/core/openspec.ts102-130 |
| 3 | Write Config | Writes the ALL_WORKFLOWS_CONFIG to the default config directory src/core/openspec.ts117 |
| 4 | openspec init | Invokes the CLI with the target path and tool IDs via buildOpenSpecInitInvocation src/core/openspec.ts29-261 |
| 5 | Restore Config | Restores the original user configuration from backup src/core/openspec.ts132-146 |
Sources: src/core/openspec.ts11-23 src/core/openspec.ts29-42 src/core/openspec.ts102-146 src/core/openspec.ts230-265
To ensure Comet's requirements are met during openspec init without permanently overwriting a user's existing OpenSpec configuration, the codebase employs two distinct patterns.
Used for the default configuration file, this pattern provides atomic updates by creating a .comet-backup file src/core/openspec.ts104
config.json exists, copy it to config.json.comet-backup src/core/openspec.ts110For execution-time isolation, Comet can create a temporary configuration environment. The createOpenSpecAllWorkflowsEnv() function:
fs.mkdtempSync src/core/openspec.ts77config.json inside it src/core/openspec.ts81XDG_CONFIG_HOME pointed at the temp directory src/core/openspec.ts87Sources: src/core/openspec.ts76-94 src/core/openspec.ts102-146
OpenSpec requires precise path resolution to correctly deploy AI tool definitions (skills and commands).
The getOpenSpecDefaultConfigDir() function implements standard platform-specific paths for OpenSpec configuration:
process.env.APPDATA for %APPDATA%\openspec or defaults to ~/AppData/Roaming/openspec src/core/openspec.ts58-63process.env.XDG_CONFIG_HOME for $XDG_CONFIG_HOME/openspec or defaults to ~/.config/openspec src/core/openspec.ts65-69A specific edge case exists for the OpenCode platform. OpenSpec historically hardcodes its skill directory as .opencode in its AI_TOOLS definitions, whereas Comet and OpenCode expect configuration in ~/.config/opencode/ (represented by globalSkillsDir) src/core/openspec.ts187-195
The migrateOpenCodeOpenSpecPaths() function resolves this by physically moving files from the "wrong" directory to the "correct" global skills directory src/core/openspec.ts187-234 It migrates both skills and commands subdirectories src/core/openspec.ts197-200 and performs a best-effort cleanup of the legacy directory src/core/openspec.ts224-234
Sources: src/core/openspec.ts56-70 src/core/openspec.ts187-234
The following diagram illustrates the flow from a Comet init command through the OpenSpec integration layer to the external CLI.
Sources: src/core/openspec.ts29-42 src/core/openspec.ts102-130 src/core/openspec.ts158-172 src/core/openspec.ts230-265
This diagram bridges the natural language concepts of "Configuration" and "Installation" to the specific TypeScript entities in the codebase.
Sources: src/core/openspec.ts11-23 src/core/openspec.ts29-35 src/core/openspec.ts72-74 src/core/openspec.ts76-94 src/core/openspec.ts96-100 src/core/openspec.ts158-185 src/core/openspec.ts187-234
The following workflows are explicitly enabled during the openspec init phase to ensure full compatibility with the Comet Five-Phase Workflow:
| Workflow | Description |
|---|---|
propose | Used in Comet Open phase to define the initial intent. |
explore | For initial codebase exploration. |
new | Creating new specifications. |
continue | Resuming existing work. |
apply | Used to apply changes during the Build phase. |
verify | Critical for the Comet Verify phase to validate specs against implementation. |
archive | Moves completed changes to the permanent specification record. |
bulk-archive | Archiving multiple changes at once. |
ff | Fast-forwarding changes. |
sync | Synchronizing local specs with the codebase. |
onboard | Used for initial project context gathering. |
Sources: src/core/openspec.ts11-23
Refresh this wiki
This wiki was recently refreshed. Please wait 7 days to refresh again.