docs: document AI contribution policy and agent guidelines

[SamBarker]

Summary

Addresses #26 — documenting how AI may be used when crafting contributions to the project.

• Adds an "Use of AI Assistance" section to CONTRIBUTING.md establishing the project's position: AI tools are permitted, but the contributor owns what they submit, must understand it, and must disclose significant AI usage.
• Adds an "About the Project" section to CONTRIBUTING.md noting the Java/Maven foundation.
• Clarifies the PR review section: AI-assisted reviews supplement but do not substitute for Committer review; merge decisions follow the project's decision making framework.
• Adds an org-level AGENTS.md providing AI coding tools with process expectations (DCO, commit discipline, PR standards, naming conventions). Individual repositories can add their own AGENTS.md with repo-specific technical details.

Why Assisted-by rather than Apache's Generated-by

Apache's Generated-by trailer is primarily about provenance tracking — an audit trail so the foundation can later query "which artifacts did model X generate?" if licensing concerns emerge around a model's training data. The focus is on the output's origin.

Kroxylicious's Assisted-by trailer is primarily about contributor responsibility. The policy's core message is "you are the contributor" — the trailer reinforces that the human is in the driving seat and the tool assisted them, rather than implying the tool produced the output and the human accepted it. The DCO sign-off already establishes legal accountability; Assisted-by extends that spirit to tooling disclosure.

In practice, both provide the same audit trail if needed. The difference is philosophical: Generated-by frames the tool as the actor, Assisted-by frames the contributor as the actor. The latter is more consistent with this project's emphasis on contributor ownership and understanding.

References consulted

• Apache Software Foundation — Generative Tooling Guidance
• IBM/Sarama — AI Assistance
• CNCF Foundation — AI contribution policy discussion
• manusa/actions-setup-minikube — AGENTS.md example

Test plan

• Review CONTRIBUTING.md for tone, completeness, and consistency with governance model
• Review AGENTS.md for clarity as instructions to AI tools
• Verify links to GOVERNANCE.md#decision-making, DCO.txt, and LICENSE resolve correctly
• Discuss whether the Assisted-by trailer format meets the project's needs

🤖 Generated with Claude Code

[tombentley]

@k-wall's issue gave the following reasons for wanting an AI contribution policy:

guide contributors as to acceptable use of AI, attribution, and the avoidance to licensing conflicts.

I think there are broadly two way we can look at those things:

1. What's legally necessary to protect the project.

   • I think it could be a serious problem is someone contributed changes which later we found to have transcluded copyrighted material. In CONTRIBUTING we should at least be requesting people turn on those controls in their AI's configuration which try to address this. And in AGENTS.md we should say something to instruct the agent to turn that up to the max, or to not generate anything at all and tell the developer if it lacks such controls. Perhaps we should also look into tools which can detect snippets of copyrighted material.
   • My understanding of US copyright law is that AI generated content is thought to not be copyrightable. In principle that could mean that over time there is less copyrightable code in the project upon which we can assert our license conditions. In order words, if contributors end up rewriting more and more of the code base using these tools we're watering down our ability to enforce our own licensing. Using Assisted-By will make it easier to figure out that this is the case. But it makes it easier for both us, and someone hostile to the goals of the project, so it's a double edged sword.
   • Likewise using Assisted-By makes it easier for someone to identify projects which have accepted lots of contributions from particular model. Perhaps that becomes a risk further down the line if it became apparent the model was trained on copyrighted data, or if there was a change in copyright law in some jurisdiction.

2. What's socially necessary to protect the project. We have not yet been deluged by AI-authored slop, though it seems likely to happen sooner or later.

   • Are we acting too soon, before we've seen how our contributors are actually using AI?

   • If now is the time to act, let's be clear that the rules should be about preserving community bandwidth. AIs can generate words a lot fast that we can consume them, and contributors need to be respectful of that. So I think the CONTRIBUTING should have this bit from the Sarama example you linked to:

     If you open a pull request you must be able to clearly explain what your changes do and how they alter the behaviour of Sarama without relying upon AI tools or prompting to roundtrip the reviewer's questions. If you cannot confidently explain and defend your contribution during review, do not submit it until you can.

     And I would add:

     We will close PRs where we suspect the contributor does not understand the code they're contributing without recourse to an AI.

   • I also liked this bit:

     AI assistance may be used when drafting issues, proposals, or discussion posts, but a human must remain fully in the loop and all AI-generated content must be reviewed, fact-checked, and edited before submission. Ensure your prompts steer it to remove unnecessary fluff, verbosity, filler and irrelevant content.

Finally, It's not clear to me that AGENTS.md is really an adopted thing that AIs are likely to respect. Certainly my own conversation with an AI suggested it was an emerging rather than recognised standard. It suggested symlinking to .cursorrules or .clinerules for the time being.

[k-wall]

I like the suggestions that @tombentley is making under the 2) bullet.

[SamBarker]

Open question: AI-assisted thinking vs AI-assisted production

One scenario worth considering: a contributor discusses design options with an AI tool but then writes the code and PR themselves, without the AI being directly involved in producing the contribution.

Under this policy, we don't think this requires disclosure. The contributor understood the problem, evaluated the options, and wrote the code — the AI influenced their thinking in much the same way that reading a blog post, discussing ideas with a colleague, or whiteboarding a design would. The policy is concerned with AI tools producing the content of a contribution, not with how a contributor arrived at their ideas.

This also helps clarify the intent behind "played a significant role in producing a contribution" — it's about the production of the submitted content, not about the contributor's broader learning or decision-making process.

Does this reading match others' expectations, or should the policy say something explicit about this distinction?

[k-wall]

Does this reading match others' expectations, or should the policy say something explicit about this distinction?

It matches my expectations. No need to say anything explicit.

[rgodfrey]

LGTM

[k-wall]

LGTM, thanks @SamBarker

[PaulRMellor]

Looks good. I left a few suggestions to improve readability and reduce ambiguity.

[PaulRMellor]

Suggested change

	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.

[PaulRMellor]

Suggested change

	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.

[PaulRMellor]

Suggested change

	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.

[PaulRMellor]

Suggested change

	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:

[PaulRMellor]

Do we need to say that the project requires that this format is followed exactly?

[PaulRMellor]

Is the tool email to use clear?
Would people know what to add there beyond a placeholder

[PaulRMellor]

Suggested change

	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.

[PaulRMellor]

Suggested change

	* **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.

[PaulRMellor]

Suggested change

	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.

[PaulRMellor]

Suggested change

	Individual repositories within the Kroxylicious organisation may include an `AGENTS.md` file.
	Individual repositories within the Kroxylicious organisation can include an `AGENTS.md` file.

[PaulRMellor]

Suggested change

	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.