The "Agents" instruction file seems very unstandardized to me.

https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions
No mention of Agents.md or Agent.md.

"# AGENTS.md spec"
https://openai.com/index/introducing-codex/#:~:text=15-,%23%20AGENTS.md%20spec,-16

15
# AGENTS.md spec
16
- Containers often contain AGENTS.md files. These files can appear anywhere in the container's filesystem. Typical locations include `/`, `~`, and in various places inside of Git repos.
17
- These files are a way for humans to give you (the agent) instructions or tips for working within the container.
18
- Some examples might be: coding conventions, info about how code is organized, or instructions for how to run or test code.
19
- AGENTS.md files may provide instructions about PR messages (messages attached to a GitHub Pull Request produced by the agent, describing the PR). These instructions should be respected.
20
- Instructions in AGENTS.md files:
21
  - The scope of an AGENTS.md file is the entire directory tree rooted at the folder that contains it.
22
  - For every file you touch in the final patch, you must obey instructions in any AGENTS.md file whose scope includes that file.
23
  - Instructions about code style, structure, naming, etc. apply only to code within the AGENTS.md file's scope, unless the file states otherwise.
24
  - More-deeply-nested AGENTS.md files take precedence in the case of conflicting instructions.
25
  - Direct system/developer/user instructions (as part of a prompt) take precedence over AGENTS.md instructions.
26
- AGENTS.md files need not live only in Git repos. For example, you may find one in your home directory.
27
- If the AGENTS.md includes programmatic checks to verify your work, you MUST run all of them and make a best effort to validate that the checks pass AFTER all code changes have been made.
28
  - This applies even for changes that appear simple, i.e. documentation. You still must run all of the programmatic checks.

• https://agents.md/
• https://agentsmd.net
  Etc

I like the idea, but this seems like not just one MORE file that will need to be kept up to date when the code changes, but possibly 6 or more depending on what other bot(s) we want to support. :/

I asked Codex to generate an agents.md and this is what it came up with:

• https://chatgpt.com/s/cd_68a597a1f27481919accdef26aaeb8a4
• docs: add AGENTS instructions #1345

Not impressed. May need to come up with a more thorough prompt. So meta to ask ChatGPT to generate a prompt for Codex! :)

Agents.md files are used by the Codex container.

One big problem with the agents file in this pr is that it instructs about macOS, but I highly doubt the container itself runs as macOS; it is most likely Linux.

So the agents file will need to assert Linux.

But Linux is our smallest install so instructing AI for Linux does not give us as big of an impact as it would if we could assert Windows or macOS... Which I don't know if we can yet.

Another opinion I have is that the natural language agents.md file in this PR seems to be written to be more beneficial to a human than a bot. I don't know if a bot really cares too much about a detailed description of the code structure. Maybe it does, but this seems more beneficial to a human than a bot that has a limited token set. I'd think that it might be better to use those tokens on more useful bot instructions than a verbose prose about the directory structure.

Here is my asking ChatGPT 5 to generate a prompt to ask Codex to generate an agents.md:
https://chatgpt.com/share/68a59d55-d25c-8013-ac83-5af1a2978b17

And then my Codex session that uses that prompt:
https://chatgpt.com/s/cd_68a59e27476081919d8d1b3d7e2f8d5d

Better, but still feels lacking.

I might still want to focus on Linux only workflow, since that is the only container platform I know Codex supports.
Maybe there is a way to support Windows (most likely) or macOS (I'd think pretty unlikely) bot containers.

I think the most likely Windows or macOS possibility would be to run the codex CLI locally on those platforms:

• https://github.com/openai/codex
• https://help.openai.com/en/articles/11096431-openai-codex-cli-getting-started

My understanding of the agents.md is to not have to rely on "every-flavor-of-the-week" AI-agents and centralise it all in one "file" for instruction.

I use it across a bunch of Claude / Gemini / openAi and self-hosted LLM.

The version in this PR is more detailed / talkative than my initial draft.

I am 100% ok for reducing it and using more bullet-point that sentences (might help in maintaining it).

This was AI-generated + manually checked / tweaked by myself ( it always wanted to go back to the MacOS specifics build and hallucinated the purpose of the CI/ folder)

What would be nice is :

• The build rules (cmake) to be expressed here too (need to maintain it when updating from the template)
• Transcribe the information in the Wiki about the Dev requirements & environment.
• Would be cool to added that "ANY comments added by AI must be prefixed by a tag (AI?)" or add that it should prompt the user to review + test the code generated anyway.

@paulpv as part of the active devs, i think you are the main one using codex. (I don't for this project).