/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.

Resource Preflight (Before QA, Bump, and Release)

Heavy steps (QA test runs, the Release build, notarization) crawl when the Mac is out of memory. During 6.0 the Release build ran 20+ minutes at 15% CPU because swap was nearly full. The cause was `fseventsd`, a macOS daemon holding 21 GB (20 GB compressed). The machine reported "31% free" and `ps` RSS showed every process small, so both looked healthy. Run this check before each heavy step, and again if a Release build passes 12 minutes:

sysctl -n vm.swapusage                                    # swap used / total
top -l 1 -o mem -n 8 -stats pid,command,mem,cmprs         # MEM includes compressed memory
df -h / | tail -1                                         # free disk
du -sh ~/Library/Developer/Xcode/DerivedData .deriveddata-* 2>/dev/null

Use `top`, not `ps`: RSS hides compressed and swapped memory, which is where the problem was. Do not trust `memory_pressure`'s "free percentage" either.

Act on what you find:

• **Swap above half of its total, or any process above 8 GB in `top` MEM** — fix before the

heavy step. If the process is `fseventsd`, restart it: launchd respawns it at once, and nothing is lost. Try `sudo -n killall fseventsd` first. When that fails (no cached sudo), stop and give the user that command without `-n` to run in Terminal, then re-check. Never kill other system daemons. For user apps (Chrome, other Claude sessions, test runners), name the biggest ones and ask the user to quit them; do not kill them yourself.

• **Free disk under 20 GB, or the DerivedData folders above 10 GB together** — recommend

deleting the repo's `.deriveddata-*` folders and `~/Library/Developer/Xcode/DerivedData`. They are build caches and regenerate. Delete them only when the user agrees, and never while a build is running.

• Otherwise continue. Report the swap and top-memory numbers in one line.

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 genuine