thedotmack 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.
Preparation
Analyze: Determine if the change is PATCH (bug fixes), MINOR (features), or MAJOR (breaking).
Environment: Identify repository owner/name from
git remote -v.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 manifestopenclaw/openclaw.plugin.json— OpenClaw plugin manifest
Verify coverage before editing:
git grep -l "\"version\": \"<OLD>\""should list all eight. 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
CHANGELOG.md— it's regenerated. - Verify:
git grep -n "\"version\": \"<NEW>\""— confirm all eight files match.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. - Publish to npm — HAND OFF TO HUMAN. The human maintainer raised npm
security, so publishing now requires credentials/2FA only they can provide.
The agent MUST NOT run
npm publish(ornp/npm run release:*, which also publish) itself. Hand off NPM publishing to the human now: stop and tell them the version is committed, tagged, and pushed, and that they must publish to npm to makenpx claude-mem@X.Y.Zresolve. Give them the command:
Wait for the human to confirm they published, then verify it landed:npm publish # run by the HUMAN — the prepublishOnly script rebuilds the package
If the publish build touched local artifacts, runnpm view claude-mem@X.Y.Z version # should print X.Y.Znpm run build-and-syncagain afterward. - 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 rewritesCHANGELOG.md.) - Sync changelog: Commit and push the updated
CHANGELOG.md. - Notify: Run the Discord notification from
~/Scripts/claude-mem/, where the.envwith Discord webhook details lives:
Do this even when the release worktree does not have a localcd ~/Scripts/claude-mem/ && npm run discord:notify vX.Y.Z.env. - Finalize:
git status— working tree must be clean.
Checklist
- All eight config files have matching versions
-
git grepfor old version returns zero hits -
npm run build-and-syncsucceeded - Git tag created and pushed
- NPM publishing handed off to the human (agent does NOT run
npm publish— human raised security); once they publish,npm view claude-mem@X.Y.Z versionconfirms it (sonpx claude-mem@X.Y.Zresolves) - GitHub release created with notes
-
CHANGELOG.mdupdated and pushed - Discord notification run from
~/Scripts/claude-mem/ -
git statusshows clean tree