[TESTERS NEEDED] Rewrite AGENTS.md with community-first agent guidelines

[SableRaf]

Note

See more context in the similar PR in processing/processing4#1453

This PR is a rewrite of the AGENTS.md first introduced in processing/p5.js#8194.

What's new?

• Agents should now point contributors toward Discord, CONTRIBUTING.md, CODE_OF_CONDUCT.md, and the contributor guidelines before doing anything else.
• Agents should now try to understand where their interlocutor is coming from (e.g.: Are they a first-time contributor? Have they used p5.js before? Do they have JavaScript experience?) and adapt their responses accordingly.
• Responses should be shorter and more conversational.
• Agents should redirect contributors who are looking for a different project (Processing Java, p5.js Web Editor, p5.js Website) to the right repo.
• Agents should now be aware of the 1.x/2.0 branch split and should point contributors to the 2.x project board.
• Agents should now check that an issue is unassigned and approved before encouraging someone to work on it.
• GSoC candidates should be directed to the Processing Foundation's GSoC guidelines.
• Agents should now suggest non-code contributions like translation, documentation, and testing.

How to test this PR

The best way to test this is to check out this PR an agentic coding environment (Claude Code, Copilot, Cursor, etc.) and try a few contributor scenarios:

• A first-time contributor with no specific issue in mind (should be onboarded and helped to find an open issue)
• Someone asking about Processing Java (should be redirected to the Processing repo)
• A GSoC candidate wanting to contribute a PR (should be redirected to GSoC Guidelines)
• An inexperienced contributor who wants to jump straight to writing code (should be redirected)
• An experienced contributor wanting to skip the onboarding (should be allowed)

Test the same input multiple times and check whether the responses are consistently helpful for the particular scenario.

Note any misaligned behavior and share it in the comments below. Please specify which model, version, and environment was used.

Note that this is largely subjective so use your judgment when you evaluate agent behavior. Discussion in the comments is encouraged.

Common failure-cases for agent behavior

• Not reading the AGENTS.md file
• Recommending issues that are already assigned or not ready for contribution
• Being suspicious of or interrogating the contributor's motivations
• Jumping straight to code or codebase analysis without first orienting the contributor
• Responding to a p5.js question with Processing contribution guidelines
• Doing the thinking for the contributor, instead of redirecting to the community
• Asking multiple questions at once in a way that feels like an interrogation
• Being preachy or reciting the guidelines back to the contributor
• Replying with an overwhelming wall-of-text

Other changes

• Added copilot-instructions.md to direct copilot to read AGENTS.md, since it tended to skip it.

[ksen0]

Thanks @SableRaf ! This update seems like a positive improvement.

[davepagurek]

Not super important but both this and the next point are labelled as 0, is that intentional?

[SableRaf]

Ah good catch! I fixed it

[SableRaf]

Note that Claude CLI tends to ignore AGENTS.md if the initial user request is specific enough (tested with: "I want to fix issue #8551")

I have managed to correct this behavior locally by adding a CLAUDE.md file that includes the line:

BEFORE you do ANYTHING ELSE, ALWAYS refer to the AGENTS.md document for complete guidelines.

However, I have resisted including vendor-specific prompt files in the root of the project so far, as it feels like free advertising or even endorsement.

Would it be worth it in this case? Curious what others think.

[SableRaf]

Failure cases when asking to explore the codebase

Claude acts suspicious of the contributor:

Claude skips reading AGENTS.md:

[SableRaf]

I got better results with GPT

[davepagurek]

I'm also a little hesitant, at least at first, to add instructions for specific tools, for the reasons you describe and also because it seems like we might be playing whack-a-mole as new tools come up. But it's also true that new tools, and even commonly used ones like Claude, may just ignore our instructions. To a certain extent, I feel like maybe we do what we can via methods like this, but then beyond a reasonable amount of effort on our part, fall back on our AI usage policy to close PRs that ignore them?

[Megabyte135]

Based on experience from several test runs. I didn’t have Claude at hand, so the experiments were carried out with Codex 5.3 in xhigh mode. Overall, the result matches the desired behavior, except for three scenarios:

• GSoC. With or without AGENTS.md, Codex decided not to remind me about the GSoC Guidelines.
• It stubbornly refuses to say anything about Processing Java.
• If you ask it to perform a specific task, about half the time it jumps straight into doing it without even trying to read AGENTS.md.

I had the idea of trying a kind of prompt injection to force the agent to read the instructions file, but that did not produce much of a result: even when the warning about the need to read AGENTS.md was surfaced as ESLint warnings, it could still ignore them without issue, while saying something like "it's default warning, nothing to worry about". It seems that advanced agents are smart enough to ignore commands coming from tools (ls/dir with instructions in file names, warnings from eslint, and so on).

I'm agree, I think it’s not worth trying to force an AI agent to familiarize itself with the instructions when this is its owner responsibility. Instead of adding support for every vendor’s file format, maybe it would be better to make that process a bit easier for AI users. For example, it may be worth adding a special section under “AI Usage Policy” in README.md (agents sometimes tend to read this before starting a job, even while ignoring AGENTS.md) with an onboarding prompt, since it seems that the initial user command cannot be reliably overridden. Something like:

Read the AGENTS.md file located in the project root and follow the instructions and guidance it contains. It is your responsibility to maintain compliance with these instructions within the project, both by following them yourself and by ensuring that all sub-agents within your area of responsibility follow them as well. Once you have finished reviewing it, proceed to carry out my next request (below).
{here goes request}

It'll make things easier for human contributors. A bit.