Skip to content

AGENTS.md

Latest commit

 

History

History
58 lines (37 loc) · 3.04 KB

AGENTS.md

File metadata and controls

58 lines (37 loc) · 3.04 KB

AGENTS.md — engrava

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) — Graph memory database for AI agents. 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.
  • Generic feature descriptions and Conventional Commit headers are always welcome.

A pre-commit hook is provided locally to give you a fast feedback loop on commit-message hygiene. Run git commit and you'll see the check fire on any message that wouldn't be appropriate for a public open-source project.

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)?
  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 pre-commit 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.