ci(#156/T4): add release-on-version-change workflow

[devallibus]

Summary

Adds a GitHub Actions workflow that, on every push to master, detects whether .claude-plugin/plugin.json version changed vs the previous commit and — if so — creates the matching vX.Y.Z Git tag and a GitHub Release with auto-generated notes covering PRs merged since the previous tag.

Closes #156 (when merged alongside T2 (#158) and T3 (#159))

Journey Timeline

Decisions

Decision	Choice	Why
Tool	Pure shell + gh release create --generate-notes	Considered release-please and softprops/action-gh-release. Shell is one short readable file with no third-party dependency, and GitHub's auto-generated notes are good enough for shiplog's surface. The workflow header records this so a future maintainer outgrowing it knows what to swap in.
Trigger	push on master filtered by paths: ['.claude-plugin/plugin.json']	Avoids running the job on every push. Only the file that drives version actually triggers the workflow.
Tag collision	Pre-flight check via gh api repos/.../git/refs/tags/<tag>	The v0.5.0 tag already exists (cut manually as part of #156 / T1). Future bumps must not re-tag silently — the workflow fails loudly if the tag exists, with a hint that this is a re-release scenario.
Permissions	contents: write only	Minimum required to create tags and releases. No PR-write or issue-write surface.
Release-notes shape	--generate-notes (GitHub-native)	Generates "What's Changed" with PR links since the last tag. We can layer a custom template later via .github/release.yml if we want to group changes — out of scope for this PR.

What we discovered

• --generate-notes requires a previous tag for the from-range. The first auto-release after this lands will compute notes from v0.5.0 (cut manually for [shiplog/plan] Plugin distribution: bump plugin.json version on content changes and start cutting releases #156/T1) onward, which is exactly what we want — no awkward "from repo creation" first run.
• paths: filter on push triggers only fires when the listed paths are in the diff of that push. Since plugin.json bumps are gated by the T3 CI check, the release workflow only fires on intentional version-bump merges. No spurious tags from unrelated docs PRs.

Changes

• Create .github/workflows/release.yml: on push to master with .claude-plugin/plugin.json in the diff, detects version change, verifies tag does not already exist, then runs gh release create vX.Y.Z --generate-notes.

Testing / Verification

The workflow can only really be verified by merging it and then merging another version-bump PR. Verification plan:

1. After this PR merges, the next chore(...): bump plugin.json to 0.5.1 PR (or similar) — once T3 forces a bump — should result in a v0.5.1 tag and release appearing automatically within about 30 seconds of the merge.
2. The release body should list the merged PR(s) under "What's Changed" with author and link, computed against v0.5.0 as the from-range.
3. If for any reason v0.5.1 already exists (e.g. someone tagged manually first), the workflow should fail loudly with the "tag already exists on remote" annotation rather than overwriting.

If T3 has not landed yet at the time of the first version-bump PR after this, the version bump can still be made manually — T4 only depends on the version field changing, not on T3's CI.

Knowledge for Future Reference

• Combined with chore(#156/T1): bump plugin.json version to 0.5.0 (backfill) #157 (T1 — version bump + first release), docs(#156/T2): add CONTRIBUTING.md with versioning policy #158 (T2 — CONTRIBUTING policy), and ci(#156/T3): add version-bump-check workflow #159 (T3 — CI bump-check), this PR closes the loop on [shiplog/plan] Plugin distribution: bump plugin.json version on content changes and start cutting releases #156: drift cannot recur because (a) bumping is required by CI, (b) bumping is documented in CONTRIBUTING, and (c) every bump auto-publishes a release that downstream installs can pin to.
• If we ever declare 1.0.0, no workflow change is needed — the version field is opaque to this workflow; it only cares that the string changed and that the tag does not yet exist.
• If a custom release-notes template becomes desirable (e.g. group commits by feat|fix|chore), drop a .github/release.yml per GitHub's auto-generated release notes config. No workflow change needed.

---

Authored-by: claude/opus-4.7 (claude-code)
Captain's log - PR timeline by shiplog

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 46711761a8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Trigger release workflow on the actual default branch

This workflow only runs for pushes to master, so it will never fire in repositories that use main (including this repo, where the active primary branch is main), which means version bumps in .claude-plugin/plugin.json will not create tags or GitHub Releases at all. Update the branch filter to the branch you actually release from (or make it branch-agnostic and guard in-script) so the automation runs on real merges.

Useful? React with 👍 / 👎.

[devallibus]

[shiplog/review] Repo owner override — proceed to merge

The repo owner (devallibus) explicitly authorized merging this #156 follow-up PR without a separate cross-model review. Per skills/shiplog/references/closure-and-review.md §3, human review counts as independent review, so this satisfies the gate. Recording the override here for the audit trail.

Reviewed-by: claude/opus-4.7 (claude-code)
Disposition: self-review (audit trail) — repo owner override authorizing merge
Scope: full diff
Note: Independent human reviewer (devallibus, repo owner) explicitly
authorized merge of this #156 follow-up. See sibling PRs #157, #158,
#159, #160 for the full T1–T4 set.

Authored-by: claude/opus-4.7 (claude-code)