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

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 [email protected] 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
   • openclaw/openclaw.plugin.json — OpenClaw plugin manifest

   Verify coverage before editing: git grep -l "\"version\": \"<OLD>\"" should list all seven. If a new manifest has been added since this doc was last updated, update this list.

Workflow

1. Update: Increment the version string in every path above. Do NOT touch CHANGELOG.md — it's regenerated.
2. Verify: git grep -n "\"version\": \"<NEW>\"" — confirm all seven files match. git grep -n "\"version\": \"<OLD>\"" — should return zero hits.
3. 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.
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. Publish to npm (this is what makes npx [email protected] work):
   bashCopy

   npm publish
   

   The prepublishOnly script re-runs the package build automatically. After publish, run npm run build-and-sync again if the publish build touched local artifacts. Confirm publish succeeded:
   bashCopy

   npm view [email protected] 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 project's changelog script:
   bashCopy

   npm run changelog:generate
   

   (Runs node scripts/generate-changelog.js, which pulls releases from the GitHub API and rewrites CHANGELOG.md.)
10. Sync changelog: Commit and push the updated CHANGELOG.md.
11. Notify: Run the Discord notification from ~/Scripts/claude-mem/, where the .env with Discord webhook details lives:
    bashCopy

    cd ~/Scripts/claude-mem/ && npm run discord:notify vX.Y.Z
    

    Do this even when the release worktree does not have a local .env.
12. Finalize: git status — working tree must be clean.

Checklist

• All seven config files have matching versions
• git grep for old version returns zero hits
• npm run build-and-sync succeeded
• Git tag created and pushed
• npm publish succeeded and npm view [email protected] version confirms it (so npx [email protected] resolves)
• GitHub release created with notes
• CHANGELOG.md updated and pushed
• Discord notification run from ~/Scripts/claude-mem/
• git status shows clean tree