eliott/claude-mem
1
0
Fork 0
mirror of https://github.com/thedotmack/claude-mem synced 2026-04-25 17:15:04 +02:00
Code Issues Packages Projects Releases Wiki Activity

feat: Add search skill with progressive disclosure and refactor existing skills

Browse Source 
Enhancements:
- Added search skill with 10 HTTP API endpoints for memory queries
- Refactored version-bump and troubleshoot skills using progressive disclosure pattern
- Added operations/ subdirectories for detailed skill documentation
- Updated CLAUDE.md with skill-based search architecture
- Enhanced worker service with search API endpoints
- Updated CHANGELOG.md with v5.4.0 migration details

Technical changes:
- New plugin/skills/search/ directory with SKILL.md
- New .claude/skills/version-bump/operations/ (workflow.md, scenarios.md)
- New plugin/skills/troubleshoot/operations/ (common-issues.md, worker.md)
- Modified src/services/worker-service.ts (added search endpoints)
- Modified plugin/scripts/worker-service.cjs (rebuilt with search API)
- Reduced main skill files by 89% using progressive disclosure
- Token savings: ~2,250 tokens per session start

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Alex Newman
2025-11-09 18:41:53 -05:00
parent 0475a57fb1
commit ca4f046777
30 changed files with 4378 additions and 587 deletions
Download Patch File Download Diff File Expand all files Collapse all files

221
.claude/skills/version-bump/SKILL.md
View File

