agentleFS
imbue-aiimbue-ai/sculptor/.claude/skills/promote-release/SKILL.md

promote-release

Skill246 starsChanged 5 months agoMITView on GitHub

Promote a QA'd Sculptor release candidate to a full production release: verify the RC build is green and has been QA'd, then from the release branch run `just promote-release` (which strips the rcN suffix, commits X.Y.0, and pushes the sculptor-vX.Y.0 tag that triggers the production build) and babysit that build up to its manual approval gate. Handles the colocated jj + git working copy and the CI flake/outage/zombie recovery playbook. Stops AT the approval gate — never approves it for you. Use when asked to "promote a release", "ship the release", or turn an RC into the real release.

3 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

6 rules. 0 are common, 4 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Don't assume the newest release branch is the one to ship.

    line 30
  2. Very specific:

    If jj st shows unrelated working-copy work, preserve it first (bookmark + jj new, per the playbook) before the checkout — never discard it.

    line 62
  3. Distinctive:

    If behind, pull/rebase before promoting.

    line 72
  4. Very specific:

    Check what will actually ship before handing it over — allow-failure jobs report success to needs, so the gate can open with a red …

    line 120
  5. Distinctive:

    If arm64 is red, rerun it first when you want that architecture in the release — and either way, tell the user which architectures this …

    line 133
  6. Distinctive:

    Follow-ups this skill does not do:

    line 150

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Promote a Sculptor Release

Turn a release candidate on release/sculptor-vX.Y.0 into the promoted X.Y.0 release. Read docs/development/release_ci_playbook.md first — the version model, approval-gate policy, flake-vs-outage triage, zombie recovery, and jj working-copy rules all live there and this skill depends on them. That playbook is a living document: anything new you learn promoting a release goes back into it in the same change.

Gate before you start: promotion publishes the real thing. Confirm the RC build for the current rcN went green and was actually QA'd before running anything here. If it wasn't QA'd, stop and get that done first.

Step 0 — Work out what to promote

Don't assume the newest release branch is the one to ship. Branches get cut and abandoned: 0.41 and 0.43 were both cut and never promoted, so production went 0.42.0 → 0.44.0 directly.

git fetch origin --tags --prune
git branch -r --list 'origin/release/*' | sort -V | tail -5    # candidate branches
git tag -l 'sculptor-v*' --sort=-v:refname | head              # rcN tags
gh release list --limit 10                                     # what actually shipped

Read those together:

  • The branch to promote is the one whose rcN prerelease appears in gh release list. That publication is proof the RC build went green and a human approved its gate — stronger evidence than "the build was green".
  • The newest non-prerelease (Latest) entry is what production runs today.
  • A release branch with no published prerelease was abandoned; leave it alone.

Step 1 — Get onto the release branch, clean

promote-release runs git checkout-based checks and needs a real git branch (release/sculptor-vX.Y.0) with a clean tree — not the usual jj detached HEAD.

jj st                                   # working copy clean/empty?
git fetch origin release/sculptor-vX.Y.0
git checkout release/sculptor-vX.Y.0
cd sculptor && python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])"; cd ..   # expect X.Y.0rcN

If jj st shows unrelated working-copy work, preserve it first (bookmark + jj new, per the playbook) before the checkout — never discard it.

Sanity checks the recipe also enforces, worth confirming yourself:

  • You're on release/sculptor-vX.Y.0 and the version is an rcN pre-release.
  • The branch is not behind its upstream:
    git fetch --prune && git status --porcelain=2 --branch | grep '^# branch.ab'
    If behind, pull/rebase before promoting.

Step 2 — Promote

just promote-release

This strips the pre-release suffix (X.Y.0rcN → X.Y.0), commits the version on the release branch, and pushes tag sculptor-vX.Y.0 — which triggers the production release build. Capture the release version and tag from the output.

