SuperClaude/RELEASE_INSTRUCTIONS.md

SuperClaude Framework Release Instructions

🚀 Complete Publishing Guide for PyPI and NPM

Version: 4.0.4 (Both PyPI and NPM)
Date: 2025-08-22
Status: READY FOR RELEASE

---

📋 Pre-Flight Checklist

Critical Fixes Applied ✅

• Version consistency fixed (Both: 4.0.4)
• License format updated to PEP 639 compliance
• NPM package name corrected to @bifrost_inc/superclaude
• NPM version incremented to 4.0.4 (from existing 4.0.2)

Required Accounts

• PyPI account with maintainer access
• TestPyPI account for testing
• NPM account with org access to @superclaude-org
• GitHub account with repo write access

---

🔐 Step 1: Setup Credentials

PyPI Credentials

1. Create PyPI API Token (if not exists):

   # Go to https://pypi.org/manage/account/token/
   # Create token with scope: "Entire account" or "Project: SuperClaude"
   # Save token securely
   

2. Create ~/.pypirc file:

   [distutils]
   index-servers =
       pypi
       testpypi
   
   [pypi]
   username = __token__
   password = pypi-YOUR_TOKEN_HERE
   
   [testpypi]
   username = __token__
   password = pypi-YOUR_TEST_TOKEN_HERE
   repository = https://test.pypi.org/legacy/
   

3. Secure the file:

   chmod 600 ~/.pypirc
   

NPM Credentials

1. Login to NPM:

   npm login
   # Enter username, password, email
   # Enter OTP if 2FA enabled
   

2. Verify login:

   npm whoami
   # Should show your username
   
   npm org ls @superclaude-org
   # Should show you have access
   

---

🧪 Step 2: Test Deployments

Test PyPI Deployment

1. Clean previous builds:

   rm -rf dist/ build/ *.egg-info
   

2. Run validation:

   python3 scripts/validate_pypi_ready.py
   # Must show 5/5 checks passed
   

3. Build packages:

   python3 setup.py sdist bdist_wheel
   