@@ -5,208 +5,91 @@ description: Manage semantic version updates for claude-mem project. Handles pat
# Version Bump Skill
IMPORTANT: This skill manages semantic versioning across the claude-mem project. YOU MUST update all FOUR version-tracked files consistently and create a git tag.
Manage semantic versioning across the claude-mem project with consistent updates to all version-tracked files.
## Quick Reference
**Files requiring updates:**
**Files requiring updates (ALL FOUR):**
1. `package.json` (line 3)
2. `.claude-plugin/marketplace.json` (line 13)
3. `plugin/.claude-plugin/plugin.json` (line 3)
4. `CLAUDE.md` (line 9 ONLY - version number, NOT version history)
**Semantic versioning:**
- PATCH (x.y.Z): Bugfixes only
- MINOR (x.Y.0): New features, backward compatible
- MAJOR (X.0.0): Breaking changes
- **PATCH** (x.y.Z): Bugfixes only
- **MINOR** (x.Y.0): New features, backward compatible
- **MAJOR** (X.0.0): Breaking changes
## Workflow
## Quick Decision Guide
When invoked, follow this process:
**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)
### 1. Analyze Changes
First, understand what changed:
```bash
git log --oneline -5
git diff HEAD~1
```
**If unclear, ASK THE USER explicitly.**
### 2. Determine Version Type
Ask yourself:
- Breaking changes? → MAJOR
- New features? → MINOR
- Bugfixes only? → PATCH
## Standard Workflow
If unclear, ASK THE USER explicitly.
See [operations/workflow.md](operations/workflow.md) for detailed step-by-step process.
### 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)
### 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"
- CLAUDE.md line 9: "**Current Version**: 4.2.9" (version number ONLY)
- Git tag: v4.2.9
Proceed? (yes/no)
```
### 5. Update Files
**Update package.json:**
```json
{
"name": "claude-mem",
"version": "4.2.9",
...
}
```
**Update .claude-plugin/marketplace.json:**
```json
{
"name": "claude-mem",
"version": "4.2.9",
...
}
```
**Update plugin/.claude-plugin/plugin.json:**
```json
{
"name": "claude-mem",
"version": "4.2.9",
...
}
```
**Update CLAUDE.md:**
ONLY update line 9 with the version number:
```markdown
**Current Version**: 4.2.9
```
**CRITICAL**: DO NOT add version history entries to CLAUDE.md. Version history is managed separately outside this skill.
### 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
```
### 7. Test
```bash
# Verify the plugin loads correctly
npm run build
```
### 8. Commit and Tag
```bash
# Stage all version files
git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json CLAUDE.md plugin/scripts/
# Commit with descriptive message
git commit -m "Release vX.Y.Z: [Brief description]"
# 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
```
### 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.
**Quick version:**
1. Determine version type (PATCH/MINOR/MAJOR)
2. Calculate new version from current
3. Preview changes to user
4. Update ALL FOUR files
5. Verify consistency
6. Build and test
7. Commit and create git tag
8. Push and create GitHub release
## Common Scenarios
**Scenario 1: Bug fix after testing**
```
User: "Fixed the memory leak in the search function"
You: Determine → PATCH
Calculate → 4.2.8 → 4.2.9
Update all four files (version numbers only)
Build and commit
Create git tag v4.2.9
Push commit and tags
Create GitHub release v4.2.9
```
See [operations/scenarios.md](operations/scenarios.md) for examples:
- Bug fix releases
- New feature releases
- Breaking change releases
**Scenario 2: New MCP tool added**
```
User: "Added web search MCP integration"
You: Determine → MINOR (new feature)
Calculate → 4.2.8 → 4.3.0
Update all four files (version numbers only)
Build and commit
Create git tag v4.3.0
Push commit and tags
Create GitHub release v4.3.0
```
## Critical Rules
**Scenario 3: Database schema redesign**
```
User: "Rewrote storage layer, old data needs migration"
You: Determine → MAJOR (breaking change)
Calculate → 4.2.8 → 5.0.0
Update all four files (version numbers only)
Build and commit
Create git tag v5.0.0
Push commit and tags
Create GitHub release v5.0.0
```
## Error Prevention
**ALWAYS verify:**
- [ ] All FOUR files have matching version numbers (package.json, marketplace.json, plugin.json, CLAUDE.md)
- [ ] Git tag created with format vX.Y.Z
- [ ] GitHub release created from the tag
- [ ] CLAUDE.md: ONLY updated line 9 (version number), did NOT touch version history
- [ ] Commit and tags pushed to remote
**ALWAYS:**
- Update ALL FOUR files with matching version numbers
- Create git tag with format `vX.Y.Z`
- Create GitHub release from the tag
- Ask user if version type is unclear
**NEVER:**
- Update only one, two, or three files - ALL FOUR must be updated
- Update only one, two, or three files
- Skip the verification step
- Forget to create git tag
- Forget to create GitHub release
- Forget to ask user if version type is unclear
- Forget to create git tag or GitHub release
- Add version history entries to CLAUDE.md (that's managed separately)
## Verification Checklist
Before considering the task complete:
- [ ] All FOUR 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
- [ ] CLAUDE.md: ONLY line 9 updated (version number), NOT version history
## Reference Commands
```bash
# View current version
cat package.json | grep version
grep '"version"' package.json
# Verify consistency across all version files
grep '"version"' package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json
# View git tags
git tag -l -n1
# Check what will be committed
git status
git diff package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json CLAUDE.md
```
For more commands, see [operations/reference.md](operations/reference.md).

275
.claude/skills/version-bump/operations/reference.md Normal file
View File

@@ -0,0 +1,275 @@
# Version Bump Reference
Quick reference for version bump commands and file locations.
## File Locations
### Version-Tracked Files (ALL FOUR)
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",`
4. **CLAUDE.md**
- Path: `CLAUDE.md`
- Line: 9
- Format: `**Current 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
grep "Current Version" CLAUDE.md
```
### 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",
# Check CLAUDE.md
grep "Current Version" CLAUDE.md
# Should output: **Current 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 CLAUDE.md 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 four 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 CLAUDE.md 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 four 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 CLAUDE.md 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 four 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 CLAUDE.md 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"
```

218
.claude/skills/version-bump/operations/scenarios.md Normal file
View File

@@ -0,0 +1,218 @@
# 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 four 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 four 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 four 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 four 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 four 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)
```

228
.claude/skills/version-bump/operations/workflow.md Normal file
View File

@@ -0,0 +1,228 @@
# 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"
- CLAUDE.md line 9: "**Current Version**: 4.2.9" (version number ONLY)
- 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.
### Update CLAUDE.md
File: `CLAUDE.md`
**ONLY update line 9 with the version number:**
```markdown
**Current Version**: 4.2.9
```
**CRITICAL:** DO NOT add version history entries to CLAUDE.md. Version history is managed separately outside this skill.
## 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 CLAUDE.md 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 <noreply@anthropic.com>"
# 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.
## 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.