Release

---
name: "release"
description: Cuts a release/<version> branch from the integration branch and opens a release PR into the production branch, with release notes and pre-release checks. Use for "release <version>" when `branches.strategy` is develop-release.
allowed-tools: Bash, Read, Grep, Glob, Skill, Agent, AskUserQuestion
argument-hint: <version, e.g. 1.4.0> [--mode eco|normal|sport]
---

Collect what has merged into the integration branch since the last release, cut `release/<version>`, and open a PR into the production branch.

## 0. Read the config

Read `reference/config.md` under the plugin root (two directories above this skill's directory), then `GROUNDWORK.md` at the repository root as it says. Stop if the file is missing or a key this skill needs is missing.

`branches.strategy` must be `develop-release`. With `main-only` there is nothing to release from; tell the user and stop.

Talk to the user in `language.conversation`. Write the PR title and release notes in `language.artifacts`.

In plan mode, do not refuse. Inspect with read-only tools, write the concrete plan (version, release notes, checks, commands), and ask for approval. After approval, carry it out as planned.

If `docs.rules` and this skill disagree, follow `docs.rules`.

## 1. Preflight

1. **Version and effort.** Parse optional `--mode <eco|normal|sport>` separately, validate it, and otherwise use the configured overall mode. Forward the effective mode to every screen-check skill, including `ux-journey` when it gates releases. The remaining version argument is required and must match `^\d+\.\d+\.\d+$`. Otherwise ask the user to call `/groundwork:release <x.y.z>` and stop.
2. **GitHub CLI.** Run `gh auth status`. If it is not authenticated or lacks permission, stop and tell the user to run `gh auth login` themselves. Never run `gh auth login` or `gh auth switch`.
3. **Clean tree.** If `git status --porcelain` is not empty, tell the user and stop, so unrelated changes cannot ride along.
4. **Fetch.** `git fetch origin <branches.production> <branches.integration> --tags`.
5. **Anything to release?** If `git rev-list --count origin/<branches.production>..origin/<branches.integration>` is 0, say there is nothing to release and stop.
6. **Open release branches.** If `git branch -a --list '*release/*'` shows another release branch, tell the user and ask whether to continue.
7. **Duplicate version.** If a tag `v<version>` or `<version>`, or a branch `release/<version>`, already exists, tell the user and stop.

## 2. Collect changes

Use merged PRs as the source of the notes; commit prefixes are only a hint.

```bash
# When the last release PR merged into the production branch
gh pr list --state merged --base <branches.production> --search "release in:title" --limit 1 \
  --json mergedAt,title,number

# PRs merged into the integration branch since then
gh pr list --state merged --base <branches.integration> --search "merged:>=<last release mergedAt>" \
  --json number,title,body,mergedAt
```

If there is no earlier release PR, use every PR in `origin/<branches.production>..origin/<branches.integration>`.

Sort each PR by what it means to users:

- New capability → **New features**
- Fixes something users ran into → **Bug fixes**
- Refactors and performance work that users notice go in whichever fits better. Otherwise leave them out.
- Docs, chores, style, tests, CI, and build changes → leave out.

## 3. Release notes

```markdown
## <version>

### New features

- <what users can now do>

### Bug fixes

- <the problem users had, now fixed>
```

- Write from the user's point of view.
- Leave out implementation details, internal module names, file paths, and issue and PR numbers.
- Drop an empty section.
- Split one PR into several bullets when it delivers several user-facing changes.
- If `docs.rules` defines a release-note format, follow it instead.

## 4. Pre-release checks

Static checks, plus release QA. Do not try to simulate production or run load tests; passing tests and builds are CI's job.

1. **Destructive migrations.** List migration files changed in `origin/<branches.production>..origin/<branches.integration>` (paths with `migration` or `migrate` in them, or the migration directory `docs.rules` names). Flag any that drop a table, column, constraint, or index; rename a table or column; change a column type; or add `NOT NULL` without a default. If `docs.rules` defines a migration policy such as expand-contract, check against it.
2. **Deploy configuration.** Flag changes to deploy and runtime configuration: CI/CD workflows, container and infrastructure files, and example environment files. A missing environment variable can break the release.
3. **Repository checks.** Apply the checks under `## Release checks` in `GROUNDWORK.md` and any release rules in `docs.rules`.
4. **Release QA.** Resolve `qa.bundle`, `ux.bundle`, and `ux.method` using Screen checks in `reference/config.md`, including the legacy QA mapping and legacy UX behavior. For each check that is release or continuous, run its full before-release gate with the effective mode on the exact `origin/<branches.integration>` candidate. Select only user personas for UX. When `ux.journey` is release, also run its journey gate as Screen checks says. A FAIL or BLOCKED stops the release; do not create a branch or PR. For manual, show uncovered ledger rows as the human checklist. Pin the candidate SHA as `RELEASE_SHA`. QA may update only the coverage ledger in the working tree; keep those evidence-only edits for the final preview and release branch. Any product fix invalidates affected QA and requires fresh verification. Do not move the integration branch or treat unrelated dirty files as QA output.

Print one line per check with ✅ or ⚠️ and, for ⚠️, the file and the pattern found.

## 5. Confirm

Show the version, the release notes, the pinned release candidate, any QA ledger edits to commit on the release branch, and the check results, and ask with AskUserQuestion (in Codex, this is an approval, so ask it as one plain-text question rather than with `request_user_input`):

- Proceed as is
- Edit the notes (the user rewrites them)
- Stop

If any check shows ⚠️, proceed only if the user explicitly chooses to. To change the version, the user calls the skill again; do not guess a new one.

## 6. Branch and push

Re-read the integration head and require it to match the pinned candidate. If it moved, refresh the candidate and required checks before proceeding. Create the release branch from `RELEASE_SHA`. If the only working-tree edits are the previewed QA ledger updates, stage that file and commit those evidence-only edits on the release branch before pushing. Never include unreviewed product changes. If the user stops, leave the ledger edits intact and report them.

```bash
git checkout -b release/<version> <RELEASE_SHA>
# Commit the previewed QA ledger updates here, if any.
git push -u origin release/<version>
```

## 7. Open the PR

```bash
gh pr create --base <branches.production> --head release/<version> \
  --title "Release <version>" --body "<notes from step 5>"
```

Show the PR URL and stop.

## Rules

- No `--no-verify`, force-push, or other destructive git commands.
- Never push to `branches.production` directly. It changes only through the PR.
- Check that no issue numbers, PR numbers, or internal module names leak into the notes.
- If `gh` or git fails, report the root cause and stop. Do not work around it or retry blindly.