[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M719HNFDXK4VH99GSVEVMZ1D":3,"skill-same:01M719HNFDXK4VH99GSVEVMZ1D":67},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":37,"linkOnly":38,"markdownContent":39,"markdownBody":40,"frontMatter":41,"refName":46,"commitSha":47,"skillDirectory":48,"forksCount":49,"repositoryHtmlUrl":50,"repositoryHomepageUrl":6,"ownerHtmlUrl":51,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":52,"install":53,"resources":66},"01M719HNFDXK4VH99GSVEVMZ1D","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.","DeDuva\u002Fsquad","DeDuva","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F8153108?v=4","01M719BQB25861D0TKS3RVHMN2","01M719BQBSWR380PSYDD5M9YD4",1,"MIT","https:\u002F\u002Fgithub.com\u002FDeDuva\u002Fsquad\u002Fblob\u002Fdev\u002Fpackages\u002Fsquad-cli\u002Ftemplates\u002Fskills\u002Fsquad-version-check\u002FSKILL.md",[],[18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36],"check","squad version check","squad","version","it","npm","registry","data","latest","2026","probe","how","cli","prompt","upgrade","coordinator","how to","for","recon","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: \"Discovered by Data; 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:** Data\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:** Data\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":42,"source":43,"confidence":44,"description":7,"allowedTools":45},"squad-internals","Discovered by Data; validated in bradygaster\u002Fsquad#1173 recon (2026-05-26).","medium",[],"dev","4ffda80d1bb1043d9169688cf161e53097345c72","packages\u002Fsquad-cli\u002Ftemplates\u002Fskills\u002Fsquad-version-check",0,"https:\u002F\u002Fgithub.com\u002FDeDuva\u002Fsquad","https:\u002F\u002Fgithub.com\u002FDeDuva","2026-11-09 20:24:44",{"source":8,"skillName":5,"commands":54,"prompt":64,"zipAvailable":65},[55,58,61],{"tool":56,"command":57},"npx","npx skills add DeDuva\u002Fsquad --skill squad-version-check",{"tool":59,"command":60},"bunx","bunx skills add DeDuva\u002Fsquad --skill squad-version-check",{"tool":62,"command":63},"pnpm","pnpm dlx skills add DeDuva\u002Fsquad --skill squad-version-check","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FDeDuva\u002Fsquad\u002Fblob\u002Fdev\u002Fpackages\u002Fsquad-cli\u002Ftemplates\u002Fskills\u002Fsquad-version-check\u002FSKILL.md",true,[],[68,84,92,108,132,147],{"skillNo":69,"name":70,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":78,"publishedAt":37},"01M719NE6ZPZT80MKVWFDECJZ3","My Skill","https:\u002F\u002Fgithub.com\u002FDeDuva\u002Fsquad\u002Fblob\u002Fdev\u002Ftest-fixtures\u002Fskills-test-abb30454\u002Fmy-skill\u002FSKILL.md",[73],{"categoryNo":74,"categoryName":75,"taxonomyType":76,"taxonomyTypeDesc":77},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[79,80,81,82,83],"my","my skill","testing","vitest","tester",{"skillNo":85,"name":86,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":37},"01M719NDJAMEWM8D9H355SCNA8","bad-skill","https:\u002F\u002Fgithub.com\u002FDeDuva\u002Fsquad\u002Fblob\u002Fdev\u002Ftest-fixtures\u002Fskills-test-abb30454\u002Fbad-skill\u002FSKILL.md",[],[90,91],"bad skill","bad",{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":96,"categories":97,"keywords":98,"publishedAt":37},"01M719NCC1AZ02GHZ1V71YPEV7","squad-conventions","Core conventions and patterns used in the Squad codebase","https:\u002F\u002Fgithub.com\u002FDeDuva\u002Fsquad\u002Fblob\u002Fdev\u002Ftemplates\u002Fskills\u002Fsquad-conventions\u002FSKILL.md",[],[99,20,100,101,102,103,104,105,106,107],"conventions","squad conventions","project-conventions","core","project","manual","high","codebase","patterns",{"skillNo":109,"name":110,"nameZh":6,"description":111,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":112,"categories":113,"keywords":114,"publishedAt":37},"01M719NAYM17B7X8MGP681EHKQ","rework-rate","Measure and interpret PR rework rate — the emerging 5th DORA metric","https:\u002F\u002Fgithub.com\u002FDeDuva\u002Fsquad\u002Fblob\u002Fdev\u002Ftemplates\u002Fskills\u002Frework-rate\u002FSKILL.md",[],[115,116,117,118,105,119,120,121,20,122,123,124,125,104,126,127,128,129,130,131],"rate","rework rate","health","analyze","review efficiency","quality","metric","metrics","efficiency","code quality","pr","prs","when","code","team","code-review","review",{"skillNo":133,"name":134,"nameZh":6,"description":135,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":136,"categories":137,"keywords":138,"publishedAt":37},"01M719NA136PDC3SQ10R4R88TH","nap","Context hygiene — compress, prune, archive .squad\u002F state","https:\u002F\u002Fgithub.com\u002FDeDuva\u002Fsquad\u002Fblob\u002Fdev\u002Ftemplates\u002Fskills\u002Fnap\u002FSKILL.md",[],[134,139,140,141,142,143,144,145,20,146],"prune","state","maintenance","context hygiene","archive","hygiene","compress","context",{"skillNo":148,"name":149,"nameZh":6,"description":150,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":151,"categories":152,"keywords":157,"publishedAt":37},"01M719N7B4PBQPNXW78TEJY4HQ","e2e-template-testing","End-to-end validation of coordinator and agent template changes","https:\u002F\u002Fgithub.com\u002FDeDuva\u002Fsquad\u002Fblob\u002Fdev\u002Ftemplates\u002Fskills\u002Fe2e-template-testing\u002FSKILL.md",[153,156],{"categoryNo":154,"categoryName":155,"taxonomyType":76,"taxonomyTypeDesc":77},"01JBSEEDCAT000000000000008","测试与质量",{"categoryNo":74,"categoryName":75,"taxonomyType":76,"taxonomyTypeDesc":77},[81,158,159,160,161,33,162,104,163,105,164],"e2e template testing","e2e","template","end","development","changes","validation"]