Add `AGENTS.md` and AI contribution guidance #2193

westonruter · 2025-09-28T01:19:56Z

This adds an AGENTS.md as was recently done for Gutenberg: WordPress/gutenberg#71796

It also updates the CONTRIBUTING.md and PULL_REQUEST_TEMPLATE.md to provide guidance on how AI tools should be used and how their use should be disclosed.

I incorporated parts of my .gemini/styleguide.md from my wp-plugin-template repo.

An initial draft of AGENTS.md was created via Gemini CLI creating a GEMINI.md via /init.

github-actions · 2025-09-28T01:20:06Z

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: westonruter <[email protected]>
Co-authored-by: mukeshpanchal27 <[email protected]>
Co-authored-by: aialvi <[email protected]>
Co-authored-by: mindctrl <[email protected]>
Co-authored-by: felixarntz <[email protected]>
Co-authored-by: adamsilverstein <[email protected]>

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

AGENTS.md

aialvi

LGTM

AGENTS.md

mindctrl

LGTM. Left a couple small comments.

felixarntz

@westonruter Happy to see this, thanks for setting it up!

AGENTS.md

CONTRIBUTING.md

felixarntz

Two high-level suggestions:

Add a section to cover some key architectural concerns (e.g. no OOP, follow WordPress Core procedural programming patterns) and directory overview (how things in different places tie together, e.g. "each plugins/* folder is a separate WordPress plugin" etc).
Use more examples instead of long explanations for things like code style, using functions to print scripts, etc.

Co-authored-by: mukeshpanchal27 <[email protected]>

Co-authored-by: Felix Arntz <[email protected]>

Co-authored-by: Felix Arntz <[email protected]> Co-authored-by: John Parris <[email protected]>

Co-authored-by: Felix Arntz <[email protected]>

AGENTS.md

felixarntz · 2025-09-30T15:47:24Z

.github/PULL_REQUEST_TEMPLATE.md


+## Use of AI Tools
+
+<!-- Please disclose whether AI tooling was used to author the code in the pull request. To what extent was AI used? Was it used as a code reviewer, or was it used to "vibe code" everything? It is your responsibility to review and take responsibility for what AI generates. For more, see CONTRIBUTING.md which includes instructions for how to provide instructions to AI agents. -->


If you apply https://github.com/WordPress/performance/pull/2193/files#r2389568757, it should probably be put here too :)

Done in 1fa61f5

Maybe this was a misunderstanding - the copy here is still the old one, it needs to be aligned with what's in CONTRIBUTING.md.

Humm. I seemed to have missed making the change I imagined myself making! Now addressed in 688a21c

Co-authored-by: Felix Arntz <[email protected]>

AGENTS.md

CONTRIBUTING.md

felixarntz

This looks great. A few more points of feedback.

felixarntz · 2025-10-02T17:06:39Z

.github/PULL_REQUEST_TEMPLATE.md


+## Use of AI Tools
+
+<!-- Please disclose whether AI tooling was used to author the code in the pull request. To what extent was AI used? Was it used as a code reviewer, or was it used to "vibe code" everything? It is your responsibility to review and take responsibility for what AI generates. For more, see CONTRIBUTING.md which includes instructions for how to provide instructions to AI agents. -->


Maybe this was a misunderstanding - the copy here is still the old one, it needs to be aligned with what's in CONTRIBUTING.md.

AGENTS.md

Co-authored-by: Adam Silverstein <[email protected]>

Co-authored-by: Felix Arntz <[email protected]>

westonruter · 2025-10-06T23:01:02Z

This looks great. A few more points of feedback.

Anything more for this initial version?

felixarntz

Let's start with this and iterate as we identify areas to improve :)

westonruter added 2 commits September 27, 2025 18:17

Add AGENTS.md

b1634f2

Update CONTRIBUTING.md and PULL_REQUEST_TEMPLATE.md with AI guidance

f28543d

westonruter requested review from mukeshpanchal27, felixarntz and thelovekesh as code owners September 28, 2025 01:19

westonruter requested a review from swissspidy September 28, 2025 01:21

westonruter added [Type] Documentation Documentation to be added or enhanced no milestone PRs that do not have a defined milestone for release skip changelog PRs that should not be mentioned in changelogs labels Sep 28, 2025

westonruter changed the title ~~Add AGENTS.md and AI guidance~~ Add AGENTS.md and AI guidance Sep 28, 2025

westonruter changed the title ~~Add AGENTS.md and AI guidance~~ Add AGENTS.md and AI contribution guidance Sep 28, 2025

mukeshpanchal27 reviewed Sep 29, 2025

View reviewed changes

AGENTS.md Outdated Show resolved Hide resolved

