docs: add release checklist and simplify AGENT.md

AGENT.md

@@ -99,100 +99,11 @@
 
 ## Package Release Rules
 
-Whenever releasing a new version of any package, ALWAYS follow this workflow.
+Whenever releasing a new version of any package, ALWAYS follow the workflow in `Release_Guide.md`.
 
-### 1. Validate the Project
-- Ensure all tests pass.
-- Ensure linting and formatting pass.
-- Verify CI is green.
-- Confirm the package builds successfully.
-- Ensure documentation is up to date.
+Quick reference: See `Release.md` for the release checklist.
 
-### 2. Update the Release
-- Update the package version following Semantic Versioning.
-- Update CHANGELOG.md with all user-facing changes.
-- Verify README examples and installation instructions.
-
-### 3. Commit Changes
-- Create a release commit if needed.
-
-Commit message:
-
-```
-release: vX.Y.Z
-```
-
-### 4. Create Git Tag
-- Create an annotated Git tag.
-
-Tag:
-
-```
-vX.Y.Z
-```
-
-Push the tag to GitHub.
-
-### 5. GitHub Release
-Create a GitHub Release using the same tag.
-
-Release title should be descriptive.
-
-Example:
-
-```
-v0.5.0 – New Features & Improvements
-```
-
-Generate release notes with the following sections:
-
-- ✨ Features
-- 🐛 Bug Fixes
-- 📚 Documentation
-- ⚙️ Internal Changes
-- ❤️ Contributors
-
-Never use the version number alone as the release title.
-
-### 6. Automated Release
-If GitHub Actions handles releases:
-
-- Wait for the workflow to finish.
-- Verify build success.
-- Verify package publishing succeeded.
-- Verify GitHub Release was created.
-- Stop immediately if any workflow fails.
-
-Never assume a release succeeded without verification.
-
-### 7. Post-Release Verification
-Verify:
-
-- Git tag exists.
-- GitHub Release exists.
-- Package is available on the package registry.
-- Fresh installation succeeds.
-- The CLI/package reports the correct version.
-
-### 8. Final Report
-After every release, provide a summary including:
-
-- Version released
-- Release status
-- CI status
-- Package publish status
-- GitHub Release status
-- Any warnings or failures
-
-### Semantic Versioning
-
-| Change | Example |
-|--------|---------|
-| PATCH (bug fixes, docs, internal) | 0.4.5 → 0.4.6 |
-| MINOR (backward-compatible features) | 0.4.5 → 0.5.0 |
-| MAJOR (breaking changes) | 1.x.x → 2.0.0 |
-
-### Rules
+Key rules:
 - Never skip tests.
 - Never skip CHANGELOG updates.
 - Never publish an unverified release.

Release.md

@@ -0,0 +1,137 @@
+# Release Checklist
+
+Quick reference for releasing new versions of OpenAgent Eval.
+
+---
+
+## Pre-Release
+
+- [ ] All tests pass (`pytest`)
+- [ ] Linting passes (`ruff check .`)
+- [ ] Formatting passes (`ruff format .`)
+- [ ] CI is green
+- [ ] Package builds successfully (`uv build`)
+- [ ] Documentation is up to date
+
+---
+
+## Update Version
+
+- [ ] Update `pyproject.toml` version
+- [ ] Update `openagent_eval/__init__.py` version (must match)
+- [ ] Update `CHANGELOG.md` with all changes since last release
+- [ ] Update comparison links in CHANGELOG.md
+
+---
+
+## Create Release Branch & PR
+
+```bash
+git checkout main
+git pull origin main
+git checkout -b release/vX.Y.Z
+git add pyproject.toml openagent_eval/__init__.py CHANGELOG.md uv.lock
+git commit -m "chore: release vX.Y.Z"
+git push -u origin release/vX.Y.Z
+gh pr create --title "chore: release vX.Y.Z" --base main
+```
+
+- [ ] PR created and reviewed
+- [ ] PR merged
+
+---
+
+## Tag Release
+
+```bash
+git checkout main
+git pull origin main
+git tag -a vX.Y.Z -m "Release vX.Y.Z"
+git push origin vX.Y.Z
+```
+
+- [ ] Tag created and pushed
+
+---
+
+## GitHub Release
+
+- [ ] GitHub Release created with descriptive title: `vX.Y.Z – [Title]`
+- [ ] Release notes include PR links: `- **Name** — description (#PR_NUMBER)`
+- [ ] Release notes include Contributors section
+
+---
+
+## Post-Release Verification
+
+- [ ] Git tag exists (`git tag -l "vX.Y.Z"`)
+- [ ] GitHub Release exists (`gh release view vX.Y.Z`)
+- [ ] Package available on PyPI (`pip install openagent-eval==X.Y.Z`)
+- [ ] CLI reports correct version (`oaeval --version`)
+- [ ] CI workflow completed successfully
+
+---
+
+## Semantic Versioning
+
+| Change | Example |
+|--------|---------|
+| PATCH (bug fixes, docs, internal) | 0.4.5 → 0.4.6 |
+| MINOR (backward-compatible features) | 0.4.5 → 0.5.0 |
+| MAJOR (breaking changes) | 1.x.x → 2.0.0 |
+
+---
+
+## Release Notes Format
+
+```markdown
+## What's Changed
+
+### ✨ Features
+- **Feature Name** — description (#PR_NUMBER)
+
+### 🐛 Bug Fixes
+- **Fix Name** — description (#PR_NUMBER)
+
+### 📚 Documentation
+- **Doc Change** — description (#PR_NUMBER)
+
+### ⚙️ Testing
+- **Test Change** — description (#PR_NUMBER)
+
+### ⚙️ Internal
+- **Internal Change** — description (#PR_NUMBER)
+
+### ❤️ Contributors
+- @contributor1
+
+**Full Changelog**: https://github.com/openagenthq/openagent-eval/compare/vPREV...vX.Y.Z
+```
+
+---
+
+## Files Involved
+
+| File | Purpose |
+|------|---------|
+| `pyproject.toml` | Canonical version |
+| `openagent_eval/__init__.py` | Runtime version |
+| `CHANGELOG.md` | Release history |
+| `uv.lock` | Lock file |
+| `.github/workflows/release.yml` | PyPI publish |
+
+---
+
+## Troubleshooting
+
+### Version mismatch
+Always update both `pyproject.toml` and `__init__.py` — they must match.
+
+### Push rejected
+Use PR workflow — direct push to `main` is blocked.
+
+### Tag exists
+```bash
+git tag -d vX.Y.Z
+git push origin :refs/tags/vX.Y.Z
+```