Add AGENTS.md to streamline contributor onboarding

[gziolo]

Problem

New contributors need to piece together information from multiple docs (CONTRIBUTING.md, docs/DEVELOPER_GUIDE.md, docs/ARCHITECTURE_OVERVIEW.md, package.json) before writing a single line of code. Two specific pain points:

1. No single entry point — there's no quick-reference file that tells you where to look for what. You have to discover each doc on your own.
2. Command confusion — all PHP commands need to run through wp-env via npm scripts (npm run lint:php, not composer lint), but this isn't obvious until you read package.json. A new contributor would likely run composer lint directly and hit errors.

Proposal

Add an AGENTS.md file to the repository (currently gitignored under "AI files" since #172). This is a lightweight, universal reference file that:

• Points to the right doc for the right task (setup, architecture, testing, experiments, etc.)
• Codifies workflow rules (e.g., prefer npm run over direct composer/vendor calls)
• Works as a quick-start for both humans and AI coding tools (Copilot, Cursor, Claude Code, Windsurf, etc.)

The file is intentionally short — it doesn't duplicate existing docs, it links to them.

Why not just improve CONTRIBUTING.md?

CONTRIBUTING.md is thorough and should stay as-is. AGENTS.md serves a different role: it's a concise routing table that helps you (or your AI tool) find the right doc fast. Think of it as a table of contents for the project's developer knowledge.

My experience

I tried onboarding as a new contributor using Claude Code. Without any project context file, the AI had to read multiple docs before it could answer basic setup questions. After adding AGENTS.md with references and workflow rules, the experience became: ask a question → get the right answer with exact commands immediately. The same file works equally well as a human-readable quick-start reference.

[jeffpaul]

New contributors need to piece together information from multiple docs (CONTRIBUTING.md, docs/DEVELOPER_GUIDE.md, docs/ARCHITECTURE_OVERVIEW.md, package.json) before writing a single line of code.

Why not just improve CONTRIBUTING.md?
CONTRIBUTING.md is thorough and should stay as-is.

Sounds like we're only optimizing for AI agent onboarding, why not (even leveraging AI to help) consolidate/improve the existing docs so that humans and AI agents could more easily onboard?

[gziolo]

Do you propose we only improve existing docs, or including the file with agents with references to other files is still possible?

[justlevine]

While I (and almost all research) am on record as firmly against committing a public AGENTS.md to other WordPress.org properties I've got slightly less hesitation in WordPress/AI since we're ostensibly the most capable of being able to handle the technical requirements/ stay on top of adaptations.

I still think it's a very bad idea.

I think a marginally better approach would be to provide an AGENTS.md.example so folks can tune it to their specific models and harnesses.

I definitely agree with @jeffpaul that streamlining our docs for both human and AI contributors is an important first step, and (maybe taking it a step further?) that it should be a prerequisite before any AGENTS.md(?.example} since it definitionally invalidates any work done there.

I tried onboarding as a new contributor using Claude Code. Without any project context file, the AI had to read multiple docs before it could answer basic setup questions. After adding AGENTS.md with references and workflow rules, the experience became: ask a question → get the right answer with exact commands immediately. The same file works equally well as a human-readable quick-start reference.

@gziolo what was your experience contributing to the repository after the new contributor flow? I've got some specific questions that I'll save for #308, but this IMO seems like the exact sort of context poisoning that best practice says you SHOULDNT include in an AGENTS.md file, since new contributor setup etc is done once while file gets injected into every session regardless of topic.

[jeffpaul]

Do you propose we only improve existing docs, or including the file with agents with references to other files is still possible?

Broadly speaking I'm fine with net new additions to docs, but also admit that a good portion of existing docs may have a noticeable percent that originated with some AI slop. We had to make the decision to merge in much of that back in late 2025 in order to get to done on the scaffolding of the plugin, so its a bit of a doc tech debt we took on then that you're running into now. For that, I apologize, but again I think with a knowledgeable contributor to our codebase some AI-assisted doc cleanup seems achieveable (and perhaps lands us in a place where both Claude Code and new human contributions could onboard more efficiently and effectively).

[gziolo]

@jeffpaul, I expanded a bit on my reasoning in #308 (comment).

I opened this PR mostly to illustrate my experience of asking the agent to extract and codify the information that would have made onboarding, review, and testing smoother. I’m not strongly attached to this exact solution, and I don’t yet have enough repository-specific context to say what the best long-term approach is here.

If the agent and I got some assumptions wrong, that’s also useful signal — it likely means those points should be clarified in the existing docs.

My experience with other repositories in the WordPress project has been that a dedicated instruction file for agents can help by making expectations and quality bars more explicit. That may be redundant at times, but in practice it can reduce mistakes, unnecessary retries, and time spent rediscovering repository-specific conventions.

That said, I’m equally happy if the outcome here is to improve the existing docs instead if necessary. I’m also fine maintaining a local version of this kind of agent guidance for my own use based on what I learn here.