From 6bfb9d2e7f621459f04d9f0c12326c7db53ba6dc Mon Sep 17 00:00:00 2001
From: gerchowl <lars.gerchow@phys.ethz.ch>
Date: Mon, 10 Nov 2025 18:45:53 +0000
Subject: [PATCH 1/4] feat(workflow): add automated tag-and-release command for
 #20

Create new /tag-and-release Cursor command to automate complete release
workflow with comprehensive validation.

Features:
- Validates prerequisites (main branch, clean working directory)
- Uses make version to extract current version from pyproject.toml
- Validates version is consecutive to existing git tags (no gaps)
- Validates CHANGELOG.md follows Keep a Changelog format
  - Version header: ## [X.Y.Z] - YYYY-MM-DD
  - Required categories present
  - At least one entry
- Extracts release notes from CHANGELOG.md
- Creates annotated git tag with release notes
- Pushes tag to remote
- Creates GitHub release with formatted notes and comparison link
- Comprehensive error messages for all validation failures

Integration:
- Works with existing version management system
- Uses make targets (make version)
- Enforces Keep a Changelog standard
- Enforces Semantic Versioning (consecutive versions only)

Related to #20
---
 .cursor/commands/create-pr.md       | 151 ++++++
 .cursor/commands/tag-and-release.md | 700 ++++++++++++++++++++++++++++
 .cursor/plans/issue-20.md           |  82 ++++
 3 files changed, 933 insertions(+)
 create mode 100644 .cursor/commands/tag-and-release.md
 create mode 100644 .cursor/plans/issue-20.md

diff --git a/.cursor/commands/create-pr.md b/.cursor/commands/create-pr.md
index abb5913..c0d30cf 100644
--- a/.cursor/commands/create-pr.md
+++ b/.cursor/commands/create-pr.md
@@ -8,6 +8,7 @@ For complete documentation on pull request guidelines, templates, and review pro
 
 - **[Pull Request Guidelines](./../pr-template.md)**
 - **[Git Workflow](./../git-workflow.md)**
+- **[Version Management](./../../docs/VERSION_MANAGEMENT.md)**
 
 ## Workflow
 
@@ -18,6 +19,156 @@ For complete documentation on pull request guidelines, templates, and review pro
 
 When creating a pull request, follow these steps:
 
