Release Publishing Workflow for @j0kz/mcp-agents

Complete workflow for releasing and publishing new versions across the monorepo.

When to Use This Skill

Releasing new package versions
Publishing to npm
Updating version.json and CHANGELOG
Creating git tags
Multi-platform deployment verification
Emergency hotfix releases

Evidence Base

Current State:

version.json as single source of truth
25+ releases documented in CHANGELOG.md
Multi-package publishing (9 tools + shared + installer)
Automated version synchronization
Platform verification (npm, GitHub)
Emergency rollback procedures

Quick Release Checklist

Pre-release validation:

All tests passing (npm test)
Build successful (npm run build)
Version alignment check (npm run version:check-shared)
CHANGELOG updated with release notes
All PRs merged to main

Release steps:

Update version.json
Run npm run version:sync
Update CHANGELOG.md
Commit changes
Publish: npm run publish-all
Create git tag
Push tag to GitHub
Verify deployment

For complete checklist: See references/complete-release-checklist.md

version.json (Single Source of Truth)

Location: version.json (root)

Format:

json

{
  "version": "1.0.36",
  "sharedVersion": "1.0.36"
}

Update version:

bash

# 1. Edit version.json
{
  "version": "1.0.37",
  "sharedVersion": "1.0.37"
}

# 2. Sync all package.json files
npm run version:sync

This updates:

All package.json files (11 packages)
README badges
tools.json metadata

CHANGELOG Management

Add release entry:

markdown

## [1.0.37] - 2025-10-XX

### 🎉 New Features / 🐛 Bug Fixes

**Key Changes:**
- Feature/Fix 1: Description
- Feature/Fix 2: Description

**Impact:**
- ✅ Benefit 1
- ✅ Benefit 2

**Test Results:**
- ✅ 388/388 tests passing
- ✅ Build successful

**Breaking Changes:** None

---

For CHANGELOG templates: See references/complete-release-checklist.md

Publishing Workflow

1. Pre-Release Validation

bash

# All tests must pass
npm test

# Build must succeed
npm run build

# Version alignment check
npm run version:check-shared

# Update test count if changed
npm run update:test-count

2. Update Version

bash

# Edit version.json
vim version.json
# Change: "version": "1.0.37"

# Sync all packages
npm run version:sync

3. Update CHANGELOG

bash

vim CHANGELOG.md
# Add new release entry at top

4. Commit Version Bump

bash

git add version.json CHANGELOG.md package.json packages/*/package.json tools.json README.md packages/*/README.md
git commit -m "chore: bump version to 1.0.37

Updated:
- version.json
- All package.json files
- CHANGELOG.md with release notes
- README badges

🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>"

5. Publish to npm

bash

# Publish all packages at once
npm run publish-all

# Or individually:
npm publish packages/smart-reviewer --access public
npm publish packages/test-generator --access public
# ... etc

Expected output:

+ @j0kz/smart-reviewer-mcp@1.0.37
+ @j0kz/test-generator-mcp@1.0.37
+ @j0kz/orchestrator-mcp@1.0.37
...
✓ 11 packages published successfully

6. Create Git Tag

bash

# Create annotated tag
git tag -a v1.0.37 -m "Release v1.0.37

- Feature 1
- Feature 2
- Bug fix 1

See CHANGELOG.md for full details"

# Push tag to GitHub
git push origin v1.0.37

# Or push all tags
git push --tags

7. Verify Deployment

Check npm:

bash

npm view @j0kz/smart-reviewer-mcp version
# Should show: 1.0.37

npm view @j0kz/orchestrator-mcp version
# Should show: 1.0.37

Check GitHub:

https://github.com/j0kz/mcp-agents/releases
# Tag should appear

Test installation:

bash

npx @j0kz/mcp-agents@latest
# Should install v1.0.37

Emergency Hotfix Release

Quick hotfix for critical bugs:

bash

# 1. Create hotfix branch
git checkout -b hotfix/critical-fix

# 2. Make minimal fix
# ... edit code ...
npm test  # Verify fix

# 3. Update version (patch)
# version.json: 1.0.37 → 1.0.38
npm run version:sync

# 4. Update CHANGELOG
# Add hotfix entry

# 5. Commit
git add .
git commit -m "fix: critical security patch"

# 6. Merge to main
git checkout main
git merge hotfix/critical-fix

# 7. Publish immediately
npm run publish-all

# 8. Tag and push
git tag -a v1.0.38 -m "Hotfix: Critical security patch"
git push origin main --tags

For emergency procedures: See references/emergency-rollback-procedures.md

Common Workflows

Standard Feature Release

bash

# 1. Validation
npm test && npm run build

