tomevault-io Release
Create semantic versioned releases from any branch or worktree.
Quick Start
# Preview release (no changes)
bun ~/.claude/skills/release/scripts/analyze.ts
# Execute release
bun ~/.claude/skills/release/scripts/release.ts
# Dry run
bun ~/.claude/skills/release/scripts/release.ts --dry-run
Command Options
| Option | Effect |
|---|---|
| no args | Analyze, confirm, release origin/main |
| --dry-run | Preview only, no changes |
| --version vX.Y.Z | Override suggested version |
| --no-changelog | Skip CHANGELOG.md, notes in GitHub release only |
| --current-branch | Release HEAD of current branch, for hotfix branches |
| --prerelease alpha | Create pre-release, e.g. v1.0.0-alpha.1 |
| --skip-ci | Skip CI status check |
Worktree-Aware Workflow
The skill releases origin/main regardless of your current branch:
You're in: ~/conductor/workspaces/.claude/casablanca (worktree)
Current branch: feat/my-feature
Release target: origin/main ✓
How it works:
- Creates ephemeral worktree at
~/.worktrees/<repo>/release-<tag> - Commits changelog, tags, pushes to origin/main
- Cleans up worktree after release
This approach is predictable and never modifies your current working directory. Use --current-branch to release from current directory instead (for hotfix branches).
Workflow
1. Analyze
Run the analyze script (read-only, safe anytime):
bun ~/.claude/skills/release/scripts/analyze.ts
Shows:
- Current context (branch, worktree status)
- Target branch (origin/main)
- Commits since last tag
- Suggested version
- Generated changelog
- CI status
2. Review and Confirm
Check the suggested version and changelog preview. Adjust with:
--version vX.Y.Zto override version--prerelease alphafor alpha/beta/rc
3. Execute
bun ~/.claude/skills/release/scripts/release.ts
The script:
- Checks CI status (fail if broken, unless
--skip-ci) - Finds or creates release worktree
- Updates CHANGELOG.md (unless
--no-changelog) - Commits:
release: vX.Y.Z - Creates and pushes tag
- Creates GitHub release
- Cleans up ephemeral worktree
Version Bumping
| Change Type | Bump | Example |
|---|---|---|
| Breaking changes | Major | 1.2.3 → 2.0.0 |
| feat commits | Minor | 1.2.3 → 1.3.0 |
| fix, chore, etc. | Patch | 1.2.3 → 1.2.4 |
Pre-1.0: Breaking → minor, feat → minor, fix → patch.
Pre-releases: --prerelease alpha → v1.0.0-alpha.1, v1.0.0-alpha.2, etc.
Changelog Format
Uses Keep a Changelog:
## [1.3.0] - 2026-01-24
### Added
- feature: New capability
### Fixed
- bug: Resolved issue
### Changed
- refactor: Improved performance
Error Recovery
See references/troubleshooting.md for:
- Partial failure recovery (commit/push/release)
- Undoing a release (delete tag, retract)
- Worktree cleanup
- CI issues
Quick fixes:
# Push failed after commit
git push origin main --tags
# GitHub release failed after push
gh release create vX.Y.Z --title "vX.Y.Z" --generate-notes
# Delete bad release
gh release delete vX.Y.Z --yes --cleanup-tag
Converted and distributed by TomeVault — claim your Tome and manage your conversions.