[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6R78G8WA7486VPTPNQWB7TF":3,"skill-same:01M6R78G8WA7486VPTPNQWB7TF":66},{"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":38,"linkOnly":39,"markdownContent":40,"markdownBody":41,"frontMatter":42,"refName":46,"commitSha":47,"skillDirectory":48,"forksCount":13,"repositoryHtmlUrl":49,"repositoryHomepageUrl":6,"ownerHtmlUrl":50,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":51,"install":52,"resources":65},"01M6R78G8WA7486VPTPNQWB7TF","versioning-policy",null,"Semver versioning rules for Squad SDK and CLI — prevents prerelease version incidents","barichter\u002Fsquad","barichter","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F96797186?v=4","01M6R712K8ESMDF089BFENBR16","01M6R712R74BSQQSG2GTXBWR8P",0,"MIT","https:\u002F\u002Fgithub.com\u002Fbarichter\u002Fsquad\u002Fblob\u002Fdev\u002F.squad\u002Fskills\u002Fversioning-policy\u002FSKILL.md",[],[18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37],"policy","versioning policy","versioning","for","cli","incidents","resolution","incident","gate","implementation","version","Rules","workspace","ci","npm","semver","release","squad","pr","sdk","2026-11-10 10:12:30",false,"---\r\nname: \"versioning-policy\"\r\ndescription: \"Semver versioning rules for Squad SDK and CLI — prevents prerelease version incidents\"\r\ndomain: \"release, versioning, npm, CI\"\r\nconfidence: \"medium\"\r\nsource: \"earned (PR #640 workspace resolution incident, PR #116 prerelease leak, CI gate implementation)\"\r\n---\r\n\r\n## Context\r\n\r\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.\r\n\r\nThis skill codifies the versioning rules every agent must follow.\r\n\r\n## 1. Version Format\r\n\r\nAll packages use **strict semver**: `MAJOR.MINOR.PATCH`\r\n\r\n- ✅ `0.9.1`, `1.0.0`, `0.10.0`\r\n- ❌ `0.9.1-build.4`, `0.9.1-preview.1`, `0.8.6.1-preview`\r\n\r\nNo prerelease suffixes on `dev` or `main` branches — ever.\r\n\r\n## 2. Prerelease Versions Are Ephemeral\r\n\r\nThe `scripts\u002Fbump-build.mjs` script creates `-build.N` versions (e.g., `0.9.1-build.4`) for **local development testing only**.\r\n\r\nRules:\r\n- `-build.N` versions are created automatically during local `npm run build`\r\n- They are **never committed** to `dev` or `main`\r\n- The script skips itself in CI (`CI=true` or `SKIP_BUILD_BUMP=1`)\r\n- If you see a `-build.N` version in a PR diff, it is a bug — reject the PR\r\n\r\n## 3. SDK and CLI Version Sync\r\n\r\nBoth `@bradygaster\u002Fsquad-sdk` and `@bradygaster\u002Fsquad-cli` **MUST have the same version** at all times. The root `package.json` version must also match.\r\n\r\n`bump-build.mjs` enforces this by updating all three `package.json` files in lockstep (root + `packages\u002Fsquad-sdk` + `packages\u002Fsquad-cli`).\r\n\r\nIf versions diverge, workspace resolution silently breaks (see §4).\r\n\r\n## 4. npm Workspace Semver Footgun\r\n\r\nThe CLI depends on the SDK via a workspace dependency with a semver range:\r\n\r\n```json\r\n\"@bradygaster\u002Fsquad-sdk\": \">=0.9.0\"\r\n```\r\n\r\n**Critical:** Per the semver specification, `>=0.9.0` does **NOT** match `0.9.1-build.4`.\r\n\r\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.\r\n\r\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.\r\n\r\nThis is the root cause of the **PR #640 incident**, where workspace packages appeared linked but were actually running against stale registry versions.\r\n\r\n## 5. Who Bumps Versions\r\n\r\n**Surgeon (Release Manager) owns all version bumps.**\r\n\r\n| Agent | May modify `version` in package.json? |\r\n|-------|---------------------------------------|\r\n| Surgeon | ✅ Yes — sole owner of version bumps |\r\n| Any other agent | ❌ No — unless explicitly fixing a prerelease leak |\r\n\r\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.\r\n\r\n## 6. Version Bump Lifecycle\r\n\r\n```\r\n┌─────────────────────────────────────────────────────────┐\r\n│  Development phase                                      │\r\n│  Versions stay at current release: 0.9.1                │\r\n│  bump-build.mjs creates -build.N locally (not committed)│\r\n├─────────────────────────────────────────────────────────┤\r\n│  Pre-release testing                                    │\r\n│  bump-build.mjs → 0.9.1-build.1, -build.2, ...         │\r\n│  Local only. Never committed. Never pushed.             │\r\n├─────────────────────────────────────────────────────────┤\r\n│  Release                                                │\r\n│  Surgeon bumps to next version (e.g., 0.9.2 or 0.10.0) │\r\n│  Tags, publishes to npm registry                        │\r\n├─────────────────────────────────────────────────────────┤\r\n│  Post-release                                           │\r\n│  Versions stay at the new release version (e.g., 0.9.2) │\r\n│  Development continues on clean version                 │\r\n└─────────────────────────────────────────────────────────┘\r\n```\r\n\r\n## 7. CI Enforcement\r\n\r\nThe **`prerelease-version-guard`** CI gate blocks any PR to `dev` or `main` that contains prerelease version strings in `package.json` files.\r\n\r\n- The gate scans all three `package.json` files for `-` in the version field\r\n- PRs with prerelease versions **cannot merge** until the version is cleaned\r\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\r\n\r\n## 8. Incident Reference — PR #640\r\n\r\n**PR #640** is the cautionary tale for this entire policy.\r\n\r\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.\r\n\r\n**Root cause:** No versioning policy existed. Agents didn't know that prerelease versions break workspace resolution, or that only Surgeon should modify versions.\r\n\r\n**Resolution:** This skill, the `prerelease-version-guard` CI gate, and the team decision to centralize version ownership under Surgeon.\r\n\r\n## Quick Reference\r\n\r\n| Rule | Summary |\r\n|------|---------|\r\n| Format | `MAJOR.MINOR.PATCH` — no prerelease on dev\u002Fmain |\r\n| Prerelease | `-build.N` is local-only, never committed |\r\n| Sync | SDK + CLI + root must have identical versions |\r\n| Ownership | Surgeon bumps versions; others don't touch them |\r\n| CI gate | `prerelease-version-guard` blocks prerelease PRs |\r\n| Escape hatch | Any agent may revert a prerelease leak to clean version |\r\n| Footgun | `>=0.9.0` does NOT match `0.9.1-build.4` per semver |\r\n","## Context\r\n\r\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.\r\n\r\nThis skill codifies the versioning rules every agent must follow.\r\n\r\n## 1. Version Format\r\n\r\nAll packages use **strict semver**: `MAJOR.MINOR.PATCH`\r\n\r\n- ✅ `0.9.1`, `1.0.0`, `0.10.0`\r\n- ❌ `0.9.1-build.4`, `0.9.1-preview.1`, `0.8.6.1-preview`\r\n\r\nNo prerelease suffixes on `dev` or `main` branches — ever.\r\n\r\n## 2. Prerelease Versions Are Ephemeral\r\n\r\nThe `scripts\u002Fbump-build.mjs` script creates `-build.N` versions (e.g., `0.9.1-build.4`) for **local development testing only**.\r\n\r\nRules:\r\n- `-build.N` versions are created automatically during local `npm run build`\r\n- They are **never committed** to `dev` or `main`\r\n- The script skips itself in CI (`CI=true` or `SKIP_BUILD_BUMP=1`)\r\n- If you see a `-build.N` version in a PR diff, it is a bug — reject the PR\r\n\r\n## 3. SDK and CLI Version Sync\r\n\r\nBoth `@bradygaster\u002Fsquad-sdk` and `@bradygaster\u002Fsquad-cli` **MUST have the same version** at all times. The root `package.json` version must also match.\r\n\r\n`bump-build.mjs` enforces this by updating all three `package.json` files in lockstep (root + `packages\u002Fsquad-sdk` + `packages\u002Fsquad-cli`).\r\n\r\nIf versions diverge, workspace resolution silently breaks (see §4).\r\n\r\n## 4. npm Workspace Semver Footgun\r\n\r\nThe CLI depends on the SDK via a workspace dependency with a semver range:\r\n\r\n```json\r\n\"@bradygaster\u002Fsquad-sdk\": \">=0.9.0\"\r\n```\r\n\r\n**Critical:** Per the semver specification, `>=0.9.0` does **NOT** match `0.9.1-build.4`.\r\n\r\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.\r\n\r\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.\r\n\r\nThis is the root cause of the **PR #640 incident**, where workspace packages appeared linked but were actually running against stale registry versions.\r\n\r\n## 5. Who Bumps Versions\r\n\r\n**Surgeon (Release Manager) owns all version bumps.**\r\n\r\n| Agent | May modify `version` in package.json? |\r\n|-------|---------------------------------------|\r\n| Surgeon | ✅ Yes — sole owner of version bumps |\r\n| Any other agent | ❌ No — unless explicitly fixing a prerelease leak |\r\n\r\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.\r\n\r\n## 6. Version Bump Lifecycle\r\n\r\n```\r\n┌─────────────────────────────────────────────────────────┐\r\n│  Development phase                                      │\r\n│  Versions stay at current release: 0.9.1                │\r\n│  bump-build.mjs creates -build.N locally (not committed)│\r\n├─────────────────────────────────────────────────────────┤\r\n│  Pre-release testing                                    │\r\n│  bump-build.mjs → 0.9.1-build.1, -build.2, ...         │\r\n│  Local only. Never committed. Never pushed.             │\r\n├─────────────────────────────────────────────────────────┤\r\n│  Release                                                │\r\n│  Surgeon bumps to next version (e.g., 0.9.2 or 0.10.0) │\r\n│  Tags, publishes to npm registry                        │\r\n├─────────────────────────────────────────────────────────┤\r\n│  Post-release                                           │\r\n│  Versions stay at the new release version (e.g., 0.9.2) │\r\n│  Development continues on clean version                 │\r\n└─────────────────────────────────────────────────────────┘\r\n```\r\n\r\n## 7. CI Enforcement\r\n\r\nThe **`prerelease-version-guard`** CI gate blocks any PR to `dev` or `main` that contains prerelease version strings in `package.json` files.\r\n\r\n- The gate scans all three `package.json` files for `-` in the version field\r\n- PRs with prerelease versions **cannot merge** until the version is cleaned\r\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\r\n\r\n## 8. Incident Reference — PR #640\r\n\r\n**PR #640** is the cautionary tale for this entire policy.\r\n\r\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.\r\n\r\n**Root cause:** No versioning policy existed. Agents didn't know that prerelease versions break workspace resolution, or that only Surgeon should modify versions.\r\n\r\n**Resolution:** This skill, the `prerelease-version-guard` CI gate, and the team decision to centralize version ownership under Surgeon.\r\n\r\n## Quick Reference\r\n\r\n| Rule | Summary |\r\n|------|---------|\r\n| Format | `MAJOR.MINOR.PATCH` — no prerelease on dev\u002Fmain |\r\n| Prerelease | `-build.N` is local-only, never committed |\r\n| Sync | SDK + CLI + root must have identical versions |\r\n| Ownership | Surgeon bumps versions; others don't touch them |\r\n| CI gate | `prerelease-version-guard` blocks prerelease PRs |\r\n| Escape hatch | Any agent may revert a prerelease leak to clean version |\r\n| Footgun | `>=0.9.0` does NOT match `0.9.1-build.4` per semver |\r\n",{"name":5,"domain":43,"source":44,"confidence":45,"description":7},"release, versioning, npm, CI","earned (PR #640 workspace resolution incident, PR #116 prerelease leak, CI gate implementation)","medium","dev","ec19f5e92325e634e3c6eff500e3cefa56131cc9",".squad\u002Fskills\u002Fversioning-policy","https:\u002F\u002Fgithub.com\u002Fbarichter\u002Fsquad","https:\u002F\u002Fgithub.com\u002Fbarichter","2026-04-13 22:53:46",{"source":8,"skillName":5,"commands":53,"prompt":63,"zipAvailable":64},[54,57,60],{"tool":55,"command":56},"npx","npx skills add barichter\u002Fsquad --skill versioning-policy",{"tool":58,"command":59},"bunx","bunx skills add barichter\u002Fsquad --skill versioning-policy",{"tool":61,"command":62},"pnpm","pnpm dlx skills add barichter\u002Fsquad --skill versioning-policy","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fbarichter\u002Fsquad\u002Fblob\u002Fdev\u002F.squad\u002Fskills\u002Fversioning-policy\u002FSKILL.md",true,[],[67,83,91,107,129,135],{"skillNo":68,"name":69,"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":70,"categories":71,"keywords":77,"publishedAt":38},"01M6R7VE8SZD1E37WWJN4ZFPWB","My Skill","https:\u002F\u002Fgithub.com\u002Fbarichter\u002Fsquad\u002Fblob\u002Fdev\u002Ftest-fixtures\u002Fskills-test-abb30454\u002Fmy-skill\u002FSKILL.md",[72],{"categoryNo":73,"categoryName":74,"taxonomyType":75,"taxonomyTypeDesc":76},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[78,79,80,81,82],"my","my skill","tester","vitest","testing",{"skillNo":84,"name":85,"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":86,"categories":87,"keywords":88,"publishedAt":38},"01M6R7VD19M4TMAA74XGD6QSZX","bad-skill","https:\u002F\u002Fgithub.com\u002Fbarichter\u002Fsquad\u002Fblob\u002Fdev\u002Ftest-fixtures\u002Fskills-test-abb30454\u002Fbad-skill\u002FSKILL.md",[],[89,90],"bad skill","bad",{"skillNo":92,"name":93,"nameZh":6,"description":94,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":95,"categories":96,"keywords":97,"publishedAt":38},"01M6R7V9TYTX6Z621V6RWA51G6","squad-conventions","Core conventions and patterns used in the Squad codebase","https:\u002F\u002Fgithub.com\u002Fbarichter\u002Fsquad\u002Fblob\u002Fdev\u002Ftemplates\u002Fskills\u002Fsquad-conventions\u002FSKILL.md",[],[98,35,99,100,101,102,103,104,105,106],"squad conventions","conventions","project-conventions","core","patterns","project","manual","high","codebase",{"skillNo":108,"name":109,"nameZh":6,"description":110,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":111,"categories":112,"keywords":113,"publishedAt":38},"01M6R7TTF0ABMGSVWASVYF6D51","rework-rate","Measure and interpret PR rework rate — the emerging 5th DORA metric","https:\u002F\u002Fgithub.com\u002Fbarichter\u002Fsquad\u002Fblob\u002Fdev\u002Ftemplates\u002Fskills\u002Frework-rate\u002FSKILL.md",[],[114,115,116,117,118,119,36,120,121,105,35,122,123,124,125,126,127,128,104],"rate","rework rate","metric","efficiency","prs","when","review","code quality","code","code-review","metrics","health","team","analyze","quality",{"skillNo":130,"name":131,"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":132,"categories":133,"keywords":134,"publishedAt":38},"01M6R7TRZPET44JRCSQF08EEA8","nap","https:\u002F\u002Fgithub.com\u002Fbarichter\u002Fsquad\u002Fblob\u002Fdev\u002Ftemplates\u002Fskills\u002Fnap\u002FSKILL.md",[],[131],{"skillNo":136,"name":137,"nameZh":6,"description":138,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":139,"categories":140,"keywords":142,"publishedAt":38},"01M6R7TK10WCT77A52E27GR5R3","{skill-name}","{what this skill teaches agents}","https:\u002F\u002Fgithub.com\u002Fbarichter\u002Fsquad\u002Fblob\u002Fdev\u002Ftemplates\u002Fskill.md",[141],{"categoryNo":73,"categoryName":74,"taxonomyType":75,"taxonomyTypeDesc":76},[143,144,145,146,147,148,149,150,151,152,104,105,82],"{skill name}","skill name","name","design","api","how","error-handling","learned","error","api-design"]