Introduce an AGENTS.MD file by terryquigleysas · Pull Request #6151 · opensearch-project/security

terryquigleysas · 2026-05-19T11:24:12Z

This is very much a proposal / first draft for both issues addressed. I will defer to those with more extensive knowledge on both counts.

Description

[Describe what this change achieves]

Category (Enhancement, New feature, Maintenance, Documentation)
Why these changes are required?
Introduce an AGENTS.MD file to provide instructions to agents to improve the experience.
Uses https://github.com/terryquigleysas/OpenSearch/blob/main/AGENTS.md as a guide.
Also update the backporting instructions due to recent changes.

Issues Resolved

Improve the agentic experience.

Testing

We have found this to improve the agentic experience on our own applicatons.

Check List

New functionality includes testing
New functionality has been documented
New Roles/Permissions have a corresponding security dashboards plugin PR
API changes companion pull request created
Commits are signed per the DCO using --signoff

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

Update backport instructions. Signed-off-by: Terry Quigley <terry.quigley@sas.com>

github-actions · 2026-05-19T11:25:13Z

PR Reviewer Guide 🔍

(Review updated until commit `3776e9b`)

Here are some key observations to aid the review process:

🧪 No relevant tests
🔒 No security concerns identified
✅ No TODO sections
🔀 No multiple PR themes
⚡ No major issues detected

github-actions · 2026-05-19T12:24:25Z

Persistent review updated to latest commit bcaaf6f

github-actions · 2026-05-19T12:24:41Z

PR Code Suggestions ✨

Latest suggestions up to 3776e9b

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Verify minimum JDK version requirement Verify that JDK 21 is actually the minimum required version for this project. If the project still supports earlier JDK versions (e.g., JDK 11 or 17), this statement could mislead developers and break compatibility expectations. AGENTS.md [71] -Minimum JDK: 21. `JAVA_HOME` must be set. +Minimum JDK: 11. `JAVA_HOME` must be set. Suggestion importance[1-10]: 7 __ Why: This suggestion asks to verify the JDK version requirement, which is important for ensuring accurate documentation. However, it's a verification request rather than identifying a concrete issue, and the suggested change to JDK 11 appears speculative without evidence from the actual build configuration.	Medium
General	Verify OpenSearch version matches build Ensure the default OpenSearch version `3.7.0-SNAPSHOT` matches the actual current development version in `build.gradle`. An outdated version reference could confuse developers about which version they're building against. AGENTS.md [76] -opensearch_version = System.getProperty("opensearch.version", "3.7.0-SNAPSHOT") +opensearch_version = System.getProperty("opensearch.version", "2.19.0-SNAPSHOT") Suggestion importance[1-10]: 6 __ Why: The suggestion asks to verify the OpenSearch version matches `build.gradle`, which is reasonable for documentation accuracy. However, the proposed change to `2.19.0-SNAPSHOT` contradicts the suggestion's own concern about outdated versions and appears arbitrary without checking the actual build file.	Low
General	Avoid hardcoding LTS branch versions Confirm that `2.19` and `3.6` are the actual current LTS branches. Hardcoded branch names in documentation can quickly become outdated and mislead contributors about which branches require backports. AGENTS.md [202] -The most common backport targets are the `2.19` and `3.6` branches, which are the current Long-Term Support (LTS) releases. +The most common backport targets are the current Long-Term Support (LTS) release branches (check the repository for active LTS versions). Suggestion importance[1-10]: 5 __ Why: While the concern about hardcoded branch names becoming outdated is valid, the suggestion to make the documentation more generic reduces its practical usefulness for developers who need concrete examples. The current approach provides clear, actionable information even if it requires periodic updates.	Low

Previous suggestions

Suggestions up to commit 51287b7

