release

name	release
description	Automate AgentOp releases: version bump, release notes from commit history, tagging, and GitHub Release publishing. Use when cutting a release, preparing release notes, bumping versions, or publishing builds. Triggers on release, version bump, deploy, publish, changelog, release notes, tag.

Release Automation

Automate the AgentOp release process — version bumps, release notes generation from commit history, tagging, and GitHub Release publishing.

When to Use This Skill

• Cutting a new release (patch, minor, or major)
• Generating release notes from commit history
• Bumping the version across the project
• Reviewing what changed since the last release
• Publishing a draft GitHub Release

Release Infrastructure

File	Purpose
releases/v{version}.md	Release notes file — CI picks this up and sets it as the GitHub Release body
apps/electron/deploy.sh	Local release script — bumps version, commits, tags, pushes
.github/workflows/release.yml	CI workflow — triggered by v* tags, builds macOS/Linux/Windows, uploads to draft GitHub Release
apps/electron/electron-builder.yml	Build config — publish target is GitHub Releases with releaseType: draft
apps/electron/package.json	Source of truth for the app version (field: version)

Release Process

Step 1 — Determine What Changed

Get the previous release tag and list commits since then:

# Find the latest existing tag
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")

# If no tags exist, use all commits
if [ -z "$LAST_TAG" ]; then
  git log --oneline --no-decorate
else
  git log --oneline --no-decorate "$LAST_TAG"..HEAD
fi

Review the commits to determine the appropriate version bump:

• patch — bug fixes, dependency updates, small tweaks
• minor — new features, meaningful UX changes
• major — breaking changes, major rewrites

Step 2 — Create Release Notes File

Create releases/v{version}.md with the release notes. CI automatically picks this file up and sets it as the GitHub Release body — no manual pasting needed.

LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
if [ -z "$LAST_TAG" ]; then
  RANGE="HEAD"
else
  RANGE="$LAST_TAG..HEAD"
fi

# Get commit messages to categorize
git log --format="%h %s" $RANGE

Then create the file:

# Create the releases directory if it doesn't exist
mkdir -p releases

# Create the notes file (version determined in Step 1)
# Example: releases/v0.2.0.md

Release Notes Format

Write the notes file in this format. Omit empty sections. Keep descriptions concise — one line per change, written for developers reading a changelog.

## What's New

### Features

- **Feature name** — Brief description of what it does (#PR if available)

### Improvements

- **Area** — What improved and why it matters

### Bug Fixes

- **What was broken** — What was fixed

### Internal

- Dependency updates, refactors, CI changes (summarize, don't list every dep bump)

**Full Changelog**: https://github.com/macromania/agentop/compare/v{previous}...v{new}

Categorization Rules

Map commit prefixes to sections:

Prefix	Section
feat:, feature:	Features
fix:, bugfix:	Bug Fixes
perf:, improve:, refactor:, ux:	Improvements
deps:, chore:, ci:, build:, test:, docs:	Internal
release:	Skip — these are version bump commits
No prefix	Read the message and categorize by intent

Writing Good Release Notes

• Write for the person updating — what will they notice?
• Lead with the user-visible change, not the implementation
• Bad: "Refactor agent session state management" → Good: "Agent sessions recover faster after crashes"
• Bad: "Add new atom for task status" → Good: "Task status updates are now real-time"
• Group related dependency bumps: "Bumped electron to v35, electron-builder to v26" not 5 separate lines
• If a commit is trivial (typo fix, formatting), skip it unless aggregating with similar ones

Step 3 — Bump Version

Update the version in apps/electron/package.json. This is the source of truth that electron-builder reads.

# Read current version
CURRENT=$(grep '"version"' apps/electron/package.json | head -1 | sed 's/.*"\([0-9]*\.[0-9]*\.[0-9]*\)".*/\1/')
echo "Current: $CURRENT"

# Compute new version (for patch bump example)
IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT"
PATCH=$((PATCH + 1))
NEW="$MAJOR.$MINOR.$PATCH"
echo "New: $NEW"

# Apply
sed -i '' "s/\"version\": \"$CURRENT\"/\"version\": \"$NEW\"/" apps/electron/package.json

Or use the deploy script which handles this automatically:

apps/electron/deploy.sh patch   # or minor, major, or explicit version

Step 4 — Commit, Tag, Push

If not using deploy.sh, do this manually:

git add apps/electron/package.json releases/v$NEW.md
git commit -m "release: v$NEW"
git tag "v$NEW"
git push origin main --tags

Important: The tag push triggers .github/workflows/release.yml which:

1. Builds on macOS, Linux, and Windows runners in parallel
2. Rebuilds better-sqlite3 native module per-platform
3. Uploads artifacts to a draft GitHub Release
4. Generates latest-mac.yml / latest.yml / latest-linux.yml for auto-updater
5. Reads releases/v{version}.md and sets it as the release body (falls back to GitHub auto-generated notes if the file is missing)

Step 5 — Verify the GitHub Release

CI handles everything automatically. After it completes (~5-10 min):

1. Go to https://github.com/macromania/agentop/releases
2. The draft release should have:
   • Release notes from releases/v{version}.md applied as the body
   • All expected artifacts attached:
     • AgentOp-{version}-arm64.dmg + .zip (macOS Apple Silicon)
     • AgentOp-{version}-x64.dmg + .zip (macOS Intel)
     • AgentOp-{version}-x64.exe (Windows)
     • AgentOp-{version}-x64.AppImage (Linux)
     • AgentOp-{version}-amd64.deb (Linux Debian)
     • latest-mac.yml, latest.yml, latest-linux.yml (auto-updater metadata)
3. Review and click Publish release

Quick Release (All-in-One)

For a fast release when you know the bump type:

# 1. Review commits since last release
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)
git log --format="%h %s" "$LAST_TAG..HEAD" | grep -v "release:"

# 2. Create release notes file
mkdir -p releases
# Write releases/v{new-version}.md with categorized notes

# 3. Bump, tag, push (triggers CI — notes file is committed automatically)
apps/electron/deploy.sh patch

# 4. CI builds all platforms, applies release notes → review draft → publish

Troubleshooting

Problem	Fix
CI build fails on macOS codesign	Check entitlements.mac.plist is valid XML — use plutil -lint to verify. Ensure <true/> not <true />.
better-sqlite3 rebuild fails	Electron version mismatch — run bun run rebuild in apps/electron/
Tag already exists	git tag -d v0.1.1 && git push origin :refs/tags/v0.1.1 to delete, then re-tag
Draft release missing artifacts	Check all 3 matrix jobs passed in Actions. Platform-specific failures don't block others (fail-fast: false).
DMG build fails locally with "Resource busy"	Transient hdiutil issue — Spotlight or antivirus locking the mount. Retry or build zip only: bunx electron-builder --mac zip --publish never