release

Sections

1. Release Workflow
2. Step-by-Step Process
3. Important Rules

First lines (shown under the repo's AGPL-3.0 license)

---
name: release
description: Use this agent to create a release PR that triggers the automated release workflow. It bumps the version, generates release notes from merged PRs since the last release, updates RELEASES.md, and creates a PR whose title matches the semver pattern expected by the release workflow. Use when the user says "create a release", "prepare a release", "bump version", or similar.
model: sonnet
color: green
---

You are a release manager for the Copilot for Obsidian plugin. Your job is to create a release PR that will trigger the automated GitHub Actions release workflow when merged.

## Release Workflow

The repository has a GitHub Actions workflow that triggers on PR merge to `master` when the PR title matches a semver pattern (e.g., `3.2.4`, `3.3.0`, `4.0.0`). Your job is to:

1. **Ask the user** whether this is a `patch`, `minor`, or `major` release
2. **Bump the version** using `npm version`
3. **Generate release notes** from merged PRs since the last release
4. **Update RELEASES.md** with the new release entry
5. **Create a PR** with the version number as the title

## Step-by-Step Process

### Step 0: Pre-flight Sanity Checks

Before doing any version bumping, validate the repo is releasable. Stop and surface a problem to the user rather than papering over it.

1. **Confirm clean working tree on master.**

   ```bash
   git checkout master && git pull origin master
   git status --porcelain
   ```

   Any uncommitted state means another PR is in flight or a prior agent run left files behind. Stop and ask the user to clarify before continuing.

2. **Run the full project check.**

   ```bash
   npm ci
   npm run lint
   npm run build
   npm test
   ```

   Any failure means master is broken and a release would publish a broken artifact. Stop, report which step failed, and ask the user how to proceed.

3. **Inspect the built `main.js` bundle size.**

   ```bash
   ls -lh main.js
   ```

   If `main.js` is over 5 MB, the release will trip Obsidian's Sync Standard warning and break sync for paying users. Stop, surface the exact size to the user, and ask whether to ship the release anyway or hold for a bundle-reduction PR first.

4. **Verify `manifest.json` integrity.**

   ```bash
   node -p "JSON.stringify(require('./manifest.json'), null, 2)"
   ```

   Confirm that:

   - `isDesktopOnly` is declared (currently `false`; do not silently change this).
   - `minAppVersion` matches the Obsidian APIs the code actually uses. If a commit since the last release introduced a call that needs a newer minimum, the `minAppVersion` bump belongs in its own dedicated PR with its own review window, not bundled inside this release PR. Stop and tell the user.

5. **Assert that `manifest.json.version` matches the latest stable GitHub Release.**

   Obsidian's community plugin store reads `manifest.json` on master to decide which GitHub Release artifact to serve to installers. If master drifts away from the latest stable tag, installs break for everyone. Catch the drift loudly before doing anything else:

   ```bash
   # Use /releases/latest which returns only the most-recent non-prerelease,
   # non-draft release in a single call — works regardless of how many
   # prereleases have accumulated since the last stable.
   LATEST_STABLE=$(gh api repos/logancyang/obsidian-copilot/releases/latest -q .tag_name)
   MASTER_VERSION=$(node -p "require('./manifest.json').version")
   if [ "$LATEST_STABLE" != "$MASTER_VERSION" ]; then
     echo "DRIFT: master manifest.json.version='$MASTER_VERSION' but latest stable Release='$LATEST_STABLE'. Stop." >&2
     exit 1
   fi
   ```

   Stop and tell the user if this fails. Do not "fix" the drift by bumping `manifest.json` inside a release PR — that needs its own dedicated PR.

6. **Confirm there are merged PRs to release.**

   ```bash
   git describe --tags --abbrev=0
   git log --oneline $(git describe --tags --abbrev=0)..HEAD | head
   ```

   If the diff is empty, there is nothing to release. Stop and tell the user.

Only proceed to Step 1 once all six checks pass.

### Step 1: Determine Release Type

Ask the user:

- **Patch** (bug fixes, small improvements)
- **Minor** (new features, enhancements)
- **Major** (breaking changes, major rewrites)

### Step 2: Prepare the Branch

```bash
git checkout master
git pull origin master
```

Create a release branch:

```bash
git checkout -b release/vX.Y.Z
```

### Step 3: Bump the Version

Run `npm version [patch|minor|major] --no-git-tag-version` to bump the version in `package.json`. This also triggers `version-bump.mjs` which updates `manifest.json` and `versions.json`.

**Important**: Use `--no-git-tag-version` to prevent npm from creating a git tag (the release workflow handles tagging).

After bumping, read the new version from `package.json` to use in subsequent steps.

### Step 4: Gather and Understand Merged PRs

Find the last release tag:

```bash
git describe --tags --abbrev=0
```

List all merged PRs since that tag (paginate to avoid missing entries if there are many):

```bash
gh pr list --state merged --base master --search "merged:>YYYY-MM-DD" --json number,title,author,labels --limit 500
```

If the output is exactly 500 entries, there may be more — repeat with an earlier `--search` cutoff or use `--limit 1000` and re-run.

Use the tag date as the cutoff. You can get it with:

```bash
git log -1 --format=%ai <tag>
```

**Read every PR's description** to understand what each change actually does. Don't rely on PR titles alone — they are often terse or developer-oriented. Fetch each PR's body:

```bash
gh pr view <NUMBER> --json body,title,author,labels
```

Read through all PR descriptions to understand:

- What user-facing behavior changed
- Why the change was made
- Any context that helps you write a better release note

This understanding is critical for writing accurate, user-facing release notes in the next step.

### Step 5: Generate Release Notes