diff --git a/.claude/skills/version-bump/SKILL.md b/.claude/skills/version-bump/SKILL.md index 8b598fd9..66040b04 100644 --- a/.claude/skills/version-bump/SKILL.md +++ b/.claude/skills/version-bump/SKILL.md @@ -5,94 +5,76 @@ description: Manage semantic version updates for claude-mem project. Handles pat # Version Bump Skill -Manage semantic versioning across the claude-mem project with consistent updates to all version-tracked files. +**IMPORTANT:** You must first ultrathink and write detailed release notes before starting the version bump workflow. -## Quick Reference +## Version Types + +- **PATCH** (x.y.Z): Bug fixes only +- **MINOR** (x.Y.0): New features, backward compatible +- **MAJOR** (X.0.0): Breaking changes + +## Files to Update (ALL THREE) -**Files requiring updates (ALL THREE):** 1. `package.json` (line 3) 2. `.claude-plugin/marketplace.json` (line 13) 3. `plugin/.claude-plugin/plugin.json` (line 3) -**Semantic versioning:** -- **PATCH** (x.y.Z): Bugfixes only -- **MINOR** (x.Y.0): New features, backward compatible -- **MAJOR** (X.0.0): Breaking changes - -## Quick Decision Guide - -**What changed?** -- "Fixed a bug" → PATCH (5.3.0 → 5.3.1) -- "Added new feature" → MINOR (5.3.0 → 5.4.0) -- "Breaking change" → MAJOR (5.3.0 → 6.0.0) - -**If unclear, ASK THE USER explicitly.** - -## Standard Workflow - -See [operations/workflow.md](operations/workflow.md) for detailed step-by-step process. - -**Quick version:** -1. Determine version type (PATCH/MINOR/MAJOR) -2. Calculate new version from current -3. Preview changes to user -4. Update ALL THREE files -5. Verify consistency -6. Build and test -7. Commit and create git tag -8. Push and create GitHub release -9. Generate CHANGELOG.md from releases and commit -10. Post Discord notification - -## Common Scenarios - -See [operations/scenarios.md](operations/scenarios.md) for examples: -- Bug fix releases -- New feature releases -- Breaking change releases - -## Critical Rules - -**ALWAYS:** -- Update ALL THREE files with matching version numbers -- Create git tag with format `vX.Y.Z` -- Create GitHub release from the tag -- Generate CHANGELOG.md from releases after creating release -- Post Discord notification after release -- Ask user if version type is unclear - -**NEVER:** -- Update only one or two files -- Skip the verification step -- Forget to create git tag or GitHub release - -## Verification Checklist - -Before considering the task complete: -- [ ] All THREE files have matching version numbers -- [ ] `npm run build` succeeds -- [ ] Git commit created with all version files -- [ ] Git tag created (format: vX.Y.Z) -- [ ] Commit and tags pushed to remote -- [ ] GitHub release created from the tag -- [ ] CHANGELOG.md generated and committed -- [ ] Discord notification sent - -## Reference Commands +## Workflow ```bash -# View current version -grep '"version"' package.json - -# Verify consistency across all version files +# 1. Check current version grep '"version"' package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json -# View git tags -git tag -l -n1 +# 2. Update all 3 files to new version (use Edit tool) -# Check what will be committed -git status -git diff package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json +# 3. Verify consistency +grep '"version"' package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json + +# 4. Build +npm run build + +# 5. Commit version files +git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json +git commit -m "chore: bump version to X.Y.Z" + +# 6. Create tag +git tag -a vX.Y.Z -m "Version X.Y.Z" + +# 7. Push +git push origin main && git push origin vX.Y.Z + +# 8. Create GitHub release (use your detailed release notes here) +gh release create vX.Y.Z --title "vX.Y.Z" --notes "RELEASE_NOTES_HERE" + +# 9. Generate CHANGELOG.md from releases +gh api repos/thedotmack/claude-mem/releases --paginate | node -e " +const releases = JSON.parse(require('fs').readFileSync(0, 'utf8')); +const lines = ['# Changelog', '', 'All notable changes to claude-mem.', '']; +releases.slice(0, 50).forEach(r => { + const date = r.published_at.split('T')[0]; + lines.push('## [' + r.tag_name + '] - ' + date); + lines.push(''); + if (r.body) lines.push(r.body.trim()); + lines.push(''); +}); +console.log(lines.join('\n')); +" > CHANGELOG.md + +# 10. Commit CHANGELOG +git add CHANGELOG.md +git commit -m "docs: update CHANGELOG.md for vX.Y.Z" +git push origin main + +# 11. Discord notification +npm run discord:notify vX.Y.Z ``` -For more commands, see [operations/reference.md](operations/reference.md). +## Checklist + +- [ ] Ultrathink + write detailed release notes +- [ ] All 3 files have matching version +- [ ] `npm run build` succeeds +- [ ] Git tag created (vX.Y.Z format) +- [ ] GitHub release created with detailed notes +- [ ] CHANGELOG.md updated +- [ ] Discord notification sent (if webhook configured) diff --git a/.claude/skills/version-bump/operations/reference.md b/.claude/skills/version-bump/operations/reference.md deleted file mode 100644 index 9f9aedd3..00000000 --- a/.claude/skills/version-bump/operations/reference.md +++ /dev/null @@ -1,265 +0,0 @@ -# Version Bump Reference - -Quick reference for version bump commands and file locations. - -## File Locations - -### Version-Tracked Files (ALL THREE) - -1. **package.json** - - Path: `package.json` - - Line: 3 - - Format: `"version": "X.Y.Z",` - -2. **marketplace.json** - - Path: `.claude-plugin/marketplace.json` - - Line: 13 - - Format: `"version": "X.Y.Z",` - -3. **plugin.json** - - Path: `plugin/.claude-plugin/plugin.json` - - Line: 3 - - Format: `"version": "X.Y.Z",` - -## Essential Commands - -### View Current Version - -```bash -# From package.json -grep '"version"' package.json - -# Extract just the version number -grep '"version"' package.json | head -1 | sed 's/.*"version": "\(.*\)".*/\1/' - -# From all version files -grep '"version"' package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json -``` - -### Verify Version Consistency - -```bash -# Check all JSON files match -grep '"version"' package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json - -# Should output identical version in all three: -# package.json:3: "version": "5.3.0", -# .claude-plugin/marketplace.json:13: "version": "5.3.0", -# plugin/.claude-plugin/plugin.json:3: "version": "5.3.0", -``` - -### Git Commands - -```bash -# View recent commits -git log --oneline -5 - -# View changes since last tag -LAST_TAG=$(git describe --tags --abbrev=0) -git log $LAST_TAG..HEAD --oneline -git diff $LAST_TAG..HEAD - -# List all tags -git tag -l - -# View tag details -git show vX.Y.Z - -# List tags with messages -git tag -l -n1 -``` - -### Build and Test - -```bash -# Build plugin -npm run build - -# Sync to marketplace -npm run sync-marketplace - -# Run tests (if available) -npm test -``` - -### Commit and Tag - -```bash -# Stage version files -git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json plugin/scripts/ - -# Commit -git commit -m "Release vX.Y.Z: [Description]" - -# Create tag -git tag vX.Y.Z -m "Release vX.Y.Z: [Description]" - -# Push -git push && git push --tags -``` - -### GitHub Release - -```bash -# Create release -gh release create vX.Y.Z --title "vX.Y.Z" --notes "[Release notes]" - -# Create with auto-generated notes -gh release create vX.Y.Z --title "vX.Y.Z" --generate-notes - -# View release -gh release view vX.Y.Z - -# List all releases -gh release list - -# Delete release (if needed) -gh release delete vX.Y.Z -``` - -## Semantic Versioning Rules - -### Version Format: MAJOR.MINOR.PATCH - -**MAJOR (X.0.0):** -- Breaking changes -- Incompatible API changes -- Schema changes requiring migration -- Removes features - -**MINOR (x.Y.0):** -- New features (backward compatible) -- New functionality -- Deprecations (but not removals) -- Resets PATCH to 0 - -**PATCH (x.y.Z):** -- Bug fixes -- Performance improvements -- Documentation fixes -- No new features - -### Incrementing Rules - -``` -PATCH: 5.3.2 → 5.3.3 -MINOR: 5.3.2 → 5.4.0 (resets patch) -MAJOR: 5.3.2 → 6.0.0 (resets minor and patch) -``` - -## Common Patterns - -### Bug Fix Release - -```bash -# Example: 5.3.0 → 5.3.1 -# 1. Update all three files to 5.3.1 -# 2. Build and test -npm run build -# 3. Commit and tag -git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json plugin/scripts/ -git commit -m "Release v5.3.1: Fixed observer crash" -git tag v5.3.1 -m "Release v5.3.1: Fixed observer crash" -git push && git push --tags -# 4. Create release -gh release create v5.3.1 --title "v5.3.1" --notes "Fixed observer crash on empty content" -``` - -### Feature Release - -```bash -# Example: 5.3.0 → 5.4.0 -# 1. Update all three files to 5.4.0 -# 2. Build and test -npm run build -# 3. Commit and tag -git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json plugin/scripts/ -git commit -m "Release v5.4.0: Added dark mode support" -git tag v5.4.0 -m "Release v5.4.0: Added dark mode support" -git push && git push --tags -# 4. Create release -gh release create v5.4.0 --title "v5.4.0" --generate-notes -``` - -### Breaking Change Release - -```bash -# Example: 5.3.0 → 6.0.0 -# 1. Update all three files to 6.0.0 -# 2. Build and test -npm run build -# 3. Commit and tag -git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json plugin/scripts/ -git commit -m "Release v6.0.0: Storage layer redesign" -git tag v6.0.0 -m "Release v6.0.0: Storage layer redesign" -git push && git push --tags -# 4. Create release with warning -gh release create v6.0.0 --title "v6.0.0" --notes "⚠️ Breaking change: Storage layer redesigned. Migration required." -``` - -## Rollback Commands - -### Delete Tag - -```bash -# Delete local tag -git tag -d vX.Y.Z - -# Delete remote tag -git push origin :refs/tags/vX.Y.Z -# Or: git push --delete origin vX.Y.Z -``` - -### Delete Release - -```bash -# Delete GitHub release -gh release delete vX.Y.Z - -# Confirm deletion -gh release delete vX.Y.Z --yes -``` - -### Revert Commit - -```bash -# Revert last commit (creates new commit) -git revert HEAD - -# Reset to previous commit (destructive) -git reset --hard HEAD~1 -git push --force # Dangerous! Only if not shared -``` - -## Error Prevention - -### Pre-commit Checks - -```bash -# Check all versions match before committing -V1=$(grep '"version"' package.json | head -1 | sed 's/.*"\([^"]*\)".*/\1/') -V2=$(grep '"version"' .claude-plugin/marketplace.json | sed 's/.*"\([^"]*\)".*/\1/') -V3=$(grep '"version"' plugin/.claude-plugin/plugin.json | head -1 | sed 's/.*"\([^"]*\)".*/\1/') - -if [ "$V1" = "$V2" ] && [ "$V2" = "$V3" ]; then - echo "✓ All versions match: $V1" -else - echo "✗ Version mismatch!" - echo " package.json: $V1" - echo " marketplace.json: $V2" - echo " plugin.json: $V3" -fi -``` - -### Pre-push Checks - -```bash -# Check tag exists -git tag -l | grep vX.Y.Z || echo "Warning: Tag not created" - -# Check build succeeds -npm run build || echo "Error: Build failed" - -# Check no uncommitted changes -git status --porcelain | grep -q . && echo "Warning: Uncommitted changes" -``` diff --git a/.claude/skills/version-bump/operations/scenarios.md b/.claude/skills/version-bump/operations/scenarios.md deleted file mode 100644 index fcd18b04..00000000 --- a/.claude/skills/version-bump/operations/scenarios.md +++ /dev/null @@ -1,218 +0,0 @@ -# Common Version Bump Scenarios - -Real-world examples of version bumps with decision rationale. - -## Scenario 1: Bug Fix After Testing - -**User request:** -> "Fixed the memory leak in the search function" - -**Analysis:** -- What changed: Bug fix -- Breaking changes: No -- New features: No -- **Decision: PATCH** - -**Workflow:** -``` -Current: 4.2.8 -New: 4.2.9 (PATCH) - -Steps: -1. Update all three files to 4.2.9 -2. npm run build -3. git commit -m "Release v4.2.9: Fixed memory leak in search" -4. git tag v4.2.9 -m "Release v4.2.9: Fixed memory leak in search" -5. git push && git push --tags -6. gh release create v4.2.9 --title "v4.2.9" --notes "Fixed memory leak in search function" -``` - -## Scenario 2: New Feature Added - -**User request:** -> "Added web search MCP integration" - -**Analysis:** -- What changed: New feature (MCP integration) -- Breaking changes: No -- Backward compatible: Yes -- **Decision: MINOR** - -**Workflow:** -``` -Current: 4.2.8 -New: 4.3.0 (MINOR - reset patch to 0) - -Steps: -1. Update all three files to 4.3.0 -2. npm run build -3. git commit -m "Release v4.3.0: Added web search MCP integration" -4. git tag v4.3.0 -m "Release v4.3.0: Added web search MCP integration" -5. git push && git push --tags -6. gh release create v4.3.0 --title "v4.3.0" --generate-notes -``` - -## Scenario 3: Database Schema Redesign - -**User request:** -> "Rewrote storage layer, old data needs migration" - -**Analysis:** -- What changed: Storage layer rewrite -- Breaking changes: Yes (requires migration) -- Backward compatible: No -- **Decision: MAJOR** - -**Workflow:** -``` -Current: 4.2.8 -New: 5.0.0 (MAJOR - reset minor and patch to 0) - -Steps: -1. Update all three files to 5.0.0 -2. npm run build -3. git commit -m "Release v5.0.0: Storage layer redesign with migration required" -4. git tag v5.0.0 -m "Release v5.0.0: Storage layer redesign" -5. git push && git push --tags -6. gh release create v5.0.0 --title "v5.0.0" --notes "⚠️ Breaking change: Storage layer redesigned. Migration required." -``` - -## Scenario 4: Multiple Small Bug Fixes - -**User request:** -> "Fixed three bugs: observer crash, viewer pagination, and date formatting" - -**Analysis:** -- What changed: Multiple bug fixes -- Breaking changes: No -- New features: No -- **Decision: PATCH** (one patch covers all fixes) - -**Workflow:** -``` -Current: 4.2.8 -New: 4.2.9 (PATCH) - -Steps: -1. Update all three files to 4.2.9 -2. npm run build -3. git commit -m "Release v4.2.9: Multiple bug fixes - -- Fixed observer crash on empty content -- Fixed viewer pagination edge case -- Fixed date formatting in timeline" -4. git tag v4.2.9 -m "Release v4.2.9: Multiple bug fixes" -5. git push && git push --tags -6. gh release create v4.2.9 --title "v4.2.9" --generate-notes -``` - -## Scenario 5: Feature + Bug Fix - -**User request:** -> "Added dark mode support and fixed the viewer crash bug" - -**Analysis:** -- What changed: New feature + bug fix -- Breaking changes: No -- **Decision: MINOR** (feature trumps bug fix) - -**Workflow:** -``` -Current: 5.1.0 -New: 5.2.0 (MINOR) - -Steps: -1. Update all three files to 5.2.0 -2. npm run build -3. git commit -m "Release v5.2.0: Dark mode support + bug fixes - -Features: -- Added dark mode toggle to viewer UI - -Bug fixes: -- Fixed viewer crash on empty database" -4. git tag v5.2.0 -m "Release v5.2.0: Dark mode support" -5. git push && git push --tags -6. gh release create v5.2.0 --title "v5.2.0" --generate-notes -``` - -## Scenario 6: Documentation Only - -**User request:** -> "Updated README with new installation instructions" - -**Analysis:** -- What changed: Documentation only -- Breaking changes: No -- Code changes: No -- **Decision: PATCH** (or skip version bump if no code changes) - -**Workflow:** -``` -Option 1: PATCH (if you want to tag doc improvements) -Current: 4.2.8 -New: 4.2.9 - -Option 2: No version bump (documentation-only changes don't require versioning) -Just commit without bumping version -``` - -**Recommendation:** Skip version bump for documentation-only changes unless it's a significant documentation overhaul. - -## Scenario 7: Configuration Change - -**User request:** -> "Changed default observation count from 50 to 30" - -**Analysis:** -- What changed: Default configuration -- Breaking changes: Yes (behavior changes) -- Users might notice different context size -- **Decision: MINOR or MAJOR** (ask user) - -**Workflow:** -``` -Ask user: -"This changes default behavior (context size). Users will see different results. -Is this: -- MINOR (acceptable behavior change): 4.2.8 → 4.3.0 -- MAJOR (breaking change): 4.2.8 → 5.0.0 - -Which should I use?" -``` - -## Scenario 8: Dependency Update - -**User request:** -> "Updated Claude SDK from 1.2.0 to 1.3.0" - -**Analysis:** -- What changed: Dependency version -- Breaking changes: Depends on SDK changes -- **Decision: Ask user or check SDK changelog** - -**Workflow:** -``` -1. Check SDK changelog for breaking changes -2. If SDK has breaking changes → MAJOR -3. If SDK adds features → MINOR -4. If SDK only fixes bugs → PATCH - -Typical: PATCH (unless SDK breaks compatibility) -``` - -## Decision Tree - -``` -Is there a breaking change? -├─ Yes → MAJOR (X.0.0) -└─ No - ├─ Is there a new feature? - │ ├─ Yes → MINOR (x.Y.0) - │ └─ No - │ ├─ Is there a bug fix? - │ │ ├─ Yes → PATCH (x.y.Z) - │ │ └─ No → Don't bump version (docs only, etc.) - │ └─ Configuration change? → Ask user (MINOR or MAJOR) - └─ Multiple changes? → Use highest level (MAJOR > MINOR > PATCH) -``` diff --git a/.claude/skills/version-bump/operations/workflow.md b/.claude/skills/version-bump/operations/workflow.md deleted file mode 100644 index 6e2e4137..00000000 --- a/.claude/skills/version-bump/operations/workflow.md +++ /dev/null @@ -1,249 +0,0 @@ -# Detailed Version Bump Workflow - -Step-by-step process for bumping versions in the claude-mem project. - -## Step 1: Analyze Changes - -First, understand what changed: - -```bash -# View recent commits -git log --oneline -5 - -# See what changed in last commit -git diff HEAD~1 - -# Or see all changes since last tag -LAST_TAG=$(git describe --tags --abbrev=0) -git log $LAST_TAG..HEAD --oneline -git diff $LAST_TAG..HEAD -``` - -## Step 2: Determine Version Type - -Ask yourself: -- **Breaking changes?** → MAJOR -- **New features?** → MINOR -- **Bugfixes only?** → PATCH - -**If unclear, ASK THE USER explicitly.** - -### Decision Matrix - -| Change Type | Version Bump | Example | -|------------|--------------|---------| -| Bug fix | PATCH | 4.2.8 → 4.2.9 | -| New feature (backward compatible) | MINOR | 4.2.8 → 4.3.0 | -| Breaking change | MAJOR | 4.2.8 → 5.0.0 | -| Multiple features | MINOR | 4.2.8 → 4.3.0 | -| Feature + breaking change | MAJOR | 4.2.8 → 5.0.0 | - -## Step 3: Calculate New Version - -From current version in `package.json`: - -```bash -grep '"version"' package.json -``` - -Apply semantic versioning rules: -- **Patch:** increment Z (4.2.8 → 4.2.9) -- **Minor:** increment Y, reset Z (4.2.8 → 4.3.0) -- **Major:** increment X, reset Y and Z (4.2.8 → 5.0.0) - -## Step 4: Preview Changes - -**BEFORE making changes, show the user:** - -``` -Current version: 4.2.8 -New version: 4.2.9 (PATCH) -Reason: Fixed database query bug - -Files to update: -- package.json: "version": "4.2.9" -- marketplace.json: "version": "4.2.9" -- plugin.json: "version": "4.2.9" -- Git tag: v4.2.9 - -Proceed? (yes/no) -``` - -Wait for user confirmation before proceeding. - -## Step 5: Update Files - -### Update package.json - -File: `package.json` - -```json -{ - "name": "claude-mem", - "version": "4.2.9", - ... -} -``` - -Update line 3 with new version. - -### Update marketplace.json - -File: `.claude-plugin/marketplace.json` - -```json -{ - "name": "claude-mem", - "version": "4.2.9", - ... -} -``` - -Update line 13 with new version. - -### Update plugin.json - -File: `plugin/.claude-plugin/plugin.json` - -```json -{ - "name": "claude-mem", - "version": "4.2.9", - ... -} -``` - -Update line 3 with new version. - -## Step 6: Verify Consistency - -```bash -# Check all versions match -grep -n '"version"' package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json - -# Should show same version in all three files: -# package.json:3: "version": "4.2.9", -# .claude-plugin/marketplace.json:13: "version": "4.2.9", -# plugin/.claude-plugin/plugin.json:3: "version": "4.2.9", -``` - -All three must match exactly. - -## Step 7: Test - -```bash -# Verify the plugin loads correctly -npm run build -``` - -Build must succeed before proceeding. - -## Step 8: Commit and Tag - -```bash -# Stage all version files -git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json plugin/scripts/ - -# Commit with descriptive message -git commit -m "Release vX.Y.Z: [Brief description] - -[Optional detailed description] - -🤖 Generated with [Claude Code](https://claude.com/claude-code) - -Co-Authored-By: Claude " - -# Create annotated git tag -git tag vX.Y.Z -m "Release vX.Y.Z: [Brief description]" - -# Push commit and tags -git push && git push --tags -``` - -Replace `X.Y.Z` with actual version (e.g., `4.2.9`). - -## Step 9: Create GitHub Release - -```bash -# Create GitHub release from the tag -gh release create vX.Y.Z --title "vX.Y.Z" --notes "[Brief release notes]" - -# Or generate notes automatically from commits -gh release create vX.Y.Z --title "vX.Y.Z" --generate-notes -``` - -**IMPORTANT:** Always create the GitHub release immediately after pushing the tag. This makes the release discoverable to users and triggers any automated workflows. - -## Step 10: Generate CHANGELOG - -After creating the GitHub release, regenerate CHANGELOG.md from all releases: - -```bash -# Generate CHANGELOG.md from all GitHub releases -npm run changelog:generate - -# Review the generated changelog -git diff CHANGELOG.md - -# Commit and push the updated changelog -git add CHANGELOG.md -git commit -m "Update CHANGELOG.md for vX.Y.Z release" -git push -``` - -**Why this step:** -- CHANGELOG.md is auto-generated from GitHub releases -- Keeps the changelog in sync with release notes -- No manual editing required -- Single source of truth: GitHub releases - -## Step 11: Discord Notification - -Post release announcement to the Discord updates channel: - -```bash -# Send Discord notification with release details -npm run discord:notify vX.Y.Z -``` - -This fetches the release notes from GitHub and posts a formatted embed to the Discord updates channel configured in `.env`. - -## Verification - -After completing all steps, verify: - -```bash -# Check git tag created -git tag -l | grep vX.Y.Z - -# Check remote has tag -git ls-remote --tags origin | grep vX.Y.Z - -# Check GitHub release exists -gh release view vX.Y.Z - -# Verify versions match -grep '"version"' package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json -``` - -All checks should pass. - -## Rollback (If Needed) - -If you made a mistake: - -```bash -# Delete local tag -git tag -d vX.Y.Z - -# Delete remote tag (if already pushed) -git push origin :refs/tags/vX.Y.Z - -# Delete GitHub release (if created) -gh release delete vX.Y.Z - -# Revert commits if needed -git revert HEAD -``` - -Then restart the workflow with correct version.