aialvi reviewed Sep 29, 2025

View reviewed changes

mindctrl reviewed Sep 29, 2025

View reviewed changes

AGENTS.md Outdated Show resolved Hide resolved

mindctrl reviewed Sep 29, 2025

View reviewed changes

AGENTS.md Outdated Show resolved Hide resolved

mindctrl reviewed Sep 29, 2025

View reviewed changes

felixarntz reviewed Sep 29, 2025

View reviewed changes

AGENTS.md Outdated Show resolved Hide resolved

AGENTS.md Outdated Show resolved Hide resolved

AGENTS.md Outdated Show resolved Hide resolved

AGENTS.md Show resolved Hide resolved

CONTRIBUTING.md Outdated Show resolved Hide resolved

felixarntz reviewed Sep 29, 2025

View reviewed changes

westonruter and others added 6 commits September 29, 2025 15:57

Fix incomplete sentence

b258b3e

Improve project overview

fad453f

Co-authored-by: mukeshpanchal27 <[email protected]>

Fix typo

e6e8e4a

Co-authored-by: Felix Arntz <[email protected]>

Improve inline documentation example

794c074

Co-authored-by: Felix Arntz <[email protected]> Co-authored-by: John Parris <[email protected]>

Remove needless git clone step and add initial build step

6dd5c7f

Co-authored-by: Felix Arntz <[email protected]>

Improve code samples

385a6be

felixarntz reviewed Sep 30, 2025

View reviewed changes

westonruter and others added 2 commits September 30, 2025 17:19

Clarify guidance for use of AI tools

1fa61f5

Co-authored-by: Felix Arntz <[email protected]>

Specify that PHP 7.2 is the minimum version

d85f821

Co-authored-by: Felix Arntz <[email protected]>

westonruter requested a review from felixarntz October 1, 2025 00:20

adamsilverstein reviewed Oct 2, 2025

View reviewed changes

AGENTS.md Outdated Show resolved Hide resolved

adamsilverstein reviewed Oct 2, 2025

View reviewed changes

AGENTS.md Show resolved Hide resolved

adamsilverstein reviewed Oct 2, 2025

View reviewed changes

CONTRIBUTING.md Show resolved Hide resolved

adamsilverstein reviewed Oct 2, 2025

View reviewed changes

CONTRIBUTING.md Outdated Show resolved Hide resolved

felixarntz reviewed Oct 2, 2025

View reviewed changes

westonruter and others added 5 commits October 2, 2025 11:18

Fix typo

248bda7

Co-authored-by: Adam Silverstein <[email protected]>

Remove many

476a1cb

Co-authored-by: Adam Silverstein <[email protected]>

Fix typo

31648f9

Co-authored-by: Felix Arntz <[email protected]>

Improve project structure docs

d66aab0

Co-authored-by: Felix Arntz <[email protected]>

Align PULL_REQUEST_TEMPLATE AI guidance with CONTRIBUTING

688a21c

westonruter requested a review from felixarntz October 2, 2025 18:28

felixarntz approved these changes Oct 7, 2025

View reviewed changes

mukeshpanchal27 approved these changes Oct 7, 2025

View reviewed changes

mukeshpanchal27 merged commit 026d3b7 into trunk Oct 7, 2025
11 of 12 checks passed

mukeshpanchal27 deleted the add/ai-guidance branch October 7, 2025 03:54


		## Use of AI Tools

		<!-- Please disclose whether AI tooling was used to author the code in the pull request. To what extent was AI used? Was it used as a code reviewer, or was it used to "vibe code" everything? It is your responsibility to review and take responsibility for what AI generates. For more, see CONTRIBUTING.md which includes instructions for how to provide instructions to AI agents. -->

Add AGENTS.md and AI contribution guidance #2193

Add AGENTS.md and AI contribution guidance #2193

Conversation

westonruter commented Sep 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Sep 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

aialvi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mindctrl left a comment

Choose a reason for hiding this comment

Uh oh!

felixarntz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

felixarntz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

felixarntz Sep 30, 2025

Choose a reason for hiding this comment

Uh oh!

westonruter Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

felixarntz Oct 2, 2025

Choose a reason for hiding this comment

Uh oh!

westonruter Oct 2, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

felixarntz left a comment

Choose a reason for hiding this comment

Uh oh!

felixarntz Oct 2, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

westonruter commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

felixarntz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Add `AGENTS.md` and AI contribution guidance #2193

Add `AGENTS.md` and AI contribution guidance #2193

westonruter commented Sep 28, 2025 •

edited

Loading

github-actions bot commented Sep 28, 2025 •

edited

Loading

westonruter commented Oct 6, 2025 •

edited

Loading