release

name

release

description

Manages package release workflows for npm and Swift/macOS ecosystems (Python and Go coming soon). Detects project type from manifest files, bumps versions, transforms changelogs (Keep a Changelog format), creates git commits and tags, and optionally generates CI publishing workflows or GitHub Releases. Use when releasing packages, cutting versions, publishing to registries, bumping versions, setting up release infrastructure, checking release readiness, doing a dry run before publishing, creating pre-release versions, or tagging a new release.

Release

One command to release any package. Detects your ecosystem, bumps the version, updates the changelog, commits, tags, pushes, and watches CI.

Commands

Command	What it does
/release patch	Bump patch version and release
/release minor	Bump minor version and release
/release major	Bump major version and release
/release alpha	Create alpha pre-release
/release beta	Create beta pre-release
/release rc	Create release candidate
/release context	Show version, commits, changelog status (read-only)
/release dry	Simulate a release without mutations
/release setup-ci	Generate CI/CD workflow files

---

Step 1: Parse Arguments

Determine the release type from the invocation:

• patch, minor, major → stable release
• alpha, beta, rc → pre-release
• context → read-only status
• dry → dry run simulation
• setup-ci → CI workflow generation
• No argument → show this command reference and stop

---

Step 2: Detect Ecosystem

Scan the project root for manifest files to determine the ecosystem:

File present	Ecosystem	Next step
package.json with a version field	npm	Read adapters/npm.md
Package.swift with .executableTarget	Swift	Read adapters/swift.md
pyproject.toml	Python	Not yet supported — print message and stop
go.mod	Go	Not yet supported — print message and stop
None of the above	Unknown	Print: "Unsupported project type. This skill supports: npm and Swift/macOS (now), Python and Go (coming soon)." and stop

To check for .executableTarget: grep -q '\.executableTarget' Package.swift

For the npm ecosystem, also detect the package manager:

Lock file present	Package manager
bun.lock or bun.lockb	bun
pnpm-lock.yaml	pnpm
yarn.lock	yarn
package-lock.json	npm
None of the above	npm (default)

If multiple lock files exist, use the highest match from the table (top = highest priority) and note the conflict to the user.

Guard Rails

Before proceeding, check for known unsupported configurations:

1. Read package.json and check for a workspaces field. If present:

   • Print: "Monorepo detected (workspaces field found). This skill supports single-package repos only. For monorepos, see changesets or release-please."
   • Stop.

2. Check for "private": true in package.json. If present:

   • Print: "Note: Package is marked private. Publishing will be skipped, but version bumping, changelog management, and tagging will still work."
   • Continue (do not stop).

---

Step 3: Check Infrastructure

Check for CHANGELOG.md with an ## [Unreleased] section (case-insensitive), a pre-push hook at .git/hooks/pre-push containing release validation, and CI publish workflows in .github/workflows/.

For context: report what's missing — don't offer to create anything.

For all other commands: if CHANGELOG.md is missing or has no [Unreleased] section, route to flows/init.md first. After init, note missing infrastructure (hook, CI) to offer post-release.

---

Step 4: Route to Flow

Read the adapter file identified in Step 2, then follow the appropriate flow:

Command	Flow
patch, minor, major	flows/release.md — 10-step release flow
alpha, beta, rc	flows/pre-release.md — pre-release flow
context	flows/context.md — read-only status report
dry	flows/dry-run.md — simulation without mutations
setup-ci	flows/setup-ci.md — CI workflow generation

---

Step 5: Post-Release Offers

After a successful stable release (push completed), check and offer:

1. Pre-push hook not installed? → "Would you like to install a pre-push hook to validate releases? It checks that tag versions match your manifest and changelog."

2. No CI publish workflow? → Check if the remote contains github.com. If yes: "Would you like to generate GitHub Actions workflows for CI and automated publishing? Run /release setup-ci." If not on GitHub: "No CI publish workflow detected. /release setup-ci can generate GitHub Actions workflows if needed, but note that only GitHub Actions is supported at this time."

These are suggestions only — never install automatically without confirmation.

---

Rollback

If anything goes wrong during a release, see reference/rollback.md for exact recovery commands for every failure scenario.

---

Design Principles

• Human-written changelogs. The skill manages the format; you write the content.
• Confirm before push. Every release shows a summary and waits for explicit approval.
• Ecosystem adapters. Same flow, different commands. Adding a new ecosystem is one file.
• Graceful degradation. Network-dependent steps (push, CI watch) degrade cleanly when unavailable. Steps 1–8 work with just filesystem and git.
• No tool-specific instructions. Commands use standard bash — works with any agent that can run shell commands.