agentleFS
huacnleehuacnlee/omamail/AGENTS.md

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.

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
  1. Distinctive:

    Read the relevant document before changing its area.

    line 5
  2. Very specific:

    Use the active Omarchy theme.

    line 33
  3. Very specific:

    Never convey state by color alone.

    line 35
  4. Very specific:

    Keep content direction separate from interface layout.

    line 37
  5. Distinctive:

    Treat mail, server responses, URLs, filenames and persisted settings as untrusted.

    line 47
  6. Common:

    Keep credentials out of argv, logs and world-readable settings.

    line 48
  7. Distinctive:

    Every review states Security: PASS / BLOCK / NOT VERIFIED for the affected boundaries.

    line 50
  8. Distinctive:

    Start with CONTRIBUTING.md — Review for scope decisions, review priorities and comment style.

    line 54
  9. Very specific:

    Run make validate after QML or behavior changes.

    line 60

≈ “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.

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

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.

AreaRequired reading
Keyboard, focus and navigationdocs/KEYS.md
Provider adapters, capabilities and account identitydocs/providers/README.md
HEYdocs/providers/hey.md
IMAP, SMTP and Proton Bridgedocs/providers/imap.md
JMAP discovery and streamingdocs/providers/jmap.md
Microsoft 365 over Graphdocs/providers/m365.md
Message HTML, images, direction and outgoing MIMEdocs/MESSAGE-RENDERING.md
Network requests, credentials, subprocesses and security reviewsdocs/SECURITY-BOUNDARIES.md
Backend APIs, binary pins and releasesdocs/BACKEND-RUNTIME.md
Adding, changing or reviewing testsdocs/TESTING.md
Writing issue reports, PR descriptions, reviews or discussion commentsCONTRIBUTING.md — Write for people
Before making a commit or creating, updating, reviewing or requesting review of a pull request, including review follow-upsCONTRIBUTING.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 in src/cli/, and dispatch in src/backend/. QML and its JavaScript live together under ui/. Rust unit tests live with their modules; UI tests live in ui/tests/; integration tests live in tests/.
  • 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.md and docs/ARCHITECTURE.md.
  • QML JavaScript libraries start with .pragma library and use var and function, not const, let, arrows or template literals. Put testable presentation rules there. Tests load module paths, e.g. load("compose/Senders.js"); ui/tests/load.js resolves QML .import chains.
  • A list or object received through a var signal argument (on Qt 6.12) or a delegate's modelData is a sequence or reference object, not a JavaScript array or object: Array.isArray says no and its keys come back sorted. A receiver that judges such a value, keeps it or writes to it takes Plain.plain (ui/backend/Plain.js) of it first; ui/tests/qml/tst_signal_lists.qml shows the pattern.
  • List new QML files in the Makefile's lint inputs and import other modules explicitly.
  • Service.qml is shell-constructed and must declare no required properties. The shell injects only shell, manifest, pluginRegistry, and barWidgetRegistry; settings arrive through the bar widget's applySettings.

UI

  • Use the active Omarchy theme. Pass semantic colors from App.qml as required component properties; derive variants with alpha or Style.normalFillFor / hoverFillFor / selectedFillFor. Secondary text mixes foreground toward background, never Qt.darker. Provider artwork retains its original colors.
  • Render sender-controlled labels with Text.PlainText, never AutoText. 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-version is 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; missing apiVersion is 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 under unreleased. 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.Z prepares 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. Follow docs/BACKEND-RUNTIME.md for release and recovery details.
  • Preserve scripts/release-notes.sh aggregation of PR release-note sections; GitHub-generated notes are not a substitute.
  • Run make validate after QML or behavior changes. make test includes Rust, JavaScript, source regressions and QML tests. Inspect the Makefile for the current targets.
  • QML tests and qmllint are local gates using the installed Qt; release CI uses make test-js test-shell. Unresolved qs.Ui / qs.Commons lint warnings are expected; the exit code is the gate.

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.