versioning-policy
SemVer rules for Squad's stable, preview, insider, and local package versions
- License 许可
- MIT
- 所属仓库
- github/squad
- 最近更新
- 2026-11-15
- Stars
- ★ 3.4k
- Forks
- 520
01 前言 Front Matter
- name
- versioning-policy
- domain
- release, versioning, npm, CI
- source
- earned (PR #640 workspace resolution incident and automated release channels)
- confidence
- high
- description
- SemVer rules for Squad's stable, preview, insider, and local package versions
03 SKILL.md 正文
Context
Squad publishes @bradygaster/squad-sdk and
@bradygaster/squad-cli from one npm workspace. Their versions and the root
version move together. A mismatched prerelease dependency can make npm silently
resolve an older registry SDK instead of the local workspace.
1. Supported versions
| Use | Version | Committed branch |
|---|---|---|
| Stable release | MAJOR.MINOR.PATCH |
main, and briefly dev during promotion |
| Preview release | MAJOR.MINOR.PATCH-preview.N |
dev |
| Insider snapshot | MAJOR.MINOR.PATCH-insider.N |
Generated by the insider workflow |
| Local build | MAJOR.MINOR.PATCH-build.N |
Never committed |
preview is a release channel, not a branch. Stable promotion merges a
sanitized release tree directly from dev to main.
2. Package versions stay in lockstep
These versions must always be identical:
package.jsonpackages/squad-sdk/package.jsonpackages/squad-cli/package.json- the corresponding workspace entries in
package-lock.json
Use the workspace-aware version command:
npm version "$VERSION" --workspaces --include-workspace-root --no-git-tag-version
Never edit only one package version.
3. Prerelease workspace dependency rule
The CLI depends on the SDK through a SemVer range. SemVer deliberately excludes
prereleases unless the comparator names a prerelease with the same base version.
For example, >=0.13.0 does not match 0.14.0-preview.1.
For every committed preview version, set both the CLI manifest and lockfile dependency floor to that exact preview:
npm pkg set "dependencies.@bradygaster/squad-sdk=>=$VERSION" \
--workspace @bradygaster/squad-cli
npm install --package-lock-only
For VERSION=0.14.0-preview.1, the required range is
>=0.14.0-preview.1. Before stable promotion, change the version and floor to
0.14.0 / >=0.14.0; never leave a prerelease floor in a stable release.
This rule prevents the PR #640 failure mode, where the build succeeded against a stale published SDK rather than the workspace SDK.
4. Local build versions are ephemeral
scripts/bump-build.mjs may create -build.N versions for local development.
- Never commit a
-build.Nversion. - The script skips itself when
CI=trueorSKIP_BUILD_BUMP=1. - If a build changes manifests locally, restore the intended release source versions before committing.
5. Release lifecycle
- On a release-preparation branch from
dev, set the nextX.Y.Z-preview.Nversion and matching SDK dependency floor. - Merge to
dev, wait for CI, and dispatchsquad-release.ymlfromdev. - Repeat with a new immutable preview version when another candidate is needed.
- Dispatch
squad-insider-publish.ymlwhenever an on-demand development snapshot is needed; it computes the next immutableX.Y.Z-insider.N. - Prepare stable
X.Y.Zand its stable SDK dependency floor ondev. - Dispatch
squad-promote.yml; it sanitizesdev, pushesmain, and explicitly dispatches the stable release. - Open the next preview-version PR for continued development.
A preview such as 0.14.0-preview.1 is never renamed or converted in place.
Stable 0.14.0 is a separate immutable package version and GitHub tag.
6. Ownership
The current Release Manager owns release version changes. Other agents may update
versions only when explicitly assigned release work or when reverting an
accidentally committed local -build.N version.
7. CI enforcement
CI verifies:
- root, SDK, and CLI versions match;
- package-lock workspace versions match;
- committed prereleases use approved
previeworinsideridentifiers; - a preview CLI dependency and lockfile entry equal
>=VERSION; - stable source does not retain a prerelease dependency floor; and
- workspace packages resolve through local links rather than stale registry packages.
Release workflows repeat the dependency checks before creating a tag or publishing.
Quick reference
| Rule | Summary |
|---|---|
| Insider | The workflow generates X.Y.Z-insider.N from the stable base version |
| Preview | Commit X.Y.Z-preview.N to dev for an on-demand prerelease |
| Stable | Only X.Y.Z may release from main |
| Sync | Root, SDK, CLI, and lockfile workspace versions must match |
| Dependency | Preview CLI range and lockfile entry must be >=VERSION |
| Local build | -build.N is local-only and never committed |
| Ownership | The current Release Manager owns planned release version changes |
04 同仓库更多 Skills
windows-compatibility
Cross-platform path handling and command patterns
versioning-policy
SemVer rules for Squad's stable, preview, insider, and local package versions
tiered-memory
Three-tier agent memory model (hot/cold/wiki) for context reduction per spawn
test-discipline
Design assertions that prove the actual contract and fail on realistic regressions
squad
Squad's command catalog and interactive menu. Invoke via /squad (slash command) or natural language ("squad commands", "what can squad do", "show me squad options"). Presents categorized operations (Install & Upgrade, Team Management, Issues & PRs, Plugins & Skills, Model & Cost, Sessions & State) as an interactive picker. Routes to the right squad CLI command or the Squad coordinator agent.
squad-version-check
Internals of how @bradygaster/squad-cli stamps its version, how `squad upgrade` works (what it preserves vs overwrites), and how to probe the npm registry for the latest version from a coordinator prompt.