AGENTS.md

1# Agent Instructions for homebrew-cask
2 
3This document helps coding agents produce high-quality PRs for Homebrew Cask contributions.
4 
5## Before Any PR
6 
71. **Check for existing PRs** for the same cask: [open PRs](https://github.com/Homebrew/homebrew-cask/pulls)
82. **Check if previously refused**: [closed unmerged PRs](https://github.com/search?q=repo%3AHomebrew%2Fhomebrew-cask+is%3Aclosed+is%3Aunmerged+&type=pullrequests)
9 
10## Golden Rules
11 
12- **One cask per PR**, one intent per PR
13- **Minimal diffs**—change only what's necessary
14- **No drive-by formatting** or unrelated stanza churn
15- **No verbose commentary**—keep PR descriptions short
16- **No non-Homebrew caveats** in PR body or cask file
17- **Use official sources** for download URLs
18- **If unsure about policy** (notability, naming, livecheck), stop and ask before opening a PR
19 
20## Version Updates
21 
22Preferred method for version bumps:
23 
24```sh
25brew bump --open-pr <cask>
26```
27 
28This handles version/sha256 updates, commit message, and opens the PR automatically.
29 
30### Manual Version Updates
31 
32If manual editing is needed:
33 
34```sh
35brew edit --cask <cask>
36# Update version, url, sha256 as needed
37# Do not add unrelated stanza changes
38```
39 
40Commit message: `<cask> <version>` (e.g., `firefox 125.0`)
41 
42## Cask Fixes
43 
44For bug fixes or improvements to existing casks:
45 
46```sh
47brew edit --cask &lt;cask&gt;
48# Make only the required changes
49```
50 
51Commit message: `<cask>: <description>` (e.g., `firefox: fix zap stanza`)
52 
53## New Casks
54 
55### Notability Requirements
56 
57New casks **will be rejected** if:
58 
59- App is too obscure (GitHub: <30 forks/watchers or <75 stars)
60- No public presence beyond "just `brew install`"
61- Unmaintained or has unpatched security vulnerabilities
62- Requires SIP to be disabled
63- Download requires login/registration (walled builds)
64- No compiled versions available (use homebrew/core instead)
65- Previously rejected for unfixable issues
66 
67See [Acceptable Casks](https://docs.brew.sh/Acceptable-Casks) for full criteria.
68 
69### Creating a New Cask
70 
71```sh
72brew create --cask &lt;url&gt;
73# Edit the generated cask
74```
75 
76Commit message: `<cask> <version> (new cask)` (e.g., `myapp 1.0.0 (new cask)`)
77 
78### Required Elements
79 
80- **Token**: Follow the [token reference](https://docs.brew.sh/Cask-Cookbook#token-reference)—lowercase, hyphens, no version numbers
81- **Required stanzas**: `version`, `sha256`, `url`, `name`, `desc`, `homepage`, and at least one artifact (`app`, `pkg`, etc.)
82- **`uninstall` stanza**: Required for `pkg` and `installer` artifacts
83- **`zap` stanza**: Recommended for thorough cleanup (preference files, caches in `~/Library`)
84 
85## Required Validation
86 
87### For Existing Cask Changes
88 
89```sh
90brew audit --cask --online &lt;cask&gt;
91brew style --fix &lt;cask&gt;
92brew install --cask &lt;cask&gt;    # or reinstall
93brew uninstall --cask &lt;cask&gt;
94```
95 
96### For New Casks
97 
98```sh
99export HOMEBREW_NO_INSTALL_FROM_API=1
100brew audit --cask --new &lt;cask&gt;
101brew style --fix &lt;cask&gt;
102brew install --cask &lt;cask&gt;
103brew uninstall --cask &lt;cask&gt;
104```
105 
106All checks MUST pass locally before opening a PR.
107 
108## PR Template Checklist
109 
110You MUST verify all items before submitting:
111 
112**For all cask changes:**
113 
114- [ ] Submission is for a [stable version](https://docs.brew.sh/Acceptable-Casks#stable-versions) or [documented exception](https://docs.brew.sh/Acceptable-Casks#but-there-is-no-stable-version)
115- [ ] `brew audit --cask --online <cask>` is error-free
116- [ ] `brew style --fix <cask>` reports no offenses
117 
118**Additionally, for new casks:**
119 
120- [ ] Named according to [token reference](https://docs.brew.sh/Cask-Cookbook#token-reference)
121- [ ] Checked cask was not [already refused](https://github.com/search?q=repo%3AHomebrew%2Fhomebrew-cask+is%3Aclosed+is%3Aunmerged+&type=pullrequests)
122- [ ] `brew audit --cask --new <cask>` worked successfully
123- [ ] `HOMEBREW_NO_INSTALL_FROM_API=1 brew install --cask <cask>` worked successfully
124- [ ] `brew uninstall --cask <cask>` worked successfully
125 
126**If AI-assisted:**
127 
128- [ ] Personally reviewed, tested, and verified all changes including `zap` stanza paths
129 
130## Commit Message Format
131 
132- Version update: `appname 1.2.3`
133- New cask: `appname 1.2.3 (new cask)`
134- Fix/change: `appname: <description>`
135- First line MUST be 50 characters or less
136 
137## PR Hygiene
138 
139### MUST
140 
141- One cask change per PR
142- Keep diffs minimal and focused
143- Provide only essential context in PR description
144 
145### MUST NOT
146 
147- Batch unrelated cask changes
148- Include formatting-only diffs
149- Add verbose logs or AI analysis in PR body
150- Add installation caveats unless the cask DSL requires it
151- Include unrelated refactors or stanza reordering
152 
153## PR Description
154 
155Keep it minimal:
156 
157```
158Built and tested locally on [macOS version].
159 
160[One sentence if not obvious from title.]
161```
162 
163Do NOT include:
164 
165- Large command output or logs
166- Lengthy explanations
167- Non-Homebrew installation advice
168 
169## CI Failures
170 
1711. Reproduce failures locally with the same commands
1722. Read error messages in "Files changed" tab annotations
1733. Fix only the failing issue
1744. Push incremental commits (do not squash after opening PR)
1755. If stuck, comment describing what you've tried
176 
177## AI Disclosure
178 
179If AI assisted with the PR, check the AI checkbox in the PR template. Briefly describe:
180 
181- How AI was used
182- What manual verification was performed (especially `zap` paths)
183 
184Do not identify an AI tool as an author, co-author, committer or signatory of a commit, including through an `Assisted-by`, `Co-developed-by` or similar commit trailer.
185Answer maintainer questions and pull request review comments yourself without using AI.
186AI assistants must not draft or post these responses; the human contributor must answer them directly.
187 
188## References
189 
190- [Cask Cookbook](https://docs.brew.sh/Cask-Cookbook)
191- [Acceptable Casks](https://docs.brew.sh/Acceptable-Casks)
192- [Adding Software to Homebrew](https://docs.brew.sh/Adding-Software-to-Homebrew#casks)
193- [CONTRIBUTING.md](CONTRIBUTING.md)
194- [How to Open a PR](https://docs.brew.sh/How-To-Open-a-Homebrew-Pull-Request)
195