kroxylicious · SamBarker · Mar 8, 2026 · Mar 8, 2026 · Mar 8, 2026 · Mar 9, 2026
@@ -0,0 +1,67 @@
+# Kroxylicious AI Agent Guidelines
+
+This file provides guidance to AI coding tools (such as GitHub Copilot, Claude Code, and similar) when working on repositories within the Kroxylicious organisation.
-This file provides guidance to AI coding tools (such as GitHub Copilot, Claude Code, and similar) when working on repositories within the Kroxylicious organisation.
+This file provides guidance for AI coding tools, such as GitHub Copilot and Claude Code, when working in Kroxylicious repositories.
-This file provides guidance to AI coding tools (such as GitHub Copilot, Claude Code, and similar) when working on repositories within the Kroxylicious organisation.
+This file provides guidance for AI coding tools, such as GitHub Copilot and Claude Code, when working in Kroxylicious repositories.
+
+Contributors using AI tools should ensure their tool has access to this file and any repository-specific `AGENTS.md`.
-Contributors using AI tools should ensure their tool has access to this file and any repository-specific `AGENTS.md`.
+Contributors using AI tools must ensure the tools can access this file and any repository-specific `AGENTS.md` file.
-Contributors using AI tools should ensure their tool has access to this file and any repository-specific `AGENTS.md`.
+Contributors using AI tools must ensure the tools can access this file and any repository-specific `AGENTS.md` file.
+Please also read the [Contributing Guidelines](./CONTRIBUTING.md), in particular the section on [Use of AI Assistance](./CONTRIBUTING.md#use-of-ai-assistance).
+
+## Contribution Process
+
+### DCO Sign-off
+
+All commits must be signed off with the Developer Certificate of Origin (DCO).
+Use `git commit -s` to add the sign-off automatically.
+
+### Assisted-by Trailer
+
+Commits produced with AI assistance must include an `Assisted-by` trailer identifying the tool and model.
-Commits produced with AI assistance must include an `Assisted-by` trailer identifying the tool and model.
+Commits created with AI assistance must include an `Assisted-by` trailer identifying the tool and model.
-Commits produced with AI assistance must include an `Assisted-by` trailer identifying the tool and model.
+Commits created with AI assistance must include an `Assisted-by` trailer identifying the tool and model.
+The trailer should be added to the commit message body, after the sign-off:
-The trailer should be added to the commit message body, after the sign-off:
+Add the trailer to the commit message body after the sign-off:
-The trailer should be added to the commit message body, after the sign-off:
+Add the trailer to the commit message body after the sign-off:
+
+```
+<commit message>
+
+Signed-off-by: Name <email>
+Assisted-by: <Tool and model> <noreply@example.com>
+```
+
+### Commit Discipline
+
+- Each commit should be atomic and represent a single logical change.
- Each commit should be atomic and represent a single logical change.
+- Each commit must be atomic and represent a single logical change.
- Each commit should be atomic and represent a single logical change.
+- Each commit must be atomic and represent a single logical change.
+- Keep commits small enough to be reviewed in a few minutes.
+- Commit messages should explain *why* the change was made, not *what* changed. Reviewers read diffs — they can see what changed. Focus on the problem being solved, the reasoning, or the decision made.
- Commit messages should explain *why* the change was made, not *what* changed. Reviewers read diffs — they can see what changed. Focus on the problem being solved, the reasoning, or the decision made.
+- Commit messages should explain *why* the change was made, not *what* changed. Reviewers can see the code changes in the diff. Focus on the problem being solved, the reasoning, or the decision made.
- Commit messages should explain *why* the change was made, not *what* changed. Reviewers read diffs — they can see what changed. Focus on the problem being solved, the reasoning, or the decision made.
+- Commit messages should explain *why* the change was made, not *what* changed. Reviewers can see the code changes in the diff. Focus on the problem being solved, the reasoning, or the decision made.
+
+### Pull Requests
+
+- A pull request should address a single cohesive goal. Do not bundle unrelated changes together — each PR should tell a clear story that a reviewer can follow from start to finish.
+- All changes must be submitted as pull requests.
- All changes must be submitted as pull requests.
+- Submit all changes as pull requests.
- All changes must be submitted as pull requests.
+- Submit all changes as pull requests.
+- At least one human [Committer](./COMMITTERS.md) must review and approve a pull request before it is merged.
+  Automated or AI-assisted reviews (such as security or style checks) may supplement but do not substitute for human review.
-  Automated or AI-assisted reviews (such as security or style checks) may supplement but do not substitute for human review.
+  Automated or AI-assisted reviews, such as security or style checks, can supplement human review but do not replace it.
-  Automated or AI-assisted reviews (such as security or style checks) may supplement but do not substitute for human review.
+  Automated or AI-assisted reviews, such as security or style checks, can supplement human review but do not replace it.
+  The decision to merge is always made by human Committer(s) following the project's [decision making](./GOVERNANCE.md#decision-making) framework.
-  The decision to merge is always made by human Committer(s) following the project's [decision making](./GOVERNANCE.md#decision-making) framework.
+  The decision to merge is always made by human committers following the project's [decision making](./GOVERNANCE.md#decision-making) framework.
-  The decision to merge is always made by human Committer(s) following the project's [decision making](./GOVERNANCE.md#decision-making) framework.
+  The decision to merge is always made by human committers following the project's [decision making](./GOVERNANCE.md#decision-making) framework.
+- PR descriptions should focus on the problem being addressed, the approach taken, and any trade-offs or alternatives considered. Note any AI tool involvement.
- PR descriptions should focus on the problem being addressed, the approach taken, and any trade-offs or alternatives considered. Note any AI tool involvement.
+- PR descriptions must focus on the problem being addressed, the approach taken, and any trade-offs or alternatives considered. They must also note any AI tool involvement.
- PR descriptions should focus on the problem being addressed, the approach taken, and any trade-offs or alternatives considered. Note any AI tool involvement.
+- PR descriptions must focus on the problem being addressed, the approach taken, and any trade-offs or alternatives considered. They must also note any AI tool involvement.
+- Ensure all CI checks pass before requesting review.
+
+### Conciseness
+
+Be concise and efficient in all generated content.
+Do not produce filler, boilerplate explanations, or unnecessary verbosity.
+Stay focused on the goal at hand — reviewers' time is limited and every line should earn its place.
-Stay focused on the goal at hand — reviewers' time is limited and every line should earn its place.
+Stay focused on the goal at hand — reviewers' time is limited and every line should add value.
-Stay focused on the goal at hand — reviewers' time is limited and every line should earn its place.
+Stay focused on the goal at hand — reviewers' time is limited and every line should add value.
+
+### Copyright and Licensing
+
+Do not reproduce copyrighted material in generated code, documentation, or other content.
+If you are aware of controls or configuration that reduce the risk of reproducing copyrighted content, ensure they are active.
-If you are aware of controls or configuration that reduce the risk of reproducing copyrighted content, ensure they are active.
+If you are aware of controls or configuration that reduce or remove the risk of reproducing copyrighted content, ensure they are active.
-If you are aware of controls or configuration that reduce the risk of reproducing copyrighted content, ensure they are active.
+If you are aware of controls or configuration that reduce or remove the risk of reproducing copyrighted content, ensure they are active.
+All contributions must be compatible with the project's [license](./LICENSE).
+
+### Naming and Comments
+
+Prefer code that is self-describing through clear naming and structure.
-Prefer code that is self-describing through clear naming and structure.
+Write code that is self-describing through clear naming and structure.
-Prefer code that is self-describing through clear naming and structure.
+Write code that is self-describing through clear naming and structure.
+A well-chosen name is almost always better than a comment.
+Names should convey intent and purpose, not encode implementation logic — logic in a name will drift from reality just as quickly as a stale comment.
-Names should convey intent and purpose, not encode implementation logic — logic in a name will drift from reality just as quickly as a stale comment.
+Names must convey intent and purpose, not implementation logic, which can can become outdated as quickly as a stale comment.
-Names should convey intent and purpose, not encode implementation logic — logic in a name will drift from reality just as quickly as a stale comment.
+Names must convey intent and purpose, not implementation logic, which can can become outdated as quickly as a stale comment.
+Reserve comments for reasoning or constraints that good naming alone cannot convey, but if you find yourself reaching for a comment, first consider whether a rename would make it unnecessary.
-Reserve comments for reasoning or constraints that good naming alone cannot convey, but if you find yourself reaching for a comment, first consider whether a rename would make it unnecessary.
+Use comments for reasoning or constraints that good naming alone cannot convey, but if you find yourself reaching for a comment, first consider whether a rename would make it unnecessary.
-Reserve comments for reasoning or constraints that good naming alone cannot convey, but if you find yourself reaching for a comment, first consider whether a rename would make it unnecessary.
+Use comments for reasoning or constraints that good naming alone cannot convey, but if you find yourself reaching for a comment, first consider whether a rename would make it unnecessary.
+
+## Technical Foundations
+
+Kroxylicious is built with Java and [Apache Maven](https://maven.apache.org/).
+Individual repositories will have their own `AGENTS.md` with specific build commands, architecture details, coding conventions, and testing expectations.
-Individual repositories will have their own `AGENTS.md` with specific build commands, architecture details, coding conventions, and testing expectations.
+Individual repositories typically include an `AGENTS.md` file with build commands, architecture details, coding conventions, and testing expectations.
-Individual repositories will have their own `AGENTS.md` with specific build commands, architecture details, coding conventions, and testing expectations.
+Individual repositories typically include an `AGENTS.md` file with build commands, architecture details, coding conventions, and testing expectations.
+
+When working on a specific repository, always prefer guidance from that repository's `AGENTS.md` over this file for technical matters.
@@ -6,6 +6,11 @@ This project and everyone participating in it is governed by the [Code of Conduc
 By participating, you are expected to uphold this code. 
 Any unacceptable behavior should be reported to [kroxylicious-admins@redhat.com](mailto:kroxylicious-admins@redhat.com).
 
+## About the Project
+
+Kroxylicious is a Java project built with [Apache Maven](https://maven.apache.org/).
+Individual repositories may have additional details in their `README.md` or `AGENTS.md` files.
+
 ## How can I contribute
 
 You can contribute by:
@@ -31,10 +36,50 @@ in your pull request. Alternatively, to signoff a bunch of commits you can use `
 
 All changes which are to be committed in project source control must be reviewed by at least one [Committer](COMMITTERS.md) before being merged.
 If the change is being authored by someone who is a Committer, that change must be reviewed by at least one other Committer before being merged.
+Automated or AI-assisted reviews (such as security or style checks) may supplement but do not substitute for review by a Committer.
-Automated or AI-assisted reviews (such as security or style checks) may supplement but do not substitute for review by a Committer.
+Automated or AI-assisted reviews, such as security or style checks, can supplement review but do not replace review by a Committer.
-Automated or AI-assisted reviews (such as security or style checks) may supplement but do not substitute for review by a Committer.
+Automated or AI-assisted reviews, such as security or style checks, can supplement review but do not replace review by a Committer.
+The decision to merge is always made by Committer(s) following the project's [decision making](./GOVERNANCE.md#decision-making) framework.
-The decision to merge is always made by Committer(s) following the project's [decision making](./GOVERNANCE.md#decision-making) framework.
+Committers make merge decisions following the project's [decision-making](./GOVERNANCE.md#decision-making) framework.
-The decision to merge is always made by Committer(s) following the project's [decision making](./GOVERNANCE.md#decision-making) framework.
+Committers make merge decisions following the project's [decision-making](./GOVERNANCE.md#decision-making) framework.
+Pull requests should be focused on a single goal and sized for effective review.
-Pull requests should be focused on a single goal and sized for effective review.
+Pull requests must focus on a single goal and be sized for effective review.
-Pull requests should be focused on a single goal and sized for effective review.
+Pull requests must focus on a single goal and be sized for effective review.
+We may close pull requests that are unfocused or too large to review effectively, and ask the contributor to break them into smaller, more reviewable changes.
+
 The GitHub teams `@kroxylicious/code-reviewers` and `@kroxylicious/doc-reviewers` can be used to request a PR review from contributors.
 
 If you're willing to provide code and/or reviews to others then let one of the [project managers](PMs.md) know and we can add you to the relevant GitHub team.
 
+## Use of AI Assistance
+
+Contributors may use AI tools (such as LLMs, code assistants, and similar) when preparing contributions to Kroxylicious.
-Contributors may use AI tools (such as LLMs, code assistants, and similar) when preparing contributions to Kroxylicious.
+Contributors can use AI tools, such as LLMs and code assistants, when preparing contributions to Kroxylicious.
-Contributors may use AI tools (such as LLMs, code assistants, and similar) when preparing contributions to Kroxylicious.
+Contributors can use AI tools, such as LLMs and code assistants, when preparing contributions to Kroxylicious.
+Like any tool, what matters is the quality of the result and that the contributor understands what they are submitting.
-Like any tool, what matters is the quality of the result and that the contributor understands what they are submitting.
+As with any tool, the contributor is responsible for the quality of the result and for understanding what they submit.
-Like any tool, what matters is the quality of the result and that the contributor understands what they are submitting.
+As with any tool, the contributor is responsible for the quality of the result and for understanding what they submit.
+
+When you submit a contribution you are the contributor, regardless of what tools you used to produce it.
+You are responsible for understanding what you are contributing and ensuring it meets the project's standards.
-When you submit a contribution you are the contributor, regardless of what tools you used to produce it.
-You are responsible for understanding what you are contributing and ensuring it meets the project's standards.
+You are responsible for understanding your contribution and ensuring that it meets project standards, regardless of the tools used.
-When you submit a contribution you are the contributor, regardless of what tools you used to produce it.
-You are responsible for understanding what you are contributing and ensuring it meets the project's standards.
+You are responsible for understanding your contribution and ensuring that it meets project standards, regardless of the tools used.
+
+### Requirements
+
+* **You are the contributor.** When you sign off the [DCO](./DCO.txt), you are certifying the contribution as your own.
-* **You are the contributor.** When you sign off the [DCO](./DCO.txt), you are certifying the contribution as your own.
+* **You are the contributor.** When you sign off the [DCO](./DCO.txt), you certify the contribution as your own.
-* **You are the contributor.** When you sign off the [DCO](./DCO.txt), you are certifying the contribution as your own.
+* **You are the contributor.** When you sign off the [DCO](./DCO.txt), you certify the contribution as your own.
+  AI-generated or AI-assisted content does not change this obligation.
+* **Understand your contribution.** You must have a clear understanding of what your contribution does and why.
+  Do not submit code, documentation, or other content that you do not understand.
-  Do not submit code, documentation, or other content that you do not understand.
+  Do not submit code, documentation, or other content that you do not fully understand.
-  Do not submit code, documentation, or other content that you do not understand.
+  Do not submit code, documentation, or other content that you do not fully understand.
+* **Disclose AI usage.** If AI tools played a significant role in producing a contribution, note this in the pull request description.
-* **Disclose AI usage.** If AI tools played a significant role in producing a contribution, note this in the pull request description.
+* **Disclose AI usage.** If AI tools play a significant role in a contribution, note this in the pull request description.
-* **Disclose AI usage.** If AI tools played a significant role in producing a contribution, note this in the pull request description.
+* **Disclose AI usage.** If AI tools play a significant role in a contribution, note this in the pull request description.
+  Commits should include an `Assisted-by` trailer identifying the tool and model used (e.g. `Assisted-by: Claude Opus 4.6 <noreply@anthropic.com>`).
-  Commits should include an `Assisted-by` trailer identifying the tool and model used (e.g. `Assisted-by: Claude Opus 4.6 <noreply@anthropic.com>`).
+  Commits must include an `Assisted-by` trailer that identifies the tool and model used (for example, `Assisted-by: Claude Opus 4.6 <noreply@anthropic.com>`).
-  Commits should include an `Assisted-by` trailer identifying the tool and model used (e.g. `Assisted-by: Claude Opus 4.6 <noreply@anthropic.com>`).
+  Commits must include an `Assisted-by` trailer that identifies the tool and model used (for example, `Assisted-by: Claude Opus 4.6 <noreply@anthropic.com>`).
+  Most AI coding tools can be configured to add this automatically — see the repository's `AGENTS.md` for details.
+  Use of AI features in the same way you would use an IDE — code completion, spelling, and the like — does not require disclosure.
-  Use of AI features in the same way you would use an IDE — code completion, spelling, and the like — does not require disclosure.
+Using AI features in the same way as an IDE, such as code completion or spelling, does not require disclosure.
-  Use of AI features in the same way you would use an IDE — code completion, spelling, and the like — does not require disclosure.
+Using AI features in the same way as an IDE, such as code completion or spelling, does not require disclosure.
+  Disclosure is expected when AI tools are used to generate substantial content such as functions, tests, documentation, or design approaches.
-  Disclosure is expected when AI tools are used to generate substantial content such as functions, tests, documentation, or design approaches.
+  Disclosure is required when AI tools are used to generate substantial content such as functions, tests, documentation, or design approaches.
-  Disclosure is expected when AI tools are used to generate substantial content such as functions, tests, documentation, or design approaches.
+  Disclosure is required when AI tools are used to generate substantial content such as functions, tests, documentation, or design approaches.
+* **Ensure originality and licensing compliance.** AI-generated content must not reproduce copyrighted material.
+  You are responsible for verifying that your contribution does not introduce intellectual property or licensing concerns
+  incompatible with the project's [license](./LICENSE). Where your AI tool offers controls to reduce the risk of
+  reproducing copyrighted content, ensure they are enabled.
-  You are responsible for verifying that your contribution does not introduce intellectual property or licensing concerns
-  incompatible with the project's [license](./LICENSE). Where your AI tool offers controls to reduce the risk of
-  reproducing copyrighted content, ensure they are enabled.
+  You must verify that your contribution does not introduce intellectual property or licensing issues that are incompatible with the project's [License](./LICENSE). If your AI tool provides controls to reduce the risk of reproducing copyrighted content, make sure that they are enabled.
-  You are responsible for verifying that your contribution does not introduce intellectual property or licensing concerns
-  incompatible with the project's [license](./LICENSE). Where your AI tool offers controls to reduce the risk of
-  reproducing copyrighted content, ensure they are enabled.
+  You must verify that your contribution does not introduce intellectual property or licensing issues that are incompatible with the project's [License](./LICENSE). If your AI tool provides controls to reduce the risk of reproducing copyrighted content, make sure that they are enabled.
+* **Meet the same quality bar.** AI-assisted contributions are reviewed to the same standard as any other contribution.
+  Code must be correct, maintainable, tested, and consistent with project conventions.
+  We may close pull requests where the contributor does not appear to understand the contribution they have submitted.
-  We may close pull requests where the contributor does not appear to understand the contribution they have submitted.
+  We may close pull requests if the contributor does not demonstrate an understanding of the submitted changes.
-  We may close pull requests where the contributor does not appear to understand the contribution they have submitted.
+  We may close pull requests if the contributor does not demonstrate an understanding of the submitted changes.
+* **Be concise.** AI tools can generate text faster than reviewers can read it.
-* **Be concise.** AI tools can generate text faster than reviewers can read it.
+* **Be concise.** AI tools can generate content faster than reviewers can read it.
-* **Be concise.** AI tools can generate text faster than reviewers can read it.
+* **Be concise.** AI tools can generate content faster than reviewers can read it.
+  Contributions, PR descriptions, and issue comments should be clear, focused, and free of unnecessary verbosity.
-  Contributions, PR descriptions, and issue comments should be clear, focused, and free of unnecessary verbosity.
+  Contributions, PR descriptions, and issue comments should be clear, focused, and free of unnecessary detail.
-  Contributions, PR descriptions, and issue comments should be clear, focused, and free of unnecessary verbosity.
+  Contributions, PR descriptions, and issue comments should be clear, focused, and free of unnecessary detail.
+
+### AGENTS.md
+
+Individual repositories within the Kroxylicious organisation may include an `AGENTS.md` file.
-Individual repositories within the Kroxylicious organisation may include an `AGENTS.md` file.
+Individual repositories within the Kroxylicious organisation can include an `AGENTS.md` file.
-Individual repositories within the Kroxylicious organisation may include an `AGENTS.md` file.
+Individual repositories within the Kroxylicious organisation can include an `AGENTS.md` file.
+These files provide AI tools with project-specific context such as build instructions, architecture, coding conventions, and testing expectations.
+If you are using an AI tool to help prepare a contribution, ensure it has access to the relevant `AGENTS.md` so that its output aligns with project norms.
-If you are using an AI tool to help prepare a contribution, ensure it has access to the relevant `AGENTS.md` so that its output aligns with project norms.
+If you use an AI tool to help prepare a contribution, ensure that it can access the relevant `AGENTS.md` so that its output aligns with project conventions.
-If you are using an AI tool to help prepare a contribution, ensure it has access to the relevant `AGENTS.md` so that its output aligns with project norms.
+If you use an AI tool to help prepare a contribution, ensure that it can access the relevant `AGENTS.md` so that its output aligns with project conventions.
+
 ## I just have a question
 
 If you encounter any issues while using Kroxylicious, you can get help using: