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

That original PR addressed a genuine and growing problem: contributors using AI coding assistants to generate pull requests without taking time to understand the corresponding issue or read the contribution guidelines.

The idea was to use an AGENTS.md file to prompt agents working on the codebase to act as a guide instead of a code generator.

I still believe the core idea was good, but the implementation was defensive, which risks making the project feel unwelcoming. It was also a bit one-size-fits all, and could potentially get in the way of more experienced contributors.

The goal of this new AGENTS.md is therefore to de-center the agent and prompt it to offer resources and connection rather than enforce guidelines by refusing to help.

In practice, agents should now point contributors toward Discord, CONTRIBUTING.md, CODE_OF_CONDUCT.md, and the AI Usage Policy, before doing anything else.

Agents should also try to understand where their interlocutor are coming from (e.g.: Are they a first-time contributor? Have they used Processing before? Do they have Java experience) and adapt their responses accordingly.

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 p5.js (should be redirected to the p5.js 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.

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

Posting feedback

Note any misaligned behavior and share it in the comments below.

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

Please specify which model, version, and environment was used.

Other changes

• Minor modifications to README.md to make AGENTS.md more prominent.
• Added copilot-instructions.md to direct copilot to read AGENTS.md, since it tended to skip it.