/release

description: "Release manager for frontend and mobile. Writes App Store notes, user-facing changelog, flags stale docs and landing copy. Actions: notes | changelog | docs | sync"
argument-hint: "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: `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 condition, memory leak) — include as "Performance improvements" not a named fix

Append to `CHANGELOG-USER.md`. Confirm: `User changelog updated → CHANGELOG-USER.md`

---

Action: `docs` — flag stale documentation

Identify what needs updating after this release:

# What changed (user-facing features)
CHANGED_FEATURES=$(git log ${PREV_TAG}..HEAD --format="%s" 2>/dev/null | grep -iE "^feat" | head -20)

# Existing docs to scan
find docs/ README.md public/ src/ -name "*.md" -newer ".great_cto/PROJECT.md" 2>/dev/null | sort | head -20
ls docs/help/ docs/guides/ docs/user/ 2>/dev/null | sort
find . -name "CHANGELOG-USER.md" -o -name "FAQ.md" -o -name "GUIDE*.md" 2>/dev/null | sort | head -10

# Landing page copy files
find . -path "*/landing*" -o -path "*/marketing*" -o -name "*.mdx" 2>/dev/null | \
  grep -v node_modules | grep -v ".next" | sort | head -15

Output:

/release docs — ${VERSION}

NEEDS UPDATE
  [file or section]: [why — which new feature affects this]
  [file or section]: [why]

LIKELY OUTDATED (check manually)
  [file]: [last modified: date, feature that may have changed it]

LANDING PAGE
  [section name or path]: [what changed that affects the copy]
  ["no landing copy detected — add paths to .great_cto/PROJECT.md under landing-paths:"]

HELP CENTER / GUIDES
  [article title or path]: [which new feature it needs to cover]
  ["no help docs found — add paths under docs-paths