agentleFS
Sign inStart free
victorhqcvictorhqc/filbert/AGENTS.md

filbert

AGENTS.md4 starsChanged 9 days agoMITView on GitHub

Problem definition -> small, safe change -> change review -> refactor - repeat the loop. This is a macOS menu-bar application that tracks AI provider usage. It makes outbound network calls to provider APIs and stores API keys in the macOS Keychain. 1. Be methodical and verify changes. Network and Keychain code deserves extra care. 2. No quick fixes or temporary hacks unless explicitly requested. 3. You have the authority and obligation to push back on requests that violate architectural…

  • 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 31,700 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 repository4 other files it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

6 rules. About 0 are common, 4 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    No quick fixes or temporary hacks unless explicitly requested.

    line 15
  2. Distinctive:

    Every feature starts as a spec.

    line 44
  3. Very specific:

    One request shape per provider: Use URLSession directly. No third-party networking libraries unless the user explicitly adds one.

    line 55
  4. Distinctive:

    Rate-limit refreshes: Default: one refresh every 5 minutes.

    line 59
  5. Distinctive:

    Respect provider rate limits: If a provider returns 429, back off exponentially.

    line 61
  6. Very specific:

    All code follows the minimal-comments skill.

    line 68

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 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

AGENTS.md

Problem definition -> small, safe change -> change review -> refactor - repeat the loop.

0. Role & Mindset

This is a macOS menu-bar application that tracks AI provider usage. It makes outbound network calls to provider APIs and stores API keys in the macOS Keychain.

  1. Be methodical and verify changes. Network and Keychain code deserves extra care.
  2. No quick fixes or temporary hacks unless explicitly requested.
  3. You have the authority and obligation to push back on requests that violate architectural integrity, type safety, or the Spec-First protocol.
  4. The provider architecture is orthogonal — adding a provider must not require changes to any other provider or to the core app layer.

Never mutate git. Do not commit, push, stage, branch, merge, rebase, or reset. Read-only inspection is fine — git status, git diff, git log, git show, git remote get-url, git rev-parse — and the pr-description and release-notes skills rely on it. When a git action changes state, give the exact commands to the user and let them run it.

1. Structure

The project follows a Swift Package Manager structure:

  • Sources/App — the macOS app target: menu bar, popover, widgets, app lifecycle.
  • Sources/Core — the provider hub: protocol definitions, registry, refresh scheduling, data aggregation.
  • Sources/Providers/<Name> — one module per provider, each implementing the AIProvider protocol.
  • Tests/ — unit and integration tests, mirroring the Sources layout.

A provider module depends only on Core. The app depends only on Core (and transitively on any provider it links). Providers have no knowledge of each other.

2. The Spec-First protocol

Every feature starts as a spec. No code is written until a spec exists and the user has reviewed it.

See .agents/skills/writing-specs/SKILL.md for the full spec format and rules.

3. Internet access

Unlike a local-only application, this project makes outbound HTTPS requests to provider APIs. Follow these rules:

  • One request shape per provider. Use URLSession directly. No third-party networking libraries unless the user explicitly adds one.
  • Handle network errors gracefully. A failed refresh must not crash the app. Show stale data with a timestamp, not a blank panel.
  • Rate-limit refreshes. Default: one refresh every 5 minutes. Providers with tighter rate limits may need longer intervals.
  • Respect provider rate limits. If a provider returns 429, back off exponentially.
  • Never cache API keys outside the Keychain. Keys are read from Keychain at request time and never stored in memory longer than needed.

4. Comments

All code follows the minimal-comments skill. Code, tests, scripts, and config never cite a spec or an acceptance criterion; spec citations stay in specs/. See .agents/skills/writing-code/SKILL.md for the rules this repo adds.

The minimal-comments and pr-description skills are not in the repo. Install them with:

npx skills add victorhqc/skills.sh --skill minimal-comments --skill pr-description

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.

Check your setup, free