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