Versioning

Actions and workflow templates are versioned together via the VERSION file at the repo root (semver). The version is embedded into the CLI at compile time.

Version strategy

Tag type	Example	Purpose
Immutable semver	`v1.2.3`	Permanent, never moves
Floating major	`v1`	Always points to latest `v1.x.y`

Consuming repos pin to the floating major tag (@v1), so they automatically get patch and minor updates.

Patch auto-bump

The version-bump.yml workflow automatically bumps the patch version when any of these paths change on main:

.github/actions/
workflow-templates/
.github/workflows/bucky-*.yml

It then:

Bumps the patch version in VERSION
Creates/moves the immutable semver tag (v1.2.3)
Creates/moves the floating major tag (v1)
Creates a GitHub Release with pre-built CLI binaries

Manual releases

For major or minor version bumps:

Edit VERSION directly (e.g., 1.0.43 → 2.0.0 or 1.1.0)
Push to main
The release.yml workflow creates tags and a release with CLI binaries

CLI binaries

Both release workflows call build-cli.yml (reusable workflow) which cross-compiles for:

Platform	Architecture	Binary name
macOS	ARM64	`bucky-aarch64-apple-darwin`
macOS	x86_64	`bucky-x86_64-apple-darwin`
Linux	ARM64	`bucky-aarch64-unknown-linux-gnu`
Linux	x86_64	`bucky-x86_64-unknown-linux-gnu`

Binaries are uploaded as release assets.

Major version bumps

On a major version bump (e.g., v1 → v2):

Update VERSION to the new major version
Update composite action refs inside reusable workflows (.github/workflows/bucky-*.yml) from @v1 to @v2
Update docs and consumer references

Plugin versioning

Plugins with skills use the version field in .claude-plugin/plugin.json. Bump the patch version when modifying any file in a skill-based plugin. Do not bump for metadata-only changes to plugin.json itself.