adk-release

name: adk-release description: Cuts a new release of ai-sdk — creates a Linear issue, branches, bumps version, updates changelog, runs checks, commits, opens a PR, and returns to main. Merging the PR triggers CI to auto-tag. Use when the user wants to release a new version of the ai_sdk gem.

AI SDK Release

Cuts a release of the ai_sdk gem end-to-end: Linear issue → branch → version bump + changelog → PR. Merging the PR to main triggers CI to auto-tag. There is no manual tagging or gem publishing step.

When to Use

• User says /adk-release 0.2.0 or "release ai-sdk"
• User wants to cut a new version of the gem

Input

A semver version string (e.g. 0.2.0). Passed as the argument.

Paths

All operations happen in /Users/kade.killary/dev/ai-sdk/.

Workflow

Step 1: Create Linear Issue

Use mcp__linear-server__create_issue to create an issue:

• Team: Applied AI
• Project: AI SDK | Ruby Gem
• Title: Bump version to X.Y.Z
• Description: Bump AI::VERSION to X.Y.Z and update CHANGELOG.md for release.
• Assignee: Kade Killary
• Estimate: 1 (XS)

Store the issue identifier (e.g. ML-700) and branch name from the response.

Step 2: Create and Checkout Branch

cd /Users/kade.killary/dev/ai-sdk
git checkout main
git pull origin main
git checkout -b <branch-name-from-linear>

Use the branchName field from the Linear issue response. If no branch name exists, derive one: <issue-id-lowercase>/bump-version-to-X-Y-Z.

Step 3: Determine What's Unreleased

Find the latest tag and gather all commits since it:

cd /Users/kade.killary/dev/ai-sdk
LATEST_TAG=$(git describe --tags --abbrev=0)
git log ${LATEST_TAG}..HEAD --oneline

Also pull the PR numbers and conventional-commit prefixes. Categorize each commit into Keep a Changelog sections:

If there are zero meaningful commits, stop and tell the user there's nothing to release.

Step 4: Draft the Changelog Entry

Read CHANGELOG.md. Build the new version section using today's date:

## [X.Y.Z] - YYYY-MM-DD

### Added
- Description of feature (#PR)

### Fixed
- Description of fix (#PR)

### Changed
- Description of change (#PR)

Rules for the entry:

• Only include sections that have items (don't add empty ### Fixed etc.)
• Each line item should be a human-readable description, not the raw commit message — rewrite if the commit message is unclear
• Include PR number in parentheses when available: (#42)
• Place the new section between ## [Unreleased] and the previous release
• Leave ## [Unreleased] empty (no subsections)

Update the comparison links at the bottom of CHANGELOG.md:

• Change the [Unreleased] link to compare against the new tag: [Unreleased]: https://github.com/simplepractice/ai-sdk/compare/vX.Y.Z...HEAD
• Add a new line for this version: [X.Y.Z]: https://github.com/simplepractice/ai-sdk/compare/vPREVIOUS...vX.Y.Z

Step 5: Bump the Version

Edit lib/ai/version.rb line 2 — update the VERSION constant:

VERSION = "X.Y.Z".freeze

Step 6: Run Checks

Run the required checks before committing:

cd /Users/kade.killary/dev/ai-sdk
bundle exec rubocop
bundle exec rspec

If either fails, stop and surface the error. Do not commit broken code.

Step 7: Commit

Stage exactly two files and commit:

cd /Users/kade.killary/dev/ai-sdk
git add CHANGELOG.md lib/ai/version.rb
git commit -m "[<ISSUE-ID>] Bump version to X.Y.Z"

The commit message follows the repo's [ISSUE-ID] Title pattern — identical to the PR title.

Step 8: Push and Open PR

cd /Users/kade.killary/dev/ai-sdk
git push -u origin <branch-name>

Create the PR using the repo's PR template and conventions:

gh pr create --title "[<ISSUE-ID>] Bump version to X.Y.Z" --label "enhancement" --body "$(cat <<'EOF'
### Summary
- Bump `AI::VERSION` to X.Y.Z
- Update CHANGELOG.md with all changes since vPREVIOUS

### [Contributing guide](https://www.notion.so/simplepractice/Contributing-Guide-13ef2f8242f18099971adbc5c9caad84?pvs=4) checklist:
- [x] The PR has a label
- [x] The PR title follows the format `[$ISSUE_ID] $ISSUE_TITLE`
- [x] The first commit follows the format `[$ISSUE_ID] $ISSUE_TITLE`
- [x] This change does not introduce an API breaking change
- [x] Code has appropriate test coverage
- [x] I have performed a self-review of this code
- [ ] I have requested 2 reviewers
- [x] I have added an assignee

## Linear Issue
<ISSUE-ID>
EOF
)"

Step 9: Return to Main

cd /Users/kade.killary/dev/ai-sdk
git checkout main

Step 10: Update Linear Issue Status

Use mcp__linear-server__update_issue to move the issue to "In Review" state.

Step 11: Post Changelog to Slack

Rewrite the changelog entry from Step 4 into a concise, human-readable Slack message. Do NOT paste the raw markdown. Instead:

• Lead with :package: *ai-sdk vX.Y.Z released*
• Summarize changes as plain-English bullet points — no markdown headers, no PR number links, no Keep a Changelog formatting
• Group related items; drop anything trivial (CI tweaks, test-only changes)
• Keep it short — a teammate skimming Slack should get the gist in 5 seconds

Example:

:package: *ai-sdk v0.5.0 released*

- Added streaming support for chat completions
- Fixed token counting for multi-turn conversations
- Switched default timeout from 30s to 60s

Write the final message to a temp file, then pipe it to the slack CLI:

slack < /tmp/ai-sdk-release-slack.txt

The slack command defaults to #ask-ai-team. Requires SLACK_BOT_TOKEN in the environment. If the token is missing or the post fails, warn the user but do not fail the release — the PR is already open.

Step 12: Confirm

Tell the user:

Release PR created. Once merged to main, CI will automatically create and push the vX.Y.Z tag (see the "Tag Release" job).

There is no gem publish step — this repo only creates a Git tag.

Print the PR URL.

Rules

• Commit message and PR title MUST be identical: [ISSUE-ID] Bump version to X.Y.Z
• Tag format is vX.Y.Z (prefixed with v) — but CI creates it on merge, not this workflow
• Only stage the two release files (CHANGELOG.md, lib/ai/version.rb) — nothing else
• Do NOT manually create or push tags — CI handles tagging via the "Tag Release" job
• Do NOT run gem push — there is no gem publishing step in this repo
• Always return to main when done, even if a step fails
• Run rubocop + rspec before committing — don't ship broken code
• If any step fails, stop and surface the error. Do not retry silently
• Changelog descriptions should be concise and user-facing — strip internal jargon