[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7AVHABPRYXYM3GWJY1RW92A":3,"skill-same:01M7AVHABPRYXYM3GWJY1RW92A":49},{"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":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":27,"commitSha":28,"skillDirectory":29,"forksCount":14,"repositoryHtmlUrl":30,"repositoryHomepageUrl":6,"ownerHtmlUrl":31,"ownerBlogUrl":32,"ownerDescription":33,"updatedAt":34,"install":35,"resources":48},"01M7AVHABPRYXYM3GWJY1RW92A","versioning-policy",null,"Semver versioning rules for Squad SDK and CLI — prevents prerelease version incidents","alonf\u002FKeyContextAI","alonf","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F554150?v=4","01M7ATEPSCNKG13BVTKA74VG59","Alon Fliess","01M7ATEPSZ4YMBM9W25SKM3GES",0,"MIT","https:\u002F\u002Fgithub.com\u002Falonf\u002FKeyContextAI\u002Fblob\u002Fmain\u002F.squad\u002Ftemplates\u002Fskills\u002Fversioning-policy\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: \"versioning-policy\"\ndescription: \"Semver versioning rules for Squad SDK and CLI — prevents prerelease version incidents\"\ndomain: \"release, versioning, npm, CI\"\nconfidence: \"medium\"\nsource: \"earned (PR #640 workspace resolution incident, PR #116 prerelease leak, CI gate implementation)\"\n---\n\n## Context\n\nSquad is a monorepo with two publishable npm packages (`@bradygaster\u002Fsquad-sdk` and `@bradygaster\u002Fsquad-cli`) managed via npm workspaces. Version mismatches and prerelease leaks have caused production incidents — most notably PR #640, where a `-build.N` prerelease version silently broke workspace dependency resolution.\n\nThis skill codifies the versioning rules every agent must follow.\n\n## 1. Version Format\n\nAll packages use **strict semver**: `MAJOR.MINOR.PATCH`\n\n- ✅ `0.9.1`, `1.0.0`, `0.10.0`\n- ❌ `0.9.1-build.4`, `0.9.1-preview.1`, `0.8.6.1-preview`\n\nNo prerelease suffixes on `dev` or `main` branches — ever.\n\n## 2. Prerelease Versions Are Ephemeral\n\nThe `scripts\u002Fbump-build.mjs` script creates `-build.N` versions (e.g., `0.9.1-build.4`) for **local development testing only**.\n\nRules:\n- `-build.N` versions are created automatically during local `npm run build`\n- They are **never committed** to `dev` or `main`\n- The script skips itself in CI (`CI=true` or `SKIP_BUILD_BUMP=1`)\n- If you see a `-build.N` version in a PR diff, it is a bug — reject the PR\n\n## 3. SDK and CLI Version Sync\n\nBoth `@bradygaster\u002Fsquad-sdk` and `@bradygaster\u002Fsquad-cli` **MUST have the same version** at all times. The root `package.json` version must also match.\n\n`bump-build.mjs` enforces this by updating all three `package.json` files in lockstep (root + `packages\u002Fsquad-sdk` + `packages\u002Fsquad-cli`).\n\nIf versions diverge, workspace resolution silently breaks (see §4).\n\n## 4. npm Workspace Semver Footgun\n\nThe CLI depends on the SDK via a workspace dependency with a semver range:\n\n```json\n\"@bradygaster\u002Fsquad-sdk\": \">=0.9.0\"\n```\n\n**Critical:** Per the semver specification, `>=0.9.0` does **NOT** match `0.9.1-build.4`.\n\nSemver prerelease versions (anything with a `-` suffix) are only matched by ranges that explicitly reference the same `MAJOR.MINOR.PATCH` base with a prerelease comparator. A bare `>=0.9.0` range skips all prerelease versions.\n\n**What happens:** When the local SDK has version `0.9.1-build.4`, npm's workspace resolution fails to match the `>=0.9.0` range. npm then **silently installs a stale published version** from the npm registry instead of using the local workspace link. The build succeeds but runs against old SDK code.\n\nThis is the root cause of the **PR #640 incident**, where workspace packages appeared linked but were actually running against stale registry versions.\n\n## 5. Who Bumps Versions\n\n**Surgeon (Release Manager) owns all version bumps.**\n\n| Agent | May modify `version` in package.json? |\n|-------|---------------------------------------|\n| Surgeon | ✅ Yes — sole owner of version bumps |\n| Any other agent | ❌ No — unless explicitly fixing a prerelease leak |\n\nIf you discover a prerelease version committed to `dev` or `main`, you may fix it (revert to the clean release version) without Surgeon's approval. This is a safety escape hatch, not a license to manage versions.\n\n## 6. Version Bump Lifecycle\n\n```\n┌─────────────────────────────────────────────────────────┐\n│  Development phase                                      │\n│  Versions stay at current release: 0.9.1                │\n│  bump-build.mjs creates -build.N locally (not committed)│\n├─────────────────────────────────────────────────────────┤\n│  Pre-release testing                                    │\n│  bump-build.mjs → 0.9.1-build.1, -build.2, ...         │\n│  Local only. Never committed. Never pushed.             │\n├─────────────────────────────────────────────────────────┤\n│  Release                                                │\n│  Surgeon bumps to next version (e.g., 0.9.2 or 0.10.0) │\n│  Tags, publishes to npm registry                        │\n├─────────────────────────────────────────────────────────┤\n│  Post-release                                           │\n│  Versions stay at the new release version (e.g., 0.9.2) │\n│  Development continues on clean version                 │\n└─────────────────────────────────────────────────────────┘\n```\n\n## 7. CI Enforcement\n\nThe **`prerelease-version-guard`** CI gate blocks any PR to `dev` or `main` that contains prerelease version strings in `package.json` files.\n\n- The gate scans all three `package.json` files for `-` in the version field\n- PRs with prerelease versions **cannot merge** until the version is cleaned\n- The `skip-version-check` label bypasses the gate — use **only** for the bump-build script's own PR (if applicable), and only with Surgeon's approval\n\n## 8. Incident Reference — PR #640\n\n**PR #640** is the cautionary tale for this entire policy.\n\n**What happened:** Prerelease versions (`0.9.1-build.4`) were committed to a branch. The workspace dependency `>=0.9.0` failed to match the prerelease version per semver spec. npm silently installed a stale published SDK from the registry instead of linking the local workspace copy. Four PRs (#637–#640) attempted iterative patches before the root cause was identified.\n\n**Root cause:** No versioning policy existed. Agents didn't know that prerelease versions break workspace resolution, or that only Surgeon should modify versions.\n\n**Resolution:** This skill, the `prerelease-version-guard` CI gate, and the team decision to centralize version ownership under Surgeon.\n\n## Quick Reference\n\n| Rule | Summary |\n|------|---------|\n| Format | `MAJOR.MINOR.PATCH` — no prerelease on dev\u002Fmain |\n| Prerelease | `-build.N` is local-only, never committed |\n| Sync | SDK + CLI + root must have identical versions |\n| Ownership | Surgeon bumps versions; others don't touch them |\n| CI gate | `prerelease-version-guard` blocks prerelease PRs |\n| Escape hatch | Any agent may revert a prerelease leak to clean version |\n| Footgun | `>=0.9.0` does NOT match `0.9.1-build.4` per semver |\n","## Context\n\nSquad is a monorepo with two publishable npm packages (`@bradygaster\u002Fsquad-sdk` and `@bradygaster\u002Fsquad-cli`) managed via npm workspaces. Version mismatches and prerelease leaks have caused production incidents — most notably PR #640, where a `-build.N` prerelease version silently broke workspace dependency resolution.\n\nThis skill codifies the versioning rules every agent must follow.\n\n## 1. Version Format\n\nAll packages use **strict semver**: `MAJOR.MINOR.PATCH`\n\n- ✅ `0.9.1`, `1.0.0`, `0.10.0`\n- ❌ `0.9.1-build.4`, `0.9.1-preview.1`, `0.8.6.1-preview`\n\nNo prerelease suffixes on `dev` or `main` branches — ever.\n\n## 2. Prerelease Versions Are Ephemeral\n\nThe `scripts\u002Fbump-build.mjs` script creates `-build.N` versions (e.g., `0.9.1-build.4`) for **local development testing only**.\n\nRules:\n- `-build.N` versions are created automatically during local `npm run build`\n- They are **never committed** to `dev` or `main`\n- The script skips itself in CI (`CI=true` or `SKIP_BUILD_BUMP=1`)\n- If you see a `-build.N` version in a PR diff, it is a bug — reject the PR\n\n## 3. SDK and CLI Version Sync\n\nBoth `@bradygaster\u002Fsquad-sdk` and `@bradygaster\u002Fsquad-cli` **MUST have the same version** at all times. The root `package.json` version must also match.\n\n`bump-build.mjs` enforces this by updating all three `package.json` files in lockstep (root + `packages\u002Fsquad-sdk` + `packages\u002Fsquad-cli`).\n\nIf versions diverge, workspace resolution silently breaks (see §4).\n\n## 4. npm Workspace Semver Footgun\n\nThe CLI depends on the SDK via a workspace dependency with a semver range:\n\n```json\n\"@bradygaster\u002Fsquad-sdk\": \">=0.9.0\"\n```\n\n**Critical:** Per the semver specification, `>=0.9.0` does **NOT** match `0.9.1-build.4`.\n\nSemver prerelease versions (anything with a `-` suffix) are only matched by ranges that explicitly reference the same `MAJOR.MINOR.PATCH` base with a prerelease comparator. A bare `>=0.9.0` range skips all prerelease versions.\n\n**What happens:** When the local SDK has version `0.9.1-build.4`, npm's workspace resolution fails to match the `>=0.9.0` range. npm then **silently installs a stale published version** from the npm registry instead of using the local workspace link. The build succeeds but runs against old SDK code.\n\nThis is the root cause of the **PR #640 incident**, where workspace packages appeared linked but were actually running against stale registry versions.\n\n## 5. Who Bumps Versions\n\n**Surgeon (Release Manager) owns all version bumps.**\n\n| Agent | May modify `version` in package.json? |\n|-------|---------------------------------------|\n| Surgeon | ✅ Yes — sole owner of version bumps |\n| Any other agent | ❌ No — unless explicitly fixing a prerelease leak |\n\nIf you discover a prerelease version committed to `dev` or `main`, you may fix it (revert to the clean release version) without Surgeon's approval. This is a safety escape hatch, not a license to manage versions.\n\n## 6. Version Bump Lifecycle\n\n```\n┌─────────────────────────────────────────────────────────┐\n│  Development phase                                      │\n│  Versions stay at current release: 0.9.1                │\n│  bump-build.mjs creates -build.N locally (not committed)│\n├─────────────────────────────────────────────────────────┤\n│  Pre-release testing                                    │\n│  bump-build.mjs → 0.9.1-build.1, -build.2, ...         │\n│  Local only. Never committed. Never pushed.             │\n├─────────────────────────────────────────────────────────┤\n│  Release                                                │\n│  Surgeon bumps to next version (e.g., 0.9.2 or 0.10.0) │\n│  Tags, publishes to npm registry                        │\n├─────────────────────────────────────────────────────────┤\n│  Post-release                                           │\n│  Versions stay at the new release version (e.g., 0.9.2) │\n│  Development continues on clean version                 │\n└─────────────────────────────────────────────────────────┘\n```\n\n## 7. CI Enforcement\n\nThe **`prerelease-version-guard`** CI gate blocks any PR to `dev` or `main` that contains prerelease version strings in `package.json` files.\n\n- The gate scans all three `package.json` files for `-` in the version field\n- PRs with prerelease versions **cannot merge** until the version is cleaned\n- The `skip-version-check` label bypasses the gate — use **only** for the bump-build script's own PR (if applicable), and only with Surgeon's approval\n\n## 8. Incident Reference — PR #640\n\n**PR #640** is the cautionary tale for this entire policy.\n\n**What happened:** Prerelease versions (`0.9.1-build.4`) were committed to a branch. The workspace dependency `>=0.9.0` failed to match the prerelease version per semver spec. npm silently installed a stale published SDK from the registry instead of linking the local workspace copy. Four PRs (#637–#640) attempted iterative patches before the root cause was identified.\n\n**Root cause:** No versioning policy existed. Agents didn't know that prerelease versions break workspace resolution, or that only Surgeon should modify versions.\n\n**Resolution:** This skill, the `prerelease-version-guard` CI gate, and the team decision to centralize version ownership under Surgeon.\n\n## Quick Reference\n\n| Rule | Summary |\n|------|---------|\n| Format | `MAJOR.MINOR.PATCH` — no prerelease on dev\u002Fmain |\n| Prerelease | `-build.N` is local-only, never committed |\n| Sync | SDK + CLI + root must have identical versions |\n| Ownership | Surgeon bumps versions; others don't touch them |\n| CI gate | `prerelease-version-guard` blocks prerelease PRs |\n| Escape hatch | Any agent may revert a prerelease leak to clean version |\n| Footgun | `>=0.9.0` does NOT match `0.9.1-build.4` per semver |\n",{"name":5,"domain":24,"source":25,"confidence":26,"description":7},"release, versioning, npm, CI","earned (PR #640 workspace resolution incident, PR #116 prerelease leak, CI gate implementation)","medium","main","176da577bfd98859f793bdd1312690c6c3940c67",".squad\u002Ftemplates\u002Fskills\u002Fversioning-policy","https:\u002F\u002Fgithub.com\u002Falonf\u002FKeyContextAI","https:\u002F\u002Fgithub.com\u002Falonf","http:\u002F\u002Falonfliess.me","CTO & Founder of Zionet.\r\nMicrosoft Regional Director and Foundry MVP.\r\n","2026-08-28 05:21:35",{"source":8,"skillName":5,"commands":36,"prompt":46,"zipAvailable":47},[37,40,43],{"tool":38,"command":39},"npx","npx skills add alonf\u002FKeyContextAI --skill versioning-policy",{"tool":41,"command":42},"bunx","bunx skills add alonf\u002FKeyContextAI --skill versioning-policy",{"tool":44,"command":45},"pnpm","pnpm dlx skills add alonf\u002FKeyContextAI --skill versioning-policy","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Falonf\u002FKeyContextAI\u002Fblob\u002Fmain\u002F.squad\u002Ftemplates\u002Fskills\u002Fversioning-policy\u002FSKILL.md",true,[],[50,57,64,71,78,85],{"skillNo":51,"name":52,"nameZh":6,"description":53,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":54,"categories":55,"keywords":56,"publishedAt":19},"01M7AVHRWWXA0BQ5PXNA8FG30W","windows-compatibility","Cross-platform path handling and command patterns","https:\u002F\u002Fgithub.com\u002Falonf\u002FKeyContextAI\u002Fblob\u002Fmain\u002F.squad\u002Ftemplates\u002Fskills\u002Fwindows-compatibility\u002FSKILL.md",[],[],{"skillNo":58,"name":59,"nameZh":6,"description":60,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":61,"categories":62,"keywords":63,"publishedAt":19},"01M7AVH4KNP3TCVQDRVS70VP19","tiered-memory","Three-tier agent memory model (hot\u002Fcold\u002Fwiki) for context reduction per spawn","https:\u002F\u002Fgithub.com\u002Falonf\u002FKeyContextAI\u002Fblob\u002Fmain\u002F.squad\u002Ftemplates\u002Fskills\u002Ftiered-memory\u002FSKILL.md",[],[],{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":19},"01M7AVH18JDSA55Z7KK2GH6X49","test-discipline","Update tests when changing APIs — no exceptions","https:\u002F\u002Fgithub.com\u002Falonf\u002FKeyContextAI\u002Fblob\u002Fmain\u002F.squad\u002Ftemplates\u002Fskills\u002Ftest-discipline\u002FSKILL.md",[],[],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":19},"01M7AVGVGWYD7NBNXAV4PAZJ92","squad","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\u002Falonf\u002FKeyContextAI\u002Fblob\u002Fmain\u002F.squad\u002Ftemplates\u002Fskills\u002Fsquad\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":19},"01M7AVGPSFT1WHW3PK35DHS5XK","squad-version-check","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.","https:\u002F\u002Fgithub.com\u002Falonf\u002FKeyContextAI\u002Fblob\u002Fmain\u002F.squad\u002Ftemplates\u002Fskills\u002Fsquad-version-check\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":19},"01M7AVGHW8X709TBZ9YZAV7GE9","squad-help","How to actually use Squad — Squad is a custom Copilot agent (invoked via the task tool with agent_type='Squad'), not a skill. This file explains the right invocation paths for setting up a team, listing squad commands, and initializing Squad in a new project.","https:\u002F\u002Fgithub.com\u002Falonf\u002FKeyContextAI\u002Fblob\u002Fmain\u002F.squad\u002Ftemplates\u002Fskills\u002Fsquad-help\u002FSKILL.md",[],[]]