---
name: ami-prepare-release
description: Prepares GitHub releases by calculating the next semantic version tag and generating bilingual release notes (English and Spanish) from git commit history in a single unified workflow.
allowed-tools: Bash, Read, Write
---

# Skill: Release Preparer

Act as a Version Control Manager and Technical Release Author. Your job is to analyze unreleased commits, compute the next SemVer version tag, and generate bilingual user-facing Release Notes in a single unified workflow.

## Operational Modes

- **Mode A: Full Preparation (Default):** Calculates the next version tag and drafts the bilingual release notes.
- **Mode B: Tag Only:** Computes only the semantic version tag.
- **Mode C: Notes Only:** Formulates only the bilingual release notes draft.

## Workflow

### 1. Fetch Remote State & Identify Baseline Tag
- Run `git fetch` to synchronize remote commits and tags.
- Scan repository documentation for versioning policies (e.g., `VERSIONING.md`, `CONTRIBUTING.md`, or `README.md`). If a non-standard tagging convention (such as package prefixes or date-based QA tags) is specified, adhere to it.
- Run `git describe --tags --abbrev=0` to locate the latest tag. If no tag exists, use `v0.0.0` as the baseline.
- **Current Tag Verification:** Compare the commit hash of the latest tag (`git rev-list -n 1 <last-tag>`) with `HEAD` (`git rev-parse HEAD`). If identical, the current commit is already tagged; recommend reusing the existing tag.

### 2. Extract & Inspect Unreleased Commits
- Run `git log <last-tag>..HEAD --oneline` (or `--pretty=format:"%s"` for raw titles).
- **No Changes Check:** If the commit list is empty, report that no new unreleased commits exist and stop.
- **Product Scope & Release Necessity Check (Release Gate):**
  - Run `git diff <last-tag>..HEAD --name-only` to inspect modified files alongside commit titles.
  - If all unreleased commits consist exclusively of non-product changes—such as pure documentation updates (`docs:`, markdown files, ADRs), internal automated tests or benchmarks (`test:`), CI/CD maintenance (`ci:`), or internal developer chores (`chore:`) that do not alter the distributed product/library source code:
    - **Halt and reject release preparation.** Inform the user that no release is warranted because no core product functionality was modified. Do not compute a new SemVer tag or generate release notes.

### 3. Calculate Semantic Version Tag (SemVer)
Analyze commit messages against Conventional Commits:
- **Major Bump (x.0.0):** If any commit contains `!` (e.g., `feat!:`) or `BREAKING CHANGE:` modifying public API contracts.
- **Minor Bump (0.x.0):** If commits introduce new user-facing features or product capabilities (`feat:`).
- **Patch Bump (0.0.x):** If commits consist of bug fixes (`fix:`), runtime performance improvements (`perf:`), or internal refactoring (`refactor:`) touching the actual distributed product codebase.
- **No Release (Rejection):** Commits limited strictly to documentation updates (`docs:`), internal tests (`test:`), CI/CD workflows (`ci:`), or internal developer chores (`chore:`) that do not alter the shipped product do NOT qualify for a patch bump and MUST NOT trigger a release.

**Tag Modifiers (if requested):**
- **QA / RC:** Append `-qa.YYYYMMDD.n` or `-rc.YYYYMMDD.n` based on the current date and daily increment.
- **Stable:** Standard base version (e.g., `v1.3.0`).

- **Build Order Advisory:** For binary distribution pipelines, source version declarations and package manifests must be updated and committed before initiating compilation or packaging installers.

### 4. Categorize & Draft Bilingual Release Notes
- **Focus on Product Value:** Filter out internal developer chores (`chore:`, `bump version...`, `[skip ci]`), internal rule citations, and minor landing page edits. Translate technical changes into clear user-facing capability improvements.
- **Group Commits:**
  - `feat:` -> Features / Nuevas Funcionalidades
  - `fix:` -> Bug Fixes / Correcciones de Errores
  - `refactor:`, `test:`, `perf:` -> Maintenance / Mantenimiento
  - `!` / `BREAKING CHANGE` -> BREAKING CHANGES / CAMBIOS IMPORTANTES
- **Formatting Constraints:**
  - Strict prohibition against emojis in titles, language separators, or section headers.
  - Strictly adhere to the Zero Flags Invariant: NEVER use country flags anywhere in release notes. Use clean semantic text links (`[English](#english) | [Español](#español)`).

**English Template:**
```markdown
# Release [Version]

## BREAKING CHANGES

## Features

## Bug Fixes

## Maintenance
```

**Spanish Template:**
```markdown
---
# Lanzamiento [Versión]

## CAMBIOS IMPORTANTES

## Nuevas Funcionalidades

## Correcciones de Errores

## Mantenimiento
```

### 5. Output
Present the prepared release bundle clearly:
1. **Target Version Tag:** e.g., `v5.2.0`
2. **Bilingual Release Notes Draft:** English followed by Spanish.
3. Confirm with the user before publishing the release or updating package manager manifests.

> [!IMPORTANT]
> **Build Order & Pre-Build Version Bump Advisory:**
> In projects producing executable binaries or distribution packages (`.exe`, `.msi`, `.apk`, installers), version bumps in source configuration files (`*.csproj`, `app.manifest`, `constants.py`, `package.json`, `Cargo.toml`, etc.) MUST be completed and committed BEFORE initiating binary builds or packaging installers.

---
**Language Rule:** Although your code and commits MUST be in English, you MUST communicate and interact in the chat using the same language the user is speaking (e.g., Spanish, French, etc.).