From a3e0acd19a99d581fd60d922bb91345cabda674a Mon Sep 17 00:00:00 2001 From: Alex Newman Date: Wed, 22 Apr 2026 16:11:00 -0700 Subject: [PATCH] docs(skill): cover npm publish and all 6 manifest paths in version-bump The skill previously listed 3 manifest paths and omitted `npm publish` entirely, which meant `npx claude-mem@X.Y.Z` only resolved when someone ran publish out-of-band. Now the skill: - Enumerates all 6 version-bearing files (package.json, plugin/package.json, .claude-plugin/marketplace.json, .claude-plugin/plugin.json, plugin/.claude-plugin/plugin.json, .codex-plugin/plugin.json). - Adds an explicit `npm publish` step with `npm view claude-mem@X.Y.Z version` verification so the npx-distributed version is the one users actually pin. - Documents `npm run release:patch|minor|major` (np helper) as an alternative. - Adds `git grep` pre-flight so new manifests are discovered automatically. Co-Authored-By: Claude Opus 4.7 (1M context) --- plugin/skills/version-bump/SKILL.md | 53 ++++++++++++++++++++--------- 1 file changed, 36 insertions(+), 17 deletions(-) diff --git a/plugin/skills/version-bump/SKILL.md b/plugin/skills/version-bump/SKILL.md index 73e4cc57..31d2b306 100644 --- a/plugin/skills/version-bump/SKILL.md +++ b/plugin/skills/version-bump/SKILL.md @@ -1,42 +1,61 @@ --- name: claude-code-plugin-release -description: Automated semantic versioning and release workflow for Claude Code plugins. Handles version increments across package.json, marketplace.json, and plugin.json, build verification, git tagging, GitHub releases, and changelog generation. +description: Automated semantic versioning and release workflow for Claude Code plugins. Handles version increments across package.json, marketplace.json, plugin.json manifests, npm publishing (so `npx claude-mem@X.Y.Z` resolves), build verification, git tagging, GitHub releases, and changelog generation. --- # Version Bump & Release Workflow -**IMPORTANT:** You must first plan and write detailed release notes before starting the version bump workflow. +**IMPORTANT:** Plan and write detailed release notes before starting. -**CRITICAL:** ALWAYS commit EVERYTHING (including build artifacts). At the end of this workflow, NOTHING should be left uncommitted or unpushed. Run `git status` at the end to verify. +**CRITICAL:** Commit EVERYTHING (including build artifacts). At the end of this workflow, NOTHING should be left uncommitted or unpushed. Run `git status` at the end to verify. ## Preparation -1. **Analyze**: Determine if the change is a **PATCH** (bug fixes), **MINOR** (features), or **MAJOR** (breaking) update. -2. **Environment**: Identify the repository owner and name (e.g., from `git remote -v`). -3. **Paths**: Verify existence of `package.json`, `.claude-plugin/marketplace.json`, and `plugin/.claude-plugin/plugin.json`. +1. **Analyze**: Determine if the change is **PATCH** (bug fixes), **MINOR** (features), or **MAJOR** (breaking). +2. **Environment**: Identify repository owner/name from `git remote -v`. +3. **Paths — every file that carries the version string**: + - `package.json` — **the npm/npx-published version** (`npx claude-mem@X.Y.Z` resolves from this) + - `plugin/package.json` — bundled plugin runtime deps + - `.claude-plugin/marketplace.json` — version inside `plugins[0].version` + - `.claude-plugin/plugin.json` — top-level Claude-plugin manifest + - `plugin/.claude-plugin/plugin.json` — bundled Claude-plugin manifest + - `.codex-plugin/plugin.json` — Codex-plugin manifest + + Verify coverage before editing: `git grep -l "\"version\": \"\""` should list all six. If a new manifest has been added since this doc was last updated, update this list. ## Workflow -1. **Update**: Increment version strings in all configuration files. -2. **Verify**: Use `grep` to ensure all files match the new version. -3. **Build**: Run `npm run build` to generate fresh artifacts. -4. **Commit**: Stage all changes including artifacts: `git add -A && git commit -m "chore: bump version to X.Y.Z"`. -5. **Tag**: Create an annotated tag: `git tag -a vX.Y.Z -m "Version X.Y.Z"`. +1. **Update**: Increment the version string in every path above. Do NOT touch `CHANGELOG.md` — it's regenerated. +2. **Verify**: `git grep -n "\"version\": \"\""` — confirm all six files match. `git grep -n "\"version\": \"\""` — should return zero hits. +3. **Build**: `npm run build` to regenerate artifacts. +4. **Commit**: `git add -A && git commit -m "chore: bump version to X.Y.Z"`. +5. **Tag**: `git tag -a vX.Y.Z -m "Version X.Y.Z"`. 6. **Push**: `git push origin main && git push origin vX.Y.Z`. -7. **Release**: `gh release create vX.Y.Z --title "vX.Y.Z" --notes "RELEASE_NOTES"`. -8. **Changelog**: Regenerate `CHANGELOG.md` using the GitHub API and the provided script: +7. **Publish to npm** (this is what makes `npx claude-mem@X.Y.Z` work): + ```bash + npm publish + ``` + The `prepublishOnly` script re-runs `npm run build` automatically. Confirm publish succeeded: + ```bash + npm view claude-mem@X.Y.Z version # should print X.Y.Z + ``` + Alternative: `npm run release:patch` / `release:minor` / `release:major` invokes `np` and handles tag+push+publish in one shot — use ONLY if you skipped steps 4–6, otherwise `np` will error on the existing tag. +8. **GitHub release**: `gh release create vX.Y.Z --title "vX.Y.Z" --notes "RELEASE_NOTES"`. +9. **Changelog**: Regenerate via the GitHub API + script: ```bash gh api repos/{owner}/{repo}/releases --paginate | ./scripts/generate_changelog.js > CHANGELOG.md ``` -9. **Sync**: Commit and push the updated `CHANGELOG.md`. -10. **Notify**: Run `npm run discord:notify vX.Y.Z` if applicable. -11. **Finalize**: Run `git status` to ensure a clean working tree. +10. **Sync changelog**: Commit and push the updated `CHANGELOG.md`. +11. **Notify**: `npm run discord:notify vX.Y.Z` if applicable. +12. **Finalize**: `git status` — working tree must be clean. ## Checklist -- [ ] All config files have matching versions +- [ ] All six config files have matching versions +- [ ] `git grep` for old version returns zero hits - [ ] `npm run build` succeeded - [ ] Git tag created and pushed +- [ ] **`npm publish` succeeded and `npm view claude-mem@X.Y.Z version` confirms it** (so `npx claude-mem@X.Y.Z` resolves) - [ ] GitHub release created with notes - [ ] `CHANGELOG.md` updated and pushed - [ ] `git status` shows clean tree