OpenParable
Skip to content
← Back to skills

Versioning Policy

Development
versioning-policy

Versioning Policy is an Agent Skill for development published in the CommunityToolkit/Aspire repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Semver versioning rules for Squad SDK and CLI — prevents prerelease version incidents

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/CommunityToolkit/Aspire/blob/HEAD/examples/squad/CommunityToolkit.Aspire.Hosting.Squad.AppHost/dev-squad/.squad/templates/skills/versioning-policy/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/versioning-policy, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Context

Squad is a monorepo with two publishable npm packages (@bradygaster/squad-sdk and @bradygaster/squad-cli) managed via npm workspaces. Version mismatches and prerelease leaks have caused production incidents — most notably PR #640, where a -build.N prerelease version silently broke workspace dependency resolution.

This skill codifies the versioning rules every agent must follow.

1. Version Format

All packages use strict semver: MAJOR.MINOR.PATCH

  • ✅ 0.9.1, 1.0.0, 0.10.0
  • ❌ 0.9.1-build.4, 0.9.1-preview.1, 0.8.6.1-preview

No prerelease suffixes on dev or main branches — ever.

2. Prerelease Versions Are Ephemeral

The scripts/bump-build.mjs script creates -build.N versions (e.g., 0.9.1-build.4) for local development testing only.

Rules:

  • -build.N versions are created automatically during local npm run build
  • They are never committed to dev or main
  • The script skips itself in CI (CI=true or SKIP_BUILD_BUMP=1)
  • If you see a -build.N version in a PR diff, it is a bug — reject the PR

3. SDK and CLI Version Sync

Both @bradygaster/squad-sdk and @bradygaster/squad-cli MUST have the same version at all times. The root package.json version must also match.

bump-build.mjs enforces this by updating all three package.json files in lockstep (root + packages/squad-sdk + packages/squad-cli).

If versions diverge, workspace resolution silently breaks (see §4).

4. npm Workspace Semver Footgun

The CLI depends on the SDK via a workspace dependency with a semver range:

"@bradygaster/squad-sdk": ">=0.9.0"

Critical: Per the semver specification, >=0.9.0 does NOT match 0.9.1-build.4.

Semver prerelease versions (anything with a - suffix) are only matched by ranges that explicitly reference the same MAJOR.MINOR.PATCH base with a prerelease comparator. A bare >=0.9.0 range skips all prerelease versions.

What happens: When the local SDK has version 0.9.1-build.4, npm's workspace resolution fails to match the >=0.9.0 range. npm then silently installs a stale published version from the npm registry instead of using the local workspace link. The build succeeds but runs against old SDK code.

This is the root cause of the PR #640 incident, where workspace packages appeared linked but were actually running against stale registry versions.

5. Who Bumps Versions

Surgeon (Release Manager) owns all version bumps.

AgentMay modify version in package.json?
Surgeon✅ Yes — sole owner of version bumps
Any other agent❌ No — unless explicitly fixing a prerelease leak

If you discover a prerelease version committed to dev or main, you may fix it (revert to the clean release version) without Surgeon's approval. This is a safety escape hatch, not a license to manage versions.

6. Version Bump Lifecycle

┌─────────────────────────────────────────────────────────┐
│  Development phase                                      │
│  Versions stay at current release: 0.9.1                │
│  bump-build.mjs creates -build.N locally (not committed)│
├─────────────────────────────────────────────────────────┤
│  Pre-release testing                                    │
│  bump-build.mjs → 0.9.1-build.1, -build.2, ...         │
│  Local only. Never committed. Never pushed.             │
├─────────────────────────────────────────────────────────┤
│  Release                                                │
│  Surgeon bumps to next version (e.g., 0.9.2 or 0.10.0) │
│  Tags, publishes to npm registry                        │
├─────────────────────────────────────────────────────────┤
│  Post-release                                           │
│  Versions stay at the new release version (e.g., 0.9.2) │
│  Development continues on clean version                 │
└─────────────────────────────────────────────────────────┘

7. CI Enforcement

The prerelease-version-guard CI gate blocks any PR to dev or main that contains prerelease version strings in package.json files.

  • The gate scans all three package.json files for - in the version field
  • PRs with prerelease versions cannot merge until the version is cleaned
  • The skip-version-check label bypasses the gate — use only for the bump-build script's own PR (if applicable), and only with Surgeon's approval

8. Incident Reference — PR #640

PR #640 is the cautionary tale for this entire policy.

What happened: Prerelease versions (0.9.1-build.4) were committed to a branch. The workspace dependency >=0.9.0 failed to match the prerelease version per semver spec. npm silently installed a stale published SDK from the registry instead of linking the local workspace copy. Four PRs (#637–#640) attempted iterative patches before the root cause was identified.

Root cause: No versioning policy existed. Agents didn't know that prerelease versions break workspace resolution, or that only Surgeon should modify versions.

Resolution: This skill, the prerelease-version-guard CI gate, and the team decision to centralize version ownership under Surgeon.

Quick Reference

RuleSummary
FormatMAJOR.MINOR.PATCH — no prerelease on dev/main
Prerelease-build.N is local-only, never committed
SyncSDK + CLI + root must have identical versions
OwnershipSurgeon bumps versions; others don't touch them
CI gateprerelease-version-guard blocks prerelease PRs
Escape hatchAny agent may revert a prerelease leak to clean version
Footgun>=0.9.0 does NOT match 0.9.1-build.4 per semver