# Release

> Full ship flow: open a PR, merge it to main, then cut a semver release (version bump, changelog, docs, build verify, tag, push). Use when the user says release, /release, ship, or merge and release. Only commit, tag, or push as part of this requested flow (or when the user explicitly asks).

- Skill: `axidify/release` (Agent Skill)
- Install (CLI): `npx skillmds@latest add axidify/release`
- Raw SKILL.md: https://api.skillmd.com/api/skills/axidify/release/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Axidify (https://skillmd.com/u/axidify)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/axidify/release

---


# Release

**Typical flow:** **open PR → merge to `main` → release checklist → tag + push**

Do **not** tag from a feature branch. Release only from `main` after shipped work
is merged.

Saying **release** means the full sequence below (Phase 0 → A → B), including
commit / tag / push for the release artifacts unless the user says otherwise
(e.g. “prepare the release but don’t push”).

## User shorthand

| User says | Agent does |
| --------- | ---------- |
| **go** | Open PR for current branch (**pr** skill); do **not** merge or release |
| **merge** | Phase A only — merge PR, sync `main` |
| **release** / **/release** / **ship** | Phase 0 → Phase A → Phase B (PR, merge, then release) |
| **merge and release** / **merge + release** | Same as **release** when a PR already exists (Phase A → B); if none, run Phase 0 first |

---

## Phase 0 — Open PR

Run **before** merge and version bump. Follow the **pr** skill.

1. **Branch** — work must be on a feature branch (not `main`). Create one if
   needed; commit release-prep changes (skill edits, version, changelog) on that
   branch when this pack or app is what you are shipping.
2. **Open or reuse PR** — if an open PR already exists for the branch, use it;
   otherwise push (user asked to release ⇒ push is in scope) and `gh pr create`.
3. **Note** the PR number and URL before merging.

### Skip Phase 0 only when

- An open PR for the work already exists → continue at Phase A, or
- HEAD is already on `main`, clean, and the commits to ship are already merged
  → continue at Phase B (tag/version only). Do **not** invent an empty PR.

---

## Phase A — Merge PR to `main`

Run **before** tagging. Prefer merging the PR from Phase 0 (or the existing open PR).

1. **Confirm the PR** — open PR exists, CI/review acceptable, scope matches what
   the user asked to ship. Note the PR number.
2. **Merge via GitHub CLI** when GitHub is the host (preferred):

   ```powershell
   gh pr merge <number> --merge --delete-branch
   ```

   Use `--squash` or `--rebase` only when the team explicitly requests it;
   default is `--merge`.
3. **Sync local `main`:**

   ```powershell
   git checkout main
   git pull origin main
   ```

4. **Verify** — `git log -1 --oneline` shows the merge commit on `main`.

### Local branch only (no PR)

If work never went through a PR (rare — quick solo fix) and the user still said
**release**, open a PR first (Phase 0) unless they explicitly waive it. If they
waive PR:

1. Ensure the branch is clean (no uncommitted changes).
2. `git checkout main && git pull origin main`
3. Merge the branch per project convention (prefer `--ff-only` when possible).
4. Resolve conflicts before continuing. Do not release with unresolved conflicts.

---

## Phase B — Release checklist

All steps run on **`main`** after Phase A (or when Phase 0/A were correctly skipped
because work was already on `main`).

If version / changelog were already landed in the merged PR, Phase B is:
verify → tag → push tag → `gh release create`. Do not double-bump.

### Pre-release gate

- [ ] Scoped from last tag (`git log vLAST..HEAD`, `git diff --stat vLAST..HEAD`)
- [ ] Version bumped in every place the project syncs
- [ ] Changelog entry written (grounded in the diff)
- [ ] Build + tests green
- [ ] Docs updated if public API or behavior changed
- [ ] Tag / push in scope (default **yes** when the user said **release**)

### Checklist

1. **Version policy** — infer from repo (semver tags, conventional commits, or
   project docs such as `.github/commands/release.md`)
2. **Bump** — update version in all synced places (e.g. `package.json`,
   `apps/*/package.json`, lockfiles if required, app manifests) if not already
   in the merged PR
3. **Changelog** — add entry (create `CHANGELOG.md` / `docs/changelog.md` if the
   project uses one and it is missing). Group by user-visible domain; ban filler
   bullets.
4. **README** — when the project ships from `main` with a version badge or
   "current release" line, update in the **same release commit**
5. **Docs** — run **document** `organize` checks if the project has a docs tree
6. **Code docs** — JSDoc / docstrings on new public APIs if that is project norm
7. **Verify** — production build and tests (follow project release command if
   present)
8. **Commit** — if Phase B still has uncommitted release files: conventional
   message, e.g. `release: vX.Y.Z — <short summary>`. Stage **only** release
   files — exclude unrelated untracked WIP. Prefer landing these in Phase 0’s PR
   so `main` only needs a tag after merge.
9. **Tag and push** — `git tag vX.Y.Z`, then `git push origin main` (if needed)
   and `git push origin vX.Y.Z`, then `gh release create` when GitHub is the host

## Hotfix

If patching production: confirm base branch (tag vs `main`), bump **patch** only
unless breaking.

## Conventional commits (if used)

- `feat:` → minor
- `fix:` / `chore:` → patch
- Breaking change → major (confirm with user if unclear)

## Report

- PR opened/merged (number + URL) when Phase 0/A ran
- New version number
- Changelog summary
- Commands run and results
- Anything left manual (store submission, deploy, etc.)

---

## Skill pack repo (`cursor-agent-skills`)

When releasing **this** distribution (not an app under development), use the same
**Phase 0 → A → B** flow:

1. Branch + bump `version` and `syncedAt` in `manifest.json` (semver)
2. Add section to `CHANGELOG.md` for the new version
3. Run `node scripts/validate-skills.mjs`
4. Update README if skills were added or renamed
5. Open PR → merge → sync `main`
6. `git tag -a vX.Y.Z` and `gh release create vX.Y.Z` with notes from the
   **latest** changelog section only
7. Remind users to `git pull` and run `install.sh` or `install.ps1`

## Related skills

- **pr** — open PR (Phase 0; user says `go` for PR-only)
- **document** — changelog and docs accuracy
- **test** — verify before tagging