Skip to content

Add AGENTS.md for contributor onboarding #308

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gziolo wants to merge 2 commits into
base: develop
Choose a base branch
from
+28 −1
Open

Add AGENTS.md for contributor onboarding #308

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f41ed33
Add AGENTS.md for contributor onboarding
gziolo Mar 16, 2026
286e098
Potential fix for pull request finding
gziolo Mar 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,6 @@ build-types/
# AI files
.gemini/
.claude/
AGENTS.md
GEMINI.md
CLAUDE.md

Expand Down
28 changes: 28 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# AI Agent Instructions

WordPress AI Experiments plugin — canonical WordPress plugin for testing AI capabilities.
Copy link
Contributor

@justlevine justlevine Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


## References

Read these before making changes:
Copy link
Contributor

@justlevine justlevine Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


- [CONTRIBUTING.md](CONTRIBUTING.md) — setup, coding standards, naming conventions, PHPDoc rules, quality checks
- [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md) — creating experiments, plugin API, asset loading
- [docs/ARCHITECTURE_OVERVIEW.md](docs/ARCHITECTURE_OVERVIEW.md) — plugin architecture
- [docs/TESTING.md](docs/TESTING.md) — testing strategy
- [docs/TESTING_REST_API.md](docs/TESTING_REST_API.md) — REST API testing
- [docs/EXPERIMENT_LIFECYCLE.md](docs/EXPERIMENT_LIFECYCLE.md) — how experiments graduate toward core

## Workflow

- PHP-related npm scripts wrap `wp-env`; some JavaScript/tooling scripts call `wp-scripts`/`tsc` directly. Prefer `npm run` over direct `composer`, `vendor/bin`, or `wp-env` calls.
- Run `npm run lint:php`, `npm run lint:php:stan`, `npm run lint:js`, and `npm run typecheck` before submitting PRs.
- Use `npm run lint:php:fix` and `npm run lint:js:fix` to auto-fix.
Comment on lines +16 to +20
Copy link
Contributor

@justlevine justlevine Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link
Contributor

@justlevine justlevine Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


## Helping Contributors Get Started

When a contributor asks for help getting started:

1. Read the relevant doc from the references list based on their topic. If no topic is given, read `CONTRIBUTING.md` and walk them through setup, dev environment, and first experiment creation.
2. Give a concise, actionable answer with exact commands.
3. When asked to set up the project, run: `composer install`, `npm i`, `npm run build`, and `npm run test:e2e:env:start`. Run independent steps in parallel where possible.
Comment on lines +22 to +28
Copy link
Contributor

@justlevine justlevine Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Loading