---
name: "squad-version-check"
description: "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."
allowedTools: []
confidence: medium
domain: squad-internals
source: "validated in bradygaster/squad#1173 recon (2026-05-26)."
title: squad-version-check
canonical_url: https://skilld.dev/gh/microsoft/waza/squad-version-check
last_updated: 2026-10-16T23:18:58.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install microsoft/waza/squad-version-check`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/squad-version-check`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/microsoft/waza/squad-version-check) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/squad-version-check`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/squad-version-check --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/squad-version-check --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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

```json
{
  "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:**
```json
{
  "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/` |
