docs: document AI contribution policy and agent guidelines

AGENTS.md

@@ -0,0 +1,68 @@
+# Kroxylicious AI Agent Guidelines
+
+This file provides guidance for AI coding tools, such as GitHub Copilot and Claude Code, when working in Kroxylicious repositories.
+
+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 created with AI assistance must include an `Assisted-by` trailer identifying the tool and model.
+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 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 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.
+- 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, can supplement human review but do not replace it.
+  The decision to merge is always made by human committers following the project's [decision making](./GOVERNANCE.md#decision-making) framework.
+- 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 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 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
+
+Write code that is self-describing through clear naming and structure.
+A well-chosen name is almost always better than a comment.
+Names must convey intent and purpose, not implementation logic, which can become outdated as quickly as a stale comment.
+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/).
+Use `mvn verify` to build and test unless the repository's `AGENTS.md` specifies otherwise.
+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.

CONTRIBUTING.md

@@ -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 include a `README.md` with context, build, and usage instructions.
+
 ## How can I contribute
 
 You can contribute by:
@@ -31,10 +36,47 @@ 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, can supplement review but do not replace review by a Committer.
+Committers make merge decisions following the project's [decision-making](./GOVERNANCE.md#decision-making) framework.
+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 can use AI tools, such as LLMs and code assistants, when preparing contributions to Kroxylicious.
+As with any tool, the contributor is responsible for the quality of the result and for understanding what they submit.
+
+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 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 fully understand.
+* **Disclose AI usage.** If AI tools play a significant role in a contribution, note this in the pull request description.
+  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.
+  Using AI features in the same way as an IDE, such as code completion or spelling, does not require disclosure.
+  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 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.
+* **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 detail.
+
+### AGENTS.md
+
+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 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: