Release 2026-05-11

.claude/agents/release-bump-charts.md

@@ -0,0 +1,76 @@
+---
+name: release-bump-charts
+description: Takes a release digest with breaking change info, bumps helm chart versions accordingly, and opens or updates a bump PR for a given release PR number.
+tools: Bash, Read, Write, Edit, Agent
+model: inherit
+---
+
+# Release Bump Charts Agent
+
+You receive a release digest (with breaking change info) and the release PR number. Your job is to bump the helm chart versions and open/update a PR.
+
+---
+
+## Input
+
+The caller provides:
+1. The release PR number (e.g. `123`)
+2. The release digest containing `### Changed Charts` and `### Breaking Changes` sections
+
+## Step 1: Parse the digest
+
+From the digest, identify:
+- Which library charts changed (from `### Changed Charts`)
+- Whether any breaking changes exist (from `### Breaking Changes`)
+
+## Step 2: Bump versions
+
+For each changed library chart listed in the digest, update `helm/library/<name>/Chart.yaml`:
+- If there are breaking changes for that chart: **minor-bump** the `version` (e.g. `0.5.14` → `0.6.0`)
+- If no breaking changes: **patch-bump** the `version` (e.g. `0.5.14` → `0.5.15`)
+
+Do NOT touch `appVersion`.
+
+Then update the matching `dependencies[].version` entry in every `helm/bundles/*/Chart.yaml` that references the bumped library chart.
+
+## Step 3: Check for existing bump PR
+
+```
+gh pr list --head release/bump-charts-<PR_NUMBER> --state open --json number,url
+```
+
+## Step 4a: If a PR already exists
+
+1. Check out the existing `release/bump-charts-<PR_NUMBER>` branch
+2. Reset it to `main`: `git reset --hard origin/main`
+3. Apply the version bumps on top
+4. Force-push the branch
+5. Update the existing PR title and body with `gh pr edit`
+
+## Step 4b: If no PR exists
+
+1. Create branch `release/bump-charts-<PR_NUMBER>` from `main`
+2. Apply the version bumps
+3. Commit changes with message: `Bump chart versions for release PR #<PR_NUMBER>`
+4. Push the branch
+5. Use the **pull-request-creator** agent to open a PR. Provide the motivation:
+   - Which charts were bumped and to which versions
+   - Note that this PR should be merged before the release PR #<PR_NUMBER>
+
+## Step 5: Report
+
+Return a structured report:
+
+```
+## Bump Charts Result
+
+### PR
+- PR #XXX: <url> (opened/updated)
+
+### Bumped Charts
+- cortex: 0.0.47 → 0.0.48
+- cortex-postgres: 0.5.14 → 0.5.15
+
+### Updated Bundles
+- cortex-nova/Chart.yaml: cortex-postgres 0.5.14 → 0.5.15, cortex 0.0.47 → 0.0.48
+```

.claude/agents/release-changelog.md

@@ -0,0 +1,100 @@
+---
+name: release-changelog
+description: Takes a release digest with bumped chart versions, generates a changelog entry, prepends it to CHANGELOG.md, and opens or updates a changelog PR.
+tools: Bash, Read, Write, Edit, Agent
+model: inherit
+---
+
+# Release Changelog Agent
+
+You receive the release PR number, a release digest (with commit details and breaking changes), and the bumped chart versions. Your job is to generate the changelog entry, prepend it to CHANGELOG.md, and open/update a PR.
+
+---
+
+## Input
+
+The caller provides:
+1. The release PR number (e.g. `123`)
+2. The release digest (with commits by component, breaking changes, and changed charts)
+3. The bumped chart versions (e.g. `cortex: 0.0.47 → 0.0.48, cortex-postgres: 0.5.14 → 0.6.0`)
+
+## Step 1: Generate the changelog entry
+
+Using the digest and bumped versions, generate a changelog following this template:
+
+```markdown
+## YYYY-MM-DD — [#NNN](https://github.com/cobaltcore-dev/cortex/pull/NNN)
+
+### <chart-name> v<NEW_bumped_version> (<appVersion>)
+
+Breaking changes:
+- <bullet per meaningful change>
+
+Non-breaking changes:
+- <bullet per meaningful change>
+
+... repeat for each changed chart ...
+
+### General
+
+Breaking changes:
+- <bullet per meaningful change>
+
+Non-breaking changes:
+- <bullet per meaningful change>
+```
+
+Rules:
+- Use the NEW bumped version numbers (provided in input), NOT the pre-bump versions.
+- One `###` section per changed chart only.
+- For bundle charts, list which library versions they include, then any bundle-specific changes.
+- Omit `### General` if empty.
+- No commit SHAs, one line per bullet.
+- Omit `Breaking changes:` subsection if there are none for that chart.
+- Omit `Non-breaking changes:` subsection if there are none for that chart.
+
+## Step 2: Update CHANGELOG.md
+
+1. If `CHANGELOG.md` does not exist, create it with a `# Changelog` header.
+2. Read the existing `CHANGELOG.md`.
+3. Insert the new changelog entry immediately below the `# Changelog` header (before any existing entries).
+
+## Step 3: Check for existing changelog PR
+
+```
+gh pr list --head release/changelog-<PR_NUMBER> --state open --json number,url
+```
+
+## Step 4a: If a PR already exists
+
+1. Check out the existing `release/changelog-<PR_NUMBER>` branch
+2. Reset it to `main`: `git reset --hard origin/main`
+3. Apply the changelog update on top
+4. Force-push the branch
+5. Update the existing PR title and body with `gh pr edit`
+
+## Step 4b: If no PR exists
+
+1. Create branch `release/changelog-<PR_NUMBER>` from `main`
+2. Apply the changelog update
+3. Commit with message: `Update changelog for release PR #<PR_NUMBER>`
+4. Push the branch
+5. Use the **pull-request-creator** agent to open a PR with:
+   - Title: `Update changelog for release PR #<PR_NUMBER>`
+   - Motivation: This PR adds the changelog entry for release PR #<PR_NUMBER>. It should be merged after the release PR.
+
+## Step 5: Report
+
+Return a structured report:
+
+```
+## Changelog PR Result
+
+### PR
+- PR #YYY: <url> (opened/updated)
+
+### Changelog Entry
+<the full changelog entry text that was generated>
+```
+
+Important: Include the full changelog entry text in your report — the orchestrator needs it for the next step.

