me2resh/apexyard / .claude/skills/release
release
VerifiedCut an apexyard release — diff dev↔main, pick semver bump, generate CHANGELOG, open release PR, auto-tag on merge.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 32.8 KB |
SKILL.md
View on GitHub---
name: release
description: Cut an apexyard release — diff dev↔main, pick semver bump, generate CHANGELOG, open release PR, auto-tag on merge.
argument-hint: "[--dry-run] [<version, e.g. v1.2.0>]"
allowed-tools: Bash, Read, Write
---
# /release — Cut an apexyard release
Generated release PR descriptions and release notes are durable, human-facing
artefacts. Read `.claude/rules/writing-standard.md`. Use the **controlled technical writing profile**:
lead with the outcome and next action, use plain concise prose, and remove empty
sections.
Standardises the `dev` → `main` release flow introduced by AgDR-0007. Reads the conventional-commit log between `main` and `dev`, proposes a semver bump, **generates and writes the CHANGELOG entry**, **opens the release PR** (dev→main), and triggers the `auto-tag-on-release-pr-merge` GitHub Actions workflow that tags the squash commit and creates a GitHub Release after merge. One command drives the operator from "nothing" to "PR open, ready for Rex + CEO". The tag and GitHub Release entry are created automatically by CI when the PR merges. The release PR also records a `Released-From` trailer with the exact `dev` cut-point SHA, and the changelog step warns loudly if commits inside the resolved changelog range aren't all making it into entries — both guard against the #872 changelog-truncation failure mode. Design rationale: AgDR-0076, AgDR-0094.
This skill is **framework-only** — it's for cutting apexyard releases, not for releasing managed projects under governance. Managed projects stay trunk-based and don't have a release-cut flow.
## Usage
```
/release # auto-detect bump from conventional commits
/release v1.2.0 # explicit version, skip auto-detect
/release --dry-run # preview changelog + PR body without writing any files
/release --dry-run v1.2.0
```
## Process
### 1. Pre-flight
Verify:
- Current repo IS the apexyard framework (origin or upstream is `me2resh/apexyard`). Refuse otherwise — this skill is framework-only.
- Working tree is clean. Refuse if uncommitted changes.
- `dev` branch exists (`git rev-parse --verify upstream/dev`). Refuse if absent — adopt the dev/main model first.
- `dev` is ahead of `main` by ≥ 1 commit. Refuse if equal — nothing to release.
### 2. Pick a version
If `<version>` arg was passed, use it (must match `v\d+\.\d+\.\d+`).
Otherwise auto-detect from the conventional-commit types in `git log upstream/main..upstream/dev`:
| Found | Bump |
|-------|------|
| Any commit subject starts with `feat!:` / `feat(...)!:` / `<type>!:` (breaking marker) | **MAJOR** |
| Any `feat:` / `feat(...):` (and no breaking) | **MINOR** |
| Only `fix:` / `chore:` / `docs:` / `refactor:` / `test:` / `style:` / `perf:` / `build:` / `ci:` (and no `feat:` or breaking) | **PATCH** |
Read the current latest tag:
```bash
PREV_TAG=$(git describe --tags --abbrev=0 upstream/main 2>/dev/null \
|| gh api repos/me2resh/apexyard/releases/latest --jq '.tag_name' 2>/dev/null \
|| echo "NONE")
```
Bump accordingly. Show the user:
```
Current latest tag: vX.Y.Z
Proposed next: vA.B.C (MINOR — N feat commits, M fix commits)
Override? [Enter to accept, or type a version like v1.3.0]
```
### 3. Generate the CHANGELOG draft
Call the helper script `bin/release-changelog.sh`, which encapsulates the `git log` + conventional-commit grouping + PR-number extraction logic and is independently tested. Capture both its stdout (the changelog) and stderr (the resolved commit range) — the count-mismatch guard below needs both:
```bash
CHANGELOG_DRAFT=$(PREV_TAG="vX.Y.Z" \
HEAD_REF="upstream/dev" \
VERSION="vA.B.C" \
DATE="$(date +%F)" \
bash bin/release-changelog.sh 2>/tmp/release-changelog-range.txt)
echo "$CHANGELOG_DRAFT"
# The script also prints the exact range it generated the changelog from —
# trailer-anchored (`<Released-From sha>..HEAD_REF`) when PREV_TAG carries a
# Released-From trailer, or the #737 sync-boundary heuristic otherwise. The
# count-mismatch guard below MUST compare against this range, not main..dev.
LOG_RANGE=$(grep -oE 'RELEASE_CHANGELOG_RANGE=.*' /tmp/release-changelog-range.txt | cut -d= -f2-)
# #1017: fail CLOSED here, not at the arithmetic below. An empty/unparseable
# $LOG_RANGE must stop the release, not silently flow into `git rev-list
# --count ""` (whose stderr never reaches $RAW_COUNT and would let the guard
# read a "0 commits, 0 gap" pass — AgDR-0104: "a gate that can't evaluate its
# precondition must block, not allow").
if [ -z "$LOG_RANGE" ]; then
echo "ERROR: could not read RELEASE_CHANGELOG_RANGE from bin/release-changelog.sh's stderr (see /tmp/release-changelog-range.txt). The count-mismatch guard has nothing to check against — do NOT proceed until this is resolved." >&2
exit 1
fi
```
**#1076 + #1490 — a `Closes` bullet requires a same-repo scope AND a closing keyword in the real PR body.** `bin/release-changelog.sh` emits `- Closes #N` only when the commit subject carries a recognised same-repo conventional-commit scope (`fix(#1042): ...`) **and** the PR body fetched with `$RELEASE_GH pr view <PR> --repo <repo> --json body --jq .body` (for subjects ending in `(#<PR>)`) contains a GitHub closing keyword for that same number (`Closes #1042`, `Fixes #1042`, or `Resolves #1042`). Do not read the squash commit body (`%b`): this repo uses `squash_merge_commit_message=COMMIT_MESSAGES`, so `%b` holds branch commit messages, not the PR description. A title reference alone is not enough when the fetch succeeds: a PR titled `feat(#N)` whose body says only `Refs #N` must produce no close line (#1490 — that nearly closed partially-fixed issues in v5.7.0). If `gh` fails for a PR, keep the pre-#1490 / `dev` behaviour for that commit (scoped title closes) and print a warning naming the PR — never silently drop a close because of a fetch failure. Unscoped commits, cross-repo scopes (`docs(owner/repo#N): ...`), and revert commits still emit no `Closes` line at all (#1076). Governing rule: prefer a MISSING close over a WRONG close when the PR body is readable.
The helper emits markdown to stdout in the format:
```markdown
## [vA.B.C] — YYYY-MM-DD
Minor release — N features, M fixes.
### Added (feat)
- (#NN) <subject> — <short-sha>
...
### Fixed (fix)
- (#NN) <subject> — <short-sha>
### Changed (refactor / chore / docs)
- (#NN) <subject> — <short-sha>
### Breaking
- <only if breaking-marker commits exist>
### Closes
- Closes #N
- Closes #M
...
```
**#1056 — one bullet per reference, not a comma list.** GitHub's `Closes` keyword only auto-closes the reference *immediately following* it — a single `Closes #N, #M, #P` line only ever closed `#N`; everything after the first was silently inert. The generator now emits one `- Closes #N` bullet per reference so every one of them actually fires. **#1076 + #1490 narrowed which numbers are eligible:** a same-repo scoped commit whose **PR body** (via `gh pr view`) closes that number (`fix(#1042): ... (#PR)` + `Closes #1042` in the PR body) is eligible; a scoped title with only `Refs #N` in the PR body is not; an unscoped commit, a cross-repo scope, and a revert commit are not. On a `gh` fetch failure the scoped title still closes, with a warning. A release with fewer `Closes` bullets than a title-only generator is expected when titles scoped issues that the PR bodies only referenced.
#### Count-mismatch guard (AgDR-0094, option D)
Immediately after generating the draft, sanity-check its entry count against the raw commit count in `$LOG_RANGE` — the **same range `bin/release-changelog.sh` actually built the changelog from**, captured in step 3 above. This is the cheap, always-on backstop behind the `Released-From` trailer (step 4) — it's what caught the v5.0.0 under-count by hand, and it stays even after the trailer exists as defence in depth against a mangled trailer or a trailer-less pre-AgDR-0094 tag.
**#1002 — do not compare against `upstream/main..upstream/dev`.** Under the release-cut model `main` only ever receives squash merges, so every individual `dev` commit stays permanently unreachable from `main` — `main..dev` grows monotonically with every release and can never shrink. Comparing the changelog's entry count against that raw, ever-growing number always false-positives (v5.2.0 cut: 402 raw commits vs. ~1-2 real entries, a "gap" of 400 on a perfectly correct changelog). `$LOG_RANGE` is anchored on the actual cut point (the `Released-From` trailer, or the #737 sync-boundary fallback) and is the range that matters:
**#1017 — what this guard can (and can't) still see.** `RAW_COUNT` and `ENTRY_COUNT` are now *both* derived from the same `$LOG_RANGE`, so the guard can no longer catch a truncated *range* the way it originally did — if `$LOG_RANGE` itself were too narrow, both counts would shrink together and the gap would stay small. That's an acceptable trade, not a silent regression: `$LOG_RANGE`'s anchor is exact by construction once a `Released-From` trailer exists (AgDR-0094), and step 6's post-merge check now makes a missing trailer a hard failure — so the truncated-range case is closed at its source. What the guard genuinely still catches is **classification drop-out inside a correct range**: a commit that really is inside `$LOG_RANGE` but that `bin/release-changelog.sh` didn't turn into a changelog bullet (a subject it failed to classify, a filtering bug, etc.). The warning text below describes that condition, not the old truncated-range one — say what's actually being detected, not what the guard detected before #1012 re-anchored it.
```bash
RAW_COUNT=$(git rev-list --count "$LOG_RANGE") || {
# #1017: fail CLOSED — don't let a `git rev-list` failure (empty or
# malformed $LOG_RANGE) leave $RAW_COUNT unset/empty and the arithmetic
# below silently treat it as 0 (GAP would go negative, no warning, guard
# passes quiet on exactly the precondition-failure case it exists to catch).
echo "ERROR: 'git rev-list --count $LOG_RANGE' failed — the count-mismatch guard cannot evaluate its precondition. Do NOT proceed; fix \$LOG_RANGE (see /tmp/release-changelog-range.txt) and rerun." >&2
exit 1
}
# Count changelog entry bullets, excluding the "- Closes #N" summary bullets
# (#1002: they are a summary, not an entry, and used to be miscounted as one,
# causing an off-by-one on every run; #1056 emits one such bullet PER
# reference instead of a single comma-joined line, so `grep -v` here still
# needs to exclude ALL of them — `-c` already counts non-matching lines, so
# no change to this filter itself was needed, only to this comment).
ENTRY_COUNT=$(printf '%s\n' "$CHANGELOG_DRAFT" | grep -E '^- ' | grep -vcE '^- Closes ' || true)
[ -n "$ENTRY_COUNT" ] || ENTRY_COUNT=0
GAP=$(( RAW_COUNT - ENTRY_COUNT ))
# Tolerance: release/sync/"Merge branch" marker commits are excluded from the
# changelog BY DESIGN (bin/release-changelog.sh's classify step) — a handful
# of those is normal, not a bug. A gap much larger than that means commits
# genuinely inside $LOG_RANGE are failing to classify into changelog entries
# — NOT a truncated range (see the #1017 note above; $LOG_RANGE itself is
# anchored on the Released-From trailer or the #737 fallback either way).
TOLERANCE=5
if [ "$GAP" -gt "$TOLERANCE" ]; then
echo "⚠️ WARNING: the release range ($LOG_RANGE) has $RAW_COUNT commits but the changelog lists only $ENTRY_COUNT entries (gap: $GAP, tolerance: $TOLERANCE)."
echo " Commits inside \$LOG_RANGE are not making it into changelog entries — read 'git log $LOG_RANGE --oneline' against the draft above and find what's missing before proceeding."
fi
```
#### Migration script check (soft, #1105)
Immediately after the changelog draft, check whether this release carries a per-adopter migration script. This is the check `docs/upgrading.md` and `.claude/skills/update/SKILL.md` § 8b have documented since AgDR-0032 but that never actually existed here until #1105 — for 21 consecutive releases nothing flagged the omission, which is exactly how `.claude/migrations/` ended up with scripts for only two of the ~30 release hops it should cover. **This check is advisory only — it warns, it does not block the release.** Making it a hard gate is a larger design decision than this fix covers (see Rule 13 below for why it's deliberately left as a follow-up, not shipped here).
```bash
MIGRATION_SCRIPT=".claude/migrations/${PREV_TAG}-to-vA.B.C.sh"
if [ ! -f "$MIGRATION_SCRIPT" ]; then
echo "⚠️ WARNING: no migration script found at $MIGRATION_SCRIPT."
echo " Every release should ship one — a real migration OR a no-op"
echo " placeholder — so /update's per-release migration chain"
echo " (.claude/migrations/, walked by _lib-migration-chain.sh) stays"
echo " walkable for adopters syncing across this release. See"
echo " .claude/migrations/README.md § 'Authoring a new migration'."
echo " If this release genuinely needs no adopter action, create the"
echo " no-op placeholder now (copy an existing one, e.g."
echo " v5.2.0-to-v5.3.0.sh, as the template) before opening the PR."
else
echo "✓ Migration script present: $MIGRATION_SCRIPT"
fi
```
#### Lines this release removes from main (#1490)
After the changelog draft (and on `--dry-run` against `upstream/dev`; after step 4 against the release branch), list every line the release tip deletes from `main`. A release cut from `dev` can drop content that is still on `main` — the v5.6.3 sync removed two contributor rows from `README.md` on `dev`, and the v5.7.0 release then removed them from `main` (#1393). Call the helper, show the listing, and **ask before continuing** when it is non-empty:
```bash
# On --dry-run use upstream/dev. After step 4 use the release branch tip.
COMPARE_REF="${RELEASE_BRANCH:-upstream/dev}"
REMOVED_LINES=$(MAIN_REF="upstream/main" HEAD_REF="$COMPARE_REF" \
bash bin/release-list-removed-lines.sh)
if [ -n "$REMOVED_LINES" ]; then
echo "⚠️ WARNING: this release REMOVES the following lines from main:"
printf '%s\n' "$REMOVED_LINES"
echo ""
echo "These deletions ship to main when the release PR merges."
echo "Continue with the release? [y/N]"
# Stop unless the operator explicitly confirms. Do not open the PR on "N".
else
echo "✓ Release removes no lines from main."
fi
```
**Show the draft** (and both warnings, if any) and let the user edit interactively before proceeding. On `--dry-run`, print the draft and stop here with:
```
Dry run — no changes made. Remove --dry-run to execute.
```
### 4. Prepare and push the release branch
Skip all of steps 4–5 on `--dry-run`.
```bash
# Check out the release branch from dev
git fetch upstream
# AgDR-0094: record the exact cut point NOW, while it's still knowable. This is
# the sha bin/release-changelog.sh will read back out of the NEXT release's
# PREV_TAG trailer — capture it here, not after checkout (the ref is what
# matters, not the local branch's HEAD, but capturing immediately after fetch
# keeps this unambiguous).
DEV_SHA=$(git rev-parse upstream/dev)
git checkout -b "release/vA.B.C" upstream/dev
# Write the CHANGELOG entry at the top of CHANGELOG.md
# (prepend the draft from step 3 above the previous top entry)
git add CHANGELOG.md
git commit -m "chore: release vA.B.C
- Prepend CHANGELOG section for vA.B.C
Refs #<release-ticket>
Released-From: $DEV_SHA"
# Push to upstream (not origin — release PRs target me2resh/apexyard)
git push upstream "release/vA.B.C"
```
**#1004 — the trailer belongs in this commit message, not only the PR body.** The release branch has exactly one commit, so this is the message a squash carries forward by construction — independent of how the merge is invoked. See step 6 for why the PR body copy alone used to silently lose the trailer.
**#1490 — re-run the removed-lines check against the release branch** before opening the PR (step 5). Step 3's dry-run compared `upstream/main..upstream/dev`. The release branch now also carries the CHANGELOG commit, so re-check with `HEAD_REF=release/vA.B.C`. If new removals appear, show them and ask again before `gh pr create`.
### 5. Open the release PR
```bash
gh pr create \
--repo me2resh/apexyard \
--base main \
--head "release/vA.B.C" \
--title "release(#<release-ticket>): vA.B.C" \
--body-file /tmp/release-pr-body.md
```
**PR body template** (write to `/tmp/release-pr-body.md` before the `gh pr create` call). Interpolate `$DEV_SHA` (captured above) into the final line, matching the trailer already written into the branch commit in step 4. This copy is for **human visibility** on the PR page — this repo's `squash_merge_commit_message` setting is `COMMIT_MESSAGES`, so GitHub builds the squash commit's body from the branch's own commit messages, not this PR body, at merge time (#1004). The step-4 commit message is the authoritative copy the squash carries forward; keep this one in sync so a reviewer reading the PR sees the same trailer without having to check the branch commit:
```markdown
<!-- multi-close: approved -->
## Summary
- **Releases vA.B.C** — see CHANGELOG section below for the full list of changes included in this release
- **CHANGELOG.md updated** — new section prepended at the top with grouped feat/fix/chore entries and PR refs
- **Auto-tag on merge** — `.github/workflows/auto-tag-on-release-pr-merge.yml` will tag the squash commit on main and create a GitHub Release entry automatically when this PR merges (AgDR-0076)
- **Release provenance recorded** — a `Released-From` trailer captures the exact `dev` SHA this release was cut from, so the next release's changelog range is deterministic instead of inferred (AgDR-0094, #872)
## CHANGELOG
<paste the draft from step 3>
## Migration script
- [ ] Does this release need a per-adopter migration? A migration script for this release — `.claude/migrations/${PREV_TAG}-to-vA.B.C.sh` (real migration OR no-op placeholder) — is included in this PR, and `docs/upgrading.md`'s "What each migration does" table has a matching row. See `.claude/migrations/README.md`. (Checked automatically by step 3's soft warning — see #1105.)
## Testing
1. After merge, confirm CI creates tag `vA.B.C` on `main` (check the `auto-tag-on-release-pr-merge` workflow run)
2. Verify `git describe --tags --abbrev=0 upstream/main` returns `vA.B.C`
3. Run `/release-sync vA.B.C` to sync main→dev and prevent squash divergence
4. Verify the squash commit's message carries the trailer: `git log -1 --pretty=format:'%(trailers:key=Released-From,valueonly)' vA.B.C`
Refs #<release-ticket>
---
## Glossary
| Term | Definition |
|------|------------|
| Squash merge | GitHub merges all commits on the PR branch into a single commit on main; the branch HEAD is discarded and the resulting main tip has a new SHA |
| Auto-tag | The `auto-tag-on-release-pr-merge.yml` workflow fires on `pull_request` → `closed` + `merged` for `release/v*` branches, tags `github.sha` (the squash commit), and creates a GitHub Release |
| Ancestry guard | `git merge-base --is-ancestor <sha> main` — fails if the tag would not be reachable from main, preventing a mis-placed tag like v2.3.0 |
| `/release-sync` | The mandatory follow-up skill that merges main→dev after a squash-merge release, preventing SHA divergence accumulation |
| `Released-From` trailer | A git trailer (`Key: value` in the commit message's final paragraph) recording the exact `dev` SHA this release was cut from — `bin/release-changelog.sh` reads it back for the next release's changelog range (AgDR-0094) |
Released-From: $DEV_SHA
```
**Why the trailer sits after the Glossary, as its own final paragraph:** `git interpret-trailers` (and the `%(trailers:...)` pretty-format used by `bin/release-changelog.sh`) only recognises a trailer block when it is the LAST paragraph of the message — a blank line before it, nothing but `Key: value` lines after it. Putting `Released-From:` anywhere earlier (e.g. inside the Summary or Testing sections) would make it invisible to the reader on the next release cut. Do not add anything below the trailer line.
**PR title format** (`release` is whitelisted in `pr.title_type_whitelist` since #168):
```
release(#<release-ticket>): vA.B.C
```
### 6. Wait for review + merge (operator step)
The release PR runs through the normal flow:
- Code Reviewer (Rex) on the PR via `/code-review`
- CEO `/approve-merge`
- Merge gate green
- Squash-merge to `main`
`/release` does **not** auto-merge. The CEO retains the discrete moment. The tag and GitHub Release are created automatically by the `auto-tag-on-release-pr-merge.yml` CI workflow **after** the merge.
**#1004 — merge with an explicit subject + body, not a bare `gh pr merge --squash`.** This repo has `squash_merge_commit_message=COMMIT_MESSAGES` (`gh api repos/me2resh/apexyard --jq '.squash_merge_commit_message'`), so GitHub's *default* squash body is built from the release branch's own commit messages, not the PR body. Step 4 already writes the `Released-From` trailer into the branch's sole commit, so a bare `gh pr merge --squash` would, in the common case, still carry the trailer through by construction. Don't rely on that alone — pass the reviewed PR body explicitly instead, so the merged commit is guaranteed to match what Rex and the CEO actually reviewed, independent of repo settings, a stray fixup commit changing the branch's commit count, or a future change to `squash_merge_commit_message`:
```bash
gh pr merge <pr-number> --repo me2resh/apexyard --squash \
--subject "release(#<release-ticket>): vA.B.C" \
--body-file /tmp/release-pr-body.md
```
`/tmp/release-pr-body.md` is the same file written in step 5 — its final paragraph is already the `Released-From` trailer, so this is the one merge command that keeps the trailer, the changelog, and the reviewed content all in sync on the squash commit.
**Merging through `/approve-merge` instead of this raw command (#1136, `AgDR-0132`):** `/approve-merge` is the mandated human-only merge path (#1042) — in practice this step's merge almost always runs there, not as the raw `gh pr merge` shown above. `/approve-merge` now detects a release-class PR (head branch `release/vA.B.C`, or title starting `release(`) the same way it already detects a sync-class PR, and automatically passes `--subject`/`--body-file` built from the PR's own title/body — so it produces the same trailer-preserving squash this rule describes, without the operator needing to run the raw command by hand. See `.claude/skills/approve-merge/SKILL.md` step 6. The raw command above stays documented as the fallback for a manual merge outside `/approve-merge` (e.g. `tracker.kind=none`, or the CEO merging directly on the GitHub UI/CLI).
**Why not just change the repo's `squash_merge_commit_message` setting to `PR_BODY`?** Considered and rejected: that's a repo-wide default that would change the squash body of *every* PR merged to this repo, not just releases — the least-targeted option from #1004's own candidate list. The explicit `--subject`/`--body-file` flags above override the default only for this one merge call, which is exactly the blast radius this fix needs.
**Verify immediately after merge — do not skip:**
```bash
git fetch upstream main
TRAILER=$(git log -1 --pretty=format:'%(trailers:key=Released-From,valueonly)' upstream/main)
if [ -z "$TRAILER" ]; then
echo "ERROR: squash commit on main has NO Released-From trailer." >&2
echo "The next release's changelog range will silently fall back to the" >&2
echo "#737 sync-boundary heuristic. Do not proceed to /release-sync until" >&2
echo "this is understood — check what merge command was actually used." >&2
exit 1
fi
echo "Released-From trailer confirmed: $TRAILER"
```
This is the loud-failure the trailer mechanism needs (#1004) — a missing trailer is otherwise invisible until the *next* release cut mis-anchors its range.
### 7. Tag + GitHub Release (automated via CI)
When the release PR is squash-merged to `main`, the `.github/workflows/auto-tag-on-release-pr-merge.yml` workflow fires automatically:
1. Extracts the version from the branch name (`release/vA.B.C` → `vA.B.C`).
2. Uses `github.sha` (the squash commit SHA — already the correct commit on `main`).
3. Runs the ancestry guard: `git merge-base --is-ancestor <sha> main`.
4. Creates an annotated tag and pushes it with `git push origin --tags`.
5. Creates a GitHub Release entry from the CHANGELOG section in the PR body (in the same job — a tag pushed via GITHUB_TOKEN does not trigger a secondary release workflow).
**No manual tagging required** after merge. The workflow handles it.
#### Manual fallback (if CI workflow fails)
If the auto-tag workflow fails for any reason, follow the manual steps:
```bash
# 1. Fetch so upstream/main points at the squash commit.
git fetch upstream
# 2. Tag the tip of upstream/main (the squash commit, NOT the branch HEAD).
git tag vA.B.C upstream/main
# 3. Ancestry guard before pushing.
if ! git merge-base --is-ancestor vA.B.C upstream/main; then
echo "ERROR: tag is mis-placed — delete and re-tag." >&2
exit 1
fi
# 4. Push the tag (use --tags, not the bare tag name, to avoid the
# branch-name validator hook misfiring on tag-push commands).
git push upstream --tags
```
#### Post-tag release checklist
Verify all four assertions hold (the first three: CI workflow also checks these; the fourth: step 6's verification above, repeated here so it isn't lost if step 6 was skipped):
- [ ] `git merge-base --is-ancestor vA.B.C upstream/main` exits 0
- [ ] `git describe --tags --abbrev=0 upstream/main` returns `vA.B.C`
- [ ] GitHub Release entry exists at `https://github.com/me2resh/apexyard/releases/tag/vA.B.C`
- [ ] `git log -1 --pretty=format:'%(trailers:key=Released-From,valueonly)' vA.B.C` is **non-empty** (#1004) — if empty, STOP before running `/release-sync`; the next release's changelog range will silently degrade to the sync-boundary heuristic
### 8. Confirm
```
Released vA.B.C — auto-tag workflow running on CI, will tag main + create GitHub Release.
N tickets auto-closed via the release PR.
Drift banner on adopters' forks will fire on next session.
Next: /release-sync vA.B.C
```
### 9. Open the main→dev sync PR (MANDATORY after every release)
Squash-merging dev→main creates SHA divergence: the squash commit on `main` is absent from `dev`, causing the next release PR to accumulate conflicts. Every release must be followed immediately by a sync-back PR.
Invoke:
```
/release-sync vA.B.C
```
This files a `sync/main-to-dev-after-vA.B.C → dev` PR that merges `upstream/main` into `upstream/dev` with `-X ours`, making the squash commit an ancestor of `dev`. The skill is idempotent — if main and dev are already in sync it exits 0 without creating a PR.
**Do not skip this step.** The v2.0.0 release suffered 99 merge conflicts because accumulated sync-back skips were not addressed for multiple release cycles (#403).
### 10. After the release (advisory checklist)
Do these steps after `/release-sync` merges. No hook enforces them. Skip none.
An outside reporter is a person who is not a maintainer account (`me2resh`, `atlas-apex`) and who opened an issue.
1. Update the README contributor credits. Add each new PR author and each new issue author since the previous release.
2. Comment on each closed issue in the release that an outside reporter opened. Name the version, link the release, and thank the reporter.
3. Add a "Thanks" section to the GitHub release notes. Name the same reporters.
4. Update the website to the new version. Use the site's own sync process (`me2resh/apexyard-site`, plan `plan-release-sync`).
Step 4 matters. The v5.10.0 release left the site on v5.6.3.
## Rules
1. **Framework-only.** Refuse to run on a managed project. The dev/main split is apexyard-the-framework's pattern, not the portfolio's.
2. **Pre-flight every check** in step 1 — never proceed past a dirty tree, missing dev branch, or zero-commit delta.
3. **Always show the bump for confirmation** — auto-detection is a proposal, not a fait accompli. The CEO's eyes are the final check on semver intent.
4. **CHANGELOG is editable** before the release PR opens. Don't auto-file what hasn't been reviewed.
5. **Never auto-merge the release PR.** Rex + CEO approval applies as for any PR. The skill stops at "PR opened."
6. **Never tag before merge, and never tag the release-branch HEAD.** The auto-tag workflow handles tagging after merge, always using `github.sha` (the squash commit). The manual fallback similarly tags `upstream/main`. See step 7 for the full guard.
7. **`<!-- multi-close: approved -->`** in the release PR body is required — release PRs legitimately close many tickets at once.
8. **`--dry-run` stops before writing any files.** The draft CHANGELOG section and PR body are shown; nothing is committed, branched, pushed, or filed.
9. **The `Released-From` trailer must be its own final paragraph** in BOTH the step-4 branch commit and the step-5 PR body (AgDR-0094). It is what makes the next release's changelog range deterministic — a trailer that lands mid-body (or gets pushed off the end by later edits) silently degrades back to the pre-AgDR-0094 sync-boundary heuristic, with all its known failure modes (#737, #872).
10. **Show the count-mismatch warning if it fires** — a loud gap between `$LOG_RANGE`'s raw commit count and the changelog's entry count means commits inside that range didn't make it into changelog entries (#1017 — not a truncated range; both counts derive from the same `$LOG_RANGE`, so a truncated range can no longer produce this gap). Don't proceed past it without the operator explicitly confirming the range is correct. **Never compare against `upstream/main..upstream/dev`** (#1002) — under the release-cut squash model that range only ever grows, so it always false-positives; `$LOG_RANGE` (captured in step 3) is the range the changelog was actually built from. **A `$LOG_RANGE` that fails to resolve or fails `git rev-list` must halt the release (`exit 1`), never pass silently** (#1017) — see step 3's guard.
11. **Merge the release PR with an explicit `--subject`/`--body-file`, never a bare `gh pr merge --squash`** (#1004) — this repo's `squash_merge_commit_message=COMMIT_MESSAGES` setting silently drops a trailer that lives only in the PR body. See step 6. **`/approve-merge` — the actual merge path for #1042 — applies this automatically for a release-class PR** (#1136, `AgDR-0132`); the raw command in step 6 is the fallback for a manual merge outside `/approve-merge`.
12. **Verify the `Released-From` trailer landed on the squash commit immediately after merge, and stop before `/release-sync` if it didn't** (#1004) — a missing trailer is invisible until the *next* release cut silently mis-anchors its changelog range. See step 6's verification block and the post-tag checklist in step 7.
13. **Surface, but don't block on, a missing migration script** (#1105) — step 3's migration-script check and the PR body's "Migration script" checkbox are both **advisory**. This is deliberate, not an oversight: whether a release needs an adopter-facing migration is a judgement call (does this release actually change anything an adopter's fork needs to react to?), and a hard-blocking gate would force every doc-only or internal-tooling release to manufacture a no-op script just to pass CI. Making it a blocking gate (a pre-push hook, or a required PR-create check) is a larger design decision — deliberately left as a follow-up, not bundled into #1105's fix. Until then, the discipline is: read the warning, decide honestly, and don't skip past it out of habit — that's exactly the discipline gap that let 21 consecutive releases ship with no migration script at all.
14. **List every line the release removes from main, and ask before continuing** (#1490) — run `bin/release-list-removed-lines.sh` against `upstream/main..$COMPARE_REF` (dev on dry-run, the release branch after step 4). A non-empty listing is a stop-and-ask, not a silent proceed: that is how the v5.7.0 cut dropped contributor rows that still lived on main.
## Related
- `AgDR-0007` — the release-cut branch model this skill enacts
- `AgDR-0076` — the automation design record (this enhancement)
- `AgDR-0094` — release provenance via the `Released-From` trailer + count-mismatch guard (#872)
- `AgDR-0197` — close only from PR-body keywords + list lines a release removes from main (#1490)
- `bin/release-changelog.sh` — the changelog generation helper script, independently tested
- `bin/release-list-removed-lines.sh` — lists lines the release tip deletes from main (#1490)
- `docs/release-process.md` — the prose runbook (this skill is the automation; the doc is the manual fallback)
- `.github/workflows/auto-tag-on-release-pr-merge.yml` — the CI workflow that tags the squash commit after merge
- `golden-paths/pipelines/auto-tag-on-release-pr-merge.yml` — the reusable template for managed projects
- `.claude/skills/update/SKILL.md` — the inverse skill, used by adopters pulling new releases into their fork
- `.claude/skills/release-sync/SKILL.md` — the mandatory follow-up skill that syncs main back to dev after every release, preventing squash-divergence accumulation
---
*Part of [ApexYard](https://github.com/me2resh/apexyard) — multi-project SDLC framework for Claude Code · MIT.*
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |