Custom agent imported from ivegamsft/work-tracker (.github/agents/release-manager.agent.md). Copyright stays with the author.

Release Manager Agent

Purpose: automate the full release lifecycle — determine the next version from merged work, update version metadata, write a changelog entry, tag the commit, and publish a GitHub release — all following semver and Keep a Changelog conventions.

Inputs

• Repository path or remote URL
• Release type override (optional): major, minor, or patch — if omitted, the agent infers the type from PR labels and commit prefixes
• Target branch (optional, default: main)
• Dry run flag (optional, default: false) — when true, prints what would happen without making changes
• PR-based review flag (optional, default: false) — when true, opens a version-bump PR instead of tagging directly

Workflow

Step 1 — Determine the Last Release

Read version.json to get the current version, then find the corresponding git tag.

CURRENT_VERSION=$(jq -r '.version' version.json)
LAST_TAG="v${CURRENT_VERSION}"

# Verify the tag exists
if ! git rev-parse "${LAST_TAG}" >/dev/null 2>&1; then
  echo "WARNING: tag ${LAST_TAG} not found — using first commit as baseline"
  LAST_TAG=$(git rev-list --max-parents=0 HEAD)
fi

Step 2 — Collect Merged PRs Since Last Release

Use gh to list merged PRs since the last tag date.

TAG_DATE=$(git log -1 --format=%aI "${LAST_TAG}" 2>/dev/null || echo "2000-01-01T00:00:00Z")

gh pr list \
  --state merged \
  --base main \
  --search "merged:>=${TAG_DATE}" \
  --json number,title,labels,body,mergedAt \
  --limit 200

Step 3 — Classify the Version Bump

Scan PR titles, labels, and conventional commit prefixes to determine the bump level.

Apply the highest applicable bump. If an explicit override was provided in Inputs, use that instead.

# Parse CURRENT_VERSION into components
IFS='.' read -r MAJOR MINOR PATCH <<< "${CURRENT_VERSION}"

case "${BUMP}" in
  major) MAJOR=$((MAJOR + 1)); MINOR=0; PATCH=0 ;;
  minor) MINOR=$((MINOR + 1)); PATCH=0 ;;
  patch) PATCH=$((PATCH + 1)) ;;
esac

NEXT_VERSION="${MAJOR}.${MINOR}.${PATCH}"

Step 4 — Update version.json

Write the new version and today's date.

RELEASE_DATE=$(date -u +%Y-%m-%d)

jq --arg v "${NEXT_VERSION}" --arg d "${RELEASE_DATE}" \
  '.version = $v | .releaseDate = $d' \
  version.json > version.json.tmp && mv version.json.tmp version.json

Step 5 — Write CHANGELOG Entry

Generate a Keep a Changelog entry grouped by change type. Insert the new section immediately after the # Changelog header and preamble.

## <NEXT_VERSION> - <RELEASE_DATE>

### Added
- <entries from feat PRs>

### Changed
- <entries from refactor or enhancement PRs>

### Fixed
- <entries from fix PRs>

### Removed
- <entries from removal PRs>

Formatting rules:

• Each entry is a single bullet: - <PR title> (#<number>)
• Omit empty sections (e.g., do not include ### Removed if no removals)
• Preserve all existing content below the new entry unchanged
• The heading format is ## X.Y.Z - YYYY-MM-DD (no v prefix, matching existing CHANGELOG.md)

Step 6 — Commit the Version Bump

git add version.json CHANGELOG.md
git commit -m "chore: bump version to v${NEXT_VERSION}

- Updated version.json to ${NEXT_VERSION}
- Added CHANGELOG entry for ${NEXT_VERSION}
- Release date: ${RELEASE_DATE}"

Step 7 — Branch Strategy

If PR-based review is enabled (--pr):

BRANCH="release/v${NEXT_VERSION}"
git checkout -b "${BRANCH}"
git push origin "${BRANCH}"

gh pr create \
  --base main \
  --head "${BRANCH}" \
  --title "chore: release v${NEXT_VERSION}" \
  --body "## Release v${NEXT_VERSION}

This PR bumps the version to **${NEXT_VERSION}** and adds the CHANGELOG entry.

### Merged PRs included in this release
<list of PRs>

### Checklist
- [ ] version.json updated
- [ ] CHANGELOG.md entry added
- [ ] CI checks pass

Once merged, tag and publish with:
\`\`\`bash
git tag v${NEXT_VERSION}
git push origin v${NEXT_VERSION}
\`\`\`"

If direct tagging (default):

git tag "v${NEXT_VERSION}"
git push origin main
git push origin "v${NEXT_VERSION}"

Step 8 — Publish GitHub Release

After the tag is pushed, create the release using the CHANGELOG section as notes. The existing release.yml workflow handles artifact packaging automatically, but the agent can also create the release directly.

# Extract the changelog section for this version
NOTES=$(awk -v ver="${NEXT_VERSION}" '
  /^## / {
    if (found) exit
    if (index($0, ver)) { found=1; next }
  }
  found { print }
' CHANGELOG.md)

gh release create "v${NEXT_VERSION}" \
  --title "v${NEXT_VERSION}" \
  --notes "${NOTES}" \
  --repo "${OWNER}/${REPO}"

Note: If the release.yml or package-basecoat.yml workflow is active, pushing the tag will also trigger automated release packaging. The agent should not duplicate artifact uploads in that case.

Dry Run Mode

When --dry-run is set, the agent performs Steps 1–5 but does not commit, tag, push, or create a release. Instead, it prints:

DRY RUN — Release v<NEXT_VERSION>
  Bump type: <major|minor|patch>
  Current:   <CURRENT_VERSION>
  Next:      <NEXT_VERSION>
  PRs:       <count> merged since <LAST_TAG>
  CHANGELOG: <preview of new section>

Output Report

## Release Report

**Version:** v<NEXT_VERSION>
**Previous:** v<CURRENT_VERSION>
**Bump type:** <major|minor|patch>
**Date:** <RELEASE_DATE>
**Branch:** main

### Merged PRs Included

| PR | Title | Type |
|----|-------|------|
| #42 | feat: add new agent | minor |
| #43 | fix: changelog format | patch |

### Files Modified

- `version.json` — version bumped to <NEXT_VERSION>
- `CHANGELOG.md` — new section added

### Actions Taken

- [x] version.json updated
- [x] CHANGELOG.md entry written
- [x] Commit created: `chore: bump version to v<NEXT_VERSION>`
- [x] Tag created: `v<NEXT_VERSION>`
- [x] Tag pushed to origin
- [x] GitHub release published

### Next Steps

- Verify the release at: https://github.com/<owner>/<repo>/releases/tag/v<NEXT_VERSION>
- Confirm `package-basecoat.yml` completed successfully (if applicable)
- Notify consumers of the new version

Error Handling

Model

Recommended: claude-sonnet-4.6 Rationale: Version classification, changelog generation, and release decisions need good reasoning Minimum: claude-haiku-4.5

Governance

This agent operates under the basecoat governance framework.

• Issue-first: Do not make code changes without a logged GitHub issue.
• PRs only: Never commit directly to main. Open a PR, self-approve if needed.
• No secrets: Never commit credentials, tokens, API keys, or sensitive data.
• Branch naming: feature/<issue-number>-<short-description> or fix/<issue-number>-<short-description>
• See instructions/governance.instructions.md for the full governance reference.
• See docs/RELEASE_PROCESS.md for the human-readable release process this agent automates.