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

cut-release

Skill246 starsChanged 5 months agoMITView on GitHub

Cut a new Sculptor release candidate from main: run `just cut-release` (which creates the release/sculptor-vX.Y.0 branch at X.Y.0rc1, pushes the tag that triggers the RC build, and opens a PR bumping main to the next .dev0), then land the version-bump PR and babysit the RC build up to its manual approval gate. Handles the colocated jj + git working-copy setup and the CI flake/outage/zombie recovery playbook. Stops AT the approval gate — never approves it for you. Use when asked to "cut a release", "cut an RC", or start a new Sculptor release.

36 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use quota-axi, iterate-pr and 6 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • layer5ioSkill

    quota-axi

    Report local Claude, Codex, Cursor, GitHub Copilot, and Grok quota windows via the quota-axi CLI - remaining percentages, reset times, and provider status read from local auth sources, with no routing, recommendation, or provider mutation. Use before deciding whether it is safe to keep spending a provider's quota, when the user asks about usage, rate limits, or remaining quota, or when comparing local provider headroom.

    Also in 4 projects that use this

  • SentrySkill

    iterate-pr

    Iterate on a PR until actionable CI passes and high/medium review feedback is addressed. Use for PR CI failures, review feedback, or green-check loops; do not wait for human approval, draft status, or merge gates.

    Also in 4 projects that use this

  • layer5ioSkill

    gh-axi

    Operate GitHub through the gh-axi CLI - issues, pull requests, workflow runs, workflows, releases, repositories, labels, Projects (v2), Actions secrets and variables, search, and raw API access. Use whenever a task touches GitHub: listing or filing issues, reviewing or merging PRs, checking CI runs, triggering workflows, cutting releases, managing Projects boards, or managing Actions secrets/variables.

    Also in 4 projects that use this

  • kunchenguidSkill

    chrome-devtools-axi

    Control a Chrome browser session through the chrome-devtools-axi CLI - navigate, snapshot, click, fill forms, run JavaScript, inspect console and network, take screenshots, audit performance. Use whenever a task needs a real browser: opening or testing a web page, clicking through a flow, extracting page content, or debugging a website.

    Also in 4 projects that use this

  • kunchenguidSkill

    lavish

    Turn complex or visual agent responses into rich, reviewable HTML artifacts (HTML files) the user can annotate and send feedback on, using the lavish-axi CLI. Use when about to give a plan, comparison, diagram, table, code diff, report, or anything easier to grasp visually than as prose.

    Also in 4 projects that use this

  • ThisIsSadeghiSkill

    verify-ui

    Verify UI implementation against Stitch design via a token audit (HTML ↔ Code, with X-component default-render checks) and an X-components compliance check.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

4 rules. 0 are common, 1 is distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 36 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Very specific:

    Check its required checks: gh pr checks <bump_pr>.

    line 69
  2. Distinctive:

    Never admin-merge past a failing required check: If it genuinely needs a bypass, refuse and hand it to the user.

    line 75
  3. Very specific:

    After they approve, the RC publishes (S3 + a prerelease GitHub release).

    line 144
  4. Very specific:

    If this cut taught you anything the playbook didn't already cover — a new flake signature, a new recovery step, a sharper command — add it …

    line 150

“Common” is measured: kept by at least 6 in 10 of the 36 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

Cut a Sculptor Release

Turn main's current X.Y.0.dev0 into a published release candidate and reset main for the next cycle. Read docs/development/release_ci_playbook.md first — it holds the shared version model, the approval-gate policy, the flake-vs-outage triage, zombie-run recovery, and the jj working-copy rules that this skill leans on. That playbook is a living document: if you learn something new during a cut, add it there and commit it in the same change.

The end state of a successful cut:

  • release/sculptor-vX.Y.0 exists at X.Y.0rc1, tag sculptor-vX.Y.0rc1 pushed, RC build running and parked at its approval gate for the user.
  • main bumped to X.(Y+1).0.dev0 via a merged version-bump PR.

Step 1 — Preflight