4. Upload to TestPyPI:

   ./scripts/publish.sh test
   # OR manually:
   python3 -m twine upload --repository testpypi dist/*
   

5. Test installation from TestPyPI:

   # Create virtual environment
   python3 -m venv test_env
   source test_env/bin/activate
   
   # Install from TestPyPI
   pip install --index-url https://test.pypi.org/simple/ \
               --extra-index-url https://pypi.org/simple/ \
               SuperClaude==4.0.4
   
   # Test the CLI
   SuperClaude --version
   SuperClaude install --dry-run
   
   # Cleanup
   deactivate
   rm -rf test_env
   

Test NPM Deployment

1. Verify package configuration:

   npm publish --dry-run
   # Check output for:
   # - Correct package name: @bifrost_inc/superclaude
   # - Version: 4.0.4
   # - Files included: bin/, README.md, LICENSE, package.json
   

2. Local test:

   # Pack the package
   npm pack
   
   # Test local installation
   npm install -g ./superclaude-org-superclaude-4.0.4.tgz
   
   # Verify it works
   superclaude --version
   
   # Uninstall test
   npm uninstall -g @bifrost_inc/superclaude
   

---

🚀 Step 3: Production Release

⚠️ FINAL CHECKS BEFORE RELEASE

# Ensure on correct branch
git branch --show-current
# Should show: SuperClaude_V4_Beta or master

# Ensure working directory is clean
git status
# Should show: nothing to commit, working tree clean

# Tag the release
git tag -a v4.0.4 -m "Release v4.0.4 - Production ready"
git push origin v4.0.4

PyPI Production Release

1. Final validation:

   python3 scripts/validate_pypi_ready.py
   # MUST show: "Project is ready for PyPI publication!"
   

2. Clean and rebuild:

   rm -rf dist/ build/ *.egg-info
   python3 setup.py sdist bdist_wheel
   

3. Upload to PyPI:

   ./scripts/publish.sh prod
   # OR manually:
   python3 -m twine upload dist/*
   

4. Verify on PyPI:

   # Wait 1-2 minutes for CDN propagation
   pip install SuperClaude==4.0.4 --no-cache-dir
   SuperClaude --version
   

NPM Production Release

1. Ensure logged in:

   npm whoami
   # Must show your username
   

2. Publish with 2FA (if enabled):

   npm publish --otp=YOUR_2FA_CODE
   # Without 2FA:
   npm publish
   

3. Verify on NPM:

   # Wait 1-2 minutes
   npm view @bifrost_inc/superclaude@4.0.4
   
   # Test installation
   npm install -g @bifrost_inc/superclaude@4.0.4
   superclaude --version
   

---

🔄 Step 4: Post-Release Verification

Verification Checklist

1. PyPI Verification:

   # Check PyPI page
   open https://pypi.org/project/SuperClaude/4.0.4/
   
   # Fresh install test
   pip install SuperClaude==4.0.4 --no-cache-dir
   SuperClaude install --list-components
   

2. NPM Verification:

   # Check NPM page
   open https://www.npmjs.com/package/@bifrost_inc/superclaude
   
   # Fresh install test
   npm install -g @bifrost_inc/superclaude@4.0.4
   superclaude install --list-components
   

3. Cross-platform test:

   # Test NPM → PyPI flow
   npm install -g @bifrost_inc/superclaude
   superclaude install --dry-run
   # Should successfully detect/install Python package
   

---

🔙 Rollback Procedures

If PyPI Release Fails

1. Yank the release (makes it non-installable):

   # Via web interface:
   # https://pypi.org/manage/project/SuperClaude/release/4.0.4/
   # Click "Options" → "Yank"
   
   # Users can still install if they specify exact version
   

2. Fix issues and release patch:

   # Update version to 4.0.1
   # Fix issues
   # Re-release following steps above
   

If NPM Release Fails

1. Unpublish (within 72 hours):

   npm unpublish @bifrost_inc/superclaude@4.0.4
   

2. Deprecate (after 72 hours):

   npm deprecate @bifrost_inc/superclaude@4.0.4 "Critical bug - use 4.0.4"
   

---

📢 Step 5: Announcement

GitHub Release

1. Create release at: https://github.com/SuperClaude-Org/SuperClaude_Framework/releases/new
2. Tag: v4.0.4
3. Title: "SuperClaude v4.0.4 - Production Release"
4. Description: Include changelog and installation instructions

Update Documentation

# Update README badges
# Update installation docs
# Update website if applicable

Community Announcement Template

🎉 SuperClaude v4.0.4 Released!

Install via:
- PyPI: `pip install SuperClaude`
- NPM: `npm install -g @bifrost_inc/superclaude`

What's New:
- 14 specialized AI agents
- 6 integrated MCP servers
- 30-50% token usage reduction
- [Full changelog](link)

Docs: https://github.com/SuperClaude-Org/SuperClaude_Framework

---

⚠️ Common Issues & Solutions

PyPI Issues

"Invalid credentials"

• Regenerate API token
• Ensure token starts with pypi-
• Check ~/.pypirc formatting

"Version already exists"

• Can't overwrite - increment version
• Update all version references

NPM Issues

"402 Payment Required"

• Package name might be private
• Check org settings

"403 Forbidden"

• No publish access to org
• Contact org admin

"E409 Conflict"

• Version already exists
• Increment version number

---

📊 Success Metrics

After 24 hours, check:

• PyPI download stats: https://pypistats.org/packages/superclaude
• NPM download stats: https://www.npmjs.com/package/@bifrost_inc/superclaude
• GitHub stars/issues
• Community feedback

---

🎯 Quick Command Summary

# PyPI Test & Release
./scripts/publish.sh test          # Test on TestPyPI
./scripts/publish.sh prod          # Release to PyPI

# NPM Test & Release  
npm publish --dry-run              # Test locally
npm publish --otp=123456           # Release to NPM

# Verification
pip install SuperClaude==4.0.4
npm install -g @bifrost_inc/superclaude@4.0.4

---

Remember: Once published to PyPI, versions cannot be reused. Plan carefully!

Good luck with the release! 🚀