Versioning

Every bundle version is identified by a semantic version string. This page covers the version format, what each number means for text-based bundles, and how version resolution works.

Version Format

Version strings follow Semantic Versioning: MAJOR.MINOR.PATCH with an optional pre-release tag.

Version pattern

MAJOR.MINOR.PATCH[-tag]

All three numeric components are required. The pre-release tag is optional.

Version	Valid	Why
`1.0.0`	Yes	Standard three-part version
`2.1.0-beta`	Yes	Pre-release tag
`1.0.0-alpha1`	Yes	Alphanumeric pre-release tag
`0.1.0`	Yes	Initial development version
`v1.0.0`	No	No `v` prefix allowed
`1.0`	No	All three parts are required
`1.0.0-beta.1`	No	Dots are not allowed in the pre-release tag
`1.0.0+build`	No	Build metadata is not supported

What the Numbers Mean

Bundles contain text assets — prompts, configs, agent specs — not code libraries. There is no “public API” in the traditional sense. Instead, think of version numbers in terms of what consumers relying on your bundle would need to change.

Component	Bump when…	Consumer impact
MAJOR	You restructure the bundle, rename or remove assets, or change content in ways that break existing consumers	Consumers must review and adapt their usage
MINOR	You add new assets, expand capabilities, or add content to existing assets without changing what already exists	Consumers can upgrade without changes
PATCH	You fix typos, clarify wording, correct errors, or make non-functional improvements to existing content	Drop-in replacement, no consumer action needed

Using a hypothetical acme/code-review bundle:

Patch 1.0.0 → 1.0.1 — Fixed a typo in prompts/review.md.
Minor 1.0.0 → 1.1.0 — Added a new asset prompts/security-review.md.
Major 1.0.0 → 2.0.0 — Renamed prompts/review.md to prompts/code-review.md and restructured the prompt template format.

Rewriting a prompt’s instructions without changing its path? MINOR — the behavior changed, but consumers using the same logical path still work.
Changing an asset’s asset_type label? MAJOR — consumers filtering by type would break.
Adding optional sections to a config template? MINOR — existing consumers are unaffected.

Pre-release Versions

Append a hyphen and an alphanumeric tag to mark a version as pre-release: 1.0.0-alpha, 2.0.0-beta, 3.0.0-rc1. Tags must be alphanumeric only — no dots, no hyphens within the tag.

Pre-release versions are treated like any other published version. They appear in version listings and can be resolved by exact version string.

Version Resolution

When you resolve a bundle, the platform selects a version using one of two strategies:

Request	Behavior
Version specified	Exact match. Returns that version or `404` if not found.
Version omitted	Returns the latest published (non-yanked) version by creation time.

Resolve examples

# Exact version
musher load acme/code-review:1.2.0

# Latest published version
musher load acme/code-review

Once a version is published, its contents never change. Resolving version 1.2.0 today returns the same manifest it will return next year. See Bundle Structure for the full immutability contract.

Yanked versions are excluded from latest resolution but remain accessible by exact version for audit purposes. See Publishing for yank semantics.

Choosing Your Next Version

When publishing a new version, ask yourself one question: will this change break consumers who depend on the current version?

Did you remove, rename, or restructure assets? Bump MAJOR.
Did you add new assets or expand existing ones? Bump MINOR.
Did you only fix typos, clarify wording, or make cosmetic changes? Bump PATCH.
Is this an early preview? Use a pre-release tag like 0.1.0-alpha or 1.0.0-rc1.