omamail
AGENTS.md331 starsChanged 17 days agoMITView on GitHub
Read the relevant document before changing its area; these contain constraints that are easy to miss in the code.
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository2 other files it gives its agents.
- review-issuesSkill
- review-prsSkill
The file
We split this AGENTS.md into the rules it gives an agent
9 rules. About 1 is common, 4 are distinctive, and 4 are very specific to this project.
≈1
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 5
Read the relevant document before changing its area.
- Very specific: line 33
Use the active Omarchy theme.
- Very specific: line 35
Never convey state by color alone.
- Very specific: line 37
Keep content direction separate from interface layout.
- Distinctive: line 47
Treat mail, server responses, URLs, filenames and persisted settings as untrusted.
- Common: line 48
Keep credentials out of argv, logs and world-readable settings.
- Distinctive: line 50
Every review states Security: PASS / BLOCK / NOT VERIFIED for the affected boundaries.
- Distinctive: line 54
Start with CONTRIBUTING.md — Review for scope decisions, review priorities and comment style.
- Very specific: line 60
Run make validate after QML or behavior changes.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Repository working agreements
Required reading by task
Read the relevant document before changing its area; these contain constraints that are easy to miss in the code.
| Area | Required reading |
| Keyboard, focus and navigation | docs/KEYS.md |
| Provider adapters, capabilities and account identity | docs/providers/README.md |
| HEY | docs/providers/hey.md |
| IMAP, SMTP and Proton Bridge | docs/providers/imap.md |
| JMAP discovery and streaming | docs/providers/jmap.md |
| Microsoft 365 over Graph | docs/providers/m365.md |
| Message HTML, images, direction and outgoing MIME | docs/MESSAGE-RENDERING.md |
| Network requests, credentials, subprocesses and security reviews | docs/SECURITY-BOUNDARIES.md |
| Backend APIs, binary pins and releases | docs/BACKEND-RUNTIME.md |
| Adding, changing or reviewing tests | docs/TESTING.md |
| Writing issue reports, PR descriptions, reviews or discussion comments | CONTRIBUTING.md — Write for people |
| Before making a commit or creating, updating, reviewing or requesting review of a pull request, including review follow-ups | CONTRIBUTING.md — mandatory; the single source of truth for commit/PR guidelines and evidence requirements |
Structure and boundaries
- Group by module, not file type. Rust lives in
src/, CLI handling insrc/cli/, and dispatch insrc/backend/. QML and its JavaScript live together underui/. Rust unit tests live with their modules; UI tests live inui/tests/; integration tests live intests/. - Rust owns mail business logic and durable agent jobs. QML owns presentation and interaction state, communicating with the persistent backend over stdin/stdout rather than invoking CLI commands. See
docs/BACKEND.mdanddocs/ARCHITECTURE.md. - QML JavaScript libraries start with
.pragma libraryand usevarandfunction, notconst,let, arrows or template literals. Put testable presentation rules there. Tests load module paths, e.g.load("compose/Senders.js");ui/tests/load.jsresolves QML.importchains. - A list or object received through a
varsignal argument (on Qt 6.12) or a delegate'smodelDatais a sequence or reference object, not a JavaScript array or object:Array.isArraysays no and its keys come back sorted. A receiver that judges such a value, keeps it or writes to it takesPlain.plain(ui/backend/Plain.js) of it first;ui/tests/qml/tst_signal_lists.qmlshows the pattern. - List new QML files in the Makefile's lint inputs and import other modules explicitly.
Service.qmlis shell-constructed and must declare no required properties. The shell injects onlyshell,manifest,pluginRegistry, andbarWidgetRegistry; settings arrive through the bar widget'sapplySettings.
UI
- Use the active Omarchy theme. Pass semantic colors from
App.qmlas required component properties; derive variants with alpha orStyle.normalFillFor/hoverFillFor/selectedFillFor. Secondary text mixes foreground toward background, neverQt.darker. Provider artwork retains its original colors. - Render sender-controlled labels with
Text.PlainText, neverAutoText. Rich message bodies go through the sanitizer. Do not fetch remote message resources directly through Qt. - Never convey state by color alone. Use accurate labels; suffix actions that open another dialog/page/browser/terminal workflow with
.... - An open popup keeps its trigger selected. Anchor to the control's edge, not the pointer. Place after opening and on height changes; on overflow, flip, clamp to the window, then clamp to zero.
- Keep content direction separate from interface layout; no
LayoutMirroring.
Backend compatibility
backend-versionis the plugin's exact binary pin, independent of Cargo's development version. Never substitute main/latest or a PATH binary. Keep both exact-version and API handshake checks; missingapiVersionis allowed only for historical 0.9.0/API 1.- New QML dependencies on methods, parameters, responses or error semantics require contract fixtures and an API revision exactly one past
releasedApiVersion, named underunreleased. Gate each feature on its fixed minimum revision even after release. Internal Rust-only changes do not require a release. - The Published backend gate exercises the actual pinned release with current QML codecs. Inventory checks and source fingerprints do not replace behavioral compatibility tests.
Security
- Treat mail, server responses, URLs, filenames and persisted settings as untrusted. Validate at the consuming boundary; encoding is not sanitization.
- Keep credentials out of argv, logs and world-readable settings. Use synthetic credentials and controlled targets for tests.
- Preserve account/draft ownership, human approval of AI proposals, and normal outbox dispatch. Model text must not supply routing or permission to send mail.
- Every review states Security: PASS / BLOCK / NOT VERIFIED for the affected boundaries. Missing evidence or a security failure blocks approval/release. Security regressions must verify the forbidden effect did not happen, not merely that an error was returned; follow
docs/SECURITY-BOUNDARIES.md.
Review priorities
Start with CONTRIBUTING.md — Review for scope decisions, review priorities and comment style. Use this file's task index to read only the domain guidance relevant to the change. Product, design and verification requirements belong in their source documents rather than being repeated in reviewer prompts.
Releasing and verification
make publish VERSION=X.Y.Zprepares one versioned release PR from clean, synchronized main; without VERSION it increments the patch. Never push main directly. Release CI publishes and verifies immutable assets before updating the binary pin and folding API metadata on that same branch. Tags alone do not publish. Followdocs/BACKEND-RUNTIME.mdfor release and recovery details.- Preserve
scripts/release-notes.shaggregation of PR release-note sections; GitHub-generated notes are not a substitute. - Run
make validateafter QML or behavior changes.make testincludes Rust, JavaScript, source regressions and QML tests. Inspect the Makefile for the current targets. - QML tests and
qmllintare local gates using the installed Qt; release CI usesmake test-js test-shell. Unresolvedqs.Ui/qs.Commonslint warnings are expected; the exit code is the gate.
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
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.

