Release notes

Draft release notes from the commits between two tags: one agent sorts the changes, another hunts for breaking changes, and a third writes the notes in your house style.

note

These agents only read the repo and write a draft. Nobody tags, publishes or posts anything — you review the draft and ship it yourself.

Pick the range

From a terminal in the repo's workspace:

git describe --tags --abbrev=0   # last release, e.g. v1.4.0

Two readers in parallel

beswarm agent start --name changes --agent claude --group release --no-focus \
  --prompt "Read-only. List every change in git log v1.4.0..HEAD, grouped into features, fixes, performance and internal. One line each, user-facing wording, with the commit hash. Write to reports/release/changes.md."
beswarm agent start --name breaking --agent codex --group release --no-focus \
  --prompt "Read-only. Diff v1.4.0..HEAD for breaking changes: removed or renamed flags, config keys, API fields, CLI output and defaults. For each, give what breaks and what a user must do. Write to reports/release/breaking.md. If there are none, say so."

Two agents from different vendors catch different things. The breaking-change pass is the one that saves you a support thread.

Write the notes

beswarm agent wait changes --until done,blocked --timeout 1800
beswarm agent wait breaking --until done,blocked --timeout 1800
 
beswarm agent start --name notes --agent claude --group release \
  --prompt "Write reports/release/v1.5.0.md from reports/release/changes.md and breaking.md. Follow the style of CHANGELOG.md. Breaking changes and upgrade steps first, then highlights, then the full list. Drop internal-only changes." \
  --wait --timeout 900

Review and ship

The draft shows up in the Artifacts tab. Check every breaking change against the code, paste the notes into your changelog, then close the group:

beswarm agent close --group release