[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M719N2G7VJFJ7SH0MWZ0DECA":3,"skill-same:01M719N2G7VJFJ7SH0MWZ0DECA":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":38,"linkOnly":39,"markdownContent":40,"markdownBody":41,"frontMatter":42,"refName":46,"commitSha":47,"skillDirectory":48,"forksCount":49,"repositoryHtmlUrl":50,"repositoryHomepageUrl":6,"ownerHtmlUrl":51,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":52,"install":53,"resources":66},"01M719N2G7VJFJ7SH0MWZ0DECA","versioning-policy",null,"Semver versioning rules for Squad SDK and CLI — prevents prerelease version incidents","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-sdk\u002Ftemplates\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","versioning policy","squad","semver","npm","implementation","gate","release","workspace","sdk","cli","resolution","version","Rules","ci","incidents","incident","for","pr","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","4ffda80d1bb1043d9169688cf161e53097345c72","packages\u002Fsquad-sdk\u002Ftemplates\u002Fskills\u002Fversioning-policy",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 versioning-policy",{"tool":59,"command":60},"bunx","bunx skills add DeDuva\u002Fsquad --skill versioning-policy",{"tool":62,"command":63},"pnpm","pnpm dlx skills add DeDuva\u002Fsquad --skill versioning-policy","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FDeDuva\u002Fsquad\u002Fblob\u002Fdev\u002Fpackages\u002Fsquad-sdk\u002Ftemplates\u002Fskills\u002Fversioning-policy\u002FSKILL.md",true,[],[68,84,92,108,131,146],{"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":38},"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":38},"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":38},"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,21,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":38},"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,21,122,123,124,37,104,125,126,127,128,129,130],"rate","rework rate","health","analyze","review efficiency","quality","metric","metrics","efficiency","code quality","prs","when","code","team","code-review","review",{"skillNo":132,"name":133,"nameZh":6,"description":134,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":135,"categories":136,"keywords":137,"publishedAt":38},"01M719NA136PDC3SQ10R4R88TH","nap","Context hygiene — compress, prune, archive .squad\u002F state","https:\u002F\u002Fgithub.com\u002FDeDuva\u002Fsquad\u002Fblob\u002Fdev\u002Ftemplates\u002Fskills\u002Fnap\u002FSKILL.md",[],[133,138,139,140,141,142,143,144,21,145],"prune","state","maintenance","context hygiene","archive","hygiene","compress","context",{"skillNo":147,"name":148,"nameZh":6,"description":149,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":150,"categories":151,"keywords":156,"publishedAt":38},"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",[152,155],{"categoryNo":153,"categoryName":154,"taxonomyType":76,"taxonomyTypeDesc":77},"01JBSEEDCAT000000000000008","测试与质量",{"categoryNo":74,"categoryName":75,"taxonomyType":76,"taxonomyTypeDesc":77},[81,157,158,159,160,161,162,104,163,105,164],"e2e template testing","e2e","template","end","coordinator","development","changes","validation"]