Add AGENTS.md for contributor onboarding

[gziolo]

Summary

• Adds AGENTS.md — a concise reference file that routes contributors (and AI coding tools) to the right docs for setup, architecture, testing, and workflow rules
• Removes AGENTS.md from .gitignore so it is tracked in the repo

Closes #307

Context

New contributors currently need to discover and read multiple docs before they can start working. AGENTS.md acts as a quick-start routing table — it doesn't duplicate existing docs, it links to them and codifies workflow rules (e.g., use npm run scripts instead of direct composer calls).

The file is agent-agnostic and works with any AI coding tool (Copilot, Cursor, Claude Code, Windsurf, etc.) as well as being a useful human-readable reference.

Test plan

• Verify AGENTS.md is no longer gitignored
• Verify all doc links in AGENTS.md resolve correctly
• Try asking an AI coding tool "how do I start contributing?" with the file present

🤖 Generated with Claude Code

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: gziolo <gziolo@git.wordpress.org>
Co-authored-by: jeffpaul <jeffpaul@git.wordpress.org>
Co-authored-by: justlevine <justlevine@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 58.03%. Comparing base (4fbb197) to head (286e098).
⚠️ Report is 219 commits behind head on develop.

Additional details and impacted files

@@              Coverage Diff              @@
##             develop     #308      +/-   ##
=============================================
+ Coverage      56.69%   58.03%   +1.33%     
- Complexity       505      576      +71     
=============================================
  Files             32       37       +5     
  Lines           2568     2955     +387     
=============================================
+ Hits            1456     1715     +259     
- Misses          1112     1240     +128     

Flag	Coverage Δ
unit	58.03% <ø> (+1.33%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[gziolo]

Example:

Screen.Recording.2026-03-16.at.12.02.10.mov

[gziolo]

Note to self: step 3 contradicts the "prefer npm run over direct composer" rule by telling agents to run composer install directly. Worth clarifying that composer install is the one exception (needed before wp-env starts), while these have npm wrappers and should use them:

Direct call	npm wrapper
composer run-script lint	npm run lint:php
composer run-script format	npm run lint:php:fix
composer run-script phpstan	npm run lint:php:stan
vendor/bin/phpunit	npm run test:php

Should also mention why: the npm wrappers run inside the wp-env Docker container, ensuring a consistent PHP version and WordPress environment regardless of local setup.

[Copilot]

Pull request overview

This PR adds a tracked AGENTS.md file intended as a quick routing/onboarding reference for contributors (and AI coding tools), and updates .gitignore so the file is no longer excluded from the repository.

Changes:

• Add AGENTS.md with links to key contributor/developer/testing docs plus workflow guidance.
• Remove AGENTS.md from .gitignore so it is committed to the repo.

Reviewed changes

Copilot reviewed 1 out of 2 changed files in this pull request and generated 1 comment.

File	Description
AGENTS.md	New onboarding/routing reference with doc links and recommended workflow commands
.gitignore	Stops ignoring AGENTS.md so it can be versioned

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jeffpaul]

Note that I left a question on the linked issue via #307 (comment) that ideally we can sort out before going much further on this PR

[justlevine]

@gziolo You seemed to have ignored the PR template - and more specifically the AI Disclosure section which is making it hard to give feedback. Please backfill that so a proper review can be done. (Marked Request Changes so it's clear it's incomplete in this state)

Also helpful would be

• explicit testing instructions (of the AGENTS.md file. what you currently wrote are instructions for testing whether github or your harness reads it).
• your explicit results from testing them: token usage and outcome comparison
• Your environment info (harness + model, skills/cache config if you're unable to disable them for the testing)
• Anything else that could help substantiate The file is agent-agnostic and works with any AI coding tool (Copilot, Cursor, Claude Code, Windsurf, etc.)

---

Left a few broad notes below, but based on your PR description as currently without the above and the changes it really seems like you're trying to use AGENTS.md to solve something best handled by fixing our docs directly.

[justlevine]

Why do you think this is important to inject into every window? IMO this is wasteful

[justlevine]

This seems heavy handed for both users and agents. Instead we should rely on progressive disclosure. if it knows the what/where, inference will tell it when to read the what.

I'd

1. get rid of the instruction
2. Drop the number of entrypoints in our docs to two (contributing + development), and ensure the primary one has a detailed directory tree that includes the other docs and what they include.

[justlevine]

I would streamline this for readability + tokenization.

Not by my desk to eval, but anecdotally, something along the lines of:

##

Prefer NPM scripts defined in `package.json` over direct tooling calls. This ensures they run in the `wp-env` environment.

### Common Scripts

```bash
# Use the wp-env environment
npm run wp-env start # Start the environment
npm run wp-env start -- --xdebug=coverage # Start the environment with coverage running
npm run wp-env clean all # Reset the wp-env databases
npm run wp-env {cli|tests-cli} run -- --env-cwd=wp-content/plugins/ai {your command} Run a command directly inside the specified wp-env container.

# Code Quality Checking
npm run lint:php # PHPCS
npm run lint:php:fix # PHPCBF
npm run lint:php:stan # PHPStan
npm run lint:js     # Run eslint
npm run lint:js:fix # Fix autofixable eslint errors
npm run typecheck # Run tsc

## Testing
npm run test:php # PHPUnit tests
npm run test:e2e  # Playwright E2E tests

## Building
npm run build 
\```

For more usage information see ./docs/{DOC.md}

(Replace the above with the actual scripts)

[justlevine]

Sorry, for some reason the PR comments only loaded for me after I submitted my review. This suggestion is basically this

[justlevine]

I would remove this entire section. The only thing here that isn't directly inferable already (after updating per the above) is the tone command.

If you really feel 3 deserves specific mention then we definitely don't want to tell it every single time to analyze and infer what should be independent. Also, the composer install violates your above Prefer... So id recommend adding something like this to the above bash:

Initial Repo Setup

# Initial Local setup:
nvm use && npm install && npm run build
npm run test:e2e:env:start -- --update
npm run wp-env run cli -- --env-cdw=wp-content/plugins/ai composer install

[gziolo]

Thanks @justlevine — this feedback makes sense to me.

The main goal of this PR was not to argue for this exact AGENTS.md content or format, but to make visible the onboarding and workflow friction the agent and I ran into while reviewing and testing several open PRs recently. It was essentially an attempt to write down the places where the expected path was not obvious in practice: which doc to start from, which commands to run, and which steps need to happen inside vs outside the expected environment. It’s a summary of my sessions where things didn’t go as expected and course corrections where necessary.

So I’m aligned with the core points in review:

• the guidance should be accurate,
• we should avoid duplicating or over-prescribing things,
• and if this is already covered by existing docs, then improving those docs is probably the better outcome.

I don’t have strong attachment to this file as such. If AGENTS.md is mostly repeating material that should live in CONTRIBUTING.md or developer docs, that’s fine with me. In that case, I’d treat this PR primarily as a concrete illustration of the repo-specific places that were not obvious to me or the agent, and use that signal to tighten the existing documentation — especially clarifying what to run, when to use wp-env, and which docs are the right entry points.