Release

Release Skill

Create versioned releases with proper git tagging and GitHub release creation. The workflow is:

1. Bump version via PR (respects branch protection)
2. Create tag on the merged commit
3. Create GitHub release with notes
4. CI publishes to npm automatically

When to Use

• After completing features/fixes ready for release
• When creating patch/minor/major version bumps
• For pre-release versions (alpha, beta, rc)
• When auditing what changes would be in a release (--dry-run)

Prerequisites:

• All related kspec tasks should be completed before release
• Run npm test locally to verify tests pass
• Ensure you're on main with a clean working tree

Arguments

$release [patch|minor|major|X.Y.Z] [options]

Workflow

Phase 1: Detect Context

Gather information about current state:

# Get current branch
git branch --show-current

# Check for uncommitted changes
git status --porcelain

# Get current version from package.json
node -p "require('./package.json').version"

# Get last tag
git describe --tags --abbrev=0 2>/dev/null || echo "no-tags"

# Get commits since last tag
git log $(git describe --tags --abbrev=0 2>/dev/null)..HEAD --oneline

Context to gather:

• Current branch (must be main)
• Working tree status (must be clean)
• Current version in package.json
• Last tag (e.g., v0.1.1)
• Commits since last tag (count and list)

Phase 2: Validate Constraints

All constraints must pass before proceeding:

Dry-run behavior: In dry-run mode, validation failures are reported but the preview continues. In normal mode, ANY validation failure stops execution immediately.

Phase 3: Determine Version

If version type not specified, auto-detect from ALL commits since last tag:

# Get all commit messages since last tag (not just merges)
git log $(git describe --tags --abbrev=0)..HEAD --pretty=format:"%s%n%b"

Auto-detection rules (conventional commits):

Resolution order:

1. If ANY commit has breaking change indicator -> major
2. Else if ANY commit starts with feat: -> minor
3. Else -> patch

Prerelease handling (--prerelease <type>):

Prerelease rules:

1. Same prerelease type -> increment counter (alpha.0 -> alpha.1)
2. Different prerelease type -> reset counter (alpha.1 -> beta.0)
3. No prerelease flag on prerelease version -> promote to stable

Phase 4: Analyze Changes for Release Notes

Parse commits and categorize them for user-friendly release notes.

Commit selection:

