Stats
Actions
Tags
From hatch3r
Release workflow with version bump, changelog, tagging, CycloneDX SBOM, npm provenance, and deploy verification. Use when cutting a release or deploying to production.
How this skill is triggered — by the user, by Claude, or both
Slash command
/hatch3r:hatch3r-releaseThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> **Note:** Commands below use `npm` as an example. Substitute with your project's package manager (`yarn`, `pnpm`, `bun`) or build tool when your project uses a different package manager.
Note: Commands below use
npmas an example. Substitute with your project's package manager (yarn,pnpm,bun) or build tool when your project uses a different package manager.
commands/hatch3r-release.md (Decision 13 handoff)This skill shares the id: hatch3r-release with the orchestrator command commands/hatch3r-release.md. The two are NOT duplicates — they split the release workflow by execution model per CONSTITUTION §6 Decision 13:
commands/hatch3r-release.md (orchestrator entry): the multi-agent release pipeline — implementer applies the version-bump + changelog + SBOM mutations, docs-writer reconciles repo/website docs, a reviewer↔fixer loop verifies the diff, testability + security run the final-quality pass, ci-watcher diagnoses red gates (agentPipeline: [hatch3r-implementer, hatch3r-docs-writer, hatch3r-reviewer, hatch3r-fixer, hatch3r-testability, hatch3r-security, hatch3r-ci-watcher]). Use the command when the release warrants sub-agent fan-out (parallel mutation + review-loop + specialist gates) and stops before publish/merge for human approval.The merge-candidate review (F16.3-H3) flagged the shared id; this handoff documentation is the explicit workflow-split declaration that disambiguates the pair, enforced by the Decision-13 command↔skill gate in src/cli/commands/validate.ts. A future collapse into a single command appendix requires coordinated edits to the command body, the bundled content inventory (skills count), and that gate.
Irreversibility alignment (D10-14): the command and this skill now share the same stop-before-irreversible boundary, so /release resolving to either artifact is safe. The command stops at its Step 9 before publish/merge; this skill's Irreversibility Gate makes every irreversible step (tag push, publish, production deploy) default-OFF behind --publish or a typed confirmation. Neither artifact auto-publishes or auto-deploys on a bare invocation — the prior mismatch (a stop-before-publish command vs an auto-publish+deploy skill at one slash name) is closed.
Task Progress:
- [ ] Step 0: Detect ambiguity (P8 B1)
- [ ] Step 1: Determine version bump (major/minor/patch) based on changes
- [ ] Step 2: Generate changelog from merged PRs and commit history
- [ ] Step 3: Update version in package.json and any other version references
- [ ] Step 4: Verify quality gates (lint, typecheck, all tests)
- [ ] Step 5: Create git tag and platform release with changelog
- [ ] Step 5b: Generate supply-chain artifacts (SBOM + provenance + SLSA + cosign)
- [ ] Step 6: Deploy and verify (staging first if applicable, then production)
- [ ] Step 7: Monitor post-deploy for errors/regressions
Before any work, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target environment, or irreversibility. If any are found, ask the user via the platform-native question tool per agents/shared/user-question-protocol.md. Do not proceed under silent assumption. Default path, not an exception. Triggers for THIS skill: bump level (major vs minor vs patch), deploy authority (cut-only vs deploy-and-monitor), staging gate (required vs skipped), rollback policy (auto vs manual), and irreversible tag/publish operations (npm publish, GitHub release).
Fan-out scales with task size; token cost never justifies serializing independent work (rules/hatch3r-fan-out-discipline.md P8 B2; agents/shared/efficiency-patterns.md). Emit sub_agents_spawned: { count, rationale } in your output.
This skill drives irreversible publish/deploy actions — git push, gh release create / glab release create, npm publish --provenance, and production deploy. Each is a one-way door: a published npm version cannot be re-published, a pushed tag and a created release are public immediately. Reversibility-first: every irreversible step is default-OFF and requires explicit operator confirmation before it runs. The default path produces and verifies the artifacts, then stops before the irreversible action and asks.
| Step | Action | Default | Run-trigger |
|---|---|---|---|
| 5 | git push origin vX.Y.Z + platform release create | OFF | --publish flag OR operator types the target version vX.Y.Z at the confirm prompt |
| 5b.2 | npm publish --provenance | OFF | same --publish/typed-version trigger as Step 5; runs in CI on the human-pushed tag (no local publish) |
| 6 | Deploy to production | OFF | operator types DEPLOY at the confirm prompt after staging smoke tests pass |
Rules:
/release, or as the inline procedure inside commands/hatch3r-release.md) without --publish runs Steps 0-4 + 5b.1/5b.3-5b.6 artifact emission, then prints the staged release summary and the exact publish/deploy commands, and stops. The operator runs the gated step or re-invokes with --publish.vX.Y.Z for publish, DEPLOY for production) so a reflexive confirmation cannot trigger an irreversible action.commands/hatch3r-release.md enforces the same stop-before-publish boundary at its Step 9 — this skill's gate is the inline-procedure equivalent of that handoff.platform in .hatch3r/hatch.json):
search_issues, PR search) or gh pr list --state merged --base {defaultBranch}az repos pr list --status completed --target-branch {defaultBranch}glab mr list --state merged --target-branch {defaultBranch}git log v1.2.0..HEAD --oneline or the platform's release/PR API).- description (#PR-number) or - description (commit hash).CHANGELOG.md or GitHub Release notes).version in package.json.package-lock.json (via npm version), docs, config files.npm install to refresh lockfile if needed.chore(release): vX.Y.Z or similar.${HATCH3R:VERIFY_GATE_ALL}
npm run build
The gate line is resolved to the project's language-aware command set at sync time (fallback when detection is unknown: npm run lint && npm run typecheck && npm run test); the build line is illustrative — substitute the project's build command.
Tag-push and release-create are irreversible (default-OFF per the Irreversibility Gate). Create the annotated tag locally, then stop and confirm before pushing it or creating the public release. Run the push + release-create only with --publish or after the operator types the target vX.Y.Z at the confirm prompt.
git tag -a vX.Y.Z -m "Release vX.Y.Z" (local, reversible — delete with git tag -d vX.Y.Z).git push origin vX.Y.Z.platform in .hatch3r/hatch.json):
gh release create vX.Y.Z --title "vX.Y.Z" --notes "{changelog}" (or use GitHub MCP if available)az repos tag create vX.Y.Z — attach release notes as a wiki page or work item, and upload build artifacts via Azure Artifactsglab release create vX.Y.Z --name "vX.Y.Z" --notes "{changelog}"F15.8-H4 (Cycle 10 D15-SA15.8): every release surface MUST emit an SBOM + provenance + SLSA attestation + container signature before deploy. Skipping these produces un-attested artifacts that fail consumer-side npm audit signatures and SLSA-Build-L3 verification.
Maturity-tier gating (per the P5 maturity-tier model — solo/team/scaleup/enterprise; see agents/shared/principles.md):
solo — MAY defer SBOM emission and SLSA generator for a single-maintainer release. Provenance (--provenance flag below) and cosign for any container image remain mandatory.team, scaleup, enterprise — MUST execute every sub-step below; consumer verification depends on these artifacts being present.npm sbom --sbom-format=cyclonedx --sbom-type=application > dist/sbom.cdx.json
Attach dist/sbom.cdx.json to the GitHub release. Reference: npm sbom (npm CLI >=10.5.0) emits CycloneDX 1.5 or SPDX 2.3.
Configure Trusted Publisher once on the npm settings page, then publish via GitHub Actions only:
permissions:
id-token: write # OIDC token for Sigstore signing
contents: read
steps:
- run: npm publish --provenance --access public
--provenance emits a Sigstore-signed attestation through Fulcio + Rekor. Reference: https://docs.npmjs.com/trusted-publishers/ (accessed 2026-05-27). Publish is irreversible (default-OFF per the Irreversibility Gate): it fires from CI only on the human-pushed Step 5 tag — there is no local npm publish on the default path.
Pin the slsa-github-generator action by 40-character commit SHA — never a tag:
uses: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@<40-char-SHA>
with:
base64-subjects: ${{ needs.publish.outputs.digest }}
upload-assets: true
Reference: https://github.com/slsa-framework/slsa-github-generator.
When the release ships a container image:
cosign sign --yes \
--oidc-issuer https://token.actions.githubusercontent.com \
ghcr.io/<owner>/<image>@<digest>
Reference: https://github.com/sigstore/cosign (cosign 2.x keyless flow).
Document the verification commands in the release notes:
npm audit signatures
slsa-verifier verify-artifact --provenance-path attestation.intoto.jsonl --source-uri github.com/<owner>/<repo> --source-tag <tag> <artifact-file>
cosign verify --certificate-identity-regexp 'https://github\.com/<owner>/<repo>/' --certificate-oidc-issuer https://token.actions.githubusercontent.com ghcr.io/<owner>/<image>:<tag>
dist/sbom.cdx.json attached to platform releasenpm publish --provenance exit 0; npm view <pkg>@<version> --json | jq .dist.signatures returns a signatureslsa-verifier verify-artifact exit 0cosign verify exit 0Production deploy is irreversible (default-OFF per the Irreversibility Gate). Staging is reversible and runs on the default path; the production step stops and confirms (operator types DEPLOY) only after staging smoke tests pass.
DEPLOY confirmation or --publish.Version formats: alpha (x.y.z-alpha.N), beta (x.y.z-beta.N), release candidate (x.y.z-rc.N). Workflow:
v1.2.0-beta.1).--tag (npm publish --tag beta) — irreversible, same default-OFF gate as Step 5b.2 (publish via CI on the pushed pre-release tag).npm distribution tags: latest (stable), beta, next (RCs), alpha. GitHub releases for pre-releases use --prerelease.
Follow Keep a Changelog:
### Added — new features### Changed — changes to existing functionality### Deprecated — soon-to-be removed### Removed — removed features### Fixed — bug fixes### Security — vulnerability fixesEntries grouped under ## [x.y.z] - YYYY-MM-DD. Generate entry as part of the release commit; stage CHANGELOG.md alongside package.json. If CHANGELOG.md does not exist, create it with the standard header pointing to keepachangelog.com and semver.org.
If a release introduces critical issues:
npm deprecate package@version "Critical issue — use version X instead". Within 72h, npm unpublish package@version is permitted (only inside npm's unpublish window). Publish a hotfix as a new patch release.--publish or its typed confirmation (Irreversibility Gate) — never silently-alpha.N, -beta.N, -rc.N) in Step 3 and Pre-Release Support.npm sbom CycloneDX 1.5 / SPDX 2.3 output and the >=10.5.0 CLI floor cited in the supply-chain step (5b).npx claudepluginhub hatch3r/hatch3r --plugin hatch3rGenerates SemVer-compliant version bumps and changelog entries from git diffs. Use when cutting releases, tagging, or publishing with precise change summaries.
Orchestrates GitHub releases with automated versioning, changelog generation, multi-platform builds, and rollback support. Use when cutting a release or coordinating a deploy.
Validates and executes software releases with changelog generation, version bumping, git tagging, and CI verification.