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

release

Skill8 starsChanged 8 months agoMITView on GitHub

Use when the user wants to release a new version, says "time to release", "let's release", "cut a release", "version bump", or similar. Orchestrates the full release workflow including milestone check, version bump, changelog generation, validation, tagging, and PR creation. Also invocable as /release.

  • Commits and pushes

193 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

  • 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

  • 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

    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

  • parcadeiSkill

    agent-context-isolation

    Agent Context Isolation

    Also in 3 projects that use this

  • +3 more from Grinv

The file

Show its rules and text

We split this skill into the rules it gives an agent

19 rules. 0 are common, 14 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 183 edited versions we read keep these.

  • 14

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before creating a release branch, verify the milestone is ready.

    line 12
  2. Distinctive:

    If there are multiple open milestones, ask the user which one to release.

    line 19
  3. Distinctive:

    If the target milestone has open issues, stop and ask the user:

    line 21
  4. Distinctive:

    Do NOT proceed until all issues in the target milestone are closed or moved.

    line 27
  5. Very specific:

    Read the current version from pyproject.toml (authoritative source).

    line 33
  6. Distinctive:

    Wait for confirmation before proceeding.

    line 37
  7. Very specific:

    Update version in ALL of these files (pyproject.toml is authoritative):

    line 49
  8. Distinctive:

    README.md: - All references to the old version (check with grep for old version string)

    line 54
  9. Distinctive:

    Use the Edit tool for each file.

    line 56
  10. Very specific:

    Use the previous version tag directly (e.g., v0.8.1).

    line 64
  11. Very specific:

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

    line 73
  12. Distinctive:

    If Critical issues are found, stop and fix before proceeding.

    line 116
  13. Distinctive:

    Verify accuracy against changes in this release:

    line 130
  14. Distinctive:

    Test count / coverage stats in CLAUDE.md header

    line 135
  15. Distinctive:

    Run ALL validation checks.

    line 142
  16. Distinctive:

    If any check fails, fix the issue and re-run.

    line 174
  17. Distinctive:

    After the user approves the PR:

    line 199
  18. Distinctive:

    After the tag is pushed, close the milestone:

    line 229
  19. Very specific:

    Use rebase merge for release PRs.

    line 239

“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

This skill orchestrates a complete release. Follow each phase in order. Stop and report if any phase fails.

Phase 1: Milestone Check

Before creating a release branch, verify the milestone is ready.

  1. Determine the target milestone. Look at open milestones:
    gh api "repos/{owner}/{repo}/milestones?state=open&sort=due_on" --jq '.[] | "\(.number) \(.title) open:\(.open_issues) closed:\(.closed_issues)"'
  2. If there are multiple open milestones, ask the user which one to release.
  3. If the target milestone has open issues, stop and ask the user:
    • List the open issues: gh api "repos/{owner}/{repo}/milestones/{number}/issues?state=open" --jq ... (or use gh issue list --milestone)
    • Present options: a. Move open issues to the next milestone (specify or create it) b. Pause to work on the open issues first c. Close the issues if they're no longer relevant
    • Do NOT proceed until all issues in the target milestone are closed or moved.
  4. Once the milestone is clean (0 open issues), proceed.

Phase 2: Version Number

  1. Read the current version from pyproject.toml (authoritative source).
  2. The milestone title tells you the target version (e.g., v0.7.3 means version 0.7.3).
  3. Validate it's a valid semver bump from the current version.
  4. Present the version to the user for confirmation: "Release version X.Y.Z? (current: A.B.C)"
  5. Wait for confirmation before proceeding.

Phase 3: Create Release Branch

git checkout main
git pull origin main
git checkout -b release/vX.Y.Z

Phase 4: Bump Version

Update version in ALL of these files (pyproject.toml is authoritative):

  1. pyproject.toml - version = "X.Y.Z"
  2. src/omnifocus_mcp/init.py - __version__ = "X.Y.Z"
  3. CLAUDE.md (.claude/CLAUDE.md) - **Version:** vX.Y.Z in the header line
  4. README.md - All references to the old version (check with grep for old version string)

Use the Edit tool for each file. Be precise about what to change.