• Prefer merge commits (contain (#N) PR reference) to avoid duplicates
• If no merge commits, include all commits matching conventional patterns
• Deduplicate by checking if a commit's changes are already in a merge commit

Categorization (commit type -> section):

kspec integration:

# Extract completed task references from commit trailers
git log $(git describe --tags --abbrev=0)..HEAD --pretty=format:"%b" | grep -E "^Task: @" | sort -u

Completed tasks provide context for what was accomplished in this release.

Phase 5: Preview (--dry-run)

For --dry-run, show comprehensive preview. No changes are made - no PRs, no tags, no releases.

## Release Preview (DRY RUN)

**Version bump:** 0.1.1 -> 0.1.2 (patch)
**Detection:** Auto-detected from 5 commits (3 fix, 2 chore)

### Validation
- [x] On main branch
- [x] Working tree clean
- [x] Up to date with origin
- [x] Has 5 commits since v0.1.1
- [x] Tag v0.1.2 does not exist

### Release Notes Preview

Bug fixes and improvements for kspec CLI.

#### Features & Additions
- Add JSON output mode for task list

#### Bug Fixes
- Fix author attribution for auto-generated notes
- Increase timeout for ref resolution

### Actions (dry-run: NOT executed)
1. Create version bump PR (package.json -> 0.1.2)
2. Regenerate kspec-agents.md with new version
3. Wait for CI, then merge PR
4. Create tag: v0.1.2
5. Push tag to origin
6. Create GitHub release with notes above
7. CI will publish to npm

To execute: run `$release` without --dry-run

Phase 6: Bump Version (PR)

Before creating the tag, update package.json via PR:

VERSION="0.1.2"  # calculated version

# Create branch for version bump
git checkout -b release/v$VERSION

# Update version without creating a tag
npm version $VERSION --no-git-tag-version

# Regenerate kspec-agents.md so the version header stays in sync
# For self-hosting (releasing kspec itself), use: npm run dev -- agents generate
kspec agents generate

# Commit and push
git add package.json package-lock.json kspec-agents.md
git commit -m "chore: bump version to $VERSION"
git push -u origin release/v$VERSION

# Create PR
gh pr create --title "chore: bump version to $VERSION" --body "Prepare release v$VERSION"

# Wait for CI to pass, then merge
gh pr merge --merge --delete-branch

Why version bump first?

• The tagged commit has the correct version in package.json
• CI publishes exactly what's in package.json
• No out-of-sync state between git tag and package version

Why regenerate kspec-agents.md?

• The freshness comment includes the kspec version (Generated by kspec vX.Y.Z)
• Regenerating after the version bump keeps the header in sync with the release
• Self-hosting note: When releasing kspec itself, the installed kspec binary still has the old version. Use npm run dev -- agents generate instead so the dev build reads the bumped version from the local package.json

Phase 7: Create Tag and Release

After the version PR is merged:

# Pull the merged version bump
git checkout main && git pull

# Create annotated tag (v prefix is convention for npm/semver)
git tag -a "v$VERSION" -m "Release v$VERSION"

# Push tag to origin
git push origin "v$VERSION"

# Create GitHub release (gh uses current repo automatically)
gh release create "v$VERSION" \
  --title "v$VERSION" \
  --notes "$(cat <<'EOF'
Brief summary of this release.

### Features & Additions
- Feature description

### Bug Fixes
- Fix description

### Other Changes
- Change description

**Full Changelog**: compare/v{previous}...v{version}
EOF
)"

Tag naming: Always use v prefix (e.g., v0.1.2) for consistency with npm versioning conventions and GitHub release detection.

CI behavior:

• Triggers on release.published event (within 1-2 minutes)
• Runs tests and publishes to npm with provenance
• Monitor progress at the repo's Actions tab

Phase 8: Report Summary

After successful release:

## Release Complete

**Version:** v0.1.2
**Tag:** v0.1.2
**Commit:** abc1234

### Completed
- [x] Version PR created and merged
- [x] kspec-agents.md regenerated with new version
- [x] Tag created and pushed
- [x] GitHub release created
- [ ] CI publishing to npm... (check Actions tab)

**Release:** {repo}/releases/tag/v0.1.2
**CI Status:** {repo}/actions

Release Notes Format

Generate friendly, user-facing release notes (not raw commit dumps):

Brief high-level summary of what this release brings (1-2 sentences).

### Features & Additions
- Feature description in plain language
- Another feature

### Bug Fixes
- Fixed issue with X when Y happened
- Resolved problem where Z

### Performance
- Improved speed of X operation

### Other Changes
- Updated internal handling of Y
- Refactored Z for maintainability

**Full Changelog**: {repo}/compare/v0.1.1...v0.1.2

Writing guidelines:

• Write in past tense ("Fixed", "Added", "Improved")
• Focus on user impact, not implementation details
• Group related changes together
• Omit test-only and CI-only changes
• Use repo-relative URLs (GitHub auto-links them)

Error Handling

Rollback Procedure

If something goes wrong after partial release:

If tag was pushed but release failed:

# Delete remote tag
git push origin --delete v$VERSION
# Delete local tag
git tag -d v$VERSION
# Fix issue and retry

If release was created but CI publish failed:

# Option 1: Delete and retry
gh release delete v$VERSION --yes
git push origin --delete v$VERSION
git tag -d v$VERSION
# Fix issue and retry from Phase 6

# Option 2: Recover the existing published release through Actions
# Prerequisite: v$VERSION already names a published, non-draft GitHub release.
# In Actions > "Publish to npm" > "Run workflow", set:
#   release-tag: v$VERSION
#   dry-run: true        # default; reruns every gate without publishing
# Review the dry-run result first. To actually recover npm publication, rerun
# with the same release-tag and explicitly set dry-run: false.
#
# Both runs fail closed unless the remote tag still resolves to the immutable
# release commit selected by preflight. Never move or recreate the tag during
# recovery; a moved tag requires a new version-first release instead.

If version PR was merged but you need to abort:

# Revert the version bump
git revert HEAD
git push origin main
# The tag was never created, so nothing else to clean up

Examples

Standard patch release

User: $release patch
Agent: [Validates state]
Agent: [Creates version bump PR, waits for CI, merges]
Agent: [Creates v0.1.2 tag, pushes, creates GH release]

Release v0.1.2 created successfully.
- Version PR: #122 (merged)
- Tag: v0.1.2
- Release: {repo}/releases/tag/v0.1.2
- CI publishing to npm...

Auto-detect version

User: $release
Agent: [Analyzes 5 commits: 2 feat, 3 fix]
Detected: feat commits present -> minor bump (0.1.1 -> 0.2.0)
[Proceeds with release]

Preview only

User: $release --dry-run
Agent: [Shows full preview, makes NO changes]

Pre-release

User: $release minor --prerelease alpha
Agent: [Creates v0.2.0-alpha.0]

Explicit version

User: $release 1.0.0
Agent: [Creates v1.0.0 - useful for major milestones]

Maintaining release notes

The RELEASE_NOTES.md file at the repository root is the single source of truth for kspec release notes. It is human-authored, reviewed by humans, and shipped in the published npm package so kspec release-notes and kspec upgrade can print it directly. There is no generator — edit the file by hand as part of the normal change flow.

Where the file lives

• Path: RELEASE_NOTES.md at the repository root (the same directory as package.json).
• Packaged: listed in package.json#files so the published tarball includes it. The CLI resolves it relative to its own install location.

File layout

• A short top-of-file preamble explains the file.
• Each release is a level-2 heading (## vX.Y.Z) with most-recent first.
• An optional ## Unreleased heading collects changes staged for the next release. It lives above the top versioned section. Promote it to a versioned heading as part of the release workflow (see below).

Required per-version subsections

Every versioned section must contain the following level-3 subsections, in this order. Use the exact headings below — the CLI and release tests rely on them:

1. ### New or changed configuration — name every new config key and describe what it controls. If there are none, write a single line - No new configuration keys.
2. ### Breaking changes — call out behavior changes that require consumer action. If there are none, write - None.

Optional additional subsections (use the ones that apply): ### Features & Additions, ### Bug Fixes, ### Performance, ### Documentation, ### CI, ### Other Changes. Match the tone and writing guidelines in Release Notes Format above.

Adding an entry

During normal work, edit the ## Unreleased section to append bullet points describing the change. Put each item in the right subsection (new config under ### New or changed configuration, breaking changes under ### Breaking changes, everything else under the appropriate optional subsection). If a required subsection isn't present yet, add it.

For cross-version aggregation, keep the most recent entries near the top of each subsection. Don't worry about chronological ordering within a section.

Promoting Unreleased at release time

When starting a release:

1. Rename the ## Unreleased heading to ## vX.Y.Z with the version number being released.
2. Make sure both required subsections are present and non-empty (write - None. / - No new configuration keys. if there's nothing to say).
3. Add a fresh empty ## Unreleased section at the top for the next release cycle. Leaving it off is fine, but having a placeholder makes the next change's diff smaller.

Pre-release check

Before running the rest of the release workflow (Phase 5 onwards), verify the notes for the version being released are present and non-empty. The exact check is:

VERSION="0.1.2"  # the version you are about to release
awk -v v="$VERSION" '
  $0 ~ "^## v?" v "([^0-9.]|$)" { in_section = 1; body = ""; next }
  /^## / && in_section { exit }
  in_section { body = body $0 "\n" }
  END {
    gsub(/[[:space:]]/, "", body)
    if (!in_section) { print "error: no section for v" v " in RELEASE_NOTES.md"; exit 1 }
    if (body == "") { print "error: section for v" v " is empty"; exit 1 }
  }
' RELEASE_NOTES.md

If the command exits non-zero, stop and author the missing notes before continuing. The release notes must be written and reviewed before the version bump PR is created — not as a follow-up commit — so the tagged commit and published tarball carry the notes users will read when they upgrade.

Key Principles

• Version bump first: PR before tag ensures package.json matches release
• Validation first: Check all constraints before any changes
• Dry-run is safe: Preview makes zero changes
• Friendly release notes: Write for users, not developers
• Branch protection compatible: All changes via PR
• CI handles publishing: Skill creates release, CI publishes to npm
• kspec integration: Complete tasks before release, reference them in commits
• Release notes in the file: Every released version has a non-empty entry in RELEASE_NOTES.md — verified by the pre-release check above

Troubleshooting

npm Trusted Publishers OIDC Failures

If npm publish fails with "Access token expired or revoked" + 404:

Root cause: Older npm versions (10.8.x bundled with Node 18) have bugs with OIDC authentication for trusted publishers.

Fix: Ensure the publish workflow installs npm@latest:

- name: Install latest npm
  run: npm install -g npm@latest && npm --version

npm 11.x+ has the necessary fixes.

PR Merge Blocked

If the version bump PR can't merge:

1. Check CI status - tests must pass
2. Check for merge conflicts - rebase if needed
3. Check branch protection rules - ensure you have merge permissions

Tag Already Exists

If you need to re-release the same version:

# Delete existing tag (local and remote)
git tag -d v0.1.2
git push origin --delete v0.1.2

# Delete GitHub release if it exists
gh release delete v0.1.2 --yes

# Now retry the release

Related Skills

• $pr - Create pull requests (used internally by this skill)
• $audit - Pre-release codebase review
• $kspec-task-work - Task lifecycle and completion tracking
• $kspec-help - Command lookup and workflow help