agentleFS
Sign inStart free
GitHubKnown publishergithub/squad/packages/squad-cli/templates/skills/versioning-policy/SKILL.md

versioning-policy

Skill3.4k starsChanged 2 months agoMITView on GitHub

SemVer rules for Squad's stable, preview, insider, and local package versions

  • Installs packages

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use the workspace-aware version command:

    line 37
  2. Distinctive:

    Never edit only one package version.

    line 43
  3. Very specific:

    Never commit a -build.N version.

    line 71
  4. Distinctive:

    If a build changes manifests locally, restore the intended release source versions before committing.

    line 73

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
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

UseVersionCommitted branch
Stable releaseMAJOR.MINOR.PATCHmain, and briefly dev during promotion
Preview releaseMAJOR.MINOR.PATCH-preview.Ndev
Insider snapshotMAJOR.MINOR.PATCH-insider.NGenerated by the insider workflow
Local buildMAJOR.MINOR.PATCH-build.NNever 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.json
  • packages/squad-sdk/package.json
  • packages/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.N version.
  • The script skips itself when CI=true or SKIP_BUILD_BUMP=1.
  • If a build changes manifests locally, restore the intended release source versions before committing.

5. Release lifecycle

  1. On a release-preparation branch from dev, set the next X.Y.Z-preview.N version and matching SDK dependency floor.
  2. Merge to dev, wait for CI, and dispatch squad-release.yml from dev.
  3. Repeat with a new immutable preview version when another candidate is needed.
  4. Dispatch squad-insider-publish.yml whenever an on-demand development snapshot is needed; it computes the next immutable X.Y.Z-insider.N.
  5. Prepare stable X.Y.Z and its stable SDK dependency floor on dev.
  6. Dispatch squad-promote.yml; it sanitizes dev, pushes main, and explicitly dispatches the stable release.
  7. 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 preview or insider identifiers;
  • 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

RuleSummary
InsiderThe workflow generates X.Y.Z-insider.N from the stable base version
PreviewCommit X.Y.Z-preview.N to dev for an on-demand prerelease
StableOnly X.Y.Z may release from main
SyncRoot, SDK, CLI, and lockfile workspace versions must match
DependencyPreview CLI range and lockfile entry must be >=VERSION
Local build-build.N is local-only and never committed
OwnershipThe current Release Manager owns planned release version changes

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free