agentleFS
s-morgan-jeffriess-morgan-jeffries/apple-mail-mcp/.claude/skills/release/SKILL.md

release

Skill104 starsChanged 2 months agoMITView on GitHub

Use when the user wants to release a new version. Orchestrates the full release workflow including milestone check, version bump, changelog generation, validation, tagging, and PR creation. Also use when discussing release planning or version management.

  • Reads credentials
  • Commits and pushes

194 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use create-agent-adapter, changelog-style and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • MicrosoftSkill

    create-agent-adapter

    Technical guide for creating a new Paperclip agent adapter. Use when building a new adapter package, adding support for a new AI coding tool (e.g. a new CLI agent, API-based agent, or custom process), or when modifying the adapter system. Covers the required interfaces, module structure, registration points, and conventions derived from the existing claude-local and codex-local adapters.

    Also in 5 projects that use this

  • GrinvSkill

    changelog-style

    Turn a commit range into CHANGELOG.md entries following common-changelog style. Use when finishing a PR or cutting a release, to write/fix the [Unreleased] section's entries — moving [Unreleased] under a new dated version heading is a separate, automated step (see the release skill / scripts/sync-version.ts), not this skill's job.

    Also in 4 projects that use this

  • GrinvSkill

    docs-consistency-check

    Check README/manifest.json/server.json/CHANGELOG.md/AGENTS.md and docs/*.md for drift against the actual registered tools and source. Use after adding, renaming, or removing a tool, or as part of a live-audit pass.

    Also in 4 projects that use this

  • Microsoft AzureSkill

    component-release

    Prepares a verifiable Agent Landing Zone UI release. Use for release branches, VERSION, changelog entries, tags, release notes, and compatibility evidence; never publish without explicit human approval.

    Also in 4 projects that use this

  • Microsoft AzureSkill

    documentation-consistency

    Keeps AI Landing Zone contributor, user, and operator documentation aligned with shipped Bicep behavior. Use for parameters, defaults, outputs, topology, deployment flow, operations, or releases.

    Also in 8 projects that use this

  • rivet-devSkill

    launch-graphics

    Generate agentOS marketing/launch graphics (launch & social heroes, code-snippet cards) from the committed generators in docs-internal/graphics. Use when asked to make, update, or render an agentOS launch image, social image, "agentOS Apps" graphic, or technical code-snippet image.

    Also in 3 projects that use this

  • +3 more from Grinv

The file

We split this skill into the rules it gives an agent

7 rules. 0 are common, 4 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 183 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Verify 0 open issues in target milestone

    line 10
  2. Distinctive:

    Stop if issues remain (ask user to move/close)

    line 11
  3. Very specific:

    Read current version from pyproject.toml (authoritative)

    line 14
  4. Very specific:

    Update ALL files (pyproject.toml is authoritative):

    line 22
  5. Very specific:

    Keep a Changelog format: ## [X.Y.Z] - YYYY-MM-DD

    line 33
  6. Distinctive:

    Run ALL checks (stop on failure):

    line 71
  7. Distinctive:

    Use rebase merge (linear history required)

    line 99

“Common” is measured: kept by at least 6 in 10 of the 183 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Release Workflow (12 Phases)

Phase 1: Milestone Check

  • List open milestones via gh api
  • Verify 0 open issues in target milestone
  • Stop if issues remain (ask user to move/close)

Phase 2: Version Number

  • Read current version from pyproject.toml (authoritative)
  • Milestone title = target version
  • Confirm with user

Phase 3: Create Release Branch

  • git checkout -b release/vX.Y.Z from main

Phase 4: Bump Version

Update ALL files (pyproject.toml is authoritative):

  1. pyproject.toml — version = "X.Y.Z"
  2. src/apple_mail_fast_mcp/__init__.py — __version__ = "X.Y.Z"
  3. .claude/CLAUDE.md — **Version:** vX.Y.Z
  4. README.md — all version references
  5. mcpb/manifest.json — "version": "X.Y.Z" (the .mcpb bundle; check_version_sync.sh enforces it)
  6. .claude-plugin/marketplace.json + .claude-plugin/plugin.json — every "version": "X.Y.Z" (the Claude Code plugin; check_version_sync.sh enforces all occurrences)

Phase 5: Generate CHANGELOG

  • Commits since last tag: git log v{prev}..HEAD --oneline
  • PRs since last release: gh pr list --state merged --search "merged:>YYYY-MM-DD"
  • Keep a Changelog format: ## [X.Y.Z] - YYYY-MM-DD
  • Categories: Added, Changed, Fixed, Removed

Phase 6: Test Coverage Review

  • Run coverage: make coverage
  • Compare against fail_under in pyproject.toml
  • Audit changed files for adequate coverage

Phase 7: Code Review

  • Launch superpowers:code-reviewer against cumulative diff
  • Critical issues block release

Phase 8: Documentation Review

  • README, CLAUDE.md, CHANGELOG, docs/**, tool docstrings, skills
  • The content-drift gate (check_docs.sh, Phase 9) automates the tool-set / removed-name / cross-ref / eval-description-sync parts; this phase is the human read for things it can't check (accuracy, tone, completeness).

Phase 8.5: Refresh derived artifacts (mandatory, #288)

Derived artifacts rot silently between releases — refresh them against the release commit so a stale snapshot can't ship:

  1. make eval-descriptions — regenerate the blind-eval tool descriptions; commit if changed. (check_docs.sh also fails on drift here.)
  2. Re-capture the benchmark baseline (#216): MAIL_TEST_MODE=true MAIL_TEST_ACCOUNT=<acct> uv run pytest tests/benchmarks/ --run-benchmark --capture-baseline (needs real Mail.app); commit the refreshed baseline.json.
  3. Re-run the blind agent eval (#219) and refresh its scored snapshot (needs OPENROUTER_API_KEY); commit.

Steps 2 and 3 are enforced by ./scripts/check_release_artifacts.sh (Phase 9): the benchmark baseline and the eval snapshot are version-stamped, and the gate fails the release if a stamp is stale. If an artifact genuinely can't be refreshed for this release (e.g. a CI/docs-only release), don't skip silently — record a waiver line (with a tracking issue) in release_artifact_waivers.txt. See docs/guides/RELEASE_ARTIFACTS.md. (#356)

Phase 9: Validation

Run ALL checks (stop on failure):

  1. ./scripts/check_version_sync.sh
  2. ./scripts/check_client_server_parity.sh
  3. ./scripts/check_complexity.sh
  4. make test
  5. make test-e2e — mandatory (requires MAIL_TEST_MODE=true + a test Mail.app account). CI excludes e2e, so this is the only gate that catches a stale e2e failure. A pre-existing failure on main is a release-blocker, not a known issue to ship around (#257).
  6. ./scripts/check_dependencies.sh — hard-fails only on advisories in direct deps (fastmcp/imapclient); transitive advisories are warnings (exit 0), surfaced continuously off the release path by .github/workflows/dependency-audit.yml so they don't block a release (#296). A direct-dep advisory still blocks — bump the pin and re-run.
  7. ./scripts/check_applescript_safety.sh
  8. ./scripts/check_docs.sh — doc/artifact drift gate (tool-set coverage, removed-name, cross-refs, eval-description sync) (#288)
  9. ./scripts/check_release_artifacts.sh — fails if the benchmark baseline or eval snapshot isn't version-stamped for this release (Phase 8.5 #2/#3) and isn't waived in release_artifact_waivers.txt (#356)

Phase 10: Commit, Push, PR

  • Commit: "release: vX.Y.Z"
  • Push: -u origin release/vX.Y.Z
  • PR to main via gh pr create

Phase 11: Merge, Tag, Push Tag

  • Rebase merge: gh pr merge NNN --rebase --delete-branch
  • Tag on main: ./scripts/create_tag.sh vX.Y.Z
  • Push tag: git push origin vX.Y.Z
  • Verify: git describe --tags --abbrev=0

Phase 12: Close Milestone

  • gh api -X PATCH repos/{owner}/{repo}/milestones/{number} -f state=closed

Notes

  • CHANGELOG only updated on release branches
  • Tags created on main AFTER PR merge
  • Use rebase merge (linear history required)
  • Each phase has explicit stop conditions — if it fails, stop and report

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.