How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/lilmgenius/paperthin --skill re0-releaseBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
Ship a release of the repository this runs in, from gathering what it carries to the published tag.
Goal
A release lands complete and trustworthy: its procedure met, every manifest bumped by kind, house-style notes as the signed tag's message, and an artifact its workflow publishes. re0-release calls sip when installed, writes messages to the standard step 5 states, and never calls another user-invoked skill. Each step that commits or writes in public waits for its own approval (Rules).
It is user-invoked: shipping is a deliberate human action, so only the human runs it.
Workflow
- Gather the release.
- Read the owner, repository and default branch with
gh repo view --json nameWithOwner,defaultBranchRef, else the default branch withgit symbolic-ref --short refs/remotes/origin/HEAD(itsorigin/dropped), else ask; then that branch's rulesets (gh api repos/<owner>/<repo>/rules/branches/<default>) and classic protection (gh api repos/<owner>/<repo>/branches/<default>/protection, a 404 meaning none). A rule read there that requires a pull request or reviews sets the pull-request path. Rules that cannot be read (a 403, an origin that is not GitHub or is afile://path, nogh) set the direct path. - The release branch carries the unreleased changes, and is checked out. On the pull-request path it is the head of the current branch's open pull request (
gh pr view --json number,headRefName,baseRefName), else of the one open pull request against the default branch (gh pr list --base <default> --state open --json number,headRefName,title), which step 8 names; with several, ask which carries the release before drafting anything. With none, or on the direct path, it is the default branch, up to date with its remote. - The release is every change on the release branch since the last release tag (
git describe --tags --abbrev=0 --match 'v*', thengit log <tag>..HEADandgit diff <tag>), from the first commit where there is no tag, plus the pending diff. The bump, the notes, the credits and the release commit's message are drafted from that range. - The procedure is the repository's own: the Shipping and Releasing sections of its root
AGENTS.md, else itsCONTRIBUTING.md, else none, said and passed. Check each requirement it states on the release's state (a roster, a manifest, a translation); an unmet one is a gap, reported and repaired only once the human authorizes the repair, never set aside. An action it describes is done by the step below that does it, in the repository's wording where the two differ, and step 8 shows the difference. A file named below that the repository lacks is skipped. - A file in the pending diff that belongs to another change or author is excluded once its recorded owner (its commits, a TODO entry, a coordination note) has been read; step 8 shows the exclusion.
- Classify the bump once every open question bearing on what ships is answered (a contract question, a behavior obligation the release would lose); until then, report it and name no version. A lost obligation blocks the release until it is restored or the human rules on it. Classify by kind, never size: a fix of wrong behavior, or a docs-only change, is patch; a new capability a user reaches for, a correct but narrower behavior widened included, is minor; a removal with no replacement is major. State the case; only a minor or major release carries
### New. - Taste-test. Call the Skill tool with "sip", or, on a host with no Skill tool, read
sip'sSKILL.mdand follow it; whensipis not installed, say so. Its findings join step 8 unapplied, each with the output that shows it; never claim a review it did not visibly run. - Plan the bump and checks. List every manifest that carries the version:
package.jsonwith its lockfile, set through the package manager (npm version X.Y.Z --no-git-tag-version), and plugin manifests such as.claude-plugin/plugin.json, where present. Name the checks: the commands the repository's CI runs, else its documented ones (in paperthin,npm testandnpm run check); with neither, step 8 says so. Both run after step 8's approval. - Draft the messages to the commit-message standard: the local log's shape, or, absent one, a subject plus one
-bullet per durable change on a single unwrapped line; supporting edits folded in; nothing the diff or version already proves; no co-author tag except a closingCo-authored-bytrailer crediting a human contributor on a squashed or carried contribution. A pending change and its bump go in one release commit, never split; only when every change in the range is already committed does it carry the bump alone. On the pull-request path every commit in the range lands as it is, so each one meets the standard, and one that does not goes to step 8 for/re0-git; the release commit is the head that lands the pull request, so its subject names the release (in paperthin,chore(release): ship paperthin X.Y.Z with <idea>), the pull request's title is that subject, and where the repository's commit form names the pull request (in paperthin,(#<n>)), the subject ends with it once the pull request has a number, its digits counted within the repository's limit (72 characters in paperthin). Cleanup of an existing commit goes to the human as/re0-git, never called here. - Write the release notes to
.re0/release/RELEASE_NOTES.local.md, scratch that becomes the signed tag's message, never committed. Wheregit check-ignore -qfinds that path not ignored, add.re0/to the filegit rev-parse --git-path info/excludenames. The house style;scripts/notes.mjsdecides each (checked) rule, and you each (judgment) one:
- one
##heading with no version number (X.Y.Z) in it (checked), naming the release's durable idea (judgment); - one paragraph on one line after it (checked), short and present-tense, saying what is true now (judgment);
- sections in this order, each at most once:
### New(or### New: <label>),### Also,### The catalog (N skills)((1 skill)for one),### Install(checked); only those the release earns, the catalog only when the roster needs re-mapping (judgment); ### Newholds only new capabilities a user reaches for; a fix or tightening of an existing skill goes under### Also(judgment);### Alsoholds only what New does not say, so a single change is one section plus Install: an Also bullet leading with a New bullet's subject fails (checked), any other repeat is (judgment);- every section but Install holds single-line
-bullets and nothing else (checked); - each New bullet opens with a bold lead (checked): the skill's name (`
**name**) or a short label (One command.`), never a whole sentence (judgment); - each catalog bullet names a perspective and its skills, plain (`
-depth/:re0) or bold and described (- **depth/** (one artifact):re0`), listing the N skills the heading counts, each once (checked), which are the real roster (judgment); ### Installis the last section and not empty (checked): the contents of the.agents/install-block.mdrelease-notes block for the note's version, fence lines left out, where one exists (checked), else the install commands the repository documents, verbatim (judgment); with neither, step 8 asks the human for the lines;- each external change is credited inline as
(#123, @handle), a run of pull requests as(#123-#125, @handle), each co-author as one more, @handle, and no other#number appears outside code, link targets and URLs (checked); every external change in the range carries its credit (judgment); - every claim about a skill stays inside what that skill's
SKILL.mdsays it does (judgment); - skill names and paths in backticks (judgment), no em dash (checked), and nothing the tag or version already proves (judgment).
- Check the notes from anywhere in the repository:
node <this skill's folder>/scripts/notes.mjs .re0/release/RELEASE_NOTES.local.md --version X.Y.Z(in paperthin the folder isskills/depth/re0-release). Exit 0 means every (checked) rule holds; an Install reported as not checked is left to its (judgment) rule. Exit 1 names each failure by line, fixed in the notes, or, for aninstall-blockfailure at line 0, in.agents/install-block.md. Exit 2 means the check could not run, for the reason its message names. Then write a verdict for each (judgment) rule. Only a reported failure or a verdict's fault changes the text, and only in notes this run wrote. - First confirmation. Show the whole proposal in one message: the release branch and range; the procedure's result and any difference from this skill; the files the commit carries and any exclusion;
sip's run and findings; the bump with its case, manifests and checks; the messages, with the release commit subject's length, its number counted; the full notes, Install included, with step 7's exit and each verdict, or a request for the Install lines where step 6 found none, nothing tagged until they are given; any exclude line added; and the landing path, the rule that set it, and its public writes: pushing the release branch, opening a pull request or retitling the open one with a new body, the number added to the release commit's subject, the fast-forward of the default branch, and the tagvX.Y.Zand its push. Whereghis missing, say how landing or watching falls to the human. A change to the exclusion or to what the notes rest on means a redraft, shown again. Nothing tracked is written before approval; then apply the bump and approvedsipfindings, run step 4's checks and step 7, quoting their output, and commit locally once both pass. Read the commit's message back (git log -1 --format=%B): it is the approved text exactly, and a mismatch, an added trailer included, is amended before anything is pushed. - Second confirmation, then land and tag. In the same run, ask to land and publish, naming the path and every public write step 8 listed. On approval:
- Direct path: sign and verify the tag on the approved commit first (below), then
git push origin <release branch>. A rejection naming a protection rule deletes that local tag (git tag -d vX.Y.Z) and turns the release to the pull-request path as its own stop: show that path's writes, and ask again. Any other rejection stops. - Pull-request path:
<subject>is the release commit's subject without its number, and<body>a file holding the release commit's bullets. Push the release branch (from the default branch, asHEAD:refs/heads/release/vX.Y.Z). Retitle the open pull request step 1 found (gh pr edit <n> --title "<subject>" --body-file <body>), or open one (gh pr create --base <default> --head <head> --title "<subject>" --body-file <body>). Where the repository's form names the pull request and the release commit's subject does not yet end with(#<n>), the check run that opening or retitling started fails on that head by design: amend the message alone to the approved one with(#<n>)added to its subject, both dates kept (in a POSIX shell,GIT_COMMITTER_DATE="$(git log -1 --format=%cd --date=raw)" git commit --amend -S -F <message-file>, its tree and author unchanged), and push it withgit push --force-with-lease origin HEAD:refs/heads/<head>to the ref the pull request's head names. Before landing, the branch must contain its base (git merge-base --is-ancestor origin/<default> HEAD); when the base moved, rebase the release branch onto it, since a merge commit cannot land on a linear history, push with--force-with-lease, then rerun steps 4 and 7 and ask again. Wait withgh pr checks <n> --watch --required; a non-zero exit stops the run, naming the failing check; nothing lands past it, admin bypass included. Land withgit push origin HEAD:refs/heads/<default>, a fast-forward to the checked head, fetch, and confirmorigin/<default>is the release branch's head andgh pr view <n> --json statereadsMERGED. A difference stops the run. Withoutghor a GitHub origin, the human lands the commit by this path. - The tag goes on the commit that carries the release (the approved commit on the direct path; on the pull-request path, the head that landed, its number amended in):
git tag -s vX.Y.Z <commit> -F .re0/release/RELEASE_NOTES.local.md --cleanup=verbatim, verified withgit tag -v vX.Y.Zbefore any push, so no branch moves before its tag verifies. Thengit push origin vX.Y.Z; report the path that ran.
- Watch the workflow.
- Find the tag's run with
gh run list --branch vX.Y.Z, retrying for about a minute; follow it withgh run watch <run-id> --exit-status;gh release view vX.Y.Z --json body,isDraftmust show the notes withisDraftfalse. - With no run, read the workflows at the tagged commit. None matching the tag (
on: push: tags) means nothing was published, and publishing is the human's step by the repository's documented route; a matching one that started no run is reported as not started, and the run stops. Observation is unavailable only afterghitself failed, quoting its error. - A failure caused outside the tagged commit is rerun with
gh run rerun <run-id> --failedonce the cause is gone. One caused inside it is reported and the run stops. - After success, compare the Release body with the tag message minus its signature block and trailing whitespace. A mismatch is reported with its cause and fixed, by a rerun or a re-cut, only on the human's approval; steps 11 and 12 go on.
- Re-cut path, for a tag whose signature or message is wrong, at the same version: it adds and moves no commit, and the new tag points at the old one's commit id. A signature re-cut copies the message byte for byte from
git cat-file tag vX.Y.Z(after the header, before the signature block) into a file, re-signs it withgit tag -s -f vX.Y.Z <commit> -F <file> --cleanup=verbatim, and runs no notes check; a message re-cut carries new notes that pass step 7. Confirmgit tag -v vX.Y.Zand, for a signature re-cut, that the message equals the file byte for byte, then push withgit push --force-with-lease=refs/tags/vX.Y.Z:<old tag object> origin vX.Y.Z. A cause in the tagged commit's files, such as a workflow defect, stops the path: its fix needs a new commit, and a new version once anything was published, the human's decision.
- Close out the contributions. After confirmed success, each contribution the release carries gets a credit comment pointing at the release, and a pull request still open is approved where it has no approval and closed with that comment, each on its own approval. The run never refuses these when asked.
- Retire the cycle after the workflow succeeded. Move
.re0/iteration/active/<version>-<workname>/into.re0/iteration/completed/withmv(it is untracked, so notgit mv), unrenamed, matched by workname when its provisional version differs. Where the repository keeps aTODO.local.md, remove the folder's entry there and fix the casebook's relative links. Skip this when no iteration folder matches.
Rules
- Never invent a CLI command or flag; verify each against its docs or a real run.
- Landing the commit and pushing the tag are the whole manual part. Never perform by hand any step the release workflow owns, publishing or titling the release page included, even to rescue a failed run; a re-cut tag (step 10) is pushed so the workflow publishes it.
- Never push a tag before every manifest's version equals it.
- Earlier tags are history, not precedent: a new note follows step 6 whatever the nearest tag did, and an existing tag's message is never checked, and changed only by a message re-cut (step 10), never by editing the Release body the workflow copies from it.
- negatives-as-corpus: retirement moves the iteration folder, never deletes it; if the release fails or is rolled back, the folder stays live.
- The stops, each its own question in the same run: a gap and a choice among several open pull requests (step 1), an open question bearing on the bump (step 2), the proposal and its local commit (step 8), landing and tagging, and again after a rejected direct push or a moved base (step 9), a mismatch fix or a re-cut tag (step 10), and each credit comment or closing (step 11). An approval covers its own stop only, and one the human already gave in their own words counts: after "go ahead with publication", publication is not asked again. A check, run or job is reported as passed only for the state it ran on and only from output the run observed, quoted. The run ends when the human declines or defers a stop, or at a stop a step names, and reports what remains without offering it.
Verification
Before finishing, confirm and report:
- Every manifest's version matches the tag, and the landed subject fits the repository's limit.
- Every commit in the range meets the commit-message standard, the release commit's subject carries the pull request's title and number on that path, and
notes.mjsexited 0 with a verdict on every (judgment) rule. - Every stop in Rules asked its own question, and the run went no further than approved.
- The landing path rested on a rule read or a server rejection, and any landing moved the default branch to the release branch's head.
- The workflow run completed with a matching Release body, or the report says what was not published or not observed.
- The iteration folder moved with its TODO entry and links, or was skipped, and every skipped step or gap is reported.