Add release skill

Author: burmudar

.agents/skills/release/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: release
+description: Guides Sourcegraph CLI patch, minor, and major releases. Use when preparing release branches, selecting patch commits, running Trivy checks, creating release tags, or managing local/pushed release artifacts.
+---
+
+# Release
+
+Use this skill when the user asks to prepare, cut, tag, or manage a release.
+
+## Start by determining release intent
+
+Gather only the information that is actually missing. Do not ask questions whose answers can be derived safely from tags, release branches, or the user's wording.
+
+Proceed without clarification when the user has already provided enough intent, for example:
+
+- "create a minor release `7.3.0`"
+- "cut the next major release from main"
+- "create a patch release" plus exact versions such as `7.2.2` and `7.1.3`
+- "next patch for current and one minor back"
+- "inspect main and decide what is patch-worthy"
+- "create everything locally first"
+
+Ask a narrow question only when the missing answer would change the release artifacts or risk pushing/tagging the wrong thing:
+
+1. Release type, if not clear from the request or version number.
+2. Exact version, if it cannot be inferred from existing tags.
+3. Source branch, if it is not the default branch.
+4. Commit selection, only if the user has not provided commits/PRs and has not asked you to inspect history and decide.
+5. Whether to push, only after local branches/tags are ready. Default to local-only unless the user explicitly asks to push.
+
+For version inference:
+
+- Inspect existing tags with `git tag --list --sort=-v:refname`.
+- Inspect release branches with `git branch -a --list '*release*'`.
+- For patch releases, increment the latest patch tag on the target release train. The current patch train is the highest release branch/tag line, for example `release/7.2.x` after `7.2.1` produces `7.2.2`.
+- For minor releases, increment the minor component from the latest released minor and set patch to `.0`, for example latest `7.2.1` produces `7.3.0`, unless the user specifies a different train.
+- For major releases, increment the major component and reset minor/patch to `.0.0`, for example latest `7.2.1` produces `8.0.0`, unless the user specifies a different train.
+- "One minor back" means the previous minor release branch, for example `release/7.1.x`; increment the latest patch tag on that line.
+- Confirm inferred versions in progress updates, but keep working unless the user asked for confirmation before mutation.
+
+## Pre-flight checks
+
+Before starting the release work:
+
+1. Make sure the working tree is clean with `git status`.
+2. Fetch current refs and tags with `git fetch --all --tags --prune`.
+3. Run Trivy and ensure vulnerabilities are addressed before continuing.
+   - For this repository, use `mise x trivy -- trivy fs --exit-code 1 --severity HIGH,CRITICAL`.
+   - Use a different documented Trivy command only if the repository adds one.
+   - Do not proceed to branch creation, cherry-picking, or tagging while unresolved Trivy vulnerabilities remain.
+   - If running from a temporary worktree, `mise` may require trusting that worktree's `mise.toml`. Run `mise trust -y <worktree>/mise.toml` when needed, then remove or untrust temporary state during cleanup.
+
+This repository is commonly used with `jj`, so `git status` may report `HEAD (no branch)`. Treat that as normal if the worktree is otherwise clean.
+
+## Release workflow
+
+Use the same workflow for patch, minor, and major releases. The release type mainly changes which commits from the source branch are included.
+
+1. Confirm or infer the final version number and target release branch.
+2. Identify the source branch or commit, usually the current default branch unless the user says otherwise.
+3. Run pre-flight validation, including Trivy, on the source branch before creating or tagging release artifacts.
+4. Prepare the target release branch:
+   - For a new release line, create the release branch from the source branch.
+   - For an existing release line, use the existing release branch.
+   - Never create a new branch for an existing patch train unless the target branch is missing and the user explicitly confirms creating it.
+   - Prefer temporary git worktrees when working on multiple release trains, or when the user's current checkout is managed by `jj`, so each release branch can be mutated independently.
+5. Select commits from the source branch according to the release type.
+6. Port selected commits with `git cherry-pick -x <sha>` when the target branch does not already contain them.
+7. Resolve conflicts carefully and keep the release branch limited to selected commits and release-process changes.
+8. Run required validation, including Trivy, on every release branch after porting changes.
+9. Tag the release on the release branch, not on the default branch.
+10. Push the release branch and tag only when requested or required by the release process.
+
+Use release branch names that match the current repository convention. Recent branches use the release train format:
+
+- `release/7.1.x` for a `7.1.0` or `7.1.3` release
+- `release/7.2.x` for a `7.2.0` or `7.2.2` release
+- `release/8.0.x` for an `8.0.0` release
+
+Older repositories may use release branch names without `.x`; prefer the convention shown by recent release branches.
+
+## Commit selection by release type
+
+For patch releases, include only patch-worthy commits. These are typically:
+
+- Critical bug fixes
+- Security fixes
+- Data-loss or correctness fixes
+- Low-risk operational fixes required for the release line
+- Toolchain, runtime, base-image, or dependency updates that are part of fixing a vulnerability, even if the commit message is phrased as `chore`, `update Go`, `bump`, or similar
+
+For patch releases, avoid including:
+
+- New features
+- Broad refactors
+- Dependency bumps unrelated to the patch fix, unless needed for a vulnerability or confirmed by the user
+- Risky behavior changes
+- Command migrations, doc generation, dev-only tooling, or cleanup-only changes unless they directly fix the patch issue
+
+For minor releases, include the normal release-train contents from the source branch unless the user asks to exclude something. Minor releases can include compatible features, fixes, dependency updates, migrations, and cleanup that are intended for the new minor train.
+
+For major releases, include the normal release-train contents from the source branch and any intentionally breaking changes approved for the major train.
+
+When the user asks you to inspect history and decide what to port, compare the target release branch to the source branch and inspect likely candidates:
+
+- `git log --oneline --reverse origin/release/7.2.x..origin/main`
+- `git show --stat --patch <candidate>`
+- `git cherry -v origin/release/7.2.x <candidate>` to notice already-applied equivalent changes
+
+Do not rely on commit messages alone. For security or vulnerability-driven releases, inspect the remediation sequence so prerequisite fixes are not missed:
+
+- Review nearby commits, parent/child relationships, and file-level dependencies around the obvious fix.
+- Treat toolchain, runtime, base-image, dependency-manifest, lockfile, scanner-configuration, and build/release-definition changes as possible prerequisite remediation, even if their commit messages are generic.
+- If a later vulnerability fix was made on top of an adjacent prerequisite change, include the prerequisite unless it is clearly unrelated or too risky and the user confirms excluding it.
+- If a scanner or release validation is the driver, check whether all changes needed to make that validation pass on the source branch are represented on the release branch, not just commits whose messages mention the scanner, vulnerability, or CVE.
+- Before finalizing candidate selection, summarize any excluded adjacent prerequisite commits and why they are excluded.
+
+## Tagging rules
+
+- Always tag on the release branch.
+- Confirm the tag name before creating it.
+- Prefer the repository's existing tag format. Inspect existing tags if unsure.
+- Verify the checked-out branch before tagging with `git branch --show-current`.
+- After tagging, show the created tag and the commit it points to.
+- This repository uses signed annotated release tags with messages like `Release v7.2.2`: `git tag -s 7.2.2 -m "Release v7.2.2"`.
+- Create tags locally first unless the user explicitly asks to push as part of the release. Push only after explicit user approval or when the release process requires it and the user has confirmed.
+
+## Safety rules
+
+- Never force-push release branches or tags unless the user explicitly authorizes it.
+- Never tag with a dirty working tree.
+- Never continue after failed tests, failed Trivy checks, or unresolved cherry-pick conflicts without user confirmation.
+- Summarize every mutation: branch creation, cherry-picks, version changes, commits, pushes, and tags.
+
+## Local-only release summary
+
+When local release artifacts are ready, report:
+
+- Versions created and target branches.
+- Cherry-picked source commits and resulting branch-tip commits.
+- Tag names, tag targets, and whether tags are annotated/signed.
+- Validation commands and outcomes.
+- Ahead counts versus origin, for example `git rev-list --left-right --count origin/release/7.2.x...release/7.2.x`.
+- That no pushes were performed, unless pushes were explicitly requested.