Add AGENTS.md files with a CI-checked related_files header

[huangzesen]

What this adds

AGENTS.md files are the cross-tool place for coding-agent instructions; Codex, Claude Code, Gemini CLI, Cursor, Copilot and others read them. This PR adds two, plus CI that keeps them accurate. It follows the same pattern as spedas/pyspedas#1491.

• AGENTS.md covers:
  • that this repo is a mirror
  • the layout, including missions split between idl/general/missions/ and idl/projects/
  • how to find a routine when IDL has no imports (file names, !PATH, duplicate file names, routines called by name from strings)
  • tplot storage (@tplot_com)
  • the shared download and CDF routines
  • which legacy folders to skip when searching
• idl/projects/themis/AGENTS.md is a pilot for one mission. It traces thm_load_fgm through thm_load_xxx, spd_download and spd_cdf2tplot.

Header rule

Every AGENTS.md starts with a YAML header with exactly two fields:

related_files:   # every file the text describes, plus related AGENTS.md files (parent, children)
  - idl/projects/themis/common/thm_load_xxx.pro
maintenance: |   # when to update this file
  Update when thm_load_xxx's keywords or flow change, ...

No folder has to have an AGENTS.md, but any that exists must have this header.

CI: .github/workflows/agents_md.yml

It runs .github/scripts/check_agents_md.py on every push and PR, and weekly an hour after the mirror sync. The mirror's own pushes use GITHUB_TOKEN, so they don't trigger workflows. The weekly run catches upstream renames that break a header.

• Fails on a missing or malformed header, extra fields, malformed or duplicate paths, a file listing itself, or an empty maintenance or body.
• Warns (as annotations) on listed paths that don't exist, files the text mentions but doesn't list, and parent/child AGENTS.md links that only go one way.

Change to the mirror workflow

mirror_bleeding_edge.yml now adds --exclude "AGENTS.md" and --exclude "/.agents/" to its rsync --delete. Without them, the next sync would delete these files. Everything else under idl/ is still replaced by the upstream snapshot as before. I checked this with a local rsync run.

Opt-in map

.github/scripts/build_agents_map.py builds .agents/map/MAP.md (Mermaid diagrams, which GitHub renders) and .agents/map/graph.json from the headers. Nothing runs it automatically. The skill in .agents/skills/agents-map/SKILL.md tells agents to rebuild the map only after a human agrees.

Checking locally

python .github/scripts/check_agents_md.py --strict
python .github/scripts/build_agents_map.py --check

These files exist only in the GitHub mirror; nothing changes in the upstream SVN repository.

🤖 Generated with Claude Code

[huangzesen]

Superseded by #471, which includes these commits plus the AGENTS.md files for the whole tree. I've combined them into one PR so they can't conflict depending on which one is merged first, as happened in pyspedas (#1491/#1492).