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:

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

Update version:

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:

[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

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

Edit version.json

vim version.json

Change: "version": "1.0.37"

Sync all packages

npm run version:sync

3. Update CHANGELOG

vim CHANGELOG.md

Add new release entry at top

4. Commit Version Bump

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 Co-Authored-By: Claude <noreply@anthropic.com>"

5. Publish to npm

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

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:

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:

npx @j0kz/mcp-agents@latest

Should install v1.0.37

Emergency Hotfix Release

Quick hotfix for critical bugs:

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

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)

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:

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

Fix with version sync

npm run version:check-shared

Shows mismatches

npm run version:sync

Fixes all versions

Issue: Tag already exists

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)

./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

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