.claude/agents/release-digest.md

@@ -0,0 +1,81 @@
+---
+name: release-digest
+description: Fetches PR metadata, classifies commits by component, checks helm charts for updated appVersions, determines breaking changes, and produces a structured release digest.
+tools: Bash, Read
+model: inherit
+---
+
+# Release Digest Agent
+
+You produce a structured release digest for a given PR number. The caller passes you the PR number as context.
+
+---
+
+## Step 1: Fetch PR metadata
+
+```
+gh pr view <PR_NUMBER> --json number,title,body,commits,files
+```
+
+## Step 2: Classify commits
+
+For each commit SHA in the PR, inspect the changed files:
+
+```
+git show --name-only --format="%H %s" <sha>
+```
+
+Classify each commit to a component:
+- **Cortex shim**: code touching `internal/shim` or `cmd/shim`
+- **Cortex postgres**: code touching the postgres docker image (`postgres/`), or its helm chart (`helm/library/cortex-postgres`)
+- **Cortex core**: core code touching anything else — the manager or external scheduler logic of cortex
+- **General**: CI, tooling, docs, or other non-code changes
+
+## Step 3: Check helm charts for updated appVersions
+
+Read through the cortex helm charts in the `helm/library/` folder. Check which ones have updated `appVersion` fields (indicating a new Docker image is available). Compare the appVersion in the current branch to what's on `main`:
+
+```
+git diff main...HEAD -- helm/library/*/Chart.yaml
+```
+
+## Step 4: Determine breaking changes
+
+Read the actual diff for each commit that touches code. A change is "breaking" if:
+- It changes or removes the public API (CRD schemas, CLI flags, REST API endpoints). Additions are NOT breaking.
+- It requires a config format change (renaming/removing a values.yaml key, changing expected format).
+
+## Step 5: Produce the release digest
+
+Output in this exact format:
+
+```
+## Release Digest — PR #NNN "{title}"
+
+### Changed Charts
+- cortex v<current_version> (sha-xxxxxxxx)
+- cortex-postgres v<current_version> (sha-xxxxxxxx)
+- cortex-nova v<current_version> — includes cortex v<x>, cortex-postgres v<y>
+
+### Commits by Component
+
+#### cortex core
+- <sha> <subject>
+
+#### cortex postgres
+- <sha> <subject>
+
+#### cortex shim
+- <sha> <subject>
+
+#### General
+- <sha> <subject>
+
+### Breaking Changes
+- [component] <description of breaking change>
+(or "None" if no breaking changes)
+```
+
+Note: The versions in `### Changed Charts` are the CURRENT versions from Chart.yaml (pre-bump). The bump agent will determine the new versions. Include only charts whose `appVersion` actually changed.
+
+Return ONLY the digest. Do not produce a changelog — that is handled by a downstream agent after version bumping.

.claude/agents/release-update-description.md

@@ -0,0 +1,53 @@
+---
+name: release-update-description
+description: Takes a changelog entry, bump PR reference, and changelog PR reference, and updates the release PR description using gh pr edit.
+tools: Bash, Read
+model: inherit
+---
+
+# Release Update Description Agent
+
+You receive the release PR number, the formatted changelog, the bump PR reference, and the changelog PR reference. Your job is to update the release PR description.
+
+---
+
+## Input
+
+The caller provides:
+1. The release PR number (e.g. `123`)
+2. The formatted changelog entry text
+3. The bump PR number and URL (e.g. `#456 https://github.com/...`)
+4. The changelog PR number and URL (e.g. `#457 https://github.com/...`)
+
+## Step 1: Build the PR description body
+
+Construct the PR description using this structure:
+
+```markdown
+## Changelog
+
+<changelog entry text here>
+
+## Dependencies
+
+- Bump PR: #<bump_pr_number> (must be merged before this PR)
+- Changelog PR: #<changelog_pr_number> (merge after this PR)
+```
+
+## Step 2: Update the PR
+
+```
+gh pr edit <PR_NUMBER> --body "<body>"
+```
+
+Use a heredoc or temp file to pass the body to avoid shell quoting issues.
+
+## Step 3: Report
+
+Return:
+
+```
+## PR Description Updated
+
+PR #<PR_NUMBER> description updated with changelog and references to bump PR #<bump_pr_number> and changelog PR #<changelog_pr_number>.
+```