agentleFS
takealook97takealook97/vat/.agents/skills/cut-a-release/SKILL.md

cut-a-release

Skill1 starsChanged 3 months agoMITView on GitHub

Take vat from a green main to a signed, published release.

  • Installs packages
  • Commits and pushes

3 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions3 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 3

    1. henit-chobisa/deck★ 33same name
    2. GCarin1/Doctrina★ 1same name
    3. royalpinto007/ship-skills★ 1same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository7 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

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

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run git fetch --tags. Every version this binary reports comes from git describe, so a checkout missing the last tag builds a binary that …

    line 21
  2. Very specific:

    Run make check. The tag is the trigger and there is no gate after it: a tag pushed on a red tree publishes a red release.

    line 28
  3. Very specific:

    Verify the release page carries, for every target, an archive and a .cdx.json, plus one checksums.txt and a provenance attestation.

    line 53
  4. Distinctive:

    Do not repair either by moving the orphaned tags.

    line 80
  5. Distinctive:

    Not for a typo.

    line 119
  6. Very specific:

    Stop before pushing if make check is red, if the working tree is dirty, or if the version cannot be justified from the diff.

    line 123

“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

Cut a release

When to use this

A version is going out. Not for a local multi-platform build — that is make release-snapshot, which publishes nothing.

Inputs

  • main, clean, with make check passing
  • CHANGELOG.md
  • .github/workflows/release.yml, which is what actually publishes

Before anything

Run git fetch --tags. Every version this binary reports comes from git describe, so a checkout missing the last tag builds a binary that names an older release: on the v0.5.1 commit with only v0.4.2 fetched, make check built vat v0.4.2-7-gaae7c2b. That was cosmetic until requires.vat began comparing versions, and it is not any more — a workspace pinned >=0.5.0 refuses that binary, built from the exact commit that satisfies it.

Run make check. The tag is the trigger and there is no gate after it: a tag pushed on a red tree publishes a red release.

Decide the version from what changed, under semantic versioning. vat is a command-line contract, so a changed exit code, a removed flag, or a changed on-disk format is a breaking change even when no Go symbol moved.

Steps

  1. Move the entries under ## [Unreleased] in CHANGELOG.md beneath a new ## [X.Y.Z] - YYYY-MM-DD heading, and leave ## [Unreleased] in place and empty above it. The heading carries no v; the tag does.
  2. Commit: chore: release vX.Y.Z.
  3. Tag: git tag vX.Y.Z. The workflow triggers on v* and on nothing else.
  4. git push origin main and then git push origin vX.Y.Z.

    Push the tag by name. --follow-tags pushes only annotated tags, and every tag this repository has is lightweight, so it skipped the tag in silence: main moved, the workflow never triggered, and the push reported success. Confirm with git ls-remote --tags origin | grep vX.Y.Z before believing the release happened.

  5. The workflow then builds the five targets in its TARGETS list, writes a CycloneDX SBOM per target, generates the shell completions, packages and checksums the archives, attests them and checksums.txt, and publishes with generated release notes.
  6. Verify the release page carries, for every target, an archive and a .cdx.json, plus one checksums.txt and a provenance attestation.

When main's history has been rewritten

A force-push that rewrites commits leaves every tag on the old history, still valid and still pointing at commits nothing reaches. On 2026-09-04 a metadata rewrite of everything after v0.2.1 orphaned seven tags, v0.3.0 through v0.5.2. The trees were identical, so no release was owed — but two things change and neither announces itself.

git describe walks the surviving history, not the tag list. On the rewritten main it answers v0.2.1-31-g6febbf2, so make check builds a binary that names v0.2.1, and a workspace pinned requires.vat: >=0.5.0 refuses it. That is the failure the fetch rule above describes, except no fetch repairs it: the tag is present and simply is not an ancestor. Releases are unaffected — release.yml stamps github.ref_name, the tag being pushed — so this is a local-build trap, and the tell is a version number far below the last release.

The forge computes release notes from a commit range. The next tag cut from the rewritten main has v0.2.1 as its most recent reachable predecessor, so the generated notes and the vX.Y.Z-1...vX.Y.Z comparison span every commit since then rather than the release. Write the notes from CHANGELOG.md instead of accepting the generated ones, and say in the release body that history was rewritten, so a reader comparing two tags is not left to conclude the release contained work it did not.

Do not repair either by moving the orphaned tags. They are published: the rule below holds, and the old commits stay alive precisely because those tags point at them.

When a published release turns out to be defective

A published tag is frozen. Never move one, and never delete one. proxy.golang.org caches a version's content the first time anyone fetches it and offers no deletion, so go install module@vX.Y.Z will serve that code forever. Re-pointing the tag leaves two different trees answering to one version while the proxy keeps serving the first, and deleting the tag on the forge does not reach the proxy at all.

The fix is two things, not one:

  1. Ship the correction as the next version. Never as the same one.
  2. Retract the defective version in go.mod, with a comment saying what was wrong with it. Retraction is what keeps the toolchain from offering it: go get refuses a retracted version, go list -m -versions hides it, and @latest skips past it.
retract (
    // What was wrong with it, in enough detail to judge the risk.
    v0.1.5
    // A contiguous range, when several versions share one defect.
    [v0.1.2, v0.1.4]
)

A retraction only takes effect once it is published in a version above the ones it names, so the retraction and the fix ship together in the new tag.

Record it in CHANGELOG.md too. The retract block is read by the toolchain and by nobody else; a person deciding whether they are running something unsafe reads the release notes.

Retract for a defect that matters to somebody running it — a disclosed credential, a write outside the directory vat governs, a wrong version stamp. Not for a typo.

When it must stop

Stop before pushing if make check is red, if the working tree is dirty, or if the version cannot be justified from the diff. Stop after pushing, too, until git ls-remote --tags origin shows the tag: a push that moved main and left the tag behind reports success and publishes nothing. None of those is recoverable afterwards, because the push is the publication.

Deciding that a defect is severe enough to retract is a judgement about other people's installations. Say what the defect is and let a human make it.

Nothing in this repository updates the Homebrew tap. If a release needs to reach brew install, that happens outside this repository and is not this skill's to assume.

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.