+### 0. Intelligent Version Bump Analysis (Automatic)
+
+**The command automatically analyzes changes and suggests version bumps:**
+
+```bash
+# 1. Get current version
+CURRENT_VERSION=$(make version | grep -oP '\d+\.\d+\.\d+')
+
+# 2. Get latest tag
+LATEST_TAG=$(git tag -l | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)
+
+# 3. Analyze commits in branch
+BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')
+COMMITS=$(git log --oneline origin/$BASE_BRANCH..HEAD)
+
+# 4. Determine bump type based on Semantic Versioning
+HAS_BREAKING=false
+HAS_FEAT=false
+HAS_FIX=false
+
+# Check for breaking changes
+if echo "$COMMITS" | grep -qE "BREAKING CHANGE|!:"; then
+  HAS_BREAKING=true
+fi
+
+# Check for features
+if echo "$COMMITS" | grep -qE "^[a-f0-9]+ feat"; then
+  HAS_FEAT=true
+fi
+
+# Check for fixes
+if echo "$COMMITS" | grep -qE "^[a-f0-9]+ fix"; then
+  HAS_FIX=true
+fi
+
+# Suggest bump type (Semantic Versioning)
+if [ "$HAS_BREAKING" = "true" ]; then
+  SUGGESTED_BUMP="major"
+  EXPLANATION="Breaking changes detected (MAJOR bump required)"
+elif [ "$HAS_FEAT" = "true" ]; then
+  SUGGESTED_BUMP="minor"
+  EXPLANATION="New features detected (MINOR bump recommended)"
+elif [ "$HAS_FIX" = "true" ]; then
+  SUGGESTED_BUMP="patch"
+  EXPLANATION="Bug fixes only (PATCH bump recommended)"
+else
+  SUGGESTED_BUMP="patch"
+  EXPLANATION="Other changes (PATCH bump default)"
+fi
+
+# Calculate suggested version
+IFS='.' read -r -a PARTS <<< "$CURRENT_VERSION"
+case "$SUGGESTED_BUMP" in
+  major)
+    SUGGESTED_VERSION="$((PARTS[0] + 1)).0.0"
+    ;;
+  minor)
+    SUGGESTED_VERSION="${PARTS[0]}.$((PARTS[1] + 1)).0"
+    ;;
+  patch)
+    SUGGESTED_VERSION="${PARTS[0]}.${PARTS[1]}.$((PARTS[2] + 1))"
+    ;;
+esac
+
+# Present to user
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "📊 Version Bump Analysis"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "Current version: $CURRENT_VERSION"
+echo "Latest tag: $LATEST_TAG"
+echo ""
+echo "Analysis:"
+BREAKING_STATUS=$([ "$HAS_BREAKING" = "true" ] && echo "✓ Found" || echo "✗ None")
+echo "  Breaking changes: $BREAKING_STATUS"
+echo "  New features: $([ "$HAS_FEAT" = "true" ] && echo "✓ Found" || echo "✗ None")"
+echo "  Bug fixes: $([ "$HAS_FIX" = "true" ] && echo "✓ Found" || echo "✗ None")"
+echo ""
+echo "📈 Suggested: $SUGGESTED_BUMP bump"
+echo "   $CURRENT_VERSION → $SUGGESTED_VERSION"
+echo ""
+echo "Explanation: $EXPLANATION"
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "Apply version bump?"
+echo "  1) patch - $CURRENT_VERSION → ${PARTS[0]}.${PARTS[1]}.$((PARTS[2] + 1))"
+echo "  2) minor - $CURRENT_VERSION → ${PARTS[0]}.$((PARTS[1] + 1)).0"
+echo "  3) major - $CURRENT_VERSION → $((PARTS[0] + 1)).0.0"
+echo "  4) skip - No version bump"
+echo ""
+read -p "Choice [1-4, default=$SUGGESTED_BUMP]: " CHOICE
+
+case "$CHOICE" in
+  1|patch)
+    echo "Bumping patch version..."
+    make bump-patch
+    ;;
+  2|minor)
+    echo "Bumping minor version..."
+    make bump-minor
+    ;;
+  3|major)
+    echo "Bumping major version..."
+    make bump-major
+    ;;
+  4|skip|"")
+    echo "Skipping version bump"
+    ;;
+  *)
+    echo "Applying suggested: $SUGGESTED_BUMP"
+    make bump-$SUGGESTED_BUMP
+    ;;
+esac
+
+# Prompt to update CHANGELOG
+if [ "$CHOICE" != "skip" ] && [ "$CHOICE" != "4" ]; then
+  NEW_VERSION=$(make version | grep -oP '\d+\.\d+\.\d+')
+  echo ""
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "📝 CHANGELOG Update Required"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo ""
+  echo "Version bumped to: $NEW_VERSION"
+  echo ""
+  echo "Please update CHANGELOG.md with actual changes:"
+  echo "  1. Open CHANGELOG.md"
+  echo "  2. Find: ## [$NEW_VERSION] - $(date +%Y-%m-%d)"
+  echo "  3. Replace placeholder with actual changes"
+  echo "  4. Use categories: Added, Changed, Fixed, etc."
+  echo ""
+  read -p "Press Enter when CHANGELOG is updated..."
+
+  # Commit version bump
+  echo ""
+  echo "Committing version bump..."
+  git add pyproject.toml CHANGELOG.md
+  git commit -m "chore(release): bump version to $NEW_VERSION
+
+Updated version and CHANGELOG for upcoming release."
+fi
+```
+
+**Semantic Versioning Summary:**
+- **MAJOR (X.0.0)**: Breaking changes (incompatible API changes)
+- **MINOR (0.X.0)**: New features (backward compatible)
+- **PATCH (0.0.X)**: Bug fixes (backward compatible)
+
+**Reference:** [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+
 1. **Ensure your branch follows naming conventions:**
    - `feature/`, `fix/`, `docs/`, `refactor/`, `test/`, `chore/`, or `release/`
    - Example: `feature/add-user-authentication`
diff --git a/.cursor/commands/tag-and-release.md b/.cursor/commands/tag-and-release.md
new file mode 100644
index 0000000..45fdc65
--- /dev/null
+++ b/.cursor/commands/tag-and-release.md
@@ -0,0 +1,700 @@
+# Tag and Release Command
+
+This command automates the complete git tag creation and GitHub release workflow.
+
+## Usage
+
+```bash
+/tag-and-release
+```
+
+**Purpose:** Create a git tag and GitHub release for the current version in pyproject.toml.
+
+## Prerequisites
+
+Before running this command, ensure:
+
+- [ ] On **main** branch
+- [ ] **Clean working directory** (no uncommitted changes)
+- [ ] **Version bumped** in pyproject.toml (via `make bump-patch/minor/major`)
+- [ ] **CHANGELOG.md updated** with release notes for current version
+- [ ] All changes **committed** to main
+
+## Workflow
+
+The command performs these steps automatically:
+
+### 1. Validate Prerequisites
+
+**Branch Check:**
+
+```bash
+# Must be on main
+BRANCH=$(git branch --show-current)
+if [ "$BRANCH" != "main" ]; then
+  echo "❌ Error: Must be on main branch (currently on: $BRANCH)"
+  exit 1
+fi
+```
+
+**Working Directory Check:**
+
+```bash
+# Must be clean
+if ! git diff-index --quiet HEAD --; then
+  echo "❌ Error: Working directory has uncommitted changes"
+  echo "Commit or stash changes before creating release"
+  exit 1
+fi
+```
+
+### 2. Get and Validate Version
+
+**Extract version from pyproject.toml:**
+
+```bash
+# Use make version to get current version
+VERSION=$(make version | grep -oP '\d+\.\d+\.\d+')
+echo "Current version: $VERSION"
+```
+
+**Validate version format:**
+
+```bash
+# Must match X.Y.Z format (Semantic Versioning)
+if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+  echo "❌ Error: Invalid version format: $VERSION"
+  echo "Expected: X.Y.Z (e.g., 0.3.3)"
+  exit 1
+fi
+```
+
+**Check version is consecutive to existing tags:**
+
+```bash
+# Get latest tag
+LATEST_TAG=$(git tag -l | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)
+
+if [ -z "$LATEST_TAG" ]; then
+  echo "ℹ️  No previous tags found - this will be the first release"
+else
+  echo "Latest tag: $LATEST_TAG"
+  echo "New version: $VERSION"
+
+  # Version must be greater than latest tag
+  LATEST_SEMVER=$(echo "$LATEST_TAG" | sed 's/v//')
+  if [ "$VERSION" == "$LATEST_SEMVER" ]; then
+    echo "❌ Error: Version $VERSION already exists as a tag"
+    echo "Bump version using: make bump-patch/minor/major"
+    exit 1
+  fi
+
+  # Check if version is consecutive (no gaps)
+  # Parse versions
+  IFS='.' read -r -a LATEST_PARTS <<< "$LATEST_SEMVER"
+  IFS='.' read -r -a NEW_PARTS <<< "$VERSION"
+
+  LATEST_MAJOR=${LATEST_PARTS[0]}
+  LATEST_MINOR=${LATEST_PARTS[1]}
+  LATEST_PATCH=${LATEST_PARTS[2]}
+
+  NEW_MAJOR=${NEW_PARTS[0]}
+  NEW_MINOR=${NEW_PARTS[1]}
+  NEW_PATCH=${NEW_PARTS[2]}
+
+  # Validate consecutive bump
+  VALID=false
+  # Major bump: X.0.0
+  if [ "$NEW_MAJOR" -eq $((LATEST_MAJOR + 1)) ] && \
+     [ "$NEW_MINOR" -eq 0 ] && [ "$NEW_PATCH" -eq 0 ]; then
+    VALID=true
+  # Minor bump: 0.X.0
+  elif [ "$NEW_MAJOR" -eq "$LATEST_MAJOR" ] && \
+       [ "$NEW_MINOR" -eq $((LATEST_MINOR + 1)) ] && \
+       [ "$NEW_PATCH" -eq 0 ]; then
+    VALID=true
+  # Patch bump: 0.0.X
+  elif [ "$NEW_MAJOR" -eq "$LATEST_MAJOR" ] && \
+       [ "$NEW_MINOR" -eq "$LATEST_MINOR" ] && \
+       [ "$NEW_PATCH" -eq $((LATEST_PATCH + 1)) ]; then
+    VALID=true
+  fi
+
+  if [ "$VALID" = "false" ]; then
+    echo "❌ Error: Version $VERSION is not consecutive to $LATEST_SEMVER"
+    echo ""
+    echo "Valid next versions:"
+    echo "  - Patch: $LATEST_MAJOR.$LATEST_MINOR.$((LATEST_PATCH + 1))"
+    echo "  - Minor: $LATEST_MAJOR.$((LATEST_MINOR + 1)).0"
+    echo "  - Major: $((LATEST_MAJOR + 1)).0.0"
+    exit 1
+  fi
+fi
+```
+
+### 3. Validate CHANGELOG.md Format
+
+**Check version entry exists:**
+
+```bash
+# CHANGELOG must have entry for current version
+if ! grep -q "^## \[$VERSION\]" CHANGELOG.md; then
+  echo "❌ Error: CHANGELOG.md missing entry for version $VERSION"
+  echo ""
+  echo "Expected format:"
+  echo "## [$VERSION] - YYYY-MM-DD"
+  echo ""
+  echo "Update CHANGELOG.md before creating release"
+  exit 1
+fi
+```
+
+**Validate Keep a Changelog format:**
+
+```bash
+# Extract the version entry
+ENTRY=$(sed -n "/^## \[$VERSION\]/,/^## \[/p" CHANGELOG.md | head -n -1)
+
+# Check for date
+DATE_PATTERN="^## \[$VERSION\] - [0-9]\{4\}-[0-9]\{2\}-[0-9]\{2\}"
+if ! echo "$ENTRY" | grep -q "$DATE_PATTERN"; then
+  echo "❌ Error: Version entry missing or incorrectly formatted date"
+  echo "Expected: ## [$VERSION] - YYYY-MM-DD"
+  exit 1
+fi
+
+# Check for at least one category (Added, Changed, Fixed, etc.)
+CATEGORIES="Added|Changed|Deprecated|Removed|Fixed|Security"
+if ! echo "$ENTRY" | grep -qE "^### ($CATEGORIES)"; then
+  echo "❌ Error: CHANGELOG entry must have at least one category"
+  echo "Categories: Added, Changed, Deprecated, Removed, Fixed, Security"
+  exit 1
+fi
+
+echo "✅ CHANGELOG.md format valid"
+```
+
+### 4. Extract Release Notes
+
+**Parse CHANGELOG for current version:**
+
+```bash
+# Extract release notes for this version
+RELEASE_NOTES=$(sed -n "/^## \[$VERSION\]/,/^## \[/p" CHANGELOG.md | head -n -1)
+
+# Extract title from first line after version header
+# Look for main feature/category
+RELEASE_TITLE="Release $VERSION"
+
+# Try to determine feature name from CHANGELOG
+# Look for the first major feature in Added or Changed sections
+FEATURE_NAME=$(echo "$RELEASE_NOTES" | grep -A1 "^### Added" | \
+  tail -1 | sed 's/^- \*\*//' | sed 's/\*\*.*//' | head -c 40)
+if [ -n "$FEATURE_NAME" ]; then
+  RELEASE_TITLE="Release $VERSION - $FEATURE_NAME"
+fi
+```
+
+### 5. Create Git Tag
+
+**Create annotated tag:**
+
+```bash
+# Create tag with message from CHANGELOG
+TAG_MESSAGE="Release $VERSION
+
+$RELEASE_NOTES"
+
+git tag -a "$VERSION" -m "$TAG_MESSAGE"
+echo "✅ Created tag: $VERSION"
+```
+
+### 6. Push Tag
+
+**Push to remote:**
+
+```bash
+git push --tags
+echo "✅ Pushed tag: $VERSION"
+```
+
+### 7. Create GitHub Release
+
+**Format release notes:**
+
+```bash
+# Create release with formatted notes
+# Add comparison link
+PREV_TAG=$(git tag -l | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | \
+  sort -V | tail -2 | head -1)
+COMPARISON_LINK=""
+if [ -n "$PREV_TAG" ]; then
+  REPO=$(gh repo view --json nameWithOwner --jq .nameWithOwner)
+  COMPARISON_URL="https://github.com/$REPO/compare/$PREV_TAG...$VERSION"
+  COMPARISON_LINK="\n\n---\n\n**Full Changelog**: $COMPARISON_URL"
+fi
+
+# Create release
+gh release create "$VERSION" \
+  --title "$RELEASE_TITLE" \
+  --notes "$RELEASE_NOTES$COMPARISON_LINK"
+
+echo "✅ Created GitHub release: $VERSION"
+```
+
+## Complete Example
+
+Here's what the command does step-by-step:
+
+```bash
+# 1. Validate prerequisites
+echo "Validating prerequisites..."
+# - Check on main branch
+# - Check clean working directory
+
+# 2. Get version
+echo "Getting version from pyproject.toml..."
+VERSION=$(make version | grep -oP '\d+\.\d+\.\d+')
+echo "Current version: $VERSION"
+
+# 3. Validate version continuity
+echo "Validating version continuity..."
+LATEST_TAG=$(git tag -l | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)
+echo "Latest tag: $LATEST_TAG"
+# - Check version is consecutive (no gaps)
+
+# 4. Validate CHANGELOG
+echo "Validating CHANGELOG.md..."
+# - Check entry exists for $VERSION
+# - Validate format: ## [X.Y.Z] - YYYY-MM-DD
+# - Check has categories (Added/Changed/Fixed/etc.)
+
+# 5. Extract release notes
+echo "Extracting release notes from CHANGELOG..."
+RELEASE_NOTES=$(sed -n "/^## \[$VERSION\]/,/^## \[/p" CHANGELOG.md | head -n -1)
+
+# 6. Create tag
+echo "Creating git tag..."
+git tag -a "$VERSION" -m "Release $VERSION
+
+$RELEASE_NOTES"
+
+# 7. Push tag
+echo "Pushing tag to remote..."
+git push --tags
+
+# 8. Create GitHub release
+echo "Creating GitHub release..."
+gh release create "$VERSION" \
+  --title "Release $VERSION - Feature Name" \
+  --notes "$RELEASE_NOTES
+
+---
+
+**Full Changelog**: https://github.com/ORG/REPO/compare/$PREV_TAG...$VERSION"
+
+echo "✅ Release complete: $VERSION"
+```
+
+## Error Handling
+
+### Not on Main Branch
+
+```text
+❌ Error: Must be on main branch (currently on: feature/xyz)
+
+Switch to main:
+  git checkout main
+```
+
+### Uncommitted Changes
+
+```text
+❌ Error: Working directory has uncommitted changes
+
+Uncommitted files:
+  - file1.py
+  - file2.md
+
+Action required:
+  1. Commit changes: git add . && git commit -m "..."
+  2. Or stash: git stash save "wip"
+
+Then run /tag-and-release again
+```
+
+### Version Already Tagged
+
+```text
+❌ Error: Version 0.3.3 already exists as a tag
+
+Current version in pyproject.toml: 0.3.3
+Existing tags: 0.3.0, 0.3.1, 0.3.2, 0.3.3
+
+Action required:
+  Bump version using:
+    make bump-patch  # → 0.3.4
+    make bump-minor  # → 0.4.0
+    make bump-major  # → 1.0.0
+```
+
+### Non-Consecutive Version
+
+```text
+❌ Error: Version 0.3.5 is not consecutive to 0.3.2
+
+Latest tag: 0.3.2
+New version: 0.3.5 (skips 0.3.3 and 0.3.4)
+
+Valid next versions:
+  - Patch: 0.3.3
+  - Minor: 0.4.0
+  - Major: 1.0.0
+
+Action required:
+  Update pyproject.toml to a consecutive version
+```
+
+### Missing CHANGELOG Entry
+
+```text
+❌ Error: CHANGELOG.md missing entry for version 0.3.3
+
+Expected format:
+## [0.3.3] - 2025-11-10
+
+### Added
+- New features
+
+### Changed
+- Changes to functionality
+
+### Fixed
+- Bug fixes
+
+Action required:
+  1. Add CHANGELOG entry for version 0.3.3
+  2. Follow Keep a Changelog format
+  3. Run /tag-and-release again
+
+Reference: https://keepachangelog.com/en/1.0.0/
+```
+
+### Invalid CHANGELOG Format
+
+```text
+❌ Error: CHANGELOG entry for 0.3.3 is incorrectly formatted
+
+Found:
+## [0.3.3]
+
+Expected:
+## [0.3.3] - YYYY-MM-DD
+
+### Added
+- Feature 1
+
+### Changed
+- Change 1
+
+Action required:
+  1. Add date to version header
+  2. Add at least one category section
+  3. Add entries under categories
+
+Reference: https://keepachangelog.com/en/1.0.0/
+```
+
+## Keep a Changelog Format Summary
+
+CHANGELOG.md must follow this structure:
+
+```markdown
+## [X.Y.Z] - YYYY-MM-DD
+
+### Added
+- New features for users
+
+### Changed
+- Changes to existing functionality
+
+### Deprecated
+- Soon-to-be removed features
+
+### Removed
+- Removed features
+
+### Fixed
+- Bug fixes
+
+### Security
+- Security vulnerability fixes
+```
+
+**Requirements:**
+- Version header: `## [X.Y.Z] - YYYY-MM-DD`
+- Most recent version at top
+- At least one category section
+- Entries are bullet points
+- Focus on user-facing changes
+
+**Reference:** [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+
+## Semantic Versioning Summary
+
+Versions follow **MAJOR.MINOR.PATCH** format (e.g., 1.4.2):
+
+- **MAJOR (X.0.0)**: Incompatible API changes (breaking changes)
+- **MINOR (0.X.0)**: New features (backward compatible)
+- **PATCH (0.0.X)**: Bug fixes (backward compatible)
+
+**Rules:**
+- Never reuse version numbers
+- Must be consecutive (no skipping versions)
+- Initial development starts at 0.1.0
+- Public API starts at 1.0.0
+
+**Reference:** [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+
+## Complete Release Workflow
+
+### Typical Release Process
+
+```bash
+# 1. Work on feature branch
+git checkout -b feature/new-feature
+# ... make changes ...
+git commit -m "feat(scope): add new feature"
+
+# 2. Create PR with version bump (see create-pr.md)
+/create-pr  # Will suggest version bump
+
+# 3. PR gets reviewed and merged to main
+# ... review, approve, merge ...
+
+# 4. Switch to main and pull
+git checkout main
+git pull origin main
+
+# 5. Create tag and release
+/tag-and-release
+
+# Done! Tag and release created automatically
+```
+
+### Quick Release (Already on Main)
+
+If you're already on main with version bumped and CHANGELOG updated:
+
+```bash
+# Just run the command
+/tag-and-release
+```
+
+It will:
+- ✅ Validate everything
+- ✅ Create git tag
+- ✅ Push tag to remote
+- ✅ Create GitHub release with CHANGELOG notes
+
+## Integration with Version Management
+
+This command integrates with the version management system:
+
+```bash
+# 1. Bump version
+make bump-patch  # or bump-minor, bump-major
+
+# 2. Update CHANGELOG.md
+vim CHANGELOG.md
+# Add actual changes for the version
+
+# 3. Commit version bump
+git add pyproject.toml CHANGELOG.md
+git commit -m "chore(release): bump version to X.Y.Z"
+
+# 4. Push to main
+git push origin main
+
+# 5. Create tag and release
+/tag-and-release
+```
+
+## Success Output
+
+```text
+🚀 Creating Tag and Release for v0.3.3
+
+✅ Prerequisites validated
+   - On main branch
+   - Working directory clean
+
+✅ Version validated: 0.3.3
+   - Latest tag: 0.3.2
+   - Consecutive bump: ✓ (patch)
+
+✅ CHANGELOG.md validated
+   - Entry exists: ## [0.3.3] - 2025-11-10
+   - Format correct: ✓
+   - Categories present: Added, Changed
+
+✅ Release notes extracted
+
+✅ Git tag created: 0.3.3
+
+✅ Tag pushed to remote
+
+✅ GitHub release created
+   - Title: Release 0.3.3 - Version Management System
+   - URL: https://github.com/ORG/REPO/releases/tag/0.3.3
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🎉 Release 0.3.3 Complete!
+
+View release: https://github.com/ORG/REPO/releases/tag/0.3.3
+```
+
+## Troubleshooting
+
+### Issue: Tag Creation Fails
+
+**Error:**
+
+```bash
+fatal: tag '0.3.3' already exists
+```
+
+**Solution:**
+
+The tag already exists locally or remotely.
+
+```bash
+# Check existing tags
+git tag -l | grep 0.3.3
+
+# If you need to recreate (CAREFUL):
+git tag -d 0.3.3              # Delete local
+git push origin :refs/tags/0.3.3  # Delete remote (CAREFUL!)
+
+# Then run /tag-and-release again
+```
+
+### Issue: Push Fails
+
+**Error:**
+
+```bash
+error: failed to push some refs
+```
+
+**Solution:**
+
+Network issue or permissions problem.
+
+```bash
+# Verify authentication
+gh auth status
+
+# Verify remote
+git remote -v
+
+# Try pushing again
+git push --tags
+```
+
+### Issue: CHANGELOG Format Invalid
+
+**Error:**
+
+```text
+❌ Error: CHANGELOG entry must have at least one category
+```
+
+**Solution:**
+
+Add at least one category section to your CHANGELOG entry:
+
+```markdown
+## [0.3.3] - 2025-11-10
+
+### Added
+- New feature X
+
+### Fixed
+- Bug in Y
+```
+
+### Issue: GitHub Release Creation Fails
+
+**Error:**
+
+```bash
+HTTP 422: Validation Failed
+```
+
+**Solution:**
+
+Tag might already have a release. Check:
+
+```bash
+# List releases
+gh release list | grep 0.3.3
+
+# If release exists, delete and recreate
+gh release delete 0.3.3 --yes
+
+# Then run /tag-and-release again
+```
+
+## Related Commands
+
+- **[git-commit.md](./git-commit.md)**: Commit changes before release
+- **[create-pr.md](./create-pr.md)**: Create PR with version bumping
+- **[Version Management](./../../docs/VERSION_MANAGEMENT.md)**: Version management system docs
+
+## Quick Reference
+
+### Command Execution
+
+```bash
+/tag-and-release
+```
+
+### Prerequisites Checklist
+
+Before running, ensure:
+- [ ] On main branch: `git branch --show-current`
+- [ ] Clean working directory: `git status`
+- [ ] Version bumped in pyproject.toml
+- [ ] CHANGELOG.md updated with:
+  - [ ] Version header: `## [X.Y.Z] - YYYY-MM-DD`
+  - [ ] At least one category
+  - [ ] Actual release notes
+- [ ] Changes committed and pushed to main
+
+### What It Does
+
+1. ✅ Validates prerequisites (branch, working directory, version)
+2. ✅ Checks version is consecutive to latest tag
+3. ✅ Validates CHANGELOG.md format
+4. ✅ Extracts release notes
+5. ✅ Creates annotated git tag
+6. ✅ Pushes tag to remote
+7. ✅ Creates GitHub release with CHANGELOG notes
+
+### Version Management Tools
+
+```bash
+# Check current version
+make version
+
+# Bump versions
+make bump-patch  # 0.3.3 → 0.3.4
+make bump-minor  # 0.3.3 → 0.4.0
+make bump-major  # 0.3.3 → 1.0.0
+```
+
+---
+
+**For version management details, see [docs/VERSION_MANAGEMENT.md](./../../docs/VERSION_MANAGEMENT.md)**
diff --git a/.cursor/plans/issue-20.md b/.cursor/plans/issue-20.md
new file mode 100644
index 0000000..058ce4d
--- /dev/null
+++ b/.cursor/plans/issue-20.md
@@ -0,0 +1,82 @@
+# YOLO Implementation Plan - Issue #20
+
+## Autonomous Analysis
+
+**Issue:** Add Cursor commands for automated tag-and-release and PR version bumping
+**Type:** Feature
+**Complexity:** Medium
+**Estimated Changes:** 2 files (1 new, 1 update)
+
+## Chosen Approach
+
+**Decision:** Create standalone `/tag-and-release` command and enhance existing `/create-pr` command
+
+**Rationale:**
+
+- Follows existing command pattern and structure
+- Single responsibility: tag-and-release handles releases, create-pr handles PRs
+- Integrates seamlessly with version management system
+- Reuses existing tools (make version, bump scripts)
+- Validates against standards (Keep a Changelog, Semantic Versioning)
+
+## Implementation Breakdown
+
+### Phase 1: Create `/tag-and-release` Command
+
+- [ ] Create `.cursor/commands/tag-and-release.md`
+- [ ] Implement validation workflow
+- [ ] Add CHANGELOG.md parser
+- [ ] Add version continuity checker
+- [ ] Add git tag creation logic
+- [ ] Add GitHub release creation logic
+
+### Phase 2: Enhance `/create-pr` Command
+
+- [ ] Read existing create-pr.md
+- [ ] Add version analysis section
+- [ ] Add commit analysis for semver suggestion
+- [ ] Add version bump workflow
+- [ ] Integrate with make targets
+
+### Phase 3: Documentation
+
+- [ ] Complete command documentation with examples
+- [ ] Add troubleshooting sections
+- [ ] Update relevant docs if needed
+
+### Phase 4: Validation
+
+- [ ] Test version extraction
+- [ ] Test CHANGELOG validation
+- [ ] Test tag continuity checking
+- [ ] Verify commands follow existing patterns
+
+## Quality Gates
+
+All must pass:
+- ✅ Commands follow existing .cursor/commands pattern
+- ✅ Clear error messages for validation failures
+- ✅ Comprehensive examples
+- ✅ Integration with version management system
+- ✅ No hardcoded values
+- ✅ Follows Keep a Changelog and Semantic Versioning standards
+
+## Commit Strategy
+
+Planned commits:
+1. `feat(workflow): add tag-and-release command for #20`
+2. `feat(workflow): enhance create-pr with version bumping for #20`
+3. `docs(changelog): update for #20`
+
+## Acceptance Criteria
+
+All from issue:
+- [x] /tag-and-release validates main branch & clean state
+- [x] Uses make version for current version
+- [x] Confirms version consecutive to existing tags
+- [x] Validates CHANGELOG.md format
+- [x] Creates tag and GitHub release
+- [x] /create-pr analyzes git history
+- [x] Suggests semver-compliant version bump
+- [x] Executes make bump-* commands
+- [x] Includes version bump in PR workflow

From f97062b1b0fd9948c5b7f9790fac228d9851436b Mon Sep 17 00:00:00 2001
From: gerchowl <lars.gerchow@phys.ethz.ch>
Date: Mon, 10 Nov 2025 18:46:43 +0000
Subject: [PATCH 2/4] docs(changelog): add entry for release workflow commands
 for #20

Add CHANGELOG entry for new /tag-and-release command and enhanced
/create-pr with intelligent version bumping.

Documents automated tag/release workflow and semantic versioning
integration for upcoming release.

Related to #20
---
 CHANGELOG.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ee6bef0..8072aad 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,32 @@ All notable changes to this template will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- **Automated Release Workflow Commands**
+  - `/tag-and-release`: Complete tag and release automation
+    - Validates prerequisites (main branch, clean working directory)
+    - Checks version consecutiveness against git tags
+    - Validates CHANGELOG.md format (Keep a Changelog standard)
+    - Creates annotated git tag with release notes
+    - Pushes tag to remote
+    - Creates GitHub release with comparison link
+    - Comprehensive error messages
+  - `/create-pr` enhancement: Intelligent version bump analysis
+    - Analyzes commit history for breaking changes/features/fixes
+    - Suggests Semantic Versioning-compliant version bump
+    - Executes `make bump-patch/minor/major`
+    - Prompts for CHANGELOG.md update
+    - Commits version bump automatically
+
+### Changed
+
+- **Cursor Commands**
+  - Enhanced `/create-pr` with version management integration
+  - Added version bump workflow before PR creation
+
 ## [0.3.3] - 2025-11-10
 
 ### Added

From 676a13533b54aef17909d3c2537f7fd7731d7945 Mon Sep 17 00:00:00 2001
From: gerchowl <lars.gerchow@phys.ethz.ch>
Date: Mon, 10 Nov 2025 18:50:54 +0000
Subject: [PATCH 3/4] feat(workflow): enhance create-pr with AI-powered
 analysis for #20

Transform create-pr into intelligent assistant that analyzes changes
and automatically generates CHANGELOG entries.

AI Analysis Features:
- Commit message analysis (mechanical baseline)
- Code diff analysis (intelligent understanding)
  - Identifies new public APIs
  - Detects breaking changes in signatures
  - Recognizes refactoring vs new features
- File impact analysis
- Contextual understanding of project structure

AI CHANGELOG Generation:
- Automatically categorizes changes (Added/Changed/Fixed/etc.)
- Generates user-focused summaries
- Follows Keep a Changelog format exactly
- Groups related changes logically
- Can be refined in PR review

Semantic Versioning Intelligence:
- MAJOR: Breaking changes detected (API changes, removals)
- MINOR: New features added (commands, public APIs)
- PATCH: Fixes, docs, internal refactoring only
- Special cases: docs-only, internal tools

Workflow:
1. AI analyzes commits + diff + files
2. Presents intelligent recommendation with rationale
3. User confirms or adjusts
4. Executes make bump-* command
5. AI generates CHANGELOG entry automatically
6. Commits version bump + CHANGELOG
7. Creates PR

Benefits:
- No manual CHANGELOG writing
- Intelligent version suggestions
- Faster PR creation
- Consistent CHANGELOG quality
- Everything reviewable in PR

Related to #20
---
 .cursor/commands/create-pr.md | 320 +++++++++++++++++++++++-----------
 1 file changed, 216 insertions(+), 104 deletions(-)

diff --git a/.cursor/commands/create-pr.md b/.cursor/commands/create-pr.md
index c0d30cf..c549f3c 100644
--- a/.cursor/commands/create-pr.md
+++ b/.cursor/commands/create-pr.md
@@ -19,153 +19,265 @@ For complete documentation on pull request guidelines, templates, and review pro
 
 When creating a pull request, follow these steps:
 
-### 0. Intelligent Version Bump Analysis (Automatic)
+### 0. Intelligent Version Bump Analysis (AI-Powered)
 
-**The command automatically analyzes changes and suggests version bumps:**
+**The AI analyzes your changes and intelligently suggests version bumps:**
+
+#### Step 1: Gather Information
 
 ```bash
-# 1. Get current version
+# Get current version
 CURRENT_VERSION=$(make version | grep -oP '\d+\.\d+\.\d+')
 
-# 2. Get latest tag
+# Get latest tag
 LATEST_TAG=$(git tag -l | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)
 
-# 3. Analyze commits in branch
+# Get base branch
 BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')
+
+# Get commits in this branch
 COMMITS=$(git log --oneline origin/$BASE_BRANCH..HEAD)
 
-# 4. Determine bump type based on Semantic Versioning
-HAS_BREAKING=false
-HAS_FEAT=false
-HAS_FIX=false
+# Get full diff
+DIFF=$(git diff origin/$BASE_BRANCH...HEAD)
 
-# Check for breaking changes
-if echo "$COMMITS" | grep -qE "BREAKING CHANGE|!:"; then
-  HAS_BREAKING=true
-fi
+# Get files changed
+FILES_CHANGED=$(git diff --name-only origin/$BASE_BRANCH...HEAD)
+```
 
-# Check for features
-if echo "$COMMITS" | grep -qE "^[a-f0-9]+ feat"; then
-  HAS_FEAT=true
-fi
+#### Step 2: AI Analysis (Intelligent)
 
-# Check for fixes
-if echo "$COMMITS" | grep -qE "^[a-f0-9]+ fix"; then
-  HAS_FIX=true
-fi
+**The AI examines:**
 
-# Suggest bump type (Semantic Versioning)
-if [ "$HAS_BREAKING" = "true" ]; then
-  SUGGESTED_BUMP="major"
-  EXPLANATION="Breaking changes detected (MAJOR bump required)"
-elif [ "$HAS_FEAT" = "true" ]; then
-  SUGGESTED_BUMP="minor"
-  EXPLANATION="New features detected (MINOR bump recommended)"
-elif [ "$HAS_FIX" = "true" ]; then
-  SUGGESTED_BUMP="patch"
-  EXPLANATION="Bug fixes only (PATCH bump recommended)"
-else
-  SUGGESTED_BUMP="patch"
-  EXPLANATION="Other changes (PATCH bump default)"
-fi
+1. **Commit Messages** (mechanical check):
+   - Breaking changes: `BREAKING CHANGE` or `!:` in commits
+   - Features: `feat:` commits
+   - Fixes: `fix:` commits
 
-# Calculate suggested version
-IFS='.' read -r -a PARTS <<< "$CURRENT_VERSION"
-case "$SUGGESTED_BUMP" in
-  major)
-    SUGGESTED_VERSION="$((PARTS[0] + 1)).0.0"
-    ;;
-  minor)
-    SUGGESTED_VERSION="${PARTS[0]}.$((PARTS[1] + 1)).0"
-    ;;
-  patch)
-    SUGGESTED_VERSION="${PARTS[0]}.${PARTS[1]}.$((PARTS[2] + 1))"
-    ;;
-esac
+2. **Code Changes** (intelligent analysis):
+   - API signature changes (breaking)
+   - New public functions/classes (feature)
+   - Internal refactoring (patch)
+   - Documentation only (no bump needed)
+   - Configuration changes
+   - Test additions
+
+3. **File Impact** (scope analysis):
+   - Core library changes vs. examples
+   - Public API vs. internal implementation
+   - Documentation vs. code
 
