Release Skill

Create a new version release using prefixed tag-based workflow for monorepo plugins.

When to Use

• User explicitly asks to "release" or "create a release"
• User asks to "publish" or "ship" a new version
• User asks to "tag" a version
• User says "let's release v0.2.0" or similar

Plugin Identification

This is a monorepo with multiple plugins. First, identify which plugin to release:

plugins/stash-downloader/package.json

downloader-vX.Y.Z

downloader-v0.5.2

plugins/stash-browser/package.json

browser-vX.Y.Z

browser-v0.1.0

If the user doesn't specify, ask which plugin to release. If both changed, release each separately.

Pre-Release Checklist

Before creating a release, verify:

1. On dev branch:

   git branch --show-current

2. No uncommitted changes:

   git status

3. Type-check passes:

   npm run type-check

4. Lint passes:

   npm run lint

5. Tests pass:

   npm test -- --run

6. Build succeeds:

   npm run build

Release Process (Tag-Based)

Step 1: Determine Version Bump

1. Check current version: Read the plugin's

   package.json

   version field
2. Review commits since last tag:

   git log $(git describe --tags --match "downloader-v*" --abbrev=0)..HEAD --oneline

   (or

   browser-v*

   for Browser)
3. Determine bump type:

feat!:

BREAKING CHANGE

feat:

fix:

docs:

chore:

Step 2: Merge dev to main and Release

For Stash Downloader:

# From dev branch, checkout main and merge
git checkout main
git merge dev

# Update version in plugin's package.json
cd plugins/stash-downloader
npm version patch  # or minor/major

# Commit the version bump
git add .
git commit -m "$(cat <<'COMMIT'
🔖 chore: release downloader-vX.Y.Z

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
COMMIT
)"

# Create and push tag (with downloader- prefix!)
git tag downloader-vX.Y.Z
git push origin main --tags

For Stash Browser:

# From dev branch, checkout main and merge
git checkout main
git merge dev

# Update version in plugin's package.json
cd plugins/stash-browser
npm version patch  # or minor/major

# Commit the version bump
git add .
git commit -m "$(cat <<'COMMIT'
🔖 chore: release browser-vX.Y.Z

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
COMMIT
)"

# Create and push tag (with browser- prefix!)
git tag browser-vX.Y.Z
git push origin main --tags

Step 3: Wait and Sync Dev

⚠️ CRITICAL: Do NOT push to dev immediately!

GitHub Pages uses a concurrency group. If you push to dev before the stable workflow finishes, the stable deploy gets CANCELLED.

# 1. Wait for workflow to complete
#    Check: https://github.com/Codename-11/Stash-Downloader/actions

# 2. AFTER workflow completes, sync dev with main
git checkout dev
git merge main
git push origin dev

What Happens After Tag Push

GitHub Actions automatically:

1. Runs CI (type-check, lint, tests)
2. Builds the plugin
3. Updates GitHub Pages (Stash plugin index)
4. Generates AI release notes (if GOOGLE_API_KEY configured)
5. Creates GitHub Release with:
   • Auto-generated changelog
   • Installation instructions
   • ZIP file attached

If Release Was Cancelled

If you accidentally pushed to dev too early and cancelled the stable deploy:

# Re-push the tag to trigger the workflow again
git push origin --delete downloader-vX.Y.Z  # or browser-vX.Y.Z
git push origin downloader-vX.Y.Z

PR-Based Release (Optional)

For significant releases where you want Claude review before merging:

# Create release branch from dev
git checkout -b release/downloader-vX.Y.Z dev

# Update version in plugin's package.json, commit
cd plugins/stash-downloader
npm version patch
git add .
git commit -m "🔖 chore: release downloader-vX.Y.Z"

# Push and create PR to main
git push -u origin release/downloader-vX.Y.Z
gh pr create --base main --title "🔖 Release downloader-vX.Y.Z" --body "Release notes..."

# After PR merge, checkout main and tag
git checkout main
git pull origin main
git tag downloader-vX.Y.Z
git push origin downloader-vX.Y.Z

Important Notes

• Tag format MUST include plugin prefix:

  downloader-vX.Y.Z

  or

  browser-vX.Y.Z

• Version in the plugin's

  package.json

  must match tag version (without prefix)
• Always start from dev branch - never commit directly to main
• Wait for workflow to complete before syncing dev
• Push to

  main

  without a tag triggers NOTHING
• Verify release succeeded in GitHub Actions after pushing tag
• Release plugins separately - if both plugins changed, create separate tags