Release Skill for Free Planning Poker

Create releases with AI-enhanced GitHub release notes. Uses release-it with @release-it/conventional-changelog for automated versioning and changelog generation.

Arguments

• •version - Version to release (patch/minor/major) or explicit version (e.g., 8.4.0). Optional.

Prerequisites

• •Must be on master branch
• •Working directory must be clean (no uncommitted changes)
• •gh CLI authenticated (gh auth login)

Configuration

Release configuration is in .release-it.json:

• •Conventional commits preset with grouped sections
• •Auto-generates CHANGELOG.md
• •Creates GitHub release automatically
• •npm override for conventional-changelog-conventionalcommits@^8.0.0 in package.json

Workflow

Phase 1: Pre-flight Checks

# Verify branch and clean state
git branch --show-current  # Must be master
git status --porcelain     # Must be empty
git describe --tags --abbrev=0  # Show last tag

Phase 2: Analyze Commits

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

Categorize by type for AI summary:

• •feat: → Features
• •fix: → Bug Fixes
• •refactor: → Refactoring
• •docs: → Documentation
• •ci: → CI/CD
• •chore: → Maintenance (hidden in changelog)

Phase 3: Generate AI Summary

Create a summary with:

1. •

   Release Title (theme, ~5 words)

   • •Example: "Observability & Developer Experience"
2. •

   Summary Paragraph (2-3 sentences)

   • •What this release brings
   • •Key improvements
3. •

   Key Highlights (5-7 bullet points)

   • •Major features
   • •Focus on impact

Phase 4: Execute Release

# Get GitHub token and run release
GITHUB_TOKEN=$(gh auth token) npm run release -- <version> --ci

Where <version> is:

• •Specific version: 8.4.0
• •Bump type: patch, minor, major
• •Auto (based on commits): omit version argument

This will:

1. •Update version in package.json
2. •Generate changelog entries in CHANGELOG.md
3. •Create git commit and tag
4. •Push to GitHub
5. •Create GitHub release with changelog

Phase 5: Enhance GitHub Release

After release completes, prepend AI summary:

# Get current notes
gh release view <version> --json body -q .body > /tmp/release-notes-original.md

# Create enhanced notes (AI summary + original)
# Write to /tmp/release-notes-enhanced.md

# Update release
gh release edit <version> \
  --title "Release <version> - <Theme Title>" \
  --notes-file /tmp/release-notes-enhanced.md

Phase 6: Verify

# Open release in browser
gh release view <version> --web

Example AI Summary Format

## <Theme Title>

<2-3 sentence summary of what this release brings>

### Key Highlights
- **Feature 1** description
- **Feature 2** description
- **Improvement** description
- ...

---

## [<version>](...) (<date>)
<auto-generated changelog below>

Troubleshooting

"Working dir must be clean"

git status  # Check what's dirty
git checkout -- <files>  # Restore if needed

"whatBump is not a function"

The .release-it.json config and overrides in package.json should prevent this. If it occurs:

1. •Verify .release-it.json exists with proper preset object format
2. •Check overrides in package.json has conventional-changelog-conventionalcommits@^8.0.0
3. •Run rm -rf node_modules package-lock.json && npm install

GitHub token issues

gh auth login  # Re-authenticate if needed
gh auth token  # Verify token works

Notes

• •CHANGELOG.md is auto-managed by release-it (don't edit manually)
• •AI summary only appears in GitHub release notes (not CHANGELOG.md)
• •Version follows semantic versioning based on conventional commits
• •The --ci flag enables non-interactive mode