Release

intent

this skill takes a project from "code is ready" to "tagged, pushed by the operator, and verified green on the exact tagged SHA." it handles pre-flight validation, changelog generation from git history, version bumps across package files, release commits, annotated tags, curated release notes, and post-push SHA verification. use it when you need to cut a release with confidence that every artifact is in sync and CI has signed off on the exact commit you tagged.

inputs

• git repo: local git repository with clean working tree (no uncommitted changes)
• package files: files containing version strings (package.json, setup.py, Cargo.toml, etc.) that need bumping
• git history: commit log with conventional commit format (feat:, fix:, breaking:) for changelog generation
• GitHub token: GITHUB_TOKEN environment variable with repo scope (required for GitHub Release creation and tag pushes)
• git user config: user.name and user.email configured locally (git config user.name, git config user.email)
• CI system access: the skill assumes a CI/CD system (GitHub Actions, GitLab CI, etc.) will verify the tagged SHA after push
• version argument (optional): semantic version string (e.g., "1.7.0") or omitted to auto-suggest from commits

procedure

1. pre-flight validation

   • input: git repo state
   • check working tree is clean (no unstaged changes, no untracked files blocking release)
   • check git user is configured
   • check GITHUB_TOKEN env var is set and valid
   • output: pass/fail status; if fail, list blocking issues

2. version determination

   • input: optional version argument from user (e.g., "1.7.0")
   • if version provided: use it
   • if version omitted: analyze commit history since last tag, suggest next version using semver rules (breaking changes = major, new features = minor, fixes = patch)
   • output: determined version string

3. changelog generation

   • input: git commit history between last tag and HEAD, version string
   • parse conventional commits (feat:, fix:, breaking:, etc.)
   • group commits by type (features, fixes, breaking changes)
   • output: formatted changelog text (markdown format)

4. version bump

   • input: determined version, list of package files in repo
   • locate version strings in each package file (e.g., "version": "1.6.0" in package.json)
   • replace with new version
   • output: modified package files (uncommitted)

5. release commit

   • input: version-bumped package files, changelog
   • stage all modified package files
   • create commit with message: "chore: release 1.7.0" (with actual version)
   • output: new commit on current branch (unpushed)

6. annotated tag

   • input: new release commit, version string, changelog
   • create annotated git tag named "v1.7.0" (with actual version)
   • tag message: changelog text
   • output: local annotated tag (unpushed)

7. publish to remote

   • input: local commit, local tag, GITHUB_TOKEN
   • push commit to remote branch (e.g., git push origin main)
   • push tag to remote (e.g., git push origin v1.7.0)
   • create GitHub Release page via GitHub API using tag and changelog
   • output: commit and tag live on GitHub, Release page created

8. CI verification trigger

   • input: pushed tag, CI webhook configuration
   • CI system automatically detects tag push and runs full test suite on exact tagged SHA
   • skill does not wait for CI; CI completion is operator's responsibility to verify
   • output: CI job triggered (link provided to operator)

decision points

• if --dry-run flag provided: execute steps 1-6 (pre-flight, version, changelog, bump, commit, tag) but do not execute step 7 (publish). show operator what would be created. allow rollback by discarding local commits and tags.
• if --check flag provided: execute step 1 (pre-flight validation) only. return GO (all checks pass) or NO-GO (blocking issues). do not modify any files or git state.
• if no version argument and no commits since last tag: suggest patch bump and continue; do not fail.
• if package files missing or unparseable: fail with clear error listing which files could not be updated. operator must fix before retry.
• if GITHUB_TOKEN invalid or missing: fail at step 7 pre-push validation. do not push commit or tag. operator must set valid token and retry (local commit and tag are preserved for reuse).
• if working tree dirty: fail at pre-flight. operator must stash or commit changes before release can proceed.
• if remote push fails (network timeout, rate limit, permissions): catch error, do not create GitHub Release, output error with retry guidance. local commit and tag remain; operator retries push manually.
• if changelog or version bump produces merge conflicts: unlikely in normal workflow, but if package files were edited on another branch, fail with conflict details. operator resolves and retries.

output contract

• dry-run output: formatted text showing (a) version to be released, (b) changelog to be included, (c) package files that would be modified, (d) commit message, (e) tag name and tag message. no files written; git state unchanged.
• check output: simple GO or NO-GO with list of failed checks (if any). no files written; git state unchanged.
• full release output: (a) local commit on current branch with bumped versions, (b) local annotated tag with changelog in tag message, (c) pushed commit and tag on GitHub, (d) GitHub Release page created with changelog, (e) CI job triggered on tagged SHA. all artifacts use consistent version string (e.g., "1.7.0" or "v1.7.0" for tag).
• file locations: modified package files in their original locations (e.g., ./package.json, ./setup.py). git objects and refs live in .git/. GitHub Release page at https://github.com/{owner}/{repo}/releases/tag/v{version}.

outcome signal

• pre-flight pass: "pre-flight check: GO. ready to release."
• version suggested: "no version provided. suggest 1.7.0 based on commits. run /release 1.7.0 to proceed."
• dry-run displayed: "dry-run: 0 files modified, 1 commit created, 1 tag created. no push. run /release 1.7.0 to publish."
• release complete: "released 1.7.0. pushed to github. tag v1.7.0 created. release page: https://github.com/owner/repo/releases/tag/v1.7.0. ci job running at [link]."
• error state: clear error message specifying the step that failed (e.g., "version bump failed: could not parse version in ./package.json") and how to recover.
• operator verification: operator navigates to GitHub to confirm (a) commit is live on main, (b) tag exists and points to correct commit, (c) Release page is published, (d) CI is running or completed on tagged SHA.