/new

name: new
description: Use when user asks to create a release, cut a release, or publish a version. Auto-detects GitHub vs GitLab vs Gitea, calculates semantic version, generates release notes from PRs/MRs or commits, shows preview for confirmation before publishing.
allowed-tools: Bash, AskUserQuestion

Release Workflow

Creates GitHub, GitLab, or Gitea releases with auto-versioning and release notes generation.

Activation Triggers

• "create release", "cut release", "new release"
• "publish version", "bump version", "new version"
• "tag and release"

Scripts

Helper scripts in skill's `scripts/` directory (use `${CLAUDE_PLUGIN_ROOT}` for path resolution):

• `detect-platform.sh` - outputs `github`, `gitlab`, or `gitea`
• `calc-version.sh <type>` - outputs new version (e.g., `v1.2.3`)
• `get-notes.sh <platform>` - outputs release notes (PRs/MRs or commits)

Every helper exits non-zero and prints the reason on stderr. If any of Steps 2, 5 or 6 fails, report that text to the user and **abort the workflow** - do not continue with an empty value. `get-notes.sh` in particular fails when the forge CLI is missing, unauthenticated or rate-limited; continuing there publishes a release whose notes list none of its PRs.

On Gitea, `get-notes.sh` collects no PRs and returns commit-derived notes with a warning on stderr, because `tea pr list` exposes neither a merged flag nor a merge timestamp. That warning is not a failure - show it to the user with the preview in Step 8 and carry on.

Workflow

Step 1: Ask Release Type

Use AskUserQuestion tool to get release type:

{
  "questions": [{
    "question": "What type of release is this?",
    "header": "Version",
    "options": [
      {"label": "Hotfix", "description": "Bug fixes (1.2.3 → 1.2.4)"},
      {"label": "Minor", "description": "New features (1.2.3 → 1.3.0)"},
      {"label": "Major", "description": "Breaking changes (1.2.3 → 2.0.0)"}
    ],
    "multiSelect": false
  }]
}

Step 2: Detect Platform

platform=$(bash ${CLAUDE_PLUGIN_ROOT}/skills/new/scripts/detect-platform.sh)

Step 3: Validate Prerequisites

# working tree must be clean
if [ -n "$(git status --porcelain)" ]; then
    echo "error: uncommitted changes - commit or stash first"
fi

# sync with remote (--tags ensures all remote tags are fetched)
git fetch origin --tags

Step 4: Get Current Version

last_tag=$(git describe --tags --abbrev=0 --match "v*" 2>/dev/null || echo "none")

Step 5: Calculate New Version

new_version=$(bash ${CLAUDE_PLUGIN_ROOT}/skills/new/scripts/calc-version.sh <release_type>)

Verify tag doesn't already exist:

if git rev-parse "$new_version" &>/dev/null; then
    echo "error: tag $new_version already exists"
fi

Step 6: Generate Release Notes

notes=$(bash ${CLAUDE_PLUGIN_ROOT}/skills/new/scripts/get-notes.sh "$platform")

Script logic: 1. Collects PRs/MRs merged after last tag (with author) 2. Collects commits since last tag (with hash) 3. Categorizes by conventional commit prefix (feat/fix/refactor/etc.) 4. Groups into: New Features, Improvements, Bug Fixes, Other 5. Strips prefix from description for cleaner output

**Post-processing (Claude must do this before presenting):**

• Deduplicate entries with same description (PRs and their commits often duplicate)
• Prefer PR entries over commit entries when duplicated (PR has #number and @author)
• Compare descriptions after stripping conventional prefix

Output format:

**New Features**
- add user authentication #45 @username
- implement caching d41d3ad

**Improvements**
- refactor auth module abc1234
- update dependencies #47 @contributor

**Bug Fixes**
- resolve login timeout #46 @username
- handle nil pointer def5678

Step 7: Check and Update CHANGELOG

# detect actual changelog filename (case-sensitive filesystem!)
changelog=""
for f in CHANGELOG.md changelog.md CHANGELOG; do
    [ -f "$f" ] && changelog="$f" && break
done

If changelog exists: 1. **CRITICAL**: Use the exact detected filename (`$changelog`) for all operations - do not hardcode "CHANGELOG.md" 2. Read the file to understand its format (Keep a Changelog, simple list, etc.) 3. Add new version section at the top (after any header/intro) 4. Use the generated release notes 5. Match the existing format and style 6. Commit the changelog update using the detected filename:

git add "$changelog"
git commit -m "docs: update changelog for $new_version"

Common formats to detect:

• **Keep a Changelog**: Has `## [Unreleased]` section, versions as `## [X.Y.Z] - YYYY-MM-DD`
• **Simple list**: Just version headers like `## X.Y.Z` or `# X.Y.Z`
• **Date-based**: Versions with dates in various formats

Step 8: Preview and Confirm

Show the release preview to user:

=== Release Preview ===
Platform: GitHub/GitLab
Current version: v1.2.3
New version: v1.3.0
Title: Version 1.3.0
CHANGELOG: <detected filename> will be updated (or "none found")

Release Notes:
--------------
**New Features**
- add user authentication #45 @username

**Improvements**
- refactor auth module abc1234

**Bug Fixes**
- resolve login timeout #46 @contributor
--------------

Use AskUserQuestion tool to confirm:

{
  "questions": [{
    "question": "Proceed with creating this release?",
    "header": "Release",
    "options": [
      {"label": "Yes, publish", "description": "Create tag and publish release"},
      {"label": "Cancel", "description": "Abort release"}
    ],
    "multiSelect": false
  }]
}

**Wait for user confirmation before creating release.**

Step 9: Create Release

Only after user confirms:

Create an annotated tag locally and push it before calling the forge. Forge release commands create lightweight tags when the tag is absent; a lightweight tag has no release time of its own, so the next release would use the target commit's older committer date as its PR cutoff and re-list already