tools-only AI Agent Quick Reference Guide
This guide provides quick commands for AI agents (like Claude Code) to perform common tasks.
Creating a Release
Workflow: Publish release in GitHub UI → Auto-bump version on main
Standard Release (Patch - Most Common)
For patch releases (bug fixes, minor improvements):
Check the draft release - Release Drafter auto-creates it from merged PRs:
gh release listPublish the release in GitHub UI:
- Go to https://github.com/greynewell/mcpbr/releases
- Edit the draft release
- Set tag to match current version (e.g.,
v0.4.1) - Review notes and publish
Automatic version bump - The post-release workflow automatically:
- Bumps to next patch (0.4.1 → 0.4.2)
- Commits to main
- Main is ready for next release!
Minor or Major Version Bumps
For minor (new features) or major (breaking changes) releases, update the version before publishing:
# For minor version bump (e.g., 0.4.2 → 0.5.0)
sed -i 's/^version = "0.4.2"/version = "0.5.0"/' pyproject.toml
python3 scripts/sync_version.py
git add pyproject.toml package.json .claude-plugin/
git commit -m "chore: Bump version to 0.5.0"
git push origin main
# Then publish release v0.5.0 in GitHub UI
# Post-release workflow will auto-bump to 0.5.1
Major version example: Same process, use 1.0.0 for breaking changes.
Version Bump Strategy
- Patch (auto after release): Bug fixes, docs, deps (0.4.1 → 0.4.2)
- Minor (manual before release): New features (0.4.2 → 0.5.0)
- Major (manual before release): Breaking changes (0.5.0 → 1.0.0)
Common Tasks
Check Current Version
grep '^version' pyproject.toml
Verify Release Published
# Check GitHub
gh release view
# Check PyPI
curl -s https://pypi.org/pypi/mcpbr/json | jq -r '.info.version'
# Check npm
npm view @greynewell/mcpbr version
Manual Version Sync (rarely needed)
# Update pyproject.toml first, then:
python3 scripts/sync_version.py
Fix Version Mismatch
# If pyproject.toml and package.json are out of sync:
python3 scripts/sync_version.py
git add pyproject.toml package.json .claude-plugin/
git commit -m "chore: sync version to $(grep '^version' pyproject.toml | cut -d'"' -f2)"
git push origin main
Workflow Checklist
When making a release:
- Ensure PR is merged to main
- For minor/major bumps: Manually update version in pyproject.toml, sync, commit, push
- For patch bumps (most common): Version is already set in main
- Check draft release:
gh release list - Publish release in GitHub UI (set correct tag version)
- Wait ~2 minutes for post-release workflow to auto-bump version
- Verify version was bumped on main:
grep '^version' pyproject.toml - Verify PyPI: Check https://pypi.org/project/mcpbr/
- Verify npm: Check https://www.npmjs.com/package/mcpbr-cli
What NOT to Do
❌ Don't manually edit version in package.json (sync script handles it) ❌ Don't create releases manually (use the workflow) ❌ Don't skip version syncing ❌ Don't publish to PyPI/npm manually (workflows handle it) ❌ Don't commit without running pre-commit hooks
Emergency Procedures
Delete a Bad Release
# Delete from GitHub
gh release delete v0.3.25 --yes
# Delete tags
git tag -d v0.3.25
git push origin :refs/tags/v0.3.25
# Note: Can't delete from PyPI/npm - must publish new version
Rollback Version
# Update to previous version in pyproject.toml
sed -i 's/version = "0.3.25"/version = "0.3.24"/' pyproject.toml
# Sync
python3 scripts/sync_version.py
# Commit
git add pyproject.toml package.json .claude-plugin/
git commit -m "chore: rollback to 0.3.24"
git push origin main
Full Documentation
For detailed information, see RELEASE.md
Examples
Standard patch release (most common)
# PRs merged to main, draft release exists
# Version is already set in pyproject.toml (e.g., 0.4.1)
# 1. Check draft
gh release list
# 2. Publish in GitHub UI with tag v0.4.1
# 3. Post-release workflow auto-bumps to 0.4.2 on main
Minor version release (new features)
# Manually bump version first
sed -i 's/^version = "0.4.2"/version = "0.5.0"/' pyproject.toml
python3 scripts/sync_version.py
git add pyproject.toml package.json .claude-plugin/
git commit -m "chore: Bump version to 0.5.0"
git push origin main
# Publish release v0.5.0 in GitHub UI
# Post-release workflow auto-bumps to 0.5.1
Major version release (breaking changes)
# Redesigned CLI interface - breaking change
sed -i 's/^version = "0.5.1"/version = "1.0.0"/' pyproject.toml
python3 scripts/sync_version.py
git add pyproject.toml package.json .claude-plugin/
git commit -m "chore: Bump version to 1.0.0"
git push origin main
# Publish release v1.0.0 in GitHub UI
# Post-release workflow auto-bumps to 1.0.1
gh workflow run release.yml -f version_bump=major
# Creates v1.0.0
Remember: One command releases everything. Don't overthink it! 🚀