Agent Brain Release Skill

Automates the release process for Agent Brain packages, including version bumping, changelog generation, git tagging, and GitHub release creation.

Version Resolution

Before running any install commands, resolve the latest version:

# Get latest from PyPI (recommended)
LATEST=$(curl -sf https://pypi.org/pypi/agent-brain-rag/json | python3 -c "import sys,json; print(json.load(sys.stdin)['info']['version'])")
echo "Latest version: $LATEST"

Current PyPI Versions:

• Check: https://pypi.org/project/agent-brain-rag/
• Check: https://pypi.org/project/agent-brain-cli/

Package Installation

Agent Brain consists of two PyPI packages that work together:

Basic Installation

# Resolve latest version first
LATEST=$(curl -sf https://pypi.org/pypi/agent-brain-rag/json | python3 -c "import sys,json; print(json.load(sys.stdin)['info']['version'])")

# Install with pinned version
pip install agent-brain-rag==$LATEST agent-brain-cli==$LATEST

With Optional Features

# With GraphRAG support (knowledge graph retrieval)
pip install "agent-brain-rag[graphrag]==$LATEST"

# With all optional features
pip install "agent-brain-rag[graphrag-all]==$LATEST"

Package Details

Quick Start After Installation

1. Set Environment Variables

export OPENAI_API_KEY=your-openai-key
export ANTHROPIC_API_KEY=your-anthropic-key

2. Start the Server

# Using CLI (recommended)
agent-brain init          # Initialize project config
agent-brain start         # Start server for current project

# Or run server directly
agent-brain-serve         # Start on http://127.0.0.1:8000

3. Index Documents

agent-brain index ./docs ./src    # Index documentation and source code

4. Query Your Knowledge Base

agent-brain query "How does authentication work?"

5. Stop the Server

agent-brain stop

Trigger Patterns

• /ag-brain-release <bump> - Create a release with specified version bump (command name)
• /ag-brain-release <bump> --dry-run - Preview release without making changes
• Skill name remains agent-brain-release for clarity; command entry is ag-brain-release.

Where <bump> is one of:

• major - Breaking changes (X.0.0 → X+1.0.0)
• minor - New features (X.Y.0 → X.Y+1.0)
• patch - Bug fixes (X.Y.Z → X.Y.Z+1)

Process Overview

The release skill performs these steps:

1. Validate Pre-conditions

• Working directory is clean (no uncommitted changes)
• On main branch
• Local branch is synced with remote
• Ensure CLI dependency is set to PyPI (not a local path). If agent-brain-cli/pyproject.toml contains {path = "../agent-brain-server"}, replace with ^<server_version> from agent-brain-server/pyproject.toml and run poetry lock --no-update.

1. Calculate New Version

• Parse current version from agent-brain-server/pyproject.toml
• Apply bump type to calculate new version

1. Update Version Files (5 files total)

• agent-brain-server/pyproject.toml
• agent-brain-server/agent_brain_server/__init__.py
• agent-brain-cli/pyproject.toml
• agent-brain-cli/agent_brain_cli/__init__.py
• agent-brain-plugin/.claude-plugin/plugin.json — MUST match CLI/server version

1. Generate Release Notes

• Collect commits since last tag
• Group by conventional commit type (feat, fix, docs, etc.)
• Format with PyPI links and documentation references

1. Create Git Commit

• Commit message: chore(release): bump version to X.Y.Z

1. Create Git Tag

• Tag format: vX.Y.Z

1. Push to Remote

• Push branch and tag to origin

1. Create GitHub Release

• Use gh release create with generated notes
• This triggers the publish-to-pypi.yml workflow

Dry Run Mode

Use --dry-run to preview all changes without executing:

/ag-brain-release minor --dry-run

[DRY RUN] Would perform the following actions:
  Current version: X.Y.Z
  New version: X.Y+1.0

  Files to update:
    - agent-brain-server/pyproject.toml
    - agent-brain-server/agent_brain_server/__init__.py
    - agent-brain-cli/pyproject.toml
    - agent-brain-cli/agent_brain_cli/__init__.py
    - agent-brain-plugin/.claude-plugin/plugin.json

  Commits since vX.Y.Z: <count>

  No changes made.

Implementation Steps

When /ag-brain-release is invoked, Claude should:

Step 1: Parse Arguments

# Extract bump type and dry-run flag from command arguments
BUMP_TYPE="minor"  # or major/patch from $ARGUMENTS
DRY_RUN=false      # true if --dry-run present

Step 2: Validate Pre-conditions

# Check for clean working directory
git status --porcelain

# Check current branch
git branch --show-current  # must be "main"

# Check remote sync
git fetch origin
git status -sb  # should show "## main...origin/main"

Step 3: Get Current Version

# Extract version from pyproject.toml
grep '^version = ' agent-brain-server/pyproject.toml | cut -d'"' -f2

Step 4: Calculate New Version

# Version calculation logic
def bump_version(current: str, bump_type: str) -> str:
    major, minor, patch = map(int, current.split('.'))
    if bump_type == 'major':
        return f"{major + 1}.0.0"
    elif bump_type == 'minor':
        return f"{major}.{minor + 1}.0"
    else:  # patch
        return f"{major}.{minor}.{patch + 1}"

Step 5: Update Version Files

# Update all 5 version files using sed or Edit tool
# See references/version-management.md for exact locations
# IMPORTANT: Update plugin.json version to match CLI/server:
#   agent-brain-plugin/.claude-plugin/plugin.json → "version": "$NEW_VERSION"

Step 6: Generate Release Notes

# Get commits since last tag
git log $(git describe --tags --abbrev=0)..HEAD --oneline

# Group by conventional commit prefix

Step 7: Commit, Tag, and Push

# Commit version changes
git add -A
git commit -m "chore(release): bump version to $NEW_VERSION"

# Create tag
git tag -a "v$NEW_VERSION" -m "Release v$NEW_VERSION"

# Push
git push origin main
git push origin "v$NEW_VERSION"

Step 8: Create GitHub Release

gh release create "v$NEW_VERSION" \
  --title "v$NEW_VERSION" \
  --notes-file release-notes.md

Release Notes Template

## What's Changed

### Features
- feat: description (#PR)

### Bug Fixes
- fix: description (#PR)

### Documentation
- docs: description (#PR)

### Other Changes
- chore/refactor/test: description (#PR)

## About Agent Brain

Agent Brain (formerly doc-serve) provides intelligent document indexing and semantic search for AI agents:

- **Semantic Search**: Natural language queries via OpenAI embeddings
- **Keyword Search (BM25)**: Traditional keyword matching with TF-IDF
- **GraphRAG**: Knowledge graph retrieval for relationship-aware queries
- **Hybrid Search**: Best of vector + keyword approaches
- **Pluggable Providers**: Choose your embedding and summarization providers

## PyPI Packages

- **agent-brain-rag**: https://pypi.org/project/agent-brain-rag/X.Y.Z/
- **agent-brain-cli**: https://pypi.org/project/agent-brain-cli/X.Y.Z/

## Installation

pip install agent-brain-rag==X.Y.Z agent-brain-cli==X.Y.Z

# With GraphRAG support
pip install agent-brain-rag[graphrag]==X.Y.Z

## Documentation

- [User Guide](https://github.com/SpillwaveSolutions/agent-brain/wiki/User-Guide)
- [Developer Guide](https://github.com/SpillwaveSolutions/agent-brain/wiki/Developer-Guide)
- [All Releases](https://github.com/SpillwaveSolutions/agent-brain/releases)

**Full Changelog**: [vPREV...vNEW](https://github.com/SpillwaveSolutions/agent-brain/compare/vPREV...vNEW)

Post-Release Reminders

After creating a release, remind the user to:

1. Monitor PyPI Publish: Check GitHub Actions for the publish-to-pypi workflow status
2. Verify PyPI Pages: Confirm packages appear at:

• <https://pypi.org/project/agent-brain-rag/>
• <https://pypi.org/project/agent-brain-cli/>

1. Update Wiki: If API changes were made, update documentation at:

• <https://github.com/SpillwaveSolutions/agent-brain/wiki>

1. Announce: Post release announcement if significant changes

Error Handling

Common issues and solutions:

References

• Version Management - Version file locations
• PyPI Setup Guide - OIDC configuration