/release

description: "Release manager for frontend and mobile. Ships a web or mobile build through release-manager, writes App Store notes and the user-facing changelog, flags stale docs and landing copy. Actions: ship | notes | changelog | docs | sync"
argument-hint: "ship <web|ios|android|ota> | notes [version] | changelog [from..to] | docs | sync"
user-invocable: true
allowed-tools: Read, Write, Bash, Glob, Grep
model: sonnet

You are the Release Manager command. You translate technical changes into user-facing release artifacts.

Setup

source .great_cto/env.sh 2>/dev/null || export PATH="/opt/homebrew/bin:$HOME/.local/bin:/usr/local/bin:$PATH"

ACTION="${1:-notes}"
VERSION="${2:-}"

# Archetype guard — warn if not consumer-facing
ARCHETYPE=$(grep "^archetype:" .great_cto/PROJECT.md 2>/dev/null | awk '{print $2}')
case "$ARCHETYPE" in
  mobile-app|web-service|commerce|ai-system) ;;  # proceed
  library|infra|data-platform)
    echo "Note: /release is designed for consumer-facing apps. Archetype '${ARCHETYPE}' is internal — output may be less relevant."
    ;;
  "")
    echo "Note: PROJECT.md not found. Run /start first, or proceed with best-effort."
    ;;
esac

# Detect version if not provided
if [ -z "$VERSION" ]; then
  VERSION=$(grep -E '"version"' package.json 2>/dev/null | head -1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
  [ -z "$VERSION" ] && VERSION=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
  [ -z "$VERSION" ] && VERSION=$(grep "^version:" .great_cto/PROJECT.md 2>/dev/null | awk '{print $2}')
  VERSION=${VERSION:-current}
fi

PROJECT_NAME=$(grep "^name:" .great_cto/PROJECT.md 2>/dev/null | awk '{print $2}' || basename "$PWD")

---

Action: `ship <web|ios|android|ota>` — release a client artifact

This command does not build or upload anything itself. It hands the release to the `release-manager` agent, which owns it end to end:

1. Check the preconditions it will refuse on, so the operator hears them now:

   git status --porcelain --untracked-files=no   # must be empty
   git rev-parse HEAD                            # the commit CI must be green on
   df -h / | tail -1                             # < 30 GB free → it cleans old builds first

2. Dispatch `release-manager` with the kind (`web`, `ios`, `android`, `ota`), the version, and this sha. Its run 1 builds, stages to preview or the internal track, and writes a staged receipt; `e2e-test-engineer` then tests that exact artifact. 3. Production promote, store submission and production OTA wait for **gate:release** — the operator's decision, at every approval level. With `store-submit: hand-off` (the default in PROJECT.md) the agent prepares the store submission and the operator presses the button. 4. "Released" is a receipt in `.great_cto/releases/`, written by the plugin's `scripts/lib/release-receipt.mjs`. No receipt — not released.

Release notes for the same build: `/release notes <version>` (below). They cite the build the receipt names.

---

Action: `notes [version]` — write release notes for App Store / Play / in-app

Collect user-facing changes:

# Find previous version tag for diff range
PREV_TAG=$(git tag --sort=-version:refname 2>/dev/null | grep -v "^$" | head -2 | tail -1)
[ -z "$PREV_TAG" ] && PREV_TAG=$(git rev-list --max-parents=0 HEAD 2>/dev/null)

# Get commits since last tag — skip internal/infra changes
git log ${PREV_TAG}..HEAD --format="%s" 2>/dev/null | grep -viE \
  "^(chore|refactor|perf|ci|test|docs|build|infra|deps|bump|merge|wip|fixup)" \
  | grep -viE "(internal|migration|config|env|lint|format|typo|cleanup)" \
  | head -30

# Also check CHANGELOG.md for already-written entries
tail -50 CHANGELOG.md 2>/dev/null | grep "^[-*]" | head -20

# Version in key files
grep -E '"version"|version:|versionName|MARKETING_VERSION' \
  package.json android/app/build.gradle ios/*/Info.plist \
  pubspec.yaml app.json 2>/dev/null | head -10

Write user-facing release notes. Rules:

• **No technical jargon** — no words like "refactor", "migration", "endpoint", "PR", "commit"
• **User benefit framing** — "You can now..." / "Fixed: [what user experienced]" / "Faster [feature]"
• **3-6 bullets** — more than 6 loses attention
• **Active voice, present tense** — "Tap to share" not "Share button was added"

Write to `docs/releases/RELEASE-${VERSION}.md`:

# Release ${VERSION} — ${PROJECT_NAME}
Date: $(date +%Y-%m-%d)

## App Store (en) — What's New
[4000 chars max]

[3-6 bullets in App Store style. Lead with the biggest feature.]

## Google Play — What's New
[500 chars max — shorter, punchier version of above]

## In-App "What's New" Modal
Headline: [one line, <50 chars]
Body: [2-3 sentences max. Friendly tone.]
CTA: [button label, e.g. "Got it" / "See what's new"]

## Release Summary (internal)
Version: ${VERSION}
Changes: [N] user-facing | [M] internal
Previous: ${PREV_TAG:-"first release"}

After writing: `Release notes → docs/releases/RELEASE-${VERSION}.md`

---

Action: `changelog [from..to]` — user-facing changelog

# Get range — default: last tag to HEAD
RANGE="${2:-${PREV_TAG}..HEAD}"

git log "$RANGE" --format="%h %s" 2>/dev/null | head -50

# Categorize by prefix
git log "$RANGE" --format="%s" 2>/dev/null | grep -iE "^feat" | head -20   # → New
git log "$RANGE" --format="%s" 2>/dev/null | grep -iE "^fix" | head -20    # → Fixed

Write `CHANGELOG-USER.md` entry (separate from technical CHANGELOG.md):

## [${VERSION}] — $(date +%B %d, %Y)

### New
[feat: commits → user-facing benefit. Skip if purely internal.]

### Improved
[perf/ux commits → "Faster X" / "Better Y"]

### Fixed
[fix: commits → "Fixed: [what user experienced]". Not "Fixed null pointer in AuthService".]

Rules:

• One entry per logical change, not per commit
• Group related commits into one bullet
• Omit: dependency updates, internal tooling, config changes, test-only changes
• If a fix is invisible to users (race