Phase 5: Generate CHANGELOG

  1. Get all commits since the last release:
    git log v{previous_version}..HEAD --oneline
    Use the previous version tag directly (e.g., v0.8.1). Do NOT use git describe --tags --abbrev=0 — it walks commit ancestry and may not find tags that were created before a squash/rebase merge.
  2. Get merged PRs since the last release:
    gh pr list --state merged --base main --search "merged:>YYYY-MM-DD" --json number,title,labels
    (Use the date of the last tag)
  3. Generate a CHANGELOG entry following the existing format in CHANGELOG.md:
    • Use Keep a Changelog format: ## [X.Y.Z] - YYYY-MM-DD
    • Categorize changes: Added, Changed, Fixed, Removed
    • Reference PR/issue numbers with (#N)
    • Be concise but descriptive
    • Include today's date
  4. Insert the new entry at the top of CHANGELOG.md (after the header, before the previous version).

Phase 6: Test Coverage Review

  1. Run coverage report:
    pytest --cov=omnifocus_mcp --cov-report=term-missing tests/ -q
  2. Compare overall coverage against the fail_under threshold in pyproject.toml. If coverage dropped below the threshold, stop and report — new code likely needs tests.
  3. Get the cumulative diff to identify changed files:
    git diff v{previous}..HEAD --stat
  4. Audit changed src/ files for adequate test coverage:
    • New code paths without unit tests
    • Modified AppleScript strings without integration tests (per CLAUDE.md hard rule: "If you wrote or modified an AppleScript string, integration tests must cover it before merge")
    • New parameters or return fields without test assertions
  5. Flag any gaps. If coverage dropped or critical paths are untested, stop and fix before proceeding.

Phase 7: Code Review

  1. Get the cumulative diff since the last release:
    git diff v{previous}..HEAD
  2. Launch the superpowers:code-reviewer agent to review the full diff. Provide context about the release scope (PRs included, features added/changed).
  3. The reviewer will report issues by severity:
    • Critical — security issues, data loss risks, correctness bugs → blocks the release
    • Important — code quality, missed edge cases → fix or document in PR
    • Minor — style, naming, suggestions → note in PR description
  4. If Critical issues are found, stop and fix before proceeding.
  5. Include Important/Minor findings in the release PR description under a "Code Review Notes" section.

Phase 8: Documentation Review

  1. Enumerate documentation to check:
    • README.md — feature descriptions, installation, usage examples
    • .claude/CLAUDE.md — version, test counts, coverage %, API surface count, performance baselines
    • CHANGELOG.md — new entry completeness
    • docs/** — architecture, profiling, AppleScript gotchas, automation notes
    • Tool docstrings in src/omnifocus_mcp/server_fastmcp.py
    • Skill files in .claude/skills/
  2. Verify accuracy against changes in this release:
    • Stale version numbers (should still be old version — Phase 4 bumped them)
    • Outdated performance baselines if perf-related changes were made
    • Missing feature documentation for new capabilities
    • Incorrect cross-references between docs
    • Test count / coverage stats in CLAUDE.md header
    • README coverage badge (coverage-XX%25-brightgreen) matches actual coverage
  3. Flag discrepancies and fix them on the release branch before proceeding.

Phase 9: Validation

Run ALL validation checks. Stop on any failure.

  1. Version sync check:
    ./scripts/check_version_sync.sh
  2. Client-server parity:
    ./scripts/check_client_server_parity.sh
  3. Complexity check:
    ./scripts/check_complexity.sh
  4. Unit tests:
    make test
  5. Dependency audit:
    ./scripts/check_dependencies.sh
  6. AppleScript safety audit:
    ./scripts/check_applescript_safety.sh

If any check fails, fix the issue and re-run. Do not proceed with failures.

Phase 10: Commit, Push, and PR

  1. Commit the version bump and changelog:
    git add -A
    git commit -m "release: vX.Y.Z"
  2. Push the branch:
    git push -u origin release/vX.Y.Z
  3. Create the PR to main:
    gh pr create --title "release: vX.Y.Z" --body "..."
    Include any Code Review Notes from Phase 7 in the PR body.
  4. Tell the user the PR is ready for review. Do NOT merge it automatically.

Phase 11: Merge, Tag, and Push Tag

After the user approves the PR:

  1. Merge using rebase merge:
    gh pr merge NNN --rebase --delete-branch
  2. Switch to main and pull:
    git checkout main
    git pull origin main
  3. Create the tag on main (where it will be reachable via git describe):
    ./scripts/create_tag.sh vX.Y.Z
  4. Push the tag:
    git push origin vX.Y.Z
  5. Verify tag reachability:
    git describe --tags --abbrev=0  # Should return vX.Y.Z

Phase 12: Close Milestone

After the tag is pushed, close the milestone:

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

Notes

  • CHANGELOG is only updated on release branches, never on feature branches.
  • Tags are created on main after the PR merge. This ensures they are reachable via git describe, which walks commit ancestry. Squash/rebase merges create new commits, so tags on the release branch would become orphaned.
  • Use rebase merge for release PRs. Merge commits are blocked by required_linear_history on main.
  • Integration tests (make test-integration, make test-e2e) require a real OmniFocus test database. Ask the user if they want to run them — they're optional for the release validation.

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.