Release
Auto reviewPublish, changelog, documentation, and deprecation policy
Dependencies
Hat Sequence
Doc Writer
Focus: Update the library's public documentation to reflect the release: API reference, migration guides for breaking changes, and consumer guidance surfaced from the security review.
Produces: Documentation updates:
- API reference — regenerated or updated to match the released API surface
- Migration guide — if this is a major version with breaking changes, a clear upgrade path
- Changelog link — from the docs site back to the release changelog
- Security guidance — consumer-facing notes from the security review, integrated into relevant sections
Reads: API Surface, changelog, security report.
Anti-patterns (RFC 2119):
- The agent MUST update docs before announcing the release, not after
- The agent MUST NOT ship breaking changes without a migration guide
- The agent MUST integrate security guidance into the relevant API sections, not bury it in a security page consumers won't read
Release Engineer
Focus: Publish the library to its target registry with a correct semver version, a complete changelog, and operational release metadata (tags, signed artifacts, provenance). Publishing is one-shot — once a version is out, it's out. Get it right before hitting publish.
Produces: A published release with:
- Version bump — following semver based on API surface changes since the last release
- Changelog entry — user-visible changes grouped by category (added, changed, fixed, security, removed)
- Git tag and release artifacts — signed where the ecosystem supports it
- Registry publish — to npm, PyPI, crates.io, Maven Central, or equivalent
Reads: API Surface (current and prior version), security report, development outputs, prior changelog.
Anti-patterns (RFC 2119):
- The agent MUST NOT publish if the version number doesn't match the semver impact of changes
- The agent MUST NOT skip the changelog entry — consumers depend on it
- The agent MUST NOT publish if the security review has unresolved high-severity findings without consumer guidance
- The agent MUST tag the git commit matching the published artifact
Review Agents
Changelog Quality
Mandate: The agent MUST verify the changelog entry for this release is complete, accurate, and useful to consumers deciding whether to upgrade.
Check:
- The agent MUST verify every public API change has a changelog line
- The agent MUST verify breaking changes are clearly marked (e.g., under a "Breaking" section or with a badge)
- The agent MUST verify security-relevant changes are labeled
- The agent MUST verify entries describe the change in consumer terms, not internal refactoring language
- The agent MUST verify the changelog follows the project's prior format (Keep a Changelog, custom, etc.)
Semver Correctness
Mandate: The agent MUST verify the release version number correctly reflects the semver impact of changes since the prior release.
Check:
- The agent MUST diff the current API surface against the prior released version
- The agent MUST verify a major bump is used when the diff contains any removed, renamed, or signature-changed public symbol
- The agent MUST verify a major bump is used when error types were removed or their meaning changed
- The agent MUST verify a minor bump is used for additions-only changes
- The agent MUST verify a patch bump is used only when no public API changed
- The agent MUST flag any behavior change to an existing API that would be observable and require a major bump even if signatures are unchanged
Release
Publishing to the target registry (npm, PyPI, crates.io, Maven Central, etc.), generating changelogs, updating the documentation site, and managing the deprecation lifecycle. Libraries don't deploy — they publish. There is no on-call, no rollback in the traditional sense; a broken release means a new patch version, not a redeployment.
Completion Signal (RFC 2119)
Changelog MUST be updated with all user-visible changes. Version MUST follow semver based on API surface changes. Documentation site MUST reflect the released version. Deprecated APIs MUST have migration guidance and a removal timeline.