-# Present to user
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-echo "📊 Version Bump Analysis"
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-echo ""
-echo "Current version: $CURRENT_VERSION"
-echo "Latest tag: $LATEST_TAG"
-echo ""
-echo "Analysis:"
-BREAKING_STATUS=$([ "$HAS_BREAKING" = "true" ] && echo "✓ Found" || echo "✗ None")
-echo "  Breaking changes: $BREAKING_STATUS"
-echo "  New features: $([ "$HAS_FEAT" = "true" ] && echo "✓ Found" || echo "✗ None")"
-echo "  Bug fixes: $([ "$HAS_FIX" = "true" ] && echo "✓ Found" || echo "✗ None")"
-echo ""
-echo "📈 Suggested: $SUGGESTED_BUMP bump"
-echo "   $CURRENT_VERSION → $SUGGESTED_VERSION"
-echo ""
-echo "Explanation: $EXPLANATION"
-echo ""
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-echo ""
-echo "Apply version bump?"
-echo "  1) patch - $CURRENT_VERSION → ${PARTS[0]}.${PARTS[1]}.$((PARTS[2] + 1))"
-echo "  2) minor - $CURRENT_VERSION → ${PARTS[0]}.$((PARTS[1] + 1)).0"
-echo "  3) major - $CURRENT_VERSION → $((PARTS[0] + 1)).0.0"
-echo "  4) skip - No version bump"
-echo ""
-read -p "Choice [1-4, default=$SUGGESTED_BUMP]: " CHOICE
+**AI presents analysis:**
 
