squad-version-check
暂无简介
- License 许可
- MIT
- 所属仓库
- zuwasi/wazatator
- 最近更新
- 2026-10-05
- Stars
- ★ 2
- Forks
- 1
03 SKILL.md 正文
SKILL: Squad CLI Internals — Version Stamping & Upgrade Mechanics
Confidence: medium Discovered by: Data 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 viapackage.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:
- HTML comment:
<!-- version: {version} -->(must be on the line immediately after frontmatter---) - Identity line:
- **Version:** {version} - 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:
- First tries HTML comment format:
/<!-- version: ([0-9.]+(?:-[a-z]+(?:\.\d+)?)?) -->/ - Falls back to old frontmatter format:
/^version:\s*"([^"]+)"/m - 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, thenstampVersion()- Files with
overwriteOnUpgrade: trueinTEMPLATE_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;stateBackendsurvives 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@latestUse@insidertag 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 spawnsagentModelOverrides.{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; uselatestVersion STALE→ cache expired (older than 24h); treat as no dataMISS→ 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/ |
04 同仓库更多 Skills
waza-runner
Run evaluations on Agent Skills to measure their effectiveness. USE FOR: "run skill evals", "evaluate my skill", "test skill quality", "check skill triggers", "skill compliance check", "measure skill performance", "run evals on [skill-name]", "grade skill execution". DO NOT USE FOR: writing skills (use skill-authoring), improving frontmatter (use sensei), or general testing unrelated to skills.
waza
**WORKFLOW SKILL** - Evaluate AI agent skills using structured benchmarks with YAML specs, fixture isolation, and pluggable validators. USE FOR: run waza, waza help, run eval, run benchmark, evaluate skill, test agent, generate eval suite, init eval, compare results, score agent, agent evaluation, skill testing, cross-model comparison. DO NOT USE FOR: improving skill frontmatter (use waza dev), creating new skills from scratch (use skill-creator), token counting or budget checks (use waza tokens). INVOKES: Copilot SDK executor, mock engine, code/regex validators. FOR SINGLE OPERATIONS: use waza run directly for a single benchmark.
waza-interactive
Interactive workflow partner for creating, testing, and improving AI agent skills with waza. USE FOR: run my evals, check my skill, compare models, create eval suite, debug failing tests, is my skill ready, ship readiness, interpret results, improve score. DO NOT USE FOR: general coding, non-skill work, writing skill content (use skill-authoring), improving frontmatter only (use sensei).
code-explainer
Explains code snippets in plain English, breaking down what the code does step by step. Perfect for learning, code reviews, or documentation.
code-explainer
**UTILITY SKILL** - Explain code snippets, functions, and algorithms in plain language. USE FOR: explain code, what does this code do, break down this function, help me understand this, walk through this algorithm, clarify this logic, explain this snippet, describe what happens here. DO NOT USE FOR: writing new code (use code generation), fixing bugs (use debugging), refactoring (use refactoring skills), code review with action items. INVOKES: file reading tools to access code, language detection for tailored explanations. FOR SINGLE OPERATIONS: If the user just needs to see file contents, use file reading tools directly.
profile-test-skill
**PROFILE TEST** - A skill for testing the profile command. USE FOR: testing profile analysis, verifying structural metrics. DO NOT USE FOR: production use.