GH-1453: Add AGENTS.md with rules for AI coding agents

[krickert]

Adds AGENTS.md at the repository root: short rules for AI coding agents and the people who run them. It covers the AI policy (the committer reviews and owns AI output; agents do not post comments, issues or PRs on their own, following the Lucene AI policy), the build, the code conventions the project enforces (no regex in production code, existing helpers before new ones, StringUtil for case and whitespace, ParamChecks), Javadoc, tests and commit format.

Fixes #1453

[rzo1]

Hi @krickert - thanks, good to have this. One point should be aligned before merging: the AI disclosure rules need to follow the ASF guidance.

• The ASF generative tooling guidance recommends a Generated-by: <Name of Tool> <Version> token in the commit message, and the RAI commit-message practice asks to name the actual tool and model rather than a generic label. The current "Do not add model identifiers" and the Assisted-by: trailer contradict both. Suggested wording:

  Disclose AI help in the commit message with a Generated-by: <tool> <version> trailer, naming the actual tool and model version, as recommended by the ASF generative tooling guidance.

• Please reference the ASF page as the primary policy; the Lucene AI policy can stay as an additional reference.
• Minor: "disucssion" → "discussion"; "enforce the user to post to discussions on GITHUB" → "ask on GitHub Discussions or dev@opennlp.apache.org"; "Standard JDK character and space tools are usually rewritten in OpenNLP" duplicates the following two bullets and can be removed.

WDYT?

[Copilot]

🟡 Changes recommended

The policy differs from the referenced Lucene policy, omits the requested repository layout, and contains unclear instructions.

5 open findings

• Document the application and module layout · New
• Clarify policy for AI-generated project comments · New
• Rewrite unclear fallback instruction · New
• Correct spelling of discussion · New
• Define the eval-tests build procedure · New

What changed in this PR

Adds repository-wide guidance for AI-assisted OpenNLP development.

Changes:

• Defines AI contribution policy.
• Documents build, coding, testing, and documentation standards.
• Establishes commit and dependency rules.

File	Description
AGENTS.md	Adds guidance for AI coding agents and contributors.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[krickert]

Fixed.

[krickert]

Hi @krickert - thanks, good to have this. One point should be aligned before merging: the AI disclosure rules need to follow the ASF guidance.

• The ASF generative tooling guidance recommends a Generated-by: <Name of Tool> <Version> token in the commit message, and the RAI commit-message practice asks to name the actual tool and model rather than a generic label. The current "Do not add model identifiers" and the Assisted-by: trailer contradict both. Suggested wording:

  Disclose AI help in the commit message with a Generated-by: <tool> <version> trailer, naming the actual tool and model version, as recommended by the ASF generative tooling guidance.

• Please reference the ASF page as the primary policy; the Lucene AI policy can stay as an additional reference.
• Minor: "disucssion" → "discussion"; "enforce the user to post to discussions on GITHUB" → "ask on GitHub Discussions or dev@opennlp.apache.org"; "Standard JDK character and space tools are usually rewritten in OpenNLP" duplicates the following two bullets and can be removed.

WDYT?

I agree to show the tool, the version of the model and version of the harness. We agreed to follow the lucene standard too and had some standards in the email mentioned- totally agree.

For the most part (pardon my french) "don't be a jerk" is the overall arching theme - but since it's an LLM, that's pretty subjective. I think all of the suggestions are spot-on - it's such an important piece that I expect a couple rounds of discussion on this one.

I'm more of an AB test sorta guy, given the uncertainty of LLMs, I think whatever our first version is we'll find tweaks we need to do all the time. A year from now let's hope the code produced never looks mean to us humans.

When I first used AI, I used to say "it must compile before I look at it" or "look at the source code instead of stack overflow" - that is no longer needed.

[rzo1]

"We agreed to follow the lucene standard too and had some standards in the email mentioned- totally agree."

AFAIR we talked about it on the dev@ list but there was no vote nor consensus found yet ;-)

[krickert]

"We agreed to follow the lucene standard too and had some standards in the email mentioned- totally agree."

AFAIR we talked about it on the dev@ list but there was no vote nor consensus found yet ;-)

Agreed :) It's good we're doing it now because putting something out there is the best way to get the vote out. I'll make all the changes in a few moments.

But my vote - Version ID of the harness, model/version, and manual sign-off.

[krickert]

Thanks, did everything we discussed.

The file follows the ASF generative tooling guidance as its only policy reference. The disclosure line calls for a Co-authored-by: trailer naming the tool, the model and their versions whenever AI contributed to a commit; I chose Co-authored-by over Generated-by because the human authors, edits and signs off the final change. The typos and the duplicate JDK bullet are fixed, and "when in doubt" points to GitHub Discussions or dev@.

Tomorrow (or tonight) I'll start a [DISCUSS] thread on dev@ so the list can settle the wording.

[krickert]

Also - I kept the removal of the lucene ref (ASF is mentioned though). No need to have it in AGENTS.md - it will confuse the LLMs when there's contradictions multiple versions etc... I'll continue our DEV thread.