Agr Release

agr Release Process

This skill walks through the full release process for the agr package. The release is tag-driven: pushing a vX.Y.Z tag triggers the GitHub Actions pipeline that runs quality checks, builds the package, publishes to PyPI, and creates a GitHub Release.

Your job is to prepare everything so that when the tag is pushed, the pipeline succeeds on the first try.

Before you start

Verify the preconditions. If any fail, stop and tell the user.

1. Clean working tree — git status should show no uncommitted changes
2. On the main branch — releases should only come from main
3. Up to date with remote — git pull to make sure you're not behind

Ask the user what kind of release this is:

• patch (0.7.10 → 0.7.11) — bug fixes, small changes
• minor (0.7.10 → 0.8.0) — new features, backwards-compatible
• major (0.7.10 → 1.0.0) — breaking changes
• beta (0.7.11b1) — pre-release for testing

If the user already said what type they want, don't ask again.

Step 1: Figure out what changed

Before touching any files, understand what's being released.

# See all commits since the last release tag
git log $(git describe --tags --abbrev=0)..HEAD --oneline

Also check the [Unreleased] section in CHANGELOG.md — it may already have entries. Cross-reference with the git log to make sure nothing is missing. If there are commits that aren't reflected in the changelog, add them.

Group changes into the standard Keep a Changelog categories:

• Added — new features
• Changed — changes to existing functionality
• Fixed — bug fixes
• Removed — removed features
• Docs — documentation-only changes

Step 2: Run quality checks

Run all three locally before proceeding. These are the same checks the CI pipeline runs, so catching failures here saves a round-trip.

uv run ruff check .
uv run ruff format --check .
uv run pytest -m "not e2e and not network and not slow"
uv run ty check

If anything fails, fix it before continuing. The release commit should pass CI cleanly.

Step 3: Check if docs need updating

Not every release needs doc changes — use judgement. Docs updates are warranted when:

• A CLI command was added, removed, or its flags changed
• A new module or public API was added
• Behavior that users rely on changed in a way they'd notice

The docs to consider:

• README.md — the primary entry point, should reflect current capabilities
• docs/docs/reference.md — CLI command reference
• docs/docs/index.md — landing page / getting started
• Other files in docs/docs/ as relevant (sdk.md, configuration.md, etc.)
• Skills in skills/ — if any exist and are affected by the changes

If nothing user-facing changed (internal refactors, test improvements, dependency bumps), skip this step and move on.

Step 4: Bump the version

The version lives in pyproject.toml (the single source of truth — importlib.metadata picks it up at runtime via agr/__init__.py):

1. pyproject.toml line 7: version = "X.Y.Z"

Calculate the new version based on the current version and the release type the user chose.

For beta releases, append b1 (or increment the beta number if one already exists):

• 0.7.10 → 0.7.11b1 (first beta of next patch)
• 0.7.11b1 → 0.7.11b2 (next beta)
• 0.7.11b2 → 0.7.11 (promote beta to stable)