[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6X1424EEA28RM2YAC8VF4M4":3,"skill-same:01M6X1424EEA28RM2YAC8VF4M4":75},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":42,"linkOnly":43,"markdownContent":44,"markdownBody":45,"frontMatter":46,"refName":51,"commitSha":52,"skillDirectory":53,"forksCount":54,"repositoryHtmlUrl":55,"repositoryHomepageUrl":56,"ownerHtmlUrl":57,"ownerBlogUrl":58,"ownerDescription":59,"updatedAt":60,"install":61,"resources":74},"01M6X1424EEA28RM2YAC8VF4M4","squad-version-check",null,"Internals of how @bradygaster\u002Fsquad-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.","github\u002Fsquad","github","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F9919?v=4","01M6AC83DS133TPXFSP1DHNCC6","GitHub","01M6X0MZ6B0WYMMDPK3Q61KER6",3391,"MIT","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fsquad\u002Fblob\u002Fdev\u002F.squad-templates\u002Fskills\u002Fsquad-version-check\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41],"squad version check","squad","check","version","2026","cli","for","latest","coordinator","it","recon","how to","upgrade","probe","prompt","how","npm","registry","2026-11-10 10:12:30",false,"---\nname: \"squad-version-check\"\ndescription: \"Internals of how @bradygaster\u002Fsquad-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.\"\nallowedTools: []\nconfidence: medium\ndomain: squad-internals\nsource: \"validated in bradygaster\u002Fsquad#1173 recon (2026-05-26).\"\n---\n\n# SKILL: Squad CLI Internals — Version Stamping & Upgrade Mechanics\n\n**Confidence:** medium\n**Discovered by:** repository investigation\n**Date:** 2026-05-26\n**Validated in:** Issue #1173 recon (bradygaster\u002Fsquad)\n\n---\n\n## What This Skill Covers\n\nReusable knowledge about how `@bradygaster\u002Fsquad-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.\n\n---\n\n## Package & Registry Facts\n\n- **Package name:** `@bradygaster\u002Fsquad-cli`\n- **Registry:** npm (public)\n- **CLI binary:** `squad` (registered via `package.json#bin.squad`)\n- **Node version requirement:** Node ≥22.5.0 (ESM-only codebase)\n\n---\n\n## Version Stamping Mechanism\n\n**Source file:** `dist\u002Fcli\u002Fcore\u002Fversion.js`\n\nThree functions:\n\n### `getPackageVersion()`\nWalks up from the compiled JS file to find `package.json`. Returns `pkg.version`. Works from both `dist\u002Fcli\u002Fcore\u002Fversion.js` and a bundled root `cli.js`. Returns `'0.0.0'` as fallback if not found.\n\n### `stampVersion(filePath, version)`\nMutates `squad.agent.md` in three places:\n1. HTML comment: `\u003C!-- version: {version} -->` (must be on the line immediately after frontmatter `---`)\n2. Identity line: `- **Version:** {version}`\n3. Greeting instruction: backtick-quoted `` `Squad v{version}` ``\n\n**Called by:** both `init` and `upgrade` — after copying the template to the destination.\n\n### `readInstalledVersion(filePath)`\nReads the stamped version back from `squad.agent.md`:\n1. First tries HTML comment format: `\u002F\u003C!-- version: ([0-9.]+(?:-[a-z]+(?:\\.\\d+)?)?) -->\u002F`\n2. Falls back to old frontmatter format: `\u002F^version:\\s*\"([^\"]+)\"\u002Fm`\n3. Returns `'0.0.0'` on any error\n\n---\n\n## `squad upgrade` Behavior\n\n**Source file:** `dist\u002Fcli\u002Fcore\u002Fupgrade.js`\n\n### What gets overwritten:\n- `squad.agent.md` — full overwrite from template, then `stampVersion()`\n- Files with `overwriteOnUpgrade: true` in `TEMPLATE_MANIFEST`: casting JSON files, template .md files, `copilot-instructions.md` (if @copilot enabled)\n- GitHub Actions workflows — from `templates\u002Fworkflows\u002F`; non-npm projects get type-aware stubs\n- Runs `runMigrations()` after file copy\n\n### What is PRESERVED:\n- `team.md`, `routing.md`, `decisions.md`, `ceremonies.md` (user-owned)\n- `agents\u002F*\u002Fhistory.md` (individual agent memory)\n- `.squad\u002Fconfig.json` — **never touched**; `stateBackend` survives intact\n- User-added files not in TEMPLATE_MANIFEST\n\n### Self-upgrade path (`selfUpgradeCli()`):\nDetects npm\u002Fpnpm\u002Fyarn via `npm_execpath` and `npm_config_user_agent`. Runs:\n- npm: `npm install -g @bradygaster\u002Fsquad-cli@latest`\n- pnpm: `pnpm add -g @bradygaster\u002Fsquad-cli@latest`\n- yarn: `yarn global add @bradygaster\u002Fsquad-cli@latest`\nUse `@insider` tag for insider builds.\n\n### `compareSemver(a, b)` utility (in upgrade.js):\nReturns -1\u002F0\u002F1. Handles pre-release: strips pre-release for base comparison, then treats pre-release as less than release (e.g., `0.9.5-insider.1` \u003C `0.9.5`). Can be ported directly if needed in prompt logic.\n\n---\n\n## `.squad\u002Fconfig.json` — What It Holds\n\n```json\n{\n  \"version\": 1,\n  \"stateBackend\": \"worktree\"\n}\n```\n\nOther optional fields added by the coordinator at runtime:\n- `defaultModel` — global model override for all agent spawns\n- `agentModelOverrides.{agentName}` — per-agent model override\n\nThe file is read-only from the upgrade path's perspective. Only the coordinator writes to it (for model preferences).\n\n---\n\n## Version-Check Probe (npm Registry)\n\nUse this one-liner from inside a coordinator prompt to fetch dist-tags:\n\n```\nnpm view @bradygaster\u002Fsquad-cli dist-tags --json\n```\n\n- Timeout: **5 seconds.** If no response within 5 seconds, abandon and show normal greeting.\n- On success: extract `dist-tags[channel]` (e.g., `dist-tags[\"insider\"]`).\n- On any error (network failure, registry unreachable, parse error): show normal greeting.\n\n---\n\n## Upstream OS-Specific Cache\n\nThe CLI (`self-update.ts`) writes `latest` version info to an OS-specific path with a 24h TTL.\n\n**One-liner to read the upstream cache:**\n```\nnode -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\u003C86400000)console.log(JSON.stringify(d));else console.log('STALE')}catch{console.log('MISS')}\"\n```\n\nOutput semantics:\n- Valid JSON `{\"latestVersion\":\"X.Y.Z\",\"checkedAt\":N}` → cache hit; use `latestVersion`\n- `STALE` → cache expired (older than 24h); treat as no data\n- `MISS` → cache missing or corrupt; treat as no data\n\n**OS-specific cache path:**\n- Windows: `%APPDATA%\\squad-cli\\update-check.json`\n- Linux: `~\u002F.config\u002Fsquad-cli\u002Fupdate-check.json`\n- macOS: `~\u002FLibrary\u002FApplication Support\u002Fsquad-cli\u002Fupdate-check.json`\n\n---\n\n## Repo-Local Cache Convention: `.squad\u002F.cache\u002Fversion-check.json`\n\nUsed by coordinator for `insider`\u002F`preview` channels (the upstream cache only stores `latest`).\n\n**Schema:**\n```json\n{\n  \"checkedAt\": \"2026-05-26T14:13:28.492Z\",\n  \"currentVersion\": \"0.9.6-insider.2\",\n  \"channel\": \"insider\",\n  \"channelVersion\": \"0.9.7-insider.1\"\n}\n```\n\n**TTL:** 24 hours from `checkedAt`.\n**Gitignore:** `.squad\u002F.cache\u002F` is listed in `.gitignore` — cache files are never committed.\n\n---\n\n## Key File Paths (installed CLI)\n\n| Purpose | Path |\n|---|---|\n| Version utilities | `dist\u002Fcli\u002Fcore\u002Fversion.js` |\n| Upgrade logic | `dist\u002Fcli\u002Fcore\u002Fupgrade.js` |\n| Init logic | `dist\u002Fcli\u002Fcore\u002Finit.js` |\n| Template manifest | `dist\u002Fcli\u002Fcore\u002Ftemplates.js` |\n| Copilot install helper | `dist\u002Fcli\u002Fcopilot-install.js` |\n| squad.agent.md template | `templates\u002Fsquad.agent.md.template` |\n| Session init reference | `templates\u002Fsession-init-reference.md` |\n| All templates | `templates\u002F` |\n","# SKILL: Squad CLI Internals — Version Stamping & Upgrade Mechanics\n\n**Confidence:** medium\n**Discovered by:** repository investigation\n**Date:** 2026-05-26\n**Validated in:** Issue #1173 recon (bradygaster\u002Fsquad)\n\n---\n\n## What This Skill Covers\n\nReusable knowledge about how `@bradygaster\u002Fsquad-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.\n\n---\n\n## Package & Registry Facts\n\n- **Package name:** `@bradygaster\u002Fsquad-cli`\n- **Registry:** npm (public)\n- **CLI binary:** `squad` (registered via `package.json#bin.squad`)\n- **Node version requirement:** Node ≥22.5.0 (ESM-only codebase)\n\n---\n\n## Version Stamping Mechanism\n\n**Source file:** `dist\u002Fcli\u002Fcore\u002Fversion.js`\n\nThree functions:\n\n### `getPackageVersion()`\nWalks up from the compiled JS file to find `package.json`. Returns `pkg.version`. Works from both `dist\u002Fcli\u002Fcore\u002Fversion.js` and a bundled root `cli.js`. Returns `'0.0.0'` as fallback if not found.\n\n### `stampVersion(filePath, version)`\nMutates `squad.agent.md` in three places:\n1. HTML comment: `\u003C!-- version: {version} -->` (must be on the line immediately after frontmatter `---`)\n2. Identity line: `- **Version:** {version}`\n3. Greeting instruction: backtick-quoted `` `Squad v{version}` ``\n\n**Called by:** both `init` and `upgrade` — after copying the template to the destination.\n\n### `readInstalledVersion(filePath)`\nReads the stamped version back from `squad.agent.md`:\n1. First tries HTML comment format: `\u002F\u003C!-- version: ([0-9.]+(?:-[a-z]+(?:\\.\\d+)?)?) -->\u002F`\n2. Falls back to old frontmatter format: `\u002F^version:\\s*\"([^\"]+)\"\u002Fm`\n3. Returns `'0.0.0'` on any error\n\n---\n\n## `squad upgrade` Behavior\n\n**Source file:** `dist\u002Fcli\u002Fcore\u002Fupgrade.js`\n\n### What gets overwritten:\n- `squad.agent.md` — full overwrite from template, then `stampVersion()`\n- Files with `overwriteOnUpgrade: true` in `TEMPLATE_MANIFEST`: casting JSON files, template .md files, `copilot-instructions.md` (if @copilot enabled)\n- GitHub Actions workflows — from `templates\u002Fworkflows\u002F`; non-npm projects get type-aware stubs\n- Runs `runMigrations()` after file copy\n\n### What is PRESERVED:\n- `team.md`, `routing.md`, `decisions.md`, `ceremonies.md` (user-owned)\n- `agents\u002F*\u002Fhistory.md` (individual agent memory)\n- `.squad\u002Fconfig.json` — **never touched**; `stateBackend` survives intact\n- User-added files not in TEMPLATE_MANIFEST\n\n### Self-upgrade path (`selfUpgradeCli()`):\nDetects npm\u002Fpnpm\u002Fyarn via `npm_execpath` and `npm_config_user_agent`. Runs:\n- npm: `npm install -g @bradygaster\u002Fsquad-cli@latest`\n- pnpm: `pnpm add -g @bradygaster\u002Fsquad-cli@latest`\n- yarn: `yarn global add @bradygaster\u002Fsquad-cli@latest`\nUse `@insider` tag for insider builds.\n\n### `compareSemver(a, b)` utility (in upgrade.js):\nReturns -1\u002F0\u002F1. Handles pre-release: strips pre-release for base comparison, then treats pre-release as less than release (e.g., `0.9.5-insider.1` \u003C `0.9.5`). Can be ported directly if needed in prompt logic.\n\n---\n\n## `.squad\u002Fconfig.json` — What It Holds\n\n```json\n{\n  \"version\": 1,\n  \"stateBackend\": \"worktree\"\n}\n```\n\nOther optional fields added by the coordinator at runtime:\n- `defaultModel` — global model override for all agent spawns\n- `agentModelOverrides.{agentName}` — per-agent model override\n\nThe file is read-only from the upgrade path's perspective. Only the coordinator writes to it (for model preferences).\n\n---\n\n## Version-Check Probe (npm Registry)\n\nUse this one-liner from inside a coordinator prompt to fetch dist-tags:\n\n```\nnpm view @bradygaster\u002Fsquad-cli dist-tags --json\n```\n\n- Timeout: **5 seconds.** If no response within 5 seconds, abandon and show normal greeting.\n- On success: extract `dist-tags[channel]` (e.g., `dist-tags[\"insider\"]`).\n- On any error (network failure, registry unreachable, parse error): show normal greeting.\n\n---\n\n## Upstream OS-Specific Cache\n\nThe CLI (`self-update.ts`) writes `latest` version info to an OS-specific path with a 24h TTL.\n\n**One-liner to read the upstream cache:**\n```\nnode -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\u003C86400000)console.log(JSON.stringify(d));else console.log('STALE')}catch{console.log('MISS')}\"\n```\n\nOutput semantics:\n- Valid JSON `{\"latestVersion\":\"X.Y.Z\",\"checkedAt\":N}` → cache hit; use `latestVersion`\n- `STALE` → cache expired (older than 24h); treat as no data\n- `MISS` → cache missing or corrupt; treat as no data\n\n**OS-specific cache path:**\n- Windows: `%APPDATA%\\squad-cli\\update-check.json`\n- Linux: `~\u002F.config\u002Fsquad-cli\u002Fupdate-check.json`\n- macOS: `~\u002FLibrary\u002FApplication Support\u002Fsquad-cli\u002Fupdate-check.json`\n\n---\n\n## Repo-Local Cache Convention: `.squad\u002F.cache\u002Fversion-check.json`\n\nUsed by coordinator for `insider`\u002F`preview` channels (the upstream cache only stores `latest`).\n\n**Schema:**\n```json\n{\n  \"checkedAt\": \"2026-05-26T14:13:28.492Z\",\n  \"currentVersion\": \"0.9.6-insider.2\",\n  \"channel\": \"insider\",\n  \"channelVersion\": \"0.9.7-insider.1\"\n}\n```\n\n**TTL:** 24 hours from `checkedAt`.\n**Gitignore:** `.squad\u002F.cache\u002F` is listed in `.gitignore` — cache files are never committed.\n\n---\n\n## Key File Paths (installed CLI)\n\n| Purpose | Path |\n|---|---|\n| Version utilities | `dist\u002Fcli\u002Fcore\u002Fversion.js` |\n| Upgrade logic | `dist\u002Fcli\u002Fcore\u002Fupgrade.js` |\n| Init logic | `dist\u002Fcli\u002Fcore\u002Finit.js` |\n| Template manifest | `dist\u002Fcli\u002Fcore\u002Ftemplates.js` |\n| Copilot install helper | `dist\u002Fcli\u002Fcopilot-install.js` |\n| squad.agent.md template | `templates\u002Fsquad.agent.md.template` |\n| Session init reference | `templates\u002Fsession-init-reference.md` |\n| All templates | `templates\u002F` |\n",{"name":5,"domain":47,"source":48,"confidence":49,"description":7,"allowedTools":50},"squad-internals","validated in bradygaster\u002Fsquad#1173 recon (2026-05-26).","medium",[],"dev","7b731ec97f35346bdc4fa87c3edaf16b808fc0ae",".squad-templates\u002Fskills\u002Fsquad-version-check",520,"https:\u002F\u002Fgithub.com\u002Fgithub\u002Fsquad","https:\u002F\u002Fgithub.github.io\u002Fsquad\u002F","https:\u002F\u002Fgithub.com\u002Fgithub","https:\u002F\u002Fgithub.com\u002Fabout","How people build software.","2026-11-15 02:13:59",{"source":8,"skillName":5,"commands":62,"prompt":72,"zipAvailable":73},[63,66,69],{"tool":64,"command":65},"npx","npx skills add github\u002Fsquad --skill squad-version-check",{"tool":67,"command":68},"bunx","bunx skills add github\u002Fsquad --skill squad-version-check",{"tool":70,"command":71},"pnpm","pnpm dlx skills add github\u002Fsquad --skill squad-version-check","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fgithub\u002Fsquad\u002Fblob\u002Fdev\u002F.squad-templates\u002Fskills\u002Fsquad-version-check\u002FSKILL.md",true,[],[76,84,91,98,105,111],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":83},"01M76752CVNE7K6NWD59CRAYNJ","windows-compatibility","Cross-platform path handling and command patterns","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fsquad\u002Fblob\u002Fdev\u002Fplugins\u002Fsquad\u002Fskills\u002Fwindows-compatibility\u002FSKILL.md",[],[],"2026-11-12 13:55:43",{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":83},"01M767508W8A4G83NX1FKEW5VN","versioning-policy","SemVer rules for Squad's stable, preview, insider, and local package versions","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fsquad\u002Fblob\u002Fdev\u002Fplugins\u002Fsquad\u002Fskills\u002Fversioning-policy\u002FSKILL.md",[],[],{"skillNo":92,"name":93,"nameZh":6,"description":94,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":95,"categories":96,"keywords":97,"publishedAt":83},"01M7674X5JJKNJ74B3SS8PGXG2","tiered-memory","Three-tier agent memory model (hot\u002Fcold\u002Fwiki) for context reduction per spawn","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fsquad\u002Fblob\u002Fdev\u002Fplugins\u002Fsquad\u002Fskills\u002Ftiered-memory\u002FSKILL.md",[],[],{"skillNo":99,"name":100,"nameZh":6,"description":101,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":102,"categories":103,"keywords":104,"publishedAt":83},"01M7674V3S9H03A76H75M1KSAF","test-discipline","Design assertions that prove the actual contract and fail on realistic regressions","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fsquad\u002Fblob\u002Fdev\u002Fplugins\u002Fsquad\u002Fskills\u002Ftest-discipline\u002FSKILL.md",[],[],{"skillNo":106,"name":25,"nameZh":6,"description":107,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":108,"categories":109,"keywords":110,"publishedAt":83},"01M7674QB8CA61RNDX2Z0NAK71","Squad's command catalog and interactive menu. Invoke via \u002Fsquad (slash command) or natural language (\"squad commands\", \"what can squad do\", \"show me squad options\"). Presents categorized operations (Install & Upgrade, Team Management, Issues & PRs, Plugins & Skills, Model & Cost, Sessions & State) as an interactive picker. Routes to the right squad CLI command or the Squad coordinator agent.","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fsquad\u002Fblob\u002Fdev\u002Fplugins\u002Fsquad\u002Fskills\u002Fsquad\u002FSKILL.md",[],[],{"skillNo":112,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":113,"categories":114,"keywords":115,"publishedAt":83},"01M7674KTQ632N30HQB1TP7TXH","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fsquad\u002Fblob\u002Fdev\u002Fplugins\u002Fsquad\u002Fskills\u002Fsquad-version-check\u002FSKILL.md",[],[]]