agentleFS
Sign inStart free
berntpoppberntpopp/vep-link/AGENTS.md

vep-link

AGENTS.md0 starsChanged 4 months agoMITView on GitHub

Shared repository instructions for agentic coding tools working in vep-link. vep-link is an MCP server wrapping Ensembl VEP and Variant Recoder; FastAPI is a thin host providing /health only and mounting the MCP HTTP app at /mcp. The MCP facade covers variant annotation, identifier recoding, canonical resolution, and cross-build liftover across GRCh38 (rest.ensembl.org) and GRCh37 (grch37.rest.ensembl.org). Primary areas: - veplink/ - Python package, MCP facade, Ensembl client, services, models, transports, and server management - veplink/mcp/ - hand-authored MCP facade (tools,…

  • Installs packages

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

19 rules. About 0 are common, 12 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈12

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this file for shared repo-wide agent guidance.

    line 30
  2. Distinctive:

    Keep CLAUDE.md lean and Claude-specific.

    line 31
  3. Very specific:

    Prefer Makefile targets over ad hoc commands.

    line 32
  4. Very specific:

    Use uv.lock as the dependency lock source of truth.

    line 33
  5. Distinctive:

    Do not revert or overwrite changes you did not make unless explicitly asked.

    line 39
  6. Distinctive:

    Keep edits scoped to the task and avoid unrelated refactors.

    line 40
  7. Distinctive:

    Prefer existing code patterns over new abstractions.

    line 41
  8. Very specific:

    Put tests under tests/; do not create alternate test roots.

    line 42
  9. Distinctive:

    Use ASCII unless a file already requires non-ASCII content.

    line 43
  10. Distinctive:

    Treat Ensembl as an external research data service.

    line 44
  11. Distinctive:

    Keep MCP tools research-use scoped and never imply clinical decision support.

    line 45
  12. Very specific:

    Zero real network in tests: All Ensembl calls are mocked with respx.

    line 46
  13. Very specific:

    Use uv for dependency management.

    line 65
  14. Very specific:

    Use modern Python typing: list[str], dict[str, int], str | None.

    line 66
  15. Distinctive:

    Keep MCP tool and service behavior covered by unit tests.

    line 68
  16. Very specific:

    Every input is normalized to canonical CHR-POS-REF-ALT before VEP.

    line 69
  17. Distinctive:

    Prefer cohesive splits: one module per responsibility.

    line 84
  18. Distinctive:

    Treat failing checks as real issues unless you have clear evidence otherwise.

    line 96
  19. Distinctive:

    Do not broaden Ruff or mypy ignores to hide new issues.

    line 97

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

Shared repository instructions for agentic coding tools working in vep-link.

Project

vep-link is an MCP server wrapping Ensembl VEP and Variant Recoder; FastAPI is a thin host providing /health only and mounting the MCP HTTP app at /mcp. The MCP facade covers variant annotation, identifier recoding, canonical resolution, and cross-build liftover across GRCh38 (rest.ensembl.org) and GRCh37 (grch37.rest.ensembl.org).

Primary areas:

  • vep_link/ - Python package, MCP facade, Ensembl client, services, models, transports, and server management
  • vep_link/mcp/ - hand-authored MCP facade (tools, resources, errors, shaping)
  • vep_link/api/ - resilient async HTTP base client + Ensembl VEP/Recoder client
  • vep_link/services/ - orchestration (resolve/annotate/recode/liftover) + annotation extraction
  • tests/ - unit and integration tests; tests/fixtures/ holds canned Ensembl payloads
  • docs/ - usage, API, and MCP tool docs
  • docker/ - Dockerfile and Compose
  • docs/superpowers/specs/ and docs/superpowers/plans/ - design + execution artifacts for agentic workers

Source Of Truth

  • Use this file for shared repo-wide agent guidance.
  • Keep CLAUDE.md lean and Claude-specific; it references this file.
  • Prefer Makefile targets over ad hoc commands.
  • Use uv.lock as the dependency lock source of truth.
  • For multi-step work, follow the spec in docs/superpowers/specs/ and the plan in docs/superpowers/plans/.

Working Rules

  • Do not revert or overwrite changes you did not make unless explicitly asked.
  • Keep edits scoped to the task and avoid unrelated refactors.
  • Prefer existing code patterns over new abstractions.
  • Put tests under tests/; do not create alternate test roots.
  • Use ASCII unless a file already requires non-ASCII content.
  • Treat Ensembl as an external research data service.
  • Keep MCP tools research-use scoped and never imply clinical decision support.
  • Zero real network in tests. All Ensembl calls are mocked with respx; the tests/conftest.py no-network guard fails any un-mocked request. Live tests are marked integration and excluded from default CI.
  • MCP tool names, schemas, resources, and response modes are owned by vep_link/mcp/. REST is intentionally minimal (/health only).

Commands

Required before claiming completion:

  • make ci-local

Useful focused commands: make install, make format, make lint, make lint-loc, make typecheck, make test, make test-fast, make test-cov, make test-integration, make precommit, make dev, make docker-build, make docker-up.

Coding Standards

  • Use uv for dependency management; never pip install directly.
  • Use modern Python typing: list[str], dict[str, int], str | None.
  • Format and lint with Ruff; type check with mypy targeting Python 3.12.
  • Keep MCP tool and service behavior covered by unit tests.
  • Every input is normalized to canonical CHR-POS-REF-ALT before VEP. Do not reintroduce per-type VEP GET endpoints on the main annotation path; resolve via Variant Recoder then batch through VEP region POST.
  • Honor Ensembl rate limits: 429/Retry-After backoff, 200-variant POST chunks.
  • Preserve MCP tool names and response schemas unless the task explicitly calls for a breaking change.

File Size Discipline

Hard cap: 600 lines per Python module in vep_link/. Enforced by make lint-loc (wired into ci-local and pre-commit). Tests are exempt.

  • New files MUST stay under 600 lines.
  • Existing oversized files are grandfathered in .loc-allowlist; they may shrink but not grow.
  • Prefer cohesive splits: one module per responsibility.

Testing Notes

  • make test runs deterministic unit tests from tests/unit/ (single process).
  • make test-fast / make test-unit run in parallel via pytest-xdist with the worker count capped by PYTEST_MAXPROCESSES (default 4) so -n auto cannot fan out to every core on a many-core host and OOM a RAM-constrained machine. Override with make test-fast PYTEST_MAXPROCESSES=8, or use make test for a single process.
  • make test-integration runs live Ensembl tests (may rate-limit).
  • make test-cov enforces the 80% coverage floor (single process).
  • Treat failing checks as real issues unless you have clear evidence otherwise.
  • Do not broaden Ruff or mypy ignores to hide new issues.

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.

Reviews can't be read right now.

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