Release Notes Agent

Automatically collect merged PRs and issues, curate release notes with proper categorization, and draft changelogs ready to ship.

Every release, you need to tell users what changed. That means reading merged PRs, categorizing them (features, fixes, security, internal), writing user-friendly summaries, and packaging it all into release notes.

A release notes agent automates this workflow. It collects commits and PRs since your last release, groups them by type, and generates a polished draft for your review.

What the agent does

When triggered (on-demand or before release), the release agent:

Gathers commits — lists all merged PRs since the last git tag or release
Categorizes changes — sorts PRs into Features, Fixes, Security, Internal, Docs based on labels and commit messages
Writes summaries — converts PR descriptions into concise, user-facing bullet points
Highlights breaking changes — flags major version bumps or API changes that require migration
Drafts a changelog — formats the release as ## [v1.2.0] - 2025-06-22 with all sections
Opens a PR — commits the draft to CHANGELOG.md and docs/releases/v1.2.0.md, ready for final review

Set it up

Prerequisites

AACWorkflow workspace with an active agent
Git repository with tagged releases (or a CHANGELOG.md)
GitHub integration configured
PRs labeled consistently (e.g., type:feature, type:fix, type:security)

Step 1: Create the release notes agent

Go to Settings → Agents and click New Agent
Choose your runtime and provider
Name it release-notes or changelog-bot
Add this system prompt:

Role: Release notes curator
Task: When assigned a "Prepare Release" task:
1. Find the last git tag (e.g., v1.2.0)
2. List all merged PRs since that tag
3. For each PR:
   - Extract title and author
   - Check labels (type:feature, type:fix, type:security, type:docs, type:chore)
   - Read description for context
   - Flag if it's a breaking change
4. Categorize into sections:
   - 🎉 Features (type:feature)
   - 🐛 Bug Fixes (type:fix)
   - 🔒 Security (type:security)
   - 📚 Documentation (type:docs)
   - 🔧 Internal / Chores (type:chore) — optional, show if significant
5. Write 1-2 line summary per PR (user perspective, not technical jargon)
6. Highlight migration guide if breaking changes exist
7. Include contributor credits
8. Create branch "release/v<VERSION>" and PR with:
   - Updated CHANGELOG.md (prepend new release)
   - New file docs/releases/v<VERSION>.md (full details)
9. Add PR to AACWorkflow for team review before merge

Output format:
## [1.2.0] - 2025-06-22

### Features
- **Workspace invites** — invite team members via email link (via @anna-dev in #123)
- **Custom agent skills** — attach reusable workflows to agents (via @devops-team in #456)

### Bug Fixes
- Fixed pagination token expiry causing 401 errors (via @alice in #789)
- Corrected timestamp display in non-UTC timezones (via @bob in #890)

### Security
- **CVE-2025-1234 (High)** — Patched request validation bypass in agent API (via @security-team in #1001)

### Breaking Changes ⚠️
- **Agent API v1 deprecated** — migrate to v2 by July 1st
  See [migration guide](/docs/api/v1-to-v2.md)

### Contributors
Thanks to @anna-dev, @devops-team, @alice, @bob, @security-team, and 3 more contributors.

Step 2: Require PR labels

Ensure your repo enforces labels on all PRs. Add a GitHub Actions workflow .github/workflows/require-pr-label.yml:

name: Require PR Label
on: pull_request
jobs:
  check-labels:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/labeler@v4
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}
      - name: Verify label applied
        if: ${{ !contains(github.event.pull_request.labels.*.name, 'type:*') }}
        run: |
          echo "❌ PR must have a 'type:' label"
          exit 1

Step 3: Trigger on-demand or scheduled

On-demand: Go to Settings → Releases and click Prepare Release. Assign to release-notes agent, it wakes up and starts.

Scheduled (e.g., monthly): Add a cron task in AACWorkflow or GitHub:

# First Monday of each month at 9 AM
0 9 * * 1 [ $(date +%d) -le 7 ] && \
  curl -X POST https://aacworkflow.com/api/tasks \
    -H "Authorization: Bearer $TOKEN" \
    -d '{"agent_id": "release-notes", "title": "Prepare monthly release"}'

Step 4: Configure release rules

Add .aacworkflow/release-config.yml:

release_notes:
  # Git tag pattern for finding last release
  tag_pattern: "v*"
  
  # Sections to include (in order)
  sections:
    - title: "🎉 Features"
      labels: ["type:feature"]
      hide_if_empty: false
    
    - title: "🐛 Bug Fixes"
      labels: ["type:fix"]
      hide_if_empty: false
    
    - title: "🔒 Security"
      labels: ["type:security"]
      hide_if_empty: true
    
    - title: "📚 Documentation"
      labels: ["type:docs"]
      hide_if_empty: true
    
    - title: "🔧 Internal"
      labels: ["type:chore"]
      hide_if_empty: true
  
  # Breaking changes
  breaking_changes_label: "breaking-change"
  breaking_changes_section: true
  
  # Include contributor credits
  include_contributors: true
  
  # Output files
  output_files:
    - CHANGELOG.md
    - docs/releases/v{VERSION}.md

Example release notes output

PR title: docs: release notes for v1.2.0

Body:

## Release Summary

**v1.2.0** — June 22, 2025

📊 **Stats:** 23 PRs merged, 12 features, 8 fixes, 3 security patches, 15 contributors

---

## 🎉 Features

- **Workspace invites** — Send email invitations to teammates; they auto-join when they click. (PR #1234)
- **Custom agent skills** — Bundle reusable workflows as skills and attach to agents. (PR #1235)
- **Workspace audit log** — Track all team activity in Settings → Audit Log. (PR #1236)

## 🐛 Bug Fixes

- Fixed agent runtime not reconnecting after network drop
- Corrected issue timestamp display in non-UTC timezones
- Pagination tokens no longer expire prematurely
- Agent comments now show in correct order (newest first)

## 🔒 Security

- **CVE-2025-1234 (High)** — Patched request validation bypass in the Agent API. All users should upgrade.
- Fixed CSRF token rotation on login.

## ⚠️ Breaking Changes

**Agent API v1 is now deprecated.** Migrate to v2 by July 1st.
[See migration guide →](/docs/agents/api-migration.md)

## Contributors

Thanks to @anna-dev, @alice, @bob, @charlie, @devops-team, @security-team, and 9 more contributors for making v1.2.0 possible.

---

**Next step:** Review the release notes above. This PR updates `CHANGELOG.md` and creates `docs/releases/v1.2.0.md`.

Merge when ready, then run `git tag v1.2.0 && git push --tags` to publish the release.

Tips & best practices

Label every PR. Release notes are only as good as your PR labels. Make labeling a habit.

Draft before tagging — prepare release notes BEFORE you tag the release, so they're ready to ship
Breaking changes callout — use a ⚠️ emoji and clear migration instructions for any breaking changes
User-first language — write from the user perspective, not technical jargon ("Invites auto-work now" not "Implemented async invite workflow")
Thank contributors — acknowledge everyone; it builds morale and community
Link docs — link to related docs, migration guides, and upgrade instructions in release notes
Publish to multiple channels — copy release notes to GitHub Releases, Slack, Twitter, your blog

Docs Maintenance Agent — keep docs in sync with releases
Dependency Update Agent — track breaking changes in your dependencies

On this page