AI Agent Quick Reference Guide

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):

1. Check the draft release - Release Drafter auto-creates it from merged PRs:

   gh release list
   

2. Publish 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

3. 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! 🚀