Two outputs look wrong but are normal (playbook field notes, 2026-08-14):

  • Releasing Sculptor <old rcN version> from git sha ... — a stale pyproject_version() echo. The version actually released is the stripped one.
  • Bypassed rule violations for refs/tags/... creations being restricted on the tag push. Expected — but it means you need tag-creation bypass on the repo ruleset; without it the promotion fails right here.

Step 3 — Babysit the production build to the approval gate

Same polling and recovery as an RC build (playbook: "Polling a build", "Flake vs. outage", "Zombie runs"):

gh run list --workflow=build-desktop.yml --limit 5    # find the sculptor-vX.Y.0 run
gh run view <run_id> --json status,conclusion -q '.status + " / " + (.conclusion // "running")'
gh api repos/imbue-ai/sculptor/actions/runs/<run_id>/pending_deployments -q 'length'
  • Infra flake / cancellation → retry (gh run rerun <run_id> --failed, or a full rerun after a cancellation).
  • A red linux-arm64 is survivable: it is allow-failure: true, and the publisher skips a non-blocking target whose artifacts are missing. The release ships without that architecture — rerun the job if you want arm64 included.
  • Outage → check githubstatus.com, back off, don't retry into it.
  • Never admin-merge / force a bad required check. Refuse and hand back.
  • Gate reached (pending_deployments ≥ 1, run status = waiting, release desktop (S3 publish + gh release) = waiting) → verify, then stop.

Note: if the production build is unrecoverable but the RC was fine, promotion isn't the place to cut a new RC — that's fixup-release on the RC side. A promoted release that later needs patching uses just hotfix-release (see the playbook's version model).

Step 4 — Verify at the gate, then hand off

Check what will actually ship before handing it over — allow-failure jobs report success to needs, so the gate can open with a red linux-arm64:

gh run view <run_id> --json jobs -q '.jobs[] | .name + " -> " + (.conclusion // "—")'

Then report that the build is parked at the release environment approval gate, and do not approve it. Per the playbook: surface it, give the user the run URL plus the env id, show them how to approve themselves (UI Review deployments, or the gh api ... pending_deployments ... state=approved command), and if asked to approve, push back gently once, then comply if they insist.

If arm64 is red, rerun it first when you want that architecture in the release — and either way, tell the user which architectures this release will contain.

Step 5 — After they approve

Confirm the publish actually landed; don't trust the job status alone:

gh run view <run_id> --json conclusion -q .conclusion             # success
gh release view sculptor-vX.Y.0 --json isPrerelease,isDraft       # false / false
curl -s https://imbue-sculptor-releases.s3.amazonaws.com/slim/AppImage/x64/latest-linux.yml | grep '^version:'

That last one matters most — the auto-update manifests are the channel that actually reaches users. (A release with 0 assets is normal: artifacts live in S3 and the release body just links them.)

Follow-ups this skill does not do:

  • Release notes (write-release-notes). The range starts at the prior promoted tag, which may be several minors back — 0.44.0's notes had to cover 0.42.0 → 0.44.0 because 0.43 never shipped. Scoping to the previous release branch silently drops half of what users are receiving. The release body is pipeline boilerplate (title + ## Assets); splice notes in above ## Assets and preserve that block verbatim, via gh release edit <tag> --notes-file <file>. Do not sign a published product changelog (Sent by Claude) — CLAUDE.md's transparency rule targets PR, issue, and chat messages, not user-facing release copy.
  • update-help-docs — optional / deprecated. The help docs (docs/help/) are no longer actively maintained, so refreshing them is no longer part of the promotion follow-up. Skip it by default; only run it (from the release branch) if you specifically want to update a page.
  • Linear hygiene for the tickets that shipped.
  • Slack needs nothing: the pipeline posts to #sculptor-release automatically on a successful publish.

Before you finish

Learned something the playbook doesn't cover? Add it to docs/development/release_ci_playbook.md (Field notes) and commit it in the same change. You have write access — write it down for the next promoter.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.