release

name

release

description

Cut a Mission Control desktop release — bump package.json (must match the git tag), commit, create an annotated v-tag, push to trigger release.yml CI. Prefer letting auto-tag-release.yml patch-bump on merges to main; use this skill for major/minor, hotfixes, or when automation was skipped with [skip release]. Read references/mission-control-release.md for the full CI pipeline, academy approval gate, and version alignment rules.

Mission Control release

Phased workflow for this Electron desktop app. Read references/mission-control-release.md for CI jobs, academy publishing, auto-tag automation, and the v0.47.1 version-mismatch incident.

Default path: merges to main are automatically patch-bumped and tagged by .github/workflows/auto-tag-release.yml after Hosted CI is green. Prefer that unless the user asked for a major/minor bump or a manual hotfix.

Bump type from args: major | minor | patch. Default patch for this repo (desktop app ships frequently).

Quality mode: mode=fast|balanced|production. Default production when cutting a public release.

---

Mission Control rules (non-negotiable)

1. Bump package.json before creating the git tag. The tag version (without v) and package.json version must be identical on the commit you tag.
2. Use pnpm version X.Y.Z --no-git-tag-version — never git tag first and bump later.
3. Never reuse or force-move a remote tag. If a bad tag shipped, bump to the next patch and release again.
4. Pushing the tag triggers release.yml — CI builds signed installers, uploads academy assets, finalizes the academy row (Approve unlocks), and attaches installers to the GitHub Release. It does not Approve / promote the Electron updater.
5. In-app Update / electron-updater only advance after you Approve on agentsystem.dev. GitHub Releases are for manual download only. Admin Waiting means not finalized yet (CI finalize failed or still running).
6. Verify after CI + after academy approval: GitHub assets + finalized draft exist after CI; academy public latestVersion only matches after you Approve.

Version alignment check (run before tagging)

PKG=$(node -p "require('./package.json').version")
echo "package.json: $PKG — tag will be v$PKG"
git rev-parse "v$PKG" 2>/dev/null && echo "ERROR: tag v$PKG already exists" && exit 1

---

Phase 1 — Preflight

Exit condition: clean tree on main, last tag known.

git status --porcelain
git rev-parse --abbrev-ref HEAD
git describe --tags --abbrev=0 2>/dev/null || echo "NO_PRIOR_TAG"
git remote -v
node -p "require('./package.json').version"

• Dirty tree → STOP.
• Not on main → confirm with user.
• Manifest: package.json only (not publish/package.json).
• If the next merge would auto-tag and the user only wanted a delay → suggest [skip release] on the merge commit instead.

---

Phase 1.5 — Quality gate

Release range: <last-tag>..HEAD (or full history if no tag).

• mode=production → run typecheck + lint + tests (pnpm typecheck, pnpm lint, pnpm test) on changed scope.
• mode=fast → residue sweep on release-range diff.

Stop on failure unless user explicitly bypasses (record Bypassed-gates: in tag body).

---

Phase 2 — Compute next version

From current package.json version, apply semver bump. Verify tag does not exist:

git rev-parse v$NEXT_VERSION 2>/dev/null && echo "TAG_EXISTS — pick next patch or delete stale tag deliberately"

---

Phase 3 — Write manifest

pnpm version $NEXT_VERSION --no-git-tag-version

Show diff. Only package.json should change (no lockfile version field in pnpm for the root package).

---

Phase 4 — Release notes

Range: LAST_TAG..HEAD (exclude the upcoming chore(release) commit if notes are generated before bump).

Use conventional-commit grouping when ≥50% of subjects match feat: / fix: / chore: etc.

Example annotation:

## v0.48.0 (2026-07-02)

### Features
- feat: add foo (abc1234)

### Fixes
- fix: bar (def5678)

---

Phase 5 — Commit, tag, push

git add package.json
git commit -m "chore(release): v$NEXT_VERSION"
git tag -a "v$NEXT_VERSION" -m "<release notes>"
git push --follow-tags

When the user explicitly requests push in the same turn, push immediately after local tag creation.

Monitor: GitHub Actions → Release workflow for the new tag. Wait for finalize-academy and publish-github to succeed. Remind the user that existing users are not prompted until they Approve the release on agentsystem.dev (Waiting/Draft means finalize has not completed).

---

NEVER

• NEVER tag before bumping package.json — causes permanent in-app update loops (see v0.47.1).
• NEVER push a tag whose commit still has the old package.json version.
• NEVER force-push or delete a published tag without explicit user request and understanding of academy/CI impact.
• NEVER use lightweight tags — always git tag -a.
• NEVER release from a dirty working tree.
• NEVER tell the user the updater is live just because GitHub Release assets exist — academy approval is the updater gate.