Nexus Release
Context: a Nexus release is one artifact — a bare X.Y.Z git tag on main.
Everything downstream (installing, building, naming the release, uploading
main.js / manifest.json / styles.css, provenance attestation) is done by
<repo>/.github/workflows/release.yml from the tagged commit. You never build
the release; you make the tagged commit correct and then tag it.
Two consequences shape everything here. The tag is the point of no return — the
workflow reads the tree as committed at that tag. And the workflow guards only
three things, so everything else is on you.
Path convention: <repo>/… means relative to the Nexus repo root. Bare paths
(protocols/…, scripts/…) are inside this skill.
Workflow
Cutting a release → follow protocols/cut-release.md end to end, in
order. Do not improvise the sequence: several steps only have any effect
before the tag exists.
Bringing user-facing docs in line (a phase of the above; also runnable on
its own) → protocols/doc-review.md.
Before pushing any tag you MUST get a clean exit from the readiness
check. It reproduces the workflow's own version guard locally, so a failure
here is a failure you would otherwise discover after the tag exists:
python3 .claude/skills/nexus-release/scripts/check_release_ready.py --tag X.Y.Z
(--repo defaults to the repo root found by walking up from the working
directory. Run --help for the flags; stdlib only, no node_modules. If the
mirror above is absent, the same file is at
<repo>/.skills/nexus-release/scripts/check_release_ready.py.)
The workflow did not run, failed its guard, or shipped the wrong assets →
protocols/recover.md. NEVER hand-create a release or hand-attach assets to
fix it — that silently drops provenance attestation.
After a release session → protocols/self-refine.md.
Map
protocols/ the how: cut-release.md, doc-review.md, recover.md,
self-refine.md.references/ the why, read on demand: release-machinery.md (what the
workflow really does, what it guards, what it does not, and the build-order
asymmetry that decides which generated file can ship stale),
changelog-format.md (the conventions the changelog actually follows).scripts/ check_release_ready.py — version consistency across
package.json, manifest.json, versions.json, the lockfile and the tag.refinement-log.md — what past releases taught this skill.
Siblings
Do not duplicate these; call them.
| Need |
Skill |
| Regenerate the tool catalog a release must ship current |
nexus-tool-schemas |
| Choose a Jest lane, or debug a failing guidance/drift test |
nexus-testing |
| Provider/model metadata that a release happens to include |
nexus-model-updates |
| Mobile or plugin-store compliance of what is being shipped |
nexus-mobile-compat |
Editing this skill
<repo>/.skills/ is the source of truth for this skill; .claude/skills/,
.codex/skills/ and .cline/skills/ are mirrors written by
npm run sync:skills. Edit the copy under <repo>/.skills/nexus-release/ and
re-run the sync. The mirror copy overwrites changed files but does not delete
extra ones, so editing a mirror leaves a half-reverted hybrid on the next sync.
1---2name: nexus-release-23description: Cut a Nexus release — bump the version with the repo's own machinery, get the docs and generated sources right, push a tag the GitHub Actions workflow will actually pick up, and recover when it does not. Use when asked to release, publish, ship, cut a release, bump the version, or tag a version, and when a release workflow did not fire, failed its version guard, or produced the wrong assets.4---56# Nexus Release78Context: a Nexus release is one artifact — a **bare `X.Y.Z` git tag on `main`**.9Everything downstream (installing, building, naming the release, uploading10`main.js` / `manifest.json` / `styles.css`, provenance attestation) is done by11`<repo>/.github/workflows/release.yml` from the tagged commit. You never build12the release; you make the tagged commit correct and then tag it.1314Two consequences shape everything here. The tag is the point of no return — the15workflow reads the tree *as committed at that tag*. And the workflow guards only16three things, so everything else is on you.1718Path convention: `<repo>/…` means relative to the Nexus repo root. Bare paths19(`protocols/…`, `scripts/…`) are inside this skill.2021## Workflow22231. **Cutting a release** → follow `protocols/cut-release.md` end to end, in24 order. Do not improvise the sequence: several steps only have any effect25 *before* the tag exists.262. **Bringing user-facing docs in line** (a phase of the above; also runnable on27 its own) → `protocols/doc-review.md`.283. **Before pushing any tag** you MUST get a clean exit from the readiness29 check. It reproduces the workflow's own version guard locally, so a failure30 here is a failure you would otherwise discover *after* the tag exists:3132 ```bash33 python3 .claude/skills/nexus-release/scripts/check_release_ready.py --tag X.Y.Z34 ```3536 (`--repo` defaults to the repo root found by walking up from the working37 directory. Run `--help` for the flags; stdlib only, no `node_modules`. If the38 mirror above is absent, the same file is at39 `<repo>/.skills/nexus-release/scripts/check_release_ready.py`.)404. **The workflow did not run, failed its guard, or shipped the wrong assets** →41 `protocols/recover.md`. NEVER hand-create a release or hand-attach assets to42 fix it — that silently drops provenance attestation.435. **After a release session** → `protocols/self-refine.md`.4445## Map4647- `protocols/` the how: `cut-release.md`, `doc-review.md`, `recover.md`,48 `self-refine.md`.49- `references/` the why, read on demand: `release-machinery.md` (what the50 workflow really does, what it guards, what it does not, and the build-order51 asymmetry that decides which generated file can ship stale),52 `changelog-format.md` (the conventions the changelog actually follows).53- `scripts/` `check_release_ready.py` — version consistency across54 `package.json`, `manifest.json`, `versions.json`, the lockfile and the tag.55- `refinement-log.md` — what past releases taught this skill.5657## Siblings5859Do not duplicate these; call them.6061| Need | Skill |62|---|---|63| Regenerate the tool catalog a release must ship current | `nexus-tool-schemas` |64| Choose a Jest lane, or debug a failing guidance/drift test | `nexus-testing` |65| Provider/model metadata that a release happens to include | `nexus-model-updates` |66| Mobile or plugin-store compliance of what is being shipped | `nexus-mobile-compat` |6768## Editing this skill6970`<repo>/.skills/` is the source of truth for this skill; `.claude/skills/`,71`.codex/skills/` and `.cline/skills/` are mirrors written by72`npm run sync:skills`. Edit the copy under `<repo>/.skills/nexus-release/` and73re-run the sync. The mirror copy overwrites changed files but does not delete74extra ones, so editing a mirror leaves a half-reverted hybrid on the next sync.
ProfSynapse