Index of every page on this site: llms.txt
All skills
microsoft avatar

/squad-version-check

@a9de923
by microsoftmicrosoft/waza1.5k stars
104
Run it yourself

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.

  • 1 file
  • 6.1 KB
  • Updated last month
  • GitHub
Use this Skill: https://skilld.dev/gh/microsoft/waza/squad-version-check

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈56 tokens for metadata: the name and description. ≈1.5k when used: this file.

Description uses 2.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈226 characters, or 2.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

SKILL: Squad CLI Internals — Version Stamping & Upgrade Mechanics

Confidence: medium Discovered by: repository investigation Date: 2026-05-26 Validated in: Issue #1173 recon (bradygaster/squad)


What This Skill Covers

Reusable knowledge about how @bradygaster/squad-cli stamps its version into squad.agent.md, how squad upgrade works, what it preserves vs. overwrites, and how to probe the npm registry for the latest version from a coordinator prompt.


Package & Registry Facts

  • Package name: @bradygaster/squad-cli
  • Registry: npm (public)
  • CLI binary: squad (registered via package.json#bin.squad)
  • Node version requirement: Node ≥22.5.0 (ESM-only codebase)

Version Stamping Mechanism

Source file: dist/cli/core/version.js

Three functions:

getPackageVersion()

Walks up from the compiled JS file to find package.json. Returns pkg.version. Works from both dist/cli/core/version.js and a bundled root cli.js. Returns '0.0.0' as fallback if not found.

stampVersion(filePath, version)

Mutates squad.agent.md in three places:

  1. HTML comment: <!-- version: {version} --> (must be on the line immediately after frontmatter ---)
  2. Identity line: - **Version:** {version}
  3. Greeting instruction: backtick-quoted `Squad v{version}`

Called by: both init and upgrade — after copying the template to the destination.

readInstalledVersion(filePath)

Reads the stamped version back from squad.agent.md:

  1. First tries HTML comment format: /<!-- version: ([0-9.]+(?:-[a-z]+(?:\.\d+)?)?) -->/
  2. Falls back to old frontmatter format: /^version:\s*"([^"]+)"/m
  3. Returns '0.0.0' on any error

squad upgrade Behavior

Source file: dist/cli/core/upgrade.js

What gets overwritten:

  • squad.agent.md — full overwrite from template, then stampVersion()
  • Files with overwriteOnUpgrade: true in TEMPLATE_MANIFEST: casting JSON files, template .md files, copilot-instructions.md (if @copilot enabled)
  • GitHub Actions workflows — from templates/workflows/; non-npm projects get type-aware stubs
  • Runs runMigrations() after file copy

What is PRESERVED:

  • team.md, routing.md, decisions.md, ceremonies.md (user-owned)
  • agents/*/history.md (individual agent memory)
  • .squad/config.json — never touched; stateBackend survives intact
  • User-added files not in TEMPLATE_MANIFEST

Self-upgrade path (selfUpgradeCli()):

Detects npm/pnpm/yarn via npm_execpath and npm_config_user_agent. Runs:

  • npm: npm install -g @bradygaster/squad-cli@latest
  • pnpm: pnpm add -g @bradygaster/squad-cli@latest
  • yarn: yarn global add @bradygaster/squad-cli@latest Use @insider tag for insider builds.

compareSemver(a, b) utility (in upgrade.js):

Returns -1/0/1. Handles pre-release: strips pre-release for base comparison, then treats pre-release as less than release (e.g., 0.9.5-insider.1 < 0.9.5). Can be ported directly if needed in prompt logic.


.squad/config.json — What It Holds

{
  "version": 1,
  "stateBackend": "worktree"
}

Other optional fields added by the coordinator at runtime:

  • defaultModel — global model override for all agent spawns
  • agentModelOverrides.{agentName} — per-agent model override

The file is read-only from the upgrade path's perspective. Only the coordinator writes to it (for model preferences).


Version-Check Probe (npm Registry)

Use this one-liner from inside a coordinator prompt to fetch dist-tags:

npm view @bradygaster/squad-cli dist-tags --json
  • Timeout: 5 seconds. If no response within 5 seconds, abandon and show normal greeting.
  • On success: extract dist-tags[channel] (e.g., dist-tags["insider"]).
  • On any error (network failure, registry unreachable, parse error): show normal greeting.

Upstream OS-Specific Cache

The CLI (self-update.ts) writes latest version info to an OS-specific path with a 24h TTL.

One-liner to read the upstream cache:

node -e "const p=require('path'),o=require('os');const b=process.env.APPDATA||(process.platform==='darwin'?p.join(o.homedir(),'Library','Application Support'):p.join(o.homedir(),'.config'));const f=p.join(b,'squad-cli','update-check.json');try{const d=JSON.parse(require('fs').readFileSync(f,'utf8'));const age=Date.now()-d.checkedAt;if(age<86400000)console.log(JSON.stringify(d));else console.log('STALE')}catch{console.log('MISS')}"

Output semantics:

  • Valid JSON {"latestVersion":"X.Y.Z","checkedAt":N} → cache hit; use latestVersion
  • STALE → cache expired (older than 24h); treat as no data
  • MISS → cache missing or corrupt; treat as no data

OS-specific cache path:

  • Windows: %APPDATA%\squad-cli\update-check.json
  • Linux: ~/.config/squad-cli/update-check.json
  • macOS: ~/Library/Application Support/squad-cli/update-check.json

Repo-Local Cache Convention: .squad/.cache/version-check.json

Used by coordinator for insider/preview channels (the upstream cache only stores latest).

Schema:

{
  "checkedAt": "2026-05-26T14:13:28.492Z",
  "currentVersion": "0.9.6-insider.2",
  "channel": "insider",
  "channelVersion": "0.9.7-insider.1"
}

TTL: 24 hours from checkedAt. Gitignore: .squad/.cache/ is listed in .gitignore — cache files are never committed.


Key File Paths (installed CLI)

Purpose Path
Version utilities dist/cli/core/version.js
Upgrade logic dist/cli/core/upgrade.js
Init logic dist/cli/core/init.js
Template manifest dist/cli/core/templates.js
Copilot install helper dist/cli/copilot-install.js
squad.agent.md template templates/squad.agent.md.template
Session init reference templates/session-init-reference.md
All templates templates/

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at a9de923. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last month
allowedTools
[]
confidence
medium
domain
squad-internals
Other metadata
source
validated in bradygaster/squad#1173 recon (2026-05-26).

README badge

README badge for microsoft/waza/squad-version-check