PwrSnap: Skill for Codex

Release

Use this skill for PwrSnap desktop releases published by .github/workflows/release.yml.

Read First

Read these files before changing release metadata:

1. ../../../docs/desktop-release-runbook.md
2. ../../../.github/workflows/release.yml
3. ../../../scripts/check-desktop-release-metadata.mjs
4. ../../../docs/package-manager-release-runbook.md
5. ../../../docs/windows/winget/README.md

Guardrails

• Release from main while it carries the current major/minor train. This includes alpha and beta builds, accepted stable releases, and small follow-up patch releases before the next major/minor work begins.

• Create a long-lived maintenance branch named releases/<major>.<minor> only when the user decides to begin the next major/minor train on main. The branch retains the current train for later patches while main moves forward. Do not create a release branch merely to promote an accepted beta to stable. Do not include the patch component in branch names: use releases/1.0, not releases/1.0.x or releases/1.0.1.

• Start from a clean working tree. If tracked files are dirty, stop and ask before changing release metadata.

• Fetch tags before planning:

  git fetch origin --tags
  

• Treat apps/desktop/package.json as the desktop release version source. The root package.json version is not the desktop app release version.

• Always use a leading-v tag such as v0.0.1-alpha.5.

• The tag version, apps/desktop/package.json version, and CHANGELOG.md release heading must match.

• Before moving main to a new major/minor train, confirm the user has chosen to cut the prior train's maintenance branch. Create it from the selected current main commit, which may intentionally include post-release fixes and enhancements. Do not assume an already-published stable tag is the correct branch point.

• After that branch cut, patch releases for the prior train must land on its maintenance branch. Until the cut, release patches for the active train from main.

• Do not create or push the tag until the version and changelog are committed and present on the intended release branch.

• Before pushing a release tag, verify the apple-signing GitHub Environment exists on pwrdrvr/PwrSnap, requires reviewer approval, is scoped to v* release tags, and has the Apple signing/notarization secrets required by the workflow. Apple signing/notarization secrets must NOT exist as repository-level secrets.

• Do not use GitHub generated release notes as the final notes.

• Do not create the GitHub Release by hand before the build succeeds. Let the CI publish job create it from the signed/notarized build and matching changelog notes.

• Never promote a GitHub Release to Latest as part of this skill. Every release task ends with the release still marked Pre-release; the operator promotes it manually in GitHub only after their own smoke checks.

• Every release, including alpha/beta/RC, must inspect the remote Winget manifests and Homebrew cask before editing metadata and again at handoff. Follow the package-manager runbook; local winget show / brew info alone do not establish the published version.

• Keep both package channels as current as practical with the newest eligible stable release. A newly uploaded GitHub Pre-release is not eligible, even with bare stable SemVer. Catch up an older eligible release when authorized; otherwise prepare the payload and name the owner/blocker. Never publish an alpha/beta/RC to these stable packages or downgrade a channel automatically.

• A bump workflow, open PR, or merged manifest is not proof of client availability. Record submission links, accepted source versions, refreshed client versions, validation results, and pending review/index/cache delays separately. Do not declare the channels current while any of these is unknown.

• Public cross-repository audits/searches use the organization-provided DISTRIBUTION_READ_TOKEN only on read steps, with GH_TOKEN: ${{ secrets.DISTRIBUTION_READ_TOKEN || github.token }} so fork PRs retain the workflow-token fallback. It is a public-read-only fine-grained PAT, not a push/submission/release credential. Leave unrelated operations on their existing tokens, and never print/copy the secret or broaden its permissions. Follow the runbook's expiration/rotation requirements. HTTP 429 and incomplete search results remain blockers after bounded retries, never package absence.

• Do not force-push the default branch or rewrite an existing release tag without explicit user approval.

• Keep the MIT license intact: do not swap LICENSE for a different SPDX or drift any workspace package.json away from "license": "MIT".