Version Bump & Release Workflow
IMPORTANT: Plan and write detailed release notes before starting.
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.
Scope — check this first
This workflow is for one repository and one npm package: thedotmack/claude-mem,
published as claude-mem. It is not a general release recipe. Do not adapt any
step of it to another repository or package.
Before doing anything else, run:
git remote get-url origin # must be github.com/thedotmack/claude-mem(.git)
node -p "require('./package.json').name" # must print claude-mem
If either check fails, stop and tell the user this skill does not apply here.
Preparation
Analyze: Determine if the change is PATCH (bug fixes), MINOR (features), or MAJOR (breaking).
Environment: The repository is
thedotmack/claude-mem, confirmed by the scope check above.Paths — every file that carries the version string:
package.json— the npm/npx-published version (npx claude-mem@X.Y.Zresolves from this)plugin/package.json— bundled plugin runtime deps.claude-plugin/marketplace.json— version insideplugins[0].version.claude-plugin/plugin.json— top-level Claude-plugin manifestplugin/.claude-plugin/plugin.json— bundled Claude-plugin manifest.codex-plugin/plugin.json— Codex-plugin manifestplugin/.codex-plugin/plugin.json— bundled Codex-plugin manifest.qoder-plugin/plugin.json— Qoder plugin manifestplugin/.qoder-plugin/plugin.json— bundled Qoder plugin manifestopenclaw/openclaw.plugin.json— OpenClaw plugin manifest.grok-plugin/plugin.json— Grok plugin manifestclaude-mem-cursor/.cursor-plugin/plugin.json— Cursor plugin manifestclaude-mem-grok-bot/.cursor-plugin/plugin.json— Grok Bot Cursor plugin manifestdsh/package.json— bundled DSH plugin packageREADME.md— the version badge (version-X.Y.Z-green), not a"version"key
Verify coverage before editing:
git grep -l "\"version\": \"<OLD>\""should list the fourteen JSON files above, andgit grep -n "version-<OLD>-green"the README badge. If a new manifest has been added since this doc was last updated, update this list.
Workflow
- Update: Increment the version string in every path above. Do NOT touch
docs/CHANGELOG.md— it's regenerated. - Verify:
git grep -n "\"version\": \"<NEW>\""— confirm all fourteen JSON files match, and the README badge readsversion-<NEW>-green.git grep -n "\"version\": \"<OLD>\""— should return zero hits. - Build and sync:
npm run build-and-syncto regenerate artifacts, sync the local marketplace copy, restart the worker, and clear the queue. Do not use plainnpm run buildfor release validation because it can leave the local marketplace/worker out of sync. - Commit:
git add -A && git commit -m "chore: bump version to X.Y.Z". - Tag:
git tag -a vX.Y.Z -m "Version X.Y.Z". - Push:
git push origin main && git push origin vX.Y.Z. - GitHub release:
gh release create vX.Y.Z --title "vX.Y.Z" --notes "RELEASE_NOTES". - Changelog: Regenerate via the project's changelog script:
(Runsnpm run changelog:generatenode scripts/generate-changelog.js, which pulls releases from the GitHub API and rewritesdocs/CHANGELOG.md.) - Sync changelog: Commit and push the updated
docs/CHANGELOG.md. - Pre-publish audit: Verify the release commit, tag, GitHub release, and changelog are pushed, and the release worktree has no pending tracked changes.
- Publish to npm — the workflow does it. Pushing the
vX.Y.Ztag triggers.github/workflows/npm-publish.yml, which builds, runs the clean-room smoke and publishes through npm trusted publishing (GitHub OIDC), so it needs no npm token. Watch the run:
Do not rungh run list --workflow npm-publish.yml --branch vX.Y.Z # tag runs report the tag as their branch gh run watch <run-id> --exit-statusnpm publishlocally, even if a local npm login works: the workflow is the only publish path, and only it attaches provenance. If the run fails, read the failing step withgh run view <run-id> --log-failed. A transient failure (network, registry outage) is re-run withgh run rerun <run-id>; a re-run builds the same tagged commit, so a fix in the code or workflow ships through a PR and the next patch release instead. Never move or recreate a pushed tag. The trusted publisher lives on npmjs.com →claude-mem→ Settings → Trusted Publisher (GitHub Actions,thedotmack/claude-mem,npm-publish.yml,npm publishallowed). Renaming the workflow file breaks publishing until that entry is updated; changing it requires the maintainer's security key. - Post-publish verification: After publishing, verify
both the exact version and the latest dist-tag:
npm view claude-mem@X.Y.Z version npm view claude-mem dist-tags.latest npm view claude-mem@X.Y.Z dist.attestations --json # provenance from the workflow - Promote for auto-update:
releases/promoted-release.jsononmainnames the version claude-mem's own updater moves installs to. Promote, hold and pull back control only that updater: installs where Claude Code's own auto-update for this marketplace is on followmaininstead, so a bad release that reachedmainis fixed with a new patch release. Do this step only after npm verification.- Promote: these commands work from a detached release worktree and
when
mainhas moved since the release push:
If the push is rejected becausegit pull --rebase origin main # set "promotedVersion" in releases/promoted-release.json to "X.Y.Z" bun test tests/infrastructure/promoted-release.test.ts git add releases/promoted-release.json git commit -m "chore: promote X.Y.Z for auto-update" git push origin HEAD:mainmainmoved again (git reportsnon-fast-forwardorfetch first), rungit pull --rebase origin mainand push again. Most installs update within about a day; a machine that is never quiet updates within about two days. - Hold: only when the owner asked to hold this release. Skip this step and say so in the release report.
- Pull back a bad release: set
promotedVersionto the last good version (find it withgit log -p -- releases/promoted-release.json) and push it with the same commands. Installs below it still move up to it. Installs already on the bad version stay there until a newer version is promoted. Nothing is downgraded.
- Promote: these commands work from a detached release worktree and
when
- Notification: Post the release to X, only after npm verification:
- Generate one image about the release with an available image-generation tool, drawn from the release notes.
- In a browser that is already logged in to X (for example Claude in
Chrome), open x.com and check the active account is
@Claude_Memory. If no browser is logged in, or the account is a different one, skip the post and say so in the release report. Never sign in or switch accounts. - Post a short summary of the release with the version, the GitHub release URL and the image attached, then report the post's URL.
- Finalize:
git status— working tree must be clean and everything must be pushed.
Checklist
- All fifteen version files (fourteen JSON manifests and the README badge) have matching versions
-
git grepfor old version returns zero hits -
npm run build-and-syncsucceeded - Git tag created and pushed
- GitHub release created with notes
-
docs/CHANGELOG.mdupdated and pushed - Pre-publish audit passed
-
Publish to npmworkflow run for the tag succeeded (no localnpm publish) - Exact npm version and
latestboth verified after publishing -
releases/promoted-release.jsonset to X.Y.Z and pushed tomainafter npm verification (or the owner's hold stated in the release report) - Release posted to X as
@Claude_Memorywith a generated image after npm verification (or skipped because no browser was logged in as that account) -
git statusshows clean tree