+```text
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🤖 AI Version Bump Analysis
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Current version: 0.3.3
+Latest tag: 0.3.3
+
+📊 Mechanical Analysis (Commit Messages):
+  Breaking changes: ✗ None
+  New features (feat:): ✓ Found (2 commits)
+  Bug fixes (fix:): ✗ None
+
+🧠 AI Analysis (Code Changes):
+  - Added new public commands: /tag-and-release
+  - Enhanced existing command: /create-pr
+  - New documentation: VERSION_MANAGEMENT.md
+  - No API breaking changes
+  - All changes backward compatible
+
+📁 Impact:
+  - Files changed: 4
+  - Core changes: ✓ (new workflow commands)
+  - Public API: ✓ (new user-facing features)
+  - Breaking changes: ✗
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📈 Recommendation: MINOR bump (0.3.3 → 0.4.0)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Rationale:
+- New user-facing features added (workflow commands)
+- Backward compatible (no breaking changes)
+- More than just bug fixes
+- Follows Semantic Versioning: MINOR for new features
+
+Semantic Versioning Rules:
+  MAJOR (X.0.0) - Breaking changes (incompatible API)
+  MINOR (0.X.0) - New features (backward compatible) ← Suggested
+  PATCH (0.0.X) - Bug fixes only
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Apply version bump?
+  1) patch  - 0.3.3 → 0.3.4 (bug fixes only)
+  2) minor  - 0.3.3 → 0.4.0 (new features) ← AI Recommendation
+  3) major  - 0.3.3 → 1.0.0 (breaking changes)
+  4) skip   - No version bump
+
+Choice [1-4, default=2]:
+```
+
+#### Step 3: Apply Version Bump
+
+```bash
+# User selects or accepts AI recommendation
 case "$CHOICE" in
   1|patch)
-    echo "Bumping patch version..."
-    make bump-patch
+    BUMP_TYPE="patch"
     ;;
-  2|minor)
-    echo "Bumping minor version..."
-    make bump-minor
+  2|minor|"")  # Default to AI suggestion
+    BUMP_TYPE="minor"
     ;;
   3|major)
-    echo "Bumping major version..."
-    make bump-major
+    BUMP_TYPE="major"
     ;;
-  4|skip|"")
+  4|skip)
     echo "Skipping version bump"
-    ;;
-  *)
-    echo "Applying suggested: $SUGGESTED_BUMP"
-    make bump-$SUGGESTED_BUMP
+    BUMP_TYPE=""
     ;;
 esac
 
-# Prompt to update CHANGELOG
-if [ "$CHOICE" != "skip" ] && [ "$CHOICE" != "4" ]; then
+if [ -n "$BUMP_TYPE" ]; then
+  echo "Applying $BUMP_TYPE bump..."
+  make bump-$BUMP_TYPE
+fi
+```
+
+#### Step 4: AI-Generated CHANGELOG Update
+
+**AI automatically generates CHANGELOG entry based on analysis:**
+
+```bash
+if [ -n "$BUMP_TYPE" ]; then
   NEW_VERSION=$(make version | grep -oP '\d+\.\d+\.\d+')
+
   echo ""
   echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-  echo "📝 CHANGELOG Update Required"
+  echo "📝 Generating CHANGELOG Entry"
   echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
   echo ""
-  echo "Version bumped to: $NEW_VERSION"
+  echo "AI is analyzing changes and generating CHANGELOG entry..."
   echo ""
-  echo "Please update CHANGELOG.md with actual changes:"
-  echo "  1. Open CHANGELOG.md"
-  echo "  2. Find: ## [$NEW_VERSION] - $(date +%Y-%m-%d)"
-  echo "  3. Replace placeholder with actual changes"
-  echo "  4. Use categories: Added, Changed, Fixed, etc."
+
+  # AI analyzes the diff and generates appropriate CHANGELOG entry
+  # Based on:
+  # - Files changed
+  # - Code changes (new features, fixes, refactoring)
+  # - Commit messages
+  # - Scope of changes
+
+  # AI generates entry following Keep a Changelog format
+  # Categories used based on actual changes:
+  # - Added: New features, new files, new capabilities
+  # - Changed: Modifications to existing functionality
+  # - Deprecated: Features marked for removal
+  # - Removed: Deleted features
+  # - Fixed: Bug fixes
+  # - Security: Security-related changes
+
+  # Example AI-generated entry:
+  # ## [0.4.0] - 2025-11-10
+  #
+  # ### Added
+  #
+  # - **Automated Release Workflow**
+  #   - New `/tag-and-release` command for complete release automation
+  #   - Validates CHANGELOG format and version continuity
+  #   - Creates git tags and GitHub releases
+  #
+  # ### Changed
+  #
+  # - **PR Creation Workflow**
+  #   - Enhanced `/create-pr` with AI-powered version bump analysis
+  #   - Automatic CHANGELOG generation
+
+  echo "Generated CHANGELOG entry for version $NEW_VERSION"
+  echo ""
+  echo "Preview of generated entry:"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+  # Show generated entry to user
+  sed -n "/^## \[$NEW_VERSION\]/,/^## \[/p" CHANGELOG.md | head -n -1
+
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
   echo ""
-  read -p "Press Enter when CHANGELOG is updated..."
+  echo "✨ AI has generated the CHANGELOG entry based on your changes"
+  echo "📝 You can refine it in the PR if needed"
+  echo ""
+  read -p "Press Enter to commit version bump and CHANGELOG..."
 
-  # Commit version bump
+  # Commit version bump with AI-generated CHANGELOG
   echo ""
   echo "Committing version bump..."
   git add pyproject.toml CHANGELOG.md
   git commit -m "chore(release): bump version to $NEW_VERSION
 
-Updated version and CHANGELOG for upcoming release."
+AI-generated CHANGELOG entry based on branch changes.
+Version bump: $CURRENT_VERSION → $NEW_VERSION ($BUMP_TYPE)
+
+Can be refined during PR review."
+
+  echo "✅ Version bumped and CHANGELOG updated"
 fi
 ```
 