Confirm the ground is clean before touching anything (see the playbook's "Working in this colocated jj + git repo" section):

jj st                                   # working copy should be clean/empty
git fetch origin main --tags
git rev-parse origin/main               # note the tip
cd sculptor && python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])"; cd ..
  • The version must be a .dev0 (e.g. 0.44.0.dev0). If it isn't, someone forgot to bump after the last release — stop and sort that out first.
  • cut-release refuses a detached HEAD (the normal jj state). If jj st is clean/empty, git checkout main. If the working copy has unrelated changes, preserve them first — bookmark + jj new per the playbook — then git checkout main.

Step 2 — Run the cut

just cut-release

This creates and pushes release/sculptor-vX.Y.0 at X.Y.0rc1, pushes tag sculptor-vX.Y.0rc1 (triggering the RC build), and opens the main-bump PR to X.(Y+1).0.dev0 with squash auto-merge enabled. Capture the release version, the RC tag, and the bump PR number from the output.

cut-release leaves git on the transient automated/bump-sculptor-v* branch. Return to a sane state: git checkout main and let jj re-import.

Step 3 — Land the version-bump PR

The bump PR has auto-merge armed; your job is to get it green (never to force it). Follow the playbook's flake-vs-outage triage and zombie-run sections:

  • Check its required checks: gh pr checks <bump_pr>.
  • Infra flake → gh run rerun <run_id> --failed, then let auto-merge land it.
  • Several checks red at setup/infra steps at once → check githubstatus.com; if Actions is down, back off and wait, don't retry into an outage.
  • Checks wedged as zombies after an outage → close/reopen the PR to get fresh runs (gh pr close <n> && sleep 3 && gh pr reopen <n>, then re-arm auto-merge).
  • Never admin-merge past a failing required check. If it genuinely needs a bypass, refuse and hand it to the user.

main merges through a merge queue, so green checks are not the last step: the PR still has to be enqueued, the queue re-runs the required workflows against main, and a failure there ejects the PR silently — it goes back to looking open and green. An enqueue can also be swallowed with no error at all when a wedged merge_group run is still alive. Don't assume; check:

gh api repos/imbue-ai/sculptor/issues/<bump_pr>/timeline --paginate \
  -q '.[] | select(.event | test("queue")) | .event + " @ " + .created_at'

See the playbook's "Merging through the merge queue" for the queue-state query and how to spot and clear a wedged run.

Confirm it landed and origin/main advanced to X.(Y+1).0.dev0:

gh pr view <bump_pr> --json state -q '.state'          # MERGED
git fetch origin main && git show origin/main:sculptor/pyproject.toml | grep -m1 '^version'

Step 4 — Babysit the RC build to the approval gate

Find the run for the RC tag and poll it (playbook: "Polling a build"):

gh run list --workflow=build-desktop.yml --limit 5   # find the sculptor-vX.Y.0rcN run

Poll in a bounded background loop, breaking when the run completes or a pending deployment appears:

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'
  • Build fails on an infra flake / cancellation → retry (gh run rerun <run_id> --failed, or a full gh run rerun <run_id> if a cancellation left partial artifacts).
  • A red linux-arm64 won't sink the RC: it is allow-failure: true, and the publisher skips a non-blocking target whose artifacts are missing. The RC just ships without that architecture — rerun the job if QA needs an arm64 build.
  • Build is wedged as a zombie after an outage → don't fight it: cut a fresh RC with just fixup-release (bumps rcN → rc(N+1)) from the release branch. (To run it you must git checkout release/sculptor-vX.Y.0 on a clean tree — preserve any stray working-copy work first, per the playbook.)
  • Build reaches the approval gate (pending_deployments ≥ 1, job release desktop (S3 publish + gh release) = waiting) → stop here.

Step 5 — Hand off at the gate

First check what will ship — 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 RC build is green and parked at the release environment approval gate, and do not approve it. Per the playbook's approval policy: surface it, show the user how to approve (UI Review deployments, or the gh api ... pending_deployments ... state=approved command with the env id from pending_deployments), and if they ask you to approve, gently push back once, then comply if they insist.

After they approve, the RC publishes (S3 + a prerelease GitHub release). Next in the release process: QA the RC, then promote-release (see the promote-release skill).

Before you finish

If this cut taught you anything the playbook didn't already cover — a new flake signature, a new recovery step, a sharper command — add it to docs/development/release_ci_playbook.md (Field notes) and commit it. You have write access; the next person cutting a release inherits what you write down.

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.