Category	Suggestion	Impact
Possible issue	Verify minimum JDK version accuracy Verify that JDK 21 is actually the minimum required version for this project. If the project still supports earlier JDK versions (e.g., JDK 11 or 17), this statement could mislead contributors and break compatibility expectations. AGENTS.md [71] -Minimum JDK: 21. `JAVA_HOME` must be set. +Minimum JDK: 11 (or verify actual minimum version). `JAVA_HOME` must be set. Suggestion importance[1-10]: 7 __ Why: The suggestion asks to verify the minimum JDK version, which is reasonable since incorrect documentation could mislead contributors. However, this is a verification request rather than identifying a concrete error, so it doesn't warrant a higher score.	Medium
General	Use placeholder for version example The hardcoded version `3.7.0-SNAPSHOT` may become outdated quickly. Consider adding a note that this is an example and contributors should check the actual version in `build.gradle`, or use a placeholder like `X.Y.Z-SNAPSHOT`. AGENTS.md [76] -opensearch_version = System.getProperty("opensearch.version", "3.7.0-SNAPSHOT") +opensearch_version = System.getProperty("opensearch.version", "X.Y.Z-SNAPSHOT") # Check build.gradle for current version Suggestion importance[1-10]: 5 __ Why: The suggestion to use a placeholder version like `X.Y.Z-SNAPSHOT` is valid to prevent documentation staleness, but the impact is minor since this is example code showing the property name and format. The current version serves as a concrete example that may be more helpful than a placeholder.	Low

Suggestions up to commit a3e5fff

Category	Suggestion	Impact
General	Use placeholder for version example The hardcoded version `3.7.0-SNAPSHOT` may become outdated quickly. Consider using a placeholder like `X.Y.Z-SNAPSHOT` or adding a note that this is an example value that should be verified in the actual `build.gradle` file to avoid confusion. AGENTS.md [76] -opensearch_version = System.getProperty("opensearch.version", "3.7.0-SNAPSHOT") +opensearch_version = System.getProperty("opensearch.version", "X.Y.Z-SNAPSHOT") Suggestion importance[1-10]: 4 __ Why: While using a placeholder like `X.Y.Z-SNAPSHOT` could reduce maintenance burden, the current specific version `3.7.0-SNAPSHOT` provides a concrete example that may be more helpful for understanding the format. This is a minor documentation style preference with limited impact.	Low

Suggestions up to commit 2cba97a

Category	Suggestion	Impact
Possible issue	Verify minimum JDK version requirement Verify that JDK 21 is actually the minimum required version for this project. If the project still supports earlier JDK versions (e.g., JDK 11 or 17), this statement could mislead developers and AI agents into using incompatible language features or APIs. AGENTS.md [58] -Minimum JDK: 21. `JAVA_HOME` must be set. +Minimum JDK: 11. `JAVA_HOME` must be set. Suggestion importance[1-10]: 7 __ Why: This suggestion asks to verify the JDK version requirement, which is important for ensuring developers use the correct toolchain. However, it's a verification request rather than identifying a definite error, and the improved code assumes JDK 11 without evidence from the PR.	Medium
General	Verify OpenSearch version accuracy The hardcoded version `3.7.0-SNAPSHOT` may be outdated or incorrect. Ensure this matches the actual default version in `build.gradle` to prevent confusion when developers or agents reference this documentation. AGENTS.md [63] -opensearch_version = System.getProperty("opensearch.version", "3.7.0-SNAPSHOT") +opensearch_version = System.getProperty("opensearch.version", "2.x.x-SNAPSHOT") Suggestion importance[1-10]: 6 __ Why: The suggestion asks to verify the `opensearch_version` matches `build.gradle`, which is reasonable for documentation accuracy. However, it's a verification request and the proposed replacement `2.x.x-SNAPSHOT` appears arbitrary without evidence from the actual `build.gradle` file.	Low

Suggestions up to commit 233b222