-**Semantic Versioning Summary:**
-- **MAJOR (X.0.0)**: Breaking changes (incompatible API changes)
-- **MINOR (0.X.0)**: New features (backward compatible)
-- **PATCH (0.0.X)**: Bug fixes (backward compatible)
+**How AI Analyzes Changes:**
+
+1. **Commit Message Analysis** (baseline):
+   - Scans for `BREAKING CHANGE`, `feat:`, `fix:`, etc.
+   - Identifies conventional commit types
+
+2. **Code Diff Analysis** (intelligent):
+   - Examines actual code changes
+   - Identifies new public APIs (functions, classes, commands)
+   - Detects signature changes (breaking)
+   - Recognizes refactoring vs. new features
+   - Distinguishes user-facing vs. internal changes
+
+3. **File Impact Analysis**:
+   - New files added (often features)
+   - Modified files (fixes or enhancements)
+   - Documentation-only changes
+   - Test additions
+
+4. **Contextual Understanding**:
+   - Relates changes to project structure
+   - Understands user-facing impact
+   - Considers backward compatibility
+
+**AI CHANGELOG Generation:**
+
+The AI automatically generates appropriate CHANGELOG entries:
+
+- **Categorizes changes** into Added/Changed/Fixed/etc.
+- **Summarizes features** from code analysis
+- **Groups related changes** logically
+- **Uses clear, user-focused language**
+- **Follows Keep a Changelog format** exactly
+
+**You can refine in PR** - Everything gets reviewed anyway!
+
+**Semantic Versioning AI Logic:**
+
+```text
+IF breaking changes detected (API changes, removed features):
+  → MAJOR bump (X.0.0)
+
+ELSE IF new features added (new public APIs, new commands, new capabilities):
+  → MINOR bump (0.X.0)
+
+ELSE IF only fixes, refactoring, or docs:
+  → PATCH bump (0.0.X)
+
+SPECIAL CASES:
+- Documentation only → Skip bump
+- Internal refactoring only → PATCH bump
+- New internal tools (not user-facing) → PATCH or MINOR
+```
 
 **Reference:** [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 

From 6fed4ad2ebb25413bd0437dd19a9b15210d0927f Mon Sep 17 00:00:00 2001
From: gerchowl <lars.gerchow@phys.ethz.ch>
Date: Mon, 10 Nov 2025 19:05:42 +0000
Subject: [PATCH 4/4] refactor(workflow): make commands concise and
 auto-integrate for #20
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Streamline create-pr and tag-and-release commands for seamless workflow.

Changes:
- create-pr: More concise AI analysis presentation
- create-pr: Tags commits with [patch]/[minor]/[major] marker
- tag-and-release: Auto-reads bump type from commits
- tag-and-release: Automatically applies version bump before release
- CHANGELOG: Updated to reflect integrated workflow

Integrated Workflow:
1. /create-pr: AI suggests bump → tags commit with [bump-type]
2. PR review and merge to main
3. /tag-and-release: Reads [bump-type] → auto-bumps → creates release

Benefits:
- No manual version bumping after PR merge
- Seamless workflow automation
- Version bump decision happens during PR (reviewable)
- tag-and-release just executes the plan

Related to #20
---
 .cursor/commands/create-pr.md       | 296 ++++++----------------------
 .cursor/commands/tag-and-release.md |  50 ++++-
 CHANGELOG.md                        |  27 +--
 3 files changed, 123 insertions(+), 250 deletions(-)

diff --git a/.cursor/commands/create-pr.md b/.cursor/commands/create-pr.md
index c549f3c..0033d33 100644
--- a/.cursor/commands/create-pr.md
+++ b/.cursor/commands/create-pr.md
@@ -19,267 +19,89 @@ For complete documentation on pull request guidelines, templates, and review pro
 
 When creating a pull request, follow these steps:
 
-### 0. Intelligent Version Bump Analysis (AI-Powered)
+### 0. AI-Powered Version Bump & CHANGELOG (Automatic)
 
-**The AI analyzes your changes and intelligently suggests version bumps:**
-
-#### Step 1: Gather Information
+**AI analyzes your changes, suggests version bump, and generates CHANGELOG:**
 
 ```bash
-# Get current version
+# Gather data
 CURRENT_VERSION=$(make version | grep -oP '\d+\.\d+\.\d+')
-
-# Get latest tag
-LATEST_TAG=$(git tag -l | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)
-
-# Get base branch
-BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')
-
-# Get commits in this branch
-COMMITS=$(git log --oneline origin/$BASE_BRANCH..HEAD)
-
-# Get full diff
-DIFF=$(git diff origin/$BASE_BRANCH...HEAD)
-
-# Get files changed
-FILES_CHANGED=$(git diff --name-only origin/$BASE_BRANCH...HEAD)
-```
-
-#### Step 2: AI Analysis (Intelligent)
-
-**The AI examines:**
-
-1. **Commit Messages** (mechanical check):
-   - Breaking changes: `BREAKING CHANGE` or `!:` in commits
-   - Features: `feat:` commits
-   - Fixes: `fix:` commits
-
-2. **Code Changes** (intelligent analysis):
-   - API signature changes (breaking)
-   - New public functions/classes (feature)
-   - Internal refactoring (patch)
-   - Documentation only (no bump needed)
-   - Configuration changes
-   - Test additions
-
-3. **File Impact** (scope analysis):
-   - Core library changes vs. examples
-   - Public API vs. internal implementation
-   - Documentation vs. code
-
-**AI presents analysis:**
-
-```text
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🤖 AI Version Bump Analysis
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Current version: 0.3.3
-Latest tag: 0.3.3
-
-📊 Mechanical Analysis (Commit Messages):
-  Breaking changes: ✗ None
-  New features (feat:): ✓ Found (2 commits)
-  Bug fixes (fix:): ✗ None
-
-🧠 AI Analysis (Code Changes):
-  - Added new public commands: /tag-and-release
-  - Enhanced existing command: /create-pr
-  - New documentation: VERSION_MANAGEMENT.md
-  - No API breaking changes
-  - All changes backward compatible
-
-📁 Impact:
-  - Files changed: 4
-  - Core changes: ✓ (new workflow commands)
-  - Public API: ✓ (new user-facing features)
-  - Breaking changes: ✗
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-📈 Recommendation: MINOR bump (0.3.3 → 0.4.0)
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Rationale:
-- New user-facing features added (workflow commands)
-- Backward compatible (no breaking changes)
-- More than just bug fixes
-- Follows Semantic Versioning: MINOR for new features
-
-Semantic Versioning Rules:
-  MAJOR (X.0.0) - Breaking changes (incompatible API)
-  MINOR (0.X.0) - New features (backward compatible) ← Suggested
-  PATCH (0.0.X) - Bug fixes only
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Apply version bump?
-  1) patch  - 0.3.3 → 0.3.4 (bug fixes only)
-  2) minor  - 0.3.3 → 0.4.0 (new features) ← AI Recommendation
-  3) major  - 0.3.3 → 1.0.0 (breaking changes)
-  4) skip   - No version bump
-
-Choice [1-4, default=2]:
-```
-
-#### Step 3: Apply Version Bump
-
-```bash
-# User selects or accepts AI recommendation
-case "$CHOICE" in
-  1|patch)
-    BUMP_TYPE="patch"
-    ;;
-  2|minor|"")  # Default to AI suggestion
-    BUMP_TYPE="minor"
-    ;;
-  3|major)
-    BUMP_TYPE="major"
-    ;;
-  4|skip)
-    echo "Skipping version bump"
-    BUMP_TYPE=""
-    ;;
+COMMITS=$(git log --oneline origin/main..HEAD)
+FILES=$(git diff --name-only origin/main...HEAD)
+
+# AI Analysis: Check commits AND examine actual code changes
+# Mechanical: BREAKING CHANGE, feat:, fix: in commits
+# Intelligent: New APIs, signature changes, file impact, user-facing changes
+
+# AI presents recommendation
+echo "🤖 AI Analysis: Current $CURRENT_VERSION"
+echo ""
+echo "Changes detected:"
+echo "  - [AI summary of actual changes]"
+echo ""
+echo "📈 Recommended: MINOR bump → 0.4.0"
+echo "    Rationale: [AI explanation]"
+echo ""
+echo "Apply version bump?"
+echo "  1) patch  - Bug fixes only"
+echo "  2) minor  - New features ← AI suggests"
+echo "  3) major  - Breaking changes"
+echo "  4) skip"
+read -p "Choice [default=2]: " CHOICE
+
+# Apply bump
+case "${CHOICE:-2}" in
+  1) make bump-patch; BUMP_TYPE="patch" ;;
+  2) make bump-minor; BUMP_TYPE="minor" ;;
+  3) make bump-major; BUMP_TYPE="major" ;;
+  4) BUMP_TYPE="" ;;
 esac
 
+# AI generates CHANGELOG entry automatically
 if [ -n "$BUMP_TYPE" ]; then
-  echo "Applying $BUMP_TYPE bump..."
-  make bump-$BUMP_TYPE
-fi
-```
-
-#### Step 4: AI-Generated CHANGELOG Update
-
-**AI automatically generates CHANGELOG entry based on analysis:**
+  # AI analyzes diff and generates Keep a Changelog formatted entry
+  # Categorizes: Added/Changed/Fixed based on actual changes
+  # Uses clear, user-focused language
 
-```bash
-if [ -n "$BUMP_TYPE" ]; then
   NEW_VERSION=$(make version | grep -oP '\d+\.\d+\.\d+')
+  echo "✨ AI generated CHANGELOG for $NEW_VERSION"
+  echo "📝 Refinable in PR review"
 
-  echo ""
-  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-  echo "📝 Generating CHANGELOG Entry"
-  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-  echo ""
-  echo "AI is analyzing changes and generating CHANGELOG entry..."
-  echo ""
-
-  # AI analyzes the diff and generates appropriate CHANGELOG entry
-  # Based on:
-  # - Files changed
-  # - Code changes (new features, fixes, refactoring)
-  # - Commit messages
-  # - Scope of changes
-
-  # AI generates entry following Keep a Changelog format
-  # Categories used based on actual changes:
-  # - Added: New features, new files, new capabilities
-  # - Changed: Modifications to existing functionality
-  # - Deprecated: Features marked for removal
-  # - Removed: Deleted features
-  # - Fixed: Bug fixes
-  # - Security: Security-related changes
-
-  # Example AI-generated entry:
-  # ## [0.4.0] - 2025-11-10
-  #
-  # ### Added
-  #
-  # - **Automated Release Workflow**
-  #   - New `/tag-and-release` command for complete release automation
-  #   - Validates CHANGELOG format and version continuity
-  #   - Creates git tags and GitHub releases
-  #
-  # ### Changed
-  #
-  # - **PR Creation Workflow**
-  #   - Enhanced `/create-pr` with AI-powered version bump analysis
-  #   - Automatic CHANGELOG generation
-
-  echo "Generated CHANGELOG entry for version $NEW_VERSION"
-  echo ""
-  echo "Preview of generated entry:"
-  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-
-  # Show generated entry to user
-  sed -n "/^## \[$NEW_VERSION\]/,/^## \[/p" CHANGELOG.md | head -n -1
-
-  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-  echo ""
-  echo "✨ AI has generated the CHANGELOG entry based on your changes"
-  echo "📝 You can refine it in the PR if needed"
-  echo ""
-  read -p "Press Enter to commit version bump and CHANGELOG..."
-
-  # Commit version bump with AI-generated CHANGELOG
-  echo ""
-  echo "Committing version bump..."
+  # Commit with version bump type in message
   git add pyproject.toml CHANGELOG.md
-  git commit -m "chore(release): bump version to $NEW_VERSION
-
-AI-generated CHANGELOG entry based on branch changes.
-Version bump: $CURRENT_VERSION → $NEW_VERSION ($BUMP_TYPE)
-
-Can be refined during PR review."
+  git commit -m "chore(release): bump version to $NEW_VERSION [$BUMP_TYPE]
 
-  echo "✅ Version bumped and CHANGELOG updated"
+AI-generated CHANGELOG. Version: $CURRENT_VERSION → $NEW_VERSION"
 fi
 ```
 
-**How AI Analyzes Changes:**
+**AI Analysis Factors:**
 
-1. **Commit Message Analysis** (baseline):
-   - Scans for `BREAKING CHANGE`, `feat:`, `fix:`, etc.
-   - Identifies conventional commit types
+- **Commits:** `BREAKING CHANGE`, `feat:`, `fix:` patterns
+- **Code:** New APIs, signature changes, refactoring detection
+- **Files:** New vs. modified, public vs. internal
+- **Impact:** User-facing vs. internal changes
 
-2. **Code Diff Analysis** (intelligent):
-   - Examines actual code changes
-   - Identifies new public APIs (functions, classes, commands)
-   - Detects signature changes (breaking)
-   - Recognizes refactoring vs. new features
-   - Distinguishes user-facing vs. internal changes
+**Semantic Versioning:**
 
-3. **File Impact Analysis**:
-   - New files added (often features)
-   - Modified files (fixes or enhancements)
-   - Documentation-only changes
-   - Test additions
+- **MAJOR (X.0.0):** Breaking changes, API removals
+- **MINOR (0.X.0):** New features (backward compatible)
+- **PATCH (0.0.X):** Bug fixes, docs, internal refactoring
 
-4. **Contextual Understanding**:
-   - Relates changes to project structure
-   - Understands user-facing impact
-   - Considers backward compatibility
+**Bump Type in PR Title:**
 
-**AI CHANGELOG Generation:**
+The version bump type is included in the commit message with `[patch]`,
+`[minor]`, or `[major]` tag. This allows `/tag-and-release` to automatically
+determine the correct version bump when creating releases.
 
-The AI automatically generates appropriate CHANGELOG entries:
+**Example:**
 
-- **Categorizes changes** into Added/Changed/Fixed/etc.
-- **Summarizes features** from code analysis
-- **Groups related changes** logically
-- **Uses clear, user-focused language**
-- **Follows Keep a Changelog format** exactly
-
-**You can refine in PR** - Everything gets reviewed anyway!
-
-**Semantic Versioning AI Logic:**
-
-```text
-IF breaking changes detected (API changes, removed features):
-  → MAJOR bump (X.0.0)
-
-ELSE IF new features added (new public APIs, new commands, new capabilities):
-  → MINOR bump (0.X.0)
-
-ELSE IF only fixes, refactoring, or docs:
-  → PATCH bump (0.0.X)
-
-SPECIAL CASES:
-- Documentation only → Skip bump
-- Internal refactoring only → PATCH bump
-- New internal tools (not user-facing) → PATCH or MINOR
+```bash
+# Commit message includes bump type
+chore(release): bump version to 0.4.0 [minor]
 ```
 
-**Reference:** [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+Tag-and-release reads this to know it's a MINOR bump.
 
 1. **Ensure your branch follows naming conventions:**
    - `feature/`, `fix/`, `docs/`, `refactor/`, `test/`, `chore/`, or `release/`
diff --git a/.cursor/commands/tag-and-release.md b/.cursor/commands/tag-and-release.md
index 45fdc65..45d4677 100644
--- a/.cursor/commands/tag-and-release.md
+++ b/.cursor/commands/tag-and-release.md
@@ -24,7 +24,55 @@ Before running this command, ensure:
 
 The command performs these steps automatically:
 
-### 1. Validate Prerequisites
+### 1. Check for Version Bump Instruction (Optional)
+
+**Read bump type from recent commits:**
+
+```bash
+# Check if recent commits indicate a version bump
+# Look for [patch], [minor], or [major] in commit messages
+RECENT_COMMIT=$(git log -1 --pretty=%B)
+BUMP_TYPE=""
+
+if echo "$RECENT_COMMIT" | grep -q "\[patch\]"; then
+  BUMP_TYPE="patch"
+elif echo "$RECENT_COMMIT" | grep -q "\[minor\]"; then
+  BUMP_TYPE="minor"
+elif echo "$RECENT_COMMIT" | grep -q "\[major\]"; then
+  BUMP_TYPE="major"
+fi
+
+# If bump type found, apply it automatically
+if [ -n "$BUMP_TYPE" ]; then
+  CURRENT=$(make version | grep -oP '\d+\.\d+\.\d+')
+  echo "🔄 Auto-applying $BUMP_TYPE bump from commit instruction"
+  echo "   Current: $CURRENT"
+
+  make bump-$BUMP_TYPE
+
+  NEW=$(make version | grep -oP '\d+\.\d+\.\d+')
+  echo "   New: $NEW"
+  echo ""
+
+  # Commit the bump
+  git add pyproject.toml CHANGELOG.md
+  git commit -m "chore(release): apply $BUMP_TYPE bump to $NEW
+
+Auto-bumped based on PR merge commit instruction."
+
+  echo "✅ Version auto-bumped: $CURRENT → $NEW"
+fi
+```
+
+**How it works:**
+
+When `/create-pr` commits a version bump, it includes `[patch]`, `[minor]`,
+or `[major]` in the commit message. After PR merge, `/tag-and-release`
+reads this and automatically applies the bump before creating the release.
+
+This eliminates manual version bumping after merging PRs!
+
+### 2. Validate Prerequisites
 
 **Branch Check:**
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8072aad..80d5d80 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,25 +11,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Automated Release Workflow Commands**
   - `/tag-and-release`: Complete tag and release automation
-    - Validates prerequisites (main branch, clean working directory)
-    - Checks version consecutiveness against git tags
-    - Validates CHANGELOG.md format (Keep a Changelog standard)
+    - Auto-applies version bump from PR commit tags `[patch]`, `[minor]`, `[major]`
+    - Validates prerequisites (main branch, clean directory)
+    - Checks version consecutiveness (no gaps allowed)
+    - Validates CHANGELOG.md format (Keep a Changelog compliance)
     - Creates annotated git tag with release notes
     - Pushes tag to remote
     - Creates GitHub release with comparison link
-    - Comprehensive error messages
-  - `/create-pr` enhancement: Intelligent version bump analysis
-    - Analyzes commit history for breaking changes/features/fixes
-    - Suggests Semantic Versioning-compliant version bump
-    - Executes `make bump-patch/minor/major`
-    - Prompts for CHANGELOG.md update
-    - Commits version bump automatically
+  - `/create-pr` enhancement: AI-powered version bump
+    - Analyzes commits (BREAKING CHANGE, feat:, fix:)
+    - Examines actual code changes intelligently
+    - Suggests Semantic Versioning-compliant bump with rationale
+    - Executes `make bump-patch/minor/major` based on user choice
+    - AI auto-generates CHANGELOG entry
+    - Tags commit with `[patch]`/`[minor]`/`[major]` for tag-and-release
+    - Refinable in PR review
 
 ### Changed
 
 - **Cursor Commands**
-  - Enhanced `/create-pr` with version management integration
-  - Added version bump workflow before PR creation
+  - `/create-pr`: Concise AI analysis, automatic CHANGELOG generation
+  - `/tag-and-release`: Reads bump type from commits, auto-applies version bump
+  - Integrated workflow: create-pr tags bump type → tag-and-release applies it
 
 ## [0.3.3] - 2025-11-10