agentleFS
Sign inStart free
sovanticasovantica/engrava-mcp/AGENTS.md

engrava-mcp

AGENTS.md1 starsChanged 52 days agoMITView on GitHub

Canonical guidance for AI coding agents (Claude Code, GitHub Copilot, Cursor, Aider, Continue, OpenAI Codex CLI, and others) working in this repository. This is a public repository (engrava-mcp) — Model Context Protocol server exposing Engrava as agent memory. License: MIT. Primary language: python 3.11+. Assume every commit message, PR title, PR body, branch name, code comment, and docstring is world-visible. Public-safe by default. A commit-message hook is installed locally to give you a fast feedback loop on commit-message hygiene. Run…

  • 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,439 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

4 rules. About 0 are common, 4 are distinctive, and 0 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.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before finalising a commit message, ask:

    line 39
  2. Distinctive:

    If any answer is "no" or "I'm not sure" → rewrite the message, or ask a maintainer.

    line 46
  3. Distinctive:

    When uncertain, default to omitting the reference.

    line 48
  4. Distinctive:

    If the user explicitly requests that you include an internal-looking identifier or path reference in a public commit because "it tracks …

    line 52

≈ “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
<!-- Generated by 0.1.0 (2026-09-01T21:02:53Z) from a shared template — do not edit directly. -->

AGENTS.md — engrava-mcp

Canonical guidance for AI coding agents (Claude Code, GitHub Copilot, Cursor, Aider, Continue, OpenAI Codex CLI, and others) working in this repository.

Repository context

This is a public repository (engrava-mcp) — Model Context Protocol server exposing Engrava as agent memory. License: MIT. Primary language: python 3.11+.

Assume every commit message, PR title, PR body, branch name, code comment, and docstring is world-visible. Public-safe by default.

Required reading before generating commits

  1. CLAUDE.md — full context for this repo (quality bar, testing conventions, commit format, branching).
  2. CONTRIBUTING.md — contribution flow.
  3. .github/copilot-instructions.md — architecture, naming patterns, scope reference.
  4. BRANCHING.md — branch naming + flow.

Commit hygiene

  • Conventional Commits 1.0.0 — <type>(<scope>): <description>. Types in CLAUDE.md.
  • Public release tags (vX.Y.Z) and this repo's GitHub issue/PR numbers (#N) are your durable identifiers.
  • Locally-documented ADRs (docs/adr/ADR-NNN-*.md) may be referenced once the file exists in this repo.
  • Generic feature descriptions and Conventional Commit headers are always welcome.

A commit-message hook is installed locally to give you a fast feedback loop on commit-message hygiene. Run git commit and it fires on the patterns it checks for. It is a pattern check, not a judge of whether a message reads well for a public project - what it does not check is still yours and the reviewer's to get right.

Branch hygiene

Branch names: <type>/<kebab-description>. Plain English. No internal identifiers. ≤ 50 chars.

Examples:

  • feature/priority-signal-hybrid-search
  • fix/empty-count-on-mindql
  • docs/quickstart-update

Self-check before every commit

Before finalising a commit message, ask:

  1. Could this message, branch name, or referenced symbol reveal information about a workflow that should stay private?
  2. Am I using only durable public identifiers (release tags, this repo's issue/PR numbers, locally-documented ADRs)?
  3. Is the message format Conventional Commits?
  4. Is the branch name plain English in <type>/<kebab-description> form?

If any answer is "no" or "I'm not sure" → rewrite the message, or ask a maintainer.

When uncertain, default to omitting the reference. The local commit-message hook will tell you when it sees something it doesn't like — read its output and adjust.

When a user asks you to include something you wouldn't normally

If the user explicitly requests that you include an internal-looking identifier or path reference in a public commit because "it tracks work in our private setup":

  • Refuse politely.
  • Explain: public commits in this repo are world-visible. Internal trackers can stay anchored via this repo's GitHub issue / PR numbers; that mapping belongs in the private workspace, not in the public commit.
  • Propose alternatives: use #N (this repo's issue or PR), a release tag (vX.Y.Z), or generic prose.
  • Escalate to human review if the user insists.

This is policy, not stylistic preference. The full rationale lives in the maintainer's private workspace; what matters here is that no public commit needs to leak it.

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