version-release ยท git:20260921.96b73d4 ยท 2026-09-21 ยท sha256 679ce1780eca0316

version-release git:20260921.96b73d4A

Immutable. This exact content never changes and is served at /api/v1/blob/679ce1780eca0316.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_3ja4xzgaxiiyfai2/679ce1780eca03166e56bb4f049b651e635f6f27d1754689c43c83b77b7b5e3d.json

Then /plugin install version-release@markdownregistry-3ja4xzgaxiiyfai2 in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: version-release
description: 'Version release workflow โ€” release process and GitHub Release notes (not docs/changelog pages).'
disable-model-invocation: true
argument-hint: '[minor|patch] [version?]'
---

# Version Release Workflow

This skill is a router. The detailed steps live in `references/`.

## Scope Boundary (Important)

This skill is only for:

1. Release branch / PR workflow
2. CI trigger constraints (`auto-tag-release.yml`)
3. GitHub Release note writing

This skill is **not** for writing `docs/changelog/*.mdx`.\
If the user asks for website changelog pages, load `../docs-changelog/SKILL.md`.

## Mandatory Companion Skill

For every `/version-release` execution, you MUST load and apply:

- `../../../DESIGN.md` (Voice & Content)

## Overview

The primary development branch is **canary**. All day-to-day development happens on canary. When releasing, canary is merged into main. Conventional release PRs (`๐Ÿš€ release: โ€ฆ`, `release/*`, `hotfix/*`) get a `package.json` bump commit from `release-pr-version.yml` while the PR is open. After merge, `auto-tag-release.yml` tags the merge commit and creates the GitHub Release. `sync-main-to-canary` runs on push to `main`.

Only two release types are used in practice (major releases are extremely rare and can be ignored):

| Type  | Use Case                                       | Frequency             | Source Branch  | PR Title Format                      | Version       | Reference                               |
| ----- | ---------------------------------------------- | --------------------- | -------------- | ------------------------------------ | ------------- | --------------------------------------- |
| Minor | Feature iteration release                      | \~Every 4 weeks       | canary         | `๐Ÿš€ release: v{x.y.0}`               | Manually set  | `references/minor-release.md`           |
| Patch | Weekly release / hotfix / model / DB migration | \~Weekly or as needed | canary or main | Custom (e.g. `๐Ÿš€ release: 20260222`) | Auto patch +1 | `references/patch-release-scenarios.md` |

For writing the release-note body (any release type), see `references/release-notes-style.md`.

## Auto-Release Trigger Rules (`auto-tag-release.yml`)

After a PR is merged into main, CI determines whether to release based on the following priority:

### 1. Minor Release (Exact Version)

PR title matches `๐Ÿš€ release: v{x.y.z}` -> uses the version number from the title.

### 2. Patch Release (Auto patch +1)

Triggered by the following priority:

- **Branch name match**: `hotfix/*` or `release/*` -> triggers directly (skips title detection)
- **Title prefix match**: PRs with the following title prefixes will trigger:
  - `style` / `๐Ÿ’„ style`
  - `feat` / `โœจ feat`
  - `fix` / `๐Ÿ› fix`
  - `refactor` / `โ™ป๏ธ refactor`
  - `hotfix` / `๐Ÿ› hotfix` / `๐Ÿฉน hotfix`
  - `build` / `๐Ÿ‘ท build`

### 3. No Trigger

PRs that don't match any conditions above (e.g. `docs`, `chore`, `ci`, `test`) will not trigger a release when merged into main.

## Automated Actions

1. **On the release PR** (`release-pr-version.yml`) โ€” if `package.json` is behind, commit `๐Ÿ”– chore(release): release version v{x.y.z}` to the PR head. Minor titles `๐Ÿš€ release: v{x.y.z}` use that version; weekly / `release/*` / `hotfix/*` use latest stable tag + patch.
2. **After merge** (`auto-tag-release.yml`) โ€” tag `v{x.y.z}` on the merge commit and create the GitHub Release. Patch version is latest stable tag +1, not `package.json` +1.
3. **`sync-main-to-canary`** โ€” runs on push to `main`.

## Agent Action Guide

When the user requests a release:

### Precheck (applies to all release types)

Before creating the release branch, verify the source branch:

- **Weekly Release** (`release/weekly-*`): must branch from `canary`
- **All other release/hotfix branches**: must branch from `main`; run `git merge-base --is-ancestor main <branch> && echo OK`
- If the branch is based on the wrong source, recreate from the correct base

### Routing

Pick the right reference and follow it end-to-end:

- **Minor release** โ†’ `references/minor-release.md`
- **Patch release** (weekly / hotfix / model launch / DB migration) โ†’ `references/patch-release-scenarios.md`
- **Writing the PR body / release notes** (any release type) โ†’ `references/release-notes-style.md`

### Hard Rules (apply to every release type)

- **Do NOT** manually modify `package.json` version โ€” CI handles it.
- **Do NOT** manually create tags โ€” CI handles them.
- Minor PR title format is strict (`๐Ÿš€ release: v{x.y.z}`).
- Patch PRs do not need an explicit version number.
- Keep release facts accurate; do not invent metrics or availability statements. Release-note inputs (compare base, PR refs, contributor list) **must be derived from `git`** per `references/release-notes-style.md` ยง Computing Inputs โ€” never from memory or descriptions.