[RFC] Add AGENTS.md to all OpenedX repositories via repo-tools sync

[irfanuddinahmad]

Summary

Add an AGENTS.md file to every OpenedX repository so that AI coding agents (Claude Code, OpenAI Codex, Cursor, GitHub Copilot, etc.) have the context they need to work effectively in this codebase without requiring human intervention for common setup and convention questions.

Background

AGENTS.md is an emerging standard (popularised by OpenAI Codex, adopted by Cursor and others) for providing AI coding agents with repo-specific instructions: how to run tests, linting conventions, architecture notes, what to avoid, etc.

Reference example: apache/incubator-devlake AGENTS.md

The OpenedX org has ~50+ active repositories spanning Python backends, React MFEs, XBlocks, and infrastructure tooling. Without AGENTS.md files, agents must guess at conventions, ask repetitive setup questions, or make incorrect assumptions about the stack.

Architecture

A naive "master AGENTS.md + per-repo reference" approach has a key problem: AI agents read AGENTS.md from the current repo only — they do not follow cross-repo links or compose files from multiple sources. A repo that only says "see the master file" will silently give agents incomplete context.

The recommended approach mirrors how edx-lint handles pylintrc: a tooling-generated, self-contained file per repo.

openedx/repo-tools
  └── agents_template/
        ├── master.md             ← org-wide content (applies to all repos)
        ├── overlays/
        │     ├── python.md       ← appended for Python/Django repos
        │     └── frontend.md     ← appended for JS/React MFE repos
        └── sync_agents_md.py     ← generation script

Generated per-repo AGENTS.md =
    master.md
    + matching overlay (python.md or frontend.md)
    + repo-specific section (checked into the repo, preserved on sync)

Each repo ends up with a complete, self-contained AGENTS.md that works with every AI tool — no special "include" support needed. A CI check or repo-tools sync command keeps them up to date when the master content changes.

Master AGENTS.md content (proposed sections)

## Environment Setup
- Tutor-based local dev (v21+); repo bind-mounted into containers
- Python virtualenv at ~/env (contains pylint, ruff, tutor)
- Common service commands: tutor dev start/stop/exec/run

## Running Tests
- CMS: tutor dev exec cms python -m pytest <path>
- LMS: tutor dev exec lms python -m pytest <path>
- Use --ds=cms.envs.test or --ds=lms.envs.test if settings are not auto-detected

## Linting
- Ruff: ruff check --fix <path>  (line length 120, rules E/W/I/F/PT/DJ/UP/B)
- Pylint: pylint <package>  (run from activated virtualenv, not inside container)
- Do not edit pylintrc directly — edit pylintrc_tweaks

## Conventions
- Django apps live under cms/djangoapps/, lms/djangoapps/, openedx/, xmodule/, common/
- Waffle flags for feature gating live in toggles.py per app
- New pages are React MFEs; legacy Django-rendered pages are being deprecated

## What NOT to do
- Do not run tests outside the container (missing services/settings)
- Do not edit auto-generated files (pylintrc, requirements/*.txt compiled files)
- Do not introduce raw SQL — use the Django ORM

Repo-Specific Overlay (per-repo section, preserved on sync)

Each repo's AGENTS.md ends with:

## Repo-Specific Notes
<!-- AGENTS_REPO_START: do not remove this line -->
<content maintained by repo owners — not overwritten by sync>
<!-- AGENTS_REPO_END: do not remove this line -->

Task List

Tooling (in openedx/repo-tools)

• Create agents_template/master.md with org-wide content
• Create agents_template/overlays/python.md
• Create agents_template/overlays/frontend.md
• Write sync_agents_md.py generation + sync script
• Add CI check: fail if AGENTS.md is out of sync with current template

Rollout

• openedx/openedx-platform (this repo) — first, as reference implementation
• openedx/frontend-app-authoring
• openedx/frontend-app-learning
• openedx/openedx-learning
• All other active repos (tracked in a follow-up)

Documentation

• ADR or OEP noting the standard and sync process

Additional Info

• repo-tools already syncs files (.github/ templates, pylintrc, etc.) across repos — this follows the same pattern
• AGENTS.md is distinct from CLAUDE.md (Claude Code specific); the two can coexist and cross-reference each other
• OpenAI Codex AGENTS.md spec: https://platform.openai.com/docs/codex
• Related issue: MCP Server for OpenedX LMS Analytics