Release

Skill nexus-substrate/nexus-agents/skills/release

Execute a release following project standards. Use when publishing a new version, creating release tags, or deploying. Triggers on "release", "publish", "version bump", "create release".From its SKILL.md

Install

npx -y skills add nexus-substrate/nexus-agents --skill release

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

23 stars23 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

6.4 KB, as published. Nobody here has run it

Release Skill

Pre-launch checklist (run before tagging)

The pnpm changeset workflow handles versioning, but the human-judgment gates below decide whether the release is ready. Run all of these:

Code quality

pnpm lint && pnpm typecheck && pnpm test — green
pnpm coverage — coverage hasn't regressed below the gate (89.66% statements, 93.26% functions per CLAUDE.md)
No TODO / FIXME / XXX comments in production source added in this release that should have been resolved
No console.log debugging statements in production code
All @deprecated markers added in this release have a clear replacement and migration path (see deprecation-and-migration skill)

Security

pnpm audit shows no critical/high vulnerabilities (or each is documented + mitigated)
No new secrets, env vars, or credentials added without .env.example placeholder + docs
CodeQL alerts at 0 high/critical (see security-scanning skill)
gh api repos/{owner}/{repo}/dependabot/alerts?state=open returns clean

Documentation

CHANGELOG entry exists for every public-API change (changesets handles this if pnpm changeset was run)
Migration recipe in changeset for any breaking change (typed-only or runtime)
inject-governance.ts regen ran cleanly (CLAUDE.md skill table, AGENTS.md, marketplace.json all in sync)
No stale @deprecated references in docs/

Pipeline health

Last 5 release runs on main succeeded (gh run list --workflow=Release --limit 5)
No release PR currently open (gh pr list --search "version packages") — if one IS open, merge it FIRST (a stale version PR is how npm gets ahead of main); see "Avoid the publish race" below
npm view nexus-agents version matches packages/nexus-agents/package.json — the Detect npm-ahead version skew step in release.yml also enforces this, but check before tagging
No changeset debt — every recent shippable-source PR shipped its own changeset (the Changeset Presence CI gate enforces this going forward)

Avoid the publish race

If you're merging a release PR while other PRs add changesets, you'll trigger the version-skip race documented in release-changeset-race.md. To avoid:

Hold non-trivial PR merges while a release PR is open
After merging the release PR, verify within 5 minutes: npm view nexus-agents version should match packages/nexus-agents/package.json
If it doesn't, the workflow's force-publish fallback (#2383) should kick in on the next push. If still stuck, see the runbook.

Pre-Release Checks

# Verify all gates pass
pnpm lint && pnpm typecheck && pnpm test

# Check fitness score (must be >= 90)
nexus-agents fitness-audit --format=json

Release Workflow (Changesets)

Releases are automated via changesets + GitHub Actions:

Add a changeset during development:
```
pnpm changeset
```
Merge PR to main — the Release workflow will:
- Create a "Version Packages" PR (bumps version, updates CHANGELOG.md)
- When that PR merges, publish to npm via OIDC trusted publishing
- Create a GitHub Release with auto-generated notes
No tokens required — npm authentication uses OIDC (see id-token: write permission in .github/workflows/release.yml). The trusted publisher is configured on npmjs.com to accept publishes from this repo's release.yml.

IMPORTANT: npm trusted publisher config must match workflow filename. The npmjs.com package settings specify the exact workflow file (release.yml), repository (nexus-substrate/nexus-agents), and environment. If you rename the workflow file, update the npm trusted publisher config to match or publishing will fail with OIDC token rejection.

Manual Publish (emergency only)

# Manual publish via the same release workflow (uses OIDC, no tokens needed)
gh workflow run release.yml

# Or with dry run:
gh workflow run release.yml -f dry_run=true

Rollback (if needed)

npm unpublish nexus-agents@<version>  # Within 72 hours
git tag -d v<version> && git push --delete origin v<version>

Release CLI Commands

The project also has built-in release automation:

nexus-agents release-notes      # Generate release notes
nexus-agents release-validate   # Validate release readiness
nexus-agents release-announce   # Announce release

Anti-rationalization — Release

Excuse	Counter
"Skip the audit, dependencies are fine"	`pnpm audit` shows critical/high before they ship. Five seconds of audit prevents a coordinated-disclosure scramble.
"I'll fix the doc drift in the next release"	Documentation drift compounds. Block release on `inject-governance` and `check-docs-indexed` clean.
"We can roll back if it's bad"	npm `unpublish` only works <72h, and even then leaves the version "published" in semver caches. Pre-release gates prevent the need.
"The release PR is open, just merge it"	If other PRs are queued with new changesets, you'll trigger the publish race (#2382). Hold queue until release PR merges.

Red flags

Release tagged with failing CI on main
pnpm audit shows critical/high vulnerabilities
CHANGELOG entry missing for a public-API change
npm view nexus-agents version doesn't match package.json after release-PR merge (publish race — see release-changeset-race.md)
Release PR merged while other changeset-adding PRs are open