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

[huangzesen]

This PR adds AGENTS.md guidance for IDL SPEDAS, organized so SVN can import it. It has two commits that can be reviewed and imported independently:

1. Portable content, only under idl/, which maps to SVN trunk.
2. GitHub-only automation, outside idl/, which stays in this mirror.

#470 was closed in favor of this one.

The AGENTS.md convention (same as pyspedas#1492)

AGENTS.md files are the cross-tool place for coding-agent instructions; Codex, Claude Code, Gemini CLI, Cursor, Copilot and others read them. 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)
  - projects/themis/common/thm_load_xxx.pro
maintenance: |   # when to update this file
  Update when thm_load_xxx's keywords or flow change, ...

Paths are relative to the top of the source tree: idl/ here, trunk/ in SVN. No folder has to have an AGENTS.md, but any that exists must have this header.

1. Portable content (idl/ only)

• idl/AGENTS.md is the trunk entry point: layout, finding a routine, tplot variables, loaders, what to skip, and the header convention.
• 59 more AGENTS.md files:
  • Indexes: projects/ (one line for each of the 39 mission folders), general/, general/missions/, spedas_gui/ and external/.
  • Shared libraries in general/: tplot, misc, science, tools, cotrans, CDF, spice, spedas_tools.
  • Missions: maven, themis, mms, SPP, iugonet, elfin, erg, SWFO, dscovr, escapade, emm, kaguya, barrel, wind, goes, mex, cluster, swx, vex, poes, icon, secs, plus FAST and RBSP under general/missions/.
  • Instrument folders: MAVEN sta, swea, lpw, sep, swia, mag, general, models, quicklook; THEMIS fields, particles, state, ground; MMS common, sitl, particles; PSP sweap, COMMON, fields; ERG satellite, ground; SWFO STIS.
• idl/agents/scripts/check_agents_md.py checks the headers. It fails on a missing or malformed header, and warns on listed paths that don't exist, files the text mentions but doesn't list, and parent/child links that only go one way. Its default root is trunk; outside a Git work tree it walks the tree and skips .git and .svn.
• Opt-in map: idl/agents/scripts/build_agents_map.py builds idl/agents/map/MAP.md (Mermaid) and idl/agents/map/graph.json from the headers. It runs only when a human agrees; see idl/agents/skills/agents-map/SKILL.md. The map in this commit covers all 60 files and 1,756 related paths, none missing.

Each AGENTS.md covers the folder's layout, how its main entry point works, and lasting traps an agent would hit: common blocks and system variables, routines called by name from strings, duplicate file names, legacy subfolders to skip, and servers and credentials.

2. GitHub-only automation (outside idl/)

• Root AGENTS.md: covers the mirror, the two workflows and reporting upstream, and points to idl/AGENTS.md for everything else.
• CI (.github/workflows/agents_md.yml) runs the checker with idl/ as the root, then checks the root AGENTS.md separately, and turns the checker's output into annotations. It runs on every push and PR, and weekly an hour after the mirror sync, because the mirror's pushes don't trigger workflows.
• Mirror (mirror_bleeding_edge.yml) always keeps the root AGENTS.md. It keeps the AGENTS.md files under idl/ and the idl/agents/ folder only while the upstream snapshot lacks them. Once trunk ships them, the sync mirrors them like the rest of the code, deletions included. I tested the rsync lines against snapshots with neither, one or both.

How it was checked

• As an SVN checkout: exported only idl/ from the first commit into a folder outside Git and ran python agents/scripts/check_agents_md.py --strict: 60 files, 0 errors, 0 warnings. build_agents_map.py --check reports the map up to date.
• As CI runs it: both checker steps report 0 errors, 0 warnings.
• Scope: no .pro or data files changed. The files were written from the code, and specific claims were spot-checked against it. Bugs noticed while reading the code were kept out of the docs and are being reported separately.
• Build-generated files: svn_version_info.txt and the *_spd_doc*.html pages come from the zip build and aren't in trunk, so no header lists them.

🤖 Generated with Claude Code

[jameswilburlewis]

Thanks for putting this agent guidance together. Before we import it, we need to account for the repository layout: SVN trunk is mirrored into the GitHub idl/ directory, while GitHub-root dot directories are not produced by the SVN snapshot.
Please move the portable resources currently under .agents/ into a visible directory under idl/, such as idl/agents/, and update all references accordingly. When mapped back to SVN, that will become trunk/agents/ and will be available in clean SVN working copies and future GitHub snapshots.
Files used only by GitHub Actions may remain under root .github/. However, agent guidance intended for developers working from SVN must not depend on .github/ or on files outside idl/.
Please also organize the changes so the portable SVN content and GitHub-only automation can be reviewed and imported independently, and verify that everything works with idl/ treated as the checkout root.

[huangzesen]

Thanks, that makes sense. I've reworked the branch into two commits that can be reviewed and imported separately:

1. 224eab6dc0: portable content, only under idl/ (65 files). idl/AGENTS.md is the new trunk entry point. .agents/ moved to idl/agents/ (the map and the map skill), and the checker and map builder moved from .github/scripts/ to idl/agents/scripts/. Every path in the headers and text is now relative to idl/, e.g. projects/themis/common/thm_init.pro, so the files work unchanged as trunk/. Nothing in this commit refers to .github/, .agents/ or anything else outside idl/.
2. 76a7c3e5c9: GitHub-only automation (3 files, none under idl/). The root AGENTS.md now covers only the mirror and the workflows, and points to idl/AGENTS.md. agents_md.yml runs the checker from idl/agents/scripts/. mirror_bleeding_edge.yml keeps the AGENTS.md files and idl/agents/ across syncs only while the upstream snapshot lacks them; once trunk ships them, the sync mirrors them like any other file.

To check it with idl/ as the checkout root, I exported only idl/ from the first commit into a folder outside Git and ran python agents/scripts/check_agents_md.py --strict there: 60 files, 0 errors, 0 warnings. The map builder also runs there, and the map in the commit is up to date. CI passes on the new head.

One thing to confirm on your side: I treated svn_version_info.txt and the *_spd_doc*.html pages as output of the zip build that isn't in trunk, so no header lists them. If they are in SVN, I'll add them back.

The PR description is updated to match.

[jameswilburlewis]

Portable content from commit 224eab6 was imported into SVN trunk as rNNNNN. The remaining commit contains GitHub-only automation.