# 2. Version bump
# Edit version.json: 1.0.36 → 1.0.37
npm run version:sync

# 3. CHANGELOG
# Add release entry

# 4. Commit
git add .
git commit -m "chore: bump version to 1.0.37"

# 5. Publish
npm run publish-all

# 6. Tag
git tag -a v1.0.37 -m "Release v1.0.37"
git push origin v1.0.37

# 7. Verify
npm view @j0kz/smart-reviewer-mcp version

Major Version Release (Breaking Changes)

bash

# 1. Update version.json
# 1.0.37 → 2.0.0

# 2. Sync
npm run version:sync

# 3. CHANGELOG with migration guide
## [2.0.0] - 2025-XX-XX

### 💥 Breaking Changes

**Changed API signature:**
- Old: `function(param1, param2)`
- New: `function({ param1, param2 })`

**Migration Guide:**
[Detailed migration steps]

# 4. Commit, publish, tag (same as above)

Troubleshooting Releases

Issue: npm publish fails

Check:

bash

# Verify logged in
npm whoami

# Verify package access
npm owner ls @j0kz/smart-reviewer-mcp

# Verify version not already published
npm view @j0kz/smart-reviewer-mcp versions

For complete troubleshooting: See references/troubleshooting-releases.md

Issue: Version mismatch

bash

# Fix with version sync
npm run version:check-shared
# Shows mismatches

npm run version:sync
# Fixes all versions

Issue: Tag already exists

bash

# Delete local tag
git tag -d v1.0.37

# Delete remote tag
git push origin :refs/tags/v1.0.37

# Recreate tag
git tag -a v1.0.37 -m "Release v1.0.37"
git push origin v1.0.37

Post-Release

After successful release:

Update wiki (if user-facing changes)
powershell
```
./publish-wiki.ps1
```
Announce release (optional)
- GitHub Discussions
- Twitter/social media
- Discord/community channels
Monitor for issues
- Check GitHub issues
- Monitor npm downloads
- Watch for bug reports
Update documentation (if needed)
- README updates
- Wiki pages
- API documentation

Quick Command Reference

bash

# Version management
npm run version:sync               # Sync all versions from version.json
npm run version:check-shared       # Check for mismatches

# Publishing
npm run publish-all                # Publish all packages
npm publish packages/tool --access public  # Publish single package

# Validation
npm test                           # Run all tests
npm run build                      # Build all packages
npm run update:test-count          # Update test count badges

# Git tagging
git tag -a v1.0.37 -m "Message"   # Create tag
git push origin v1.0.37            # Push tag
git push --tags                    # Push all tags

# Verification
npm view @j0kz/package version     # Check published version

Best Practices

✅ DO

Always update version.json first (single source of truth)
Run version:sync after version changes
Update CHANGELOG before publishing
Run full test suite before publishing
Create annotated tags (not lightweight)
Verify deployment after publishing

❌ DON'T

Don't manually edit package.json versions (use version.json)
Don't skip CHANGELOG updates
Don't publish without testing
Don't forget to push tags
Don't force push tags (coordinate with team)

Related Skills

git-pr-workflow - Creating PRs before release
documentation-generation - Updating docs for release
project-standardization - Version.json usage

References

Detailed Guides:

Complete Release Checklist - Step-by-step release process
Emergency Rollback Procedures - Handling failed releases
Troubleshooting Releases - Common release issues

Project Files:

version.json - Single source of truth for versions
CHANGELOG.md - 25+ documented releases
scripts/version-sync.js - Automated version synchronization
package.json workspaces - Multi-package setup

Release Principles:

version.json is the ONLY source of truth
ALWAYS run version:sync after version changes
ALWAYS update CHANGELOG before releasing
ALWAYS test before publishing
NEVER skip verification steps
Document breaking changes clearly
Have rollback plan ready

Search AI Tools

release-publishing-workflow

Install this agent skill to your Project

SKILL.md

Release Publishing Workflow for @j0kz/mcp-agents

When to Use This Skill

Evidence Base

Quick Release Checklist

version.json (Single Source of Truth)

CHANGELOG Management

Publishing Workflow

1. Pre-Release Validation

2. Update Version

3. Update CHANGELOG

4. Commit Version Bump

5. Publish to npm

6. Create Git Tag

7. Verify Deployment

Emergency Hotfix Release

Common Workflows

Standard Feature Release

Major Version Release (Breaking Changes)

Troubleshooting Releases

Issue: npm publish fails

Issue: Version mismatch

Issue: Tag already exists

Post-Release

Quick Command Reference

Best Practices

✅ DO

❌ DON'T

Related Skills

References