/deploy

name: deploy
description: Use when shipping a release of Agent Sessions — bumping version, updating CHANGELOG, building, signing, notarizing, publishing appcast, and creating a GitHub release.

Deployment Skill (Agent Sessions)

This skill is an agent-facing entrypoint that avoids duplicating the deployment runbook.

Canonical Sources (Single Source of Truth)

• Runbook: `docs/deployment.md`
• Unified tool: `tools/release/deploy` (see `tools/release/deploy --help`)
• Recommended pre-release QA checklist: `docs/release/pre-release-qa.md`

If anything here disagrees with the runbook, follow `docs/deployment.md`.

Workspace Policy (Hard Rule)

• Always run deployment from the user's current local repository checkout.
• Do not clone to temporary directories and do not switch to alternate worktrees as a deployment workaround.
• If the local worktree is dirty, stop and tell the user to clean the tree first (commit, stash, or discard), then continue in the same local repo.

QA Gate (Mandatory — Run Automatically Before Deploy)

• **Always run QA automatically** before any bump/release/verify step, unless the user explicitly says to skip it (e.g. "skip QA", "no QA").
• Do not ask whether to run QA — just run it.
• QA execution order:

1. **Scope** — `git log --oneline --decorate -n 30` and `git diff --name-only <LAST_TAG>..HEAD`; identify high-risk areas. 2. **Build** — `xcodebuild -project AgentSessions.xcodeproj -scheme AgentSessions -configuration Debug build` 3. **Full test suite** — `./scripts/xcode_test_stable.sh` 4. **Targeted tests** — run suites for touched high-risk areas (session parsing, usage tracking, onboarding, etc.) 5. **Warnings sweep** — flag any new actionable warnings in build output. 6. **Manual smoke reminder** — list the manual steps from `docs/release/pre-release-qa.md` §3–4 and ask the user to confirm GO/NO-GO after completing them.

• If automated gates fail → stop, report failure, do not proceed to bump/release.
• If user says "skip QA" or "no QA" → proceed without running, note it was skipped.

**Test count.** QA reads the authoritative pass count from the `.xcresult` bundle (stdout reports per-bundle totals and this scheme has two — it under-reports) and compares it to `tools/release/test-count-baseline.txt`. A drop **warns and continues**, deliberately: it does not block a release. So the warning has to actually be read — a deleted suite still exits 0 from xcodebuild, and this line is the only thing that says so. When the count changes for a real reason, update the baseline file in the same release.

Before Starting (Ask the User)

1. Target version (`X.Y` for major/minor releases, `X.Y.Z` only for patch releases; never ship `X.Y.0`) 2. Any headline changes (new agents, major features) that must be reflected in `docs/CHANGELOG.md` 3. Whether this is a major release that requires onboarding updates 4. Public copy updates needed for README/GitHub Pages (major changes to highlight, renamed features, or outdated wording to fix)

**Do NOT ask about QA status** — QA always runs automatically as part of pre-deploy (see QA Gate above).

Public Copy Update (Required for All Releases)

Always update (every release)

• `README.md` download link: `v{VERSION}/AgentSessions-{VERSION}.dmg` and label `Download Agent Sessions {VERSION} (DMG)`
• `README.md` Option A download link (second occurrence under Install section)
• `docs/index.html` download button URL and label
• `docs/index.html` version meta-line (`Version {VERSION} · Free & open source · No telemetry`)

Do NOT version-pin the site meta descriptions

`docs/index.html`'s `description`, `og:description` and `twitter:description` are **deliberately version-agnostic** as of the 2026-08-29 SEO work. This checklist used to demand "mention current version + key change" there, which is how the homepage description reached 541 chars reading "Version 5.0 makes every agent a plug-in adapter…" — past the ~155-char SERP budget, and stale the day after every release.

Leave them alone. If the product's positioning genuinely changes, rewrite them on their own merits and keep the budget: **title ≤60, description ≤155.** Adding a version string is the one edit that is always wrong. See the `reference-docs-site-seo-conventions` memory.

Update for minor/major or user-visible feature releases

• `README.md` "What's New in X.Y" section: update heading to new version, rewrite TL;DR and Highlights to reflect this release's key changes (do not keep old version's copy)
• `docs/index.html` hero/feature copy if features were renamed or new agents added

Never add

• Versioned "What's New in X.Y" section to `docs/index.html`
• Detailed release notes to README or website (those live in `docs/CHANGELOG.md`)

Never Announce a Bug the User Never Had (Hard Rule)

**A fix to a feature that ships in this same release is not a Bug Fix. It is development.**

When a feature is new in X.Y, every defect found and fixed in it before X.Y shipped was never in anyone's hands. Listing those under "Bug Fixes" invents a history of breakage users never experienced, and buries the actual feature under a list of things that sound broken. Ship the feature; the fixes are part of it.

Before writing any Bug Fix entry, ask: **which released version had this bug?** If the answer is "none — the code is new in this release", the entry does not exist. Fold anything user-visible into the feature's own Highlight instead.

Worked example (4.8, Grok CLI's first release):

• ❌ "A Grok session shows the title its own sidecar records" — Grok shipped in 4.8; no

user ever saw the wrong title.

• ❌ "Grok transcripts open with content in them" — same.
• ❌ "A Grok session's message count matches its transcript" — same.
• ✅ "Grok CLI is the eleventh current agent source…" — the Highlight, which already says

transcripts, images, Analytics and resume work.

Mixed entries need splitting, not deleting: a fix spanning shipped **and** new sourc