Category	Suggestion	Impact
Possible issue	Verify minimum JDK version requirement Verify that JDK 21 is indeed the minimum required version for this project. If the project still supports earlier JDK versions (e.g., JDK 11 or 17), this statement could mislead developers and AI agents, potentially causing build failures or compatibility issues. AGENTS.md [58] -Minimum JDK: 21. `JAVA_HOME` must be set. +Minimum JDK: 11. `JAVA_HOME` must be set. Suggestion importance[1-10]: 7 __ Why: This suggestion asks to verify the JDK version requirement, which is important for build compatibility. However, it's a verification request rather than identifying a concrete issue, and the improved code suggests JDK 11 without evidence that this is correct.	Medium
General	Verify OpenSearch version accuracy Ensure the default OpenSearch version "3.7.0-SNAPSHOT" matches the actual current development version in `build.gradle`. An outdated version reference could confuse developers about which version they're building against. AGENTS.md [63] -opensearch_version = System.getProperty("opensearch.version", "3.7.0-SNAPSHOT") +opensearch_version = System.getProperty("opensearch.version", "2.x.x-SNAPSHOT") Suggestion importance[1-10]: 6 __ Why: The suggestion asks to verify the OpenSearch version matches `build.gradle`, which is reasonable for documentation accuracy. However, it's a verification request and the improved code suggests "2.x.x-SNAPSHOT" without evidence this is the correct version.	Low

Suggestions up to commit e2c528a

Category	Suggestion	Impact
Possible issue	Verify minimum JDK version requirement Verify that JDK 21 is indeed the minimum required version for this project. If the project still supports earlier JDK versions (e.g., JDK 11 or 17), this statement could mislead developers and AI agents, potentially causing build failures or incorrect environment setup. AGENTS.md [58] -Minimum JDK: 21. `JAVA_HOME` must be set. +Minimum JDK: 11. `JAVA_HOME` must be set. Suggestion importance[1-10]: 7 __ Why: The suggestion asks to verify the JDK version requirement, which is reasonable since incorrect documentation could mislead developers. However, this is a verification request rather than identifying a definite error, and the `improved_code` proposes JDK 11 without evidence that this is correct.	Medium
General	Verify OpenSearch version accuracy Ensure the default OpenSearch version `3.7.0-SNAPSHOT` accurately reflects the current development version in `build.gradle`. An outdated version reference could confuse developers about compatibility requirements and lead to build mismatches. AGENTS.md [63] -opensearch_version = System.getProperty("opensearch.version", "3.7.0-SNAPSHOT") +opensearch_version = System.getProperty("opensearch.version", "2.x.x-SNAPSHOT") Suggestion importance[1-10]: 6 __ Why: The suggestion asks to verify the `opensearch_version` value is current, which is valid maintenance advice. However, the `improved_code` proposes `2.x.x-SNAPSHOT` without evidence this is more accurate than `3.7.0-SNAPSHOT`, and this is primarily a verification request rather than a concrete issue.	Low

github-actions · 2026-05-19T14:12:45Z

Persistent review updated to latest commit e2c528a

github-actions · 2026-05-20T08:05:18Z

Persistent review updated to latest commit 233b222

github-actions · 2026-05-20T13:01:08Z

Persistent review updated to latest commit 2cba97a

cwperks · 2026-05-20T14:10:09Z

+
+## Build
+
+**Minimum JDK: 21.** `JAVA_HOME` must be set.


Any idea what happens when Agents.md file becomes outdated? Does the agent automatically understand that and update accordingly? I know where I'm at we talk about dynamic knowledge bases frequently to ensure that agents can work with up-to-date information.

On my own application I added a section to explicitly direct agents to keep it up to date. I can do the same here.

I'm pretty sure some agents already know to do this but I will add something.

cwperks · 2026-05-20T14:16:23Z

+When adding or removing a non-test scope dependency in `build.gradle`:
+
+1. Copy the library's `LICENSE.txt` and `NOTICE.txt` into `licenses/` as `<artifact>-LICENSE.txt` and `<artifact>-NOTICE.txt`.
+2. Run `./gradlew updateSHAs` to regenerate SHA checksum files.


This is actually disabled on this repo.

