blurt: Skill for Claude Code

Releasing Blurt

Everything happens in GitHub Actions, not on this machine — so this works from a web or chat session with no terminal, and without permission to dispatch a workflow. Confirm the target version with the user before starting — publishing is hard to undo.

Preconditions (verify first)

• main is up to date and green; releases ship from main.
• The release-build environment has the signing + notary secrets and SPARKLE_ED_PRIVATE_KEY, and release-publish has required reviewers. See RELEASE.md — that is the source of truth for custody. Without them the release workflow fails on its secrets-presence step.
• Check the highest existing vX.Y.Z tag, not just the version on main: an orphan tag from an abandoned release means the next patch number is already taken, and release-bump.sh refuses to reuse one.

Steps

1. Start release-bump. You almost certainly can't dispatch a workflow (that needs actions: write), so push a marker branch instead — it needs only the push you already do:

   git push origin main:refs/heads/release/v0.1.37
   

   The branch name names the version, and it must carry nothing of its own: the workflow refuses a marker that isn't an ancestor of main. It then runs scripts/release-bump.sh on macos-26 (marketing version + build number in App/Blurt/project.yml, regenerate the project, commit) and force-pushes the bump onto that same branch. Dispatching still works if you do have the permission, and only that path accepts an empty version (next patch).

2. Get the release notes written. The bump also commits release-notes/X.Y.Z.md: the commits since the last release in an HTML comment, and a TODO where the notes go. They are what Sparkle's update window shows every user, check fails while the TODO is there, and the release build refuses to run without them — there is no automatic fallback. Read RELEASE.md → Release notes → Writing them first and follow it: translate each commit into what a user notices, drop what they wouldn't (refactors, CI, docs, reverted work), order by how noticeable it is, and match the length and voice of the model notes there. Fewer bullets is better than padding. Before drafting, skim the merged PRs behind the subjects (gh pr view <n>) when a subject doesn't say what the user sees. Run scripts/check-release-notes.sh, then show the draft to the user — with the commits you left out and why — and get their go-ahead before committing it to the release branch. Their judgment is the point of the rule.

3. Open the PR for that branch and hand it to the user to merge. The workflow does not open it, on purpose: a PR created by GITHUB_TOKEN never triggers check and so can never merge. Opening it from here works — an agent's own credentials are not GITHUB_TOKEN.

4. Merging it starts release — no dispatch. release.yml triggers on a push to main touching project.yml; its resolve job confirms the version changed and isn't already tagged, then the build job does the whole Apple path (xcodebuild Release → sign nested code → notarize → staple → DMG → verify → EdDSA-sign the DMG → write appcast.xml with the notes) and uploads the artifacts. Dispatch release by hand only to re-run a failed build, to republish, or for a non-main dry run.

5. Hand the ship gate to the user — the publish job parks on the release-publish environment. Tell them to download the DMG from the run's artifacts, install it, and approve once it works. Nothing is rebuilt after approval, so what they test is what ships. release-publish.sh then tags, pushes, and publishes — and flipping the release to latest is what moves the Sparkle feed, so installed copies see it within a day.