API Versioning Policy

Updated: 2025-12-27

Calvin follows Semantic Versioning for the CLI and crate. There are two versioning concerns:

1. Source format version: the .promptpack/ schema (frontmatter + directory conventions)
2. Adapter output version: per-platform output formats (Claude/Cursor/VS Code/Antigravity/Codex)

Source Format Version

The current source format version is 1.0.

$ calvin version
Calvin v0.6.0
Source Format: 1.0

Current Behavior (Honest State)

• Source format version is currently fixed to 1.0 in the CLI output.
• A [format] section in config.toml is reserved for future use, but Calvin does not currently enforce a user-declared format version.

Adapter Output Versions

calvin version also reports adapter output versions (currently v1 for all adapters):

$ calvin version
Adapters:
  - ClaudeCode   v1
  - Cursor       v1
  - VSCode       v1
  - Antigravity  v1
  - Codex        v1

Current Behavior (Honest State)

• Adapter versions are informational (Calvin does not currently negotiate/auto-detect IDE versions).
• IDE version detection and richer adapter version metadata are planned and tracked in TODO.md (TD-18).

Migration

Calvin includes a hidden/debug calvin migrate command. Today it is used for lockfile location migration (legacy .promptpack/.calvin.lock → ./calvin.lock).

Other migration dimensions (format migration, adapter migration) are reserved for future work.