We certainly could re-enable it, but we'd be at the whim of upstream opensearch and constantly updating what's in licenses/ depending on changes in core's version catalog.

I'd be amenable to enabling this if we can likewise update the logic to exclude licenses that overlap from the core.

I know the performance-analyzer repo gets into a state where checks fail constantly and its very annoying.

Thanks, I'll remove it.

cwperks · 2026-05-20T14:18:38Z

+
+## Commits
+
+Run `./gradlew precommit` before every commit.


not relevant in this repo.

I'm definitely not opposed to adding a precommit hook though

Thanks, I'll remove it.

cwperks · 2026-05-20T14:19:15Z

+
+## Pull Requests
+
+- Always push to your personal fork. Never push directly to `opensearch-project/security` or to `main`.


yes and this is actually enforced now regardless of branch name! No maintainer can push to upstream.

cwperks · 2026-05-20T14:20:28Z

+```bash
+# Check out a new branch from the target release branch
+git fetch upstream
+git checkout -b backport/my-fix-2.x upstream/2.x


Let's not use 2.x here as that is a dead branch. Let's mention something about 2.19 being in LTS.

Thanks, I will change this.

cwperks · 2026-05-20T14:20:41Z

+2. Check out the target branch locally:
+   ```bash
+   git fetch upstream
+   git checkout -b backport/my-fix-2.x upstream/2.x


Signed-off-by: Terry Quigley <terry.quigley@sas.com>

github-actions · 2026-05-20T14:58:30Z

Persistent review updated to latest commit a3e5fff

Signed-off-by: Terry Quigley <terry.quigley@sas.com>

github-actions · 2026-05-20T15:19:19Z

Persistent review updated to latest commit 51287b7

github-actions · 2026-05-20T16:48:20Z

Persistent review updated to latest commit 3776e9b

Introduce an AGENTS.MD file

95dfa86

Update backport instructions. Signed-off-by: Terry Quigley <terry.quigley@sas.com>

terryquigleysas requested review from DarshitChanpura, RyanL1997, cwperks, derek-ho, finnegancarroll, nibix, reta, shikharj05 and willyborankin as code owners May 19, 2026 11:24

Merge branch 'main' into create_agents_md_file

bcaaf6f

Merge branch 'main' into create_agents_md_file

e2c528a

Merge branch 'main' into create_agents_md_file

233b222

Merge branch 'main' into create_agents_md_file

2cba97a

cwperks reviewed May 20, 2026

View reviewed changes

Comment thread AGENTS.md

cwperks reviewed May 20, 2026

View reviewed changes

Comment thread AGENTS.md

cwperks reviewed May 20, 2026

View reviewed changes

Add advice for keeping file up to date

a3e5fff

Signed-off-by: Terry Quigley <terry.quigley@sas.com>

Code review updates

51287b7

Signed-off-by: Terry Quigley <terry.quigley@sas.com>

Merge branch 'main' into create_agents_md_file

3776e9b


		## Pull Requests

		- Always push to your personal fork. Never push directly to `opensearch-project/security` or to `main`.

Conversation

terryquigleysas commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Issues Resolved

Testing

Check List

Uh oh!

github-actions Bot commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Reviewer Guide 🔍

(Review updated until commit 3776e9b)

Uh oh!

github-actions Bot commented May 19, 2026

Uh oh!

github-actions Bot commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Code Suggestions ✨

Previous suggestions

Uh oh!

github-actions Bot commented May 19, 2026

Uh oh!

github-actions Bot commented May 20, 2026

Uh oh!

github-actions Bot commented May 20, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cwperks May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented May 20, 2026

Uh oh!

github-actions Bot commented May 20, 2026

Uh oh!

github-actions Bot commented May 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

terryquigleysas commented May 19, 2026 •

edited

Loading

github-actions Bot commented May 19, 2026 •

edited

Loading

(Review updated until commit `3776e9b`)

github-actions Bot commented May 19, 2026 •

edited

Loading

cwperks May 20, 2026 •

edited

Loading