name	release-publishing-workflow
description	Complete release workflow including version updates, CHANGELOG management, npm publishing, git tagging, and deployment verification. Use when releasing new versions or publishing packages.

Release Publishing Workflow for @j0kz/mcp-agents

Name: release-publishing-workflow
Author: j0KZ

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](https://claude.com/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

release-publishing-workflow

Install Skill

SKILL.md