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.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
- ```
plugin/.codex-plugin/plugin.json
```
  — bundled Codex-plugin manifest
- ```
openclaw/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.

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-sync
```
to regenerate artifacts, sync the local marketplace copy, restart the worker, and clear the queue. Do not use plain
```
npm run build
```
for 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"

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
```
(or
```
np
```
/
```
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 make
```
npx claude-mem@X.Y.Z
```
resolve. Give them the command:
bash
```
npm publish   # run by the HUMAN — the prepublishOnly script rebuilds the package
```
Wait for the human to confirm they published, then verify it landed:
bash
```
npm view claude-mem@X.Y.Z version   # should print X.Y.Z
```
If the publish build touched local artifacts, run
```
npm run build-and-sync
```
again afterward.

GitHub release:

gh release create vX.Y.Z --title "vX.Y.Z" --notes "RELEASE_NOTES"

Changelog: Regenerate via the project's changelog script:
bash
```
npm run changelog:generate
```
(Runs
```
node scripts/generate-changelog.js
```
, which pulls releases from the GitHub API and rewrites
```
CHANGELOG.md
```
.)
Sync changelog: Commit and push the updated
```
CHANGELOG.md
```
.
Notify: Run the Discord notification from
```
~/Scripts/claude-mem/
```
, where the
```
.env
```
with Discord webhook details lives:
bash
```
cd ~/Scripts/claude-mem/ && npm run discord:notify vX.Y.Z
```
Do this even when the release worktree does not have a local
```
.env
```
.
Finalize:
```
git status
```
— working tree must be clean.