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

	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?

[SamBarker]

I think this is specific enough for the LLM, but influencing them is a bit tricky so alway open to suggestions

[PaulRMellor]

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

[SamBarker]

the agents file is for the llm and it will know what to put, I think.

[robobario]

LGTM, thanks @SamBarker

[tombentley]

"too large" is a big vague. It would be more helpful to the reader if we could explain what we mean in more concrete terms.

[tombentley]

"You" is assumed to be a human. We're basically assuming that there's a human in the loop for opening the PR. That might be what we want, or not. But either way we should be explicit about what our expectations are.

[tombentley]

I think we can be a bit clearer on this point: The project requires DCO on all commits. The DCO requires that signoff is done by a legal person. An AI is not a legal entity so it cannot sign off. When a person signs off on the commit they're taking responsibility for an AI assistance included in that commit.

[tombentley]

Suggested change

	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 fully understand.
	You should be able to answer reviewers' questions yourself, without recourse to AI.
	In particular, do not waste the time of other contributors by being a proxy between reviewers and an AI.

[tombentley]

TBH I'm in two minds on this one. I see that by requiring this you're putting the onus on the human to own what they're pushing. But the fact is that some commits are going to be entirely generated by API, and actually Generated-by or Coauthored-by seem to be to be more appropriate.

[tombentley]

I'm confused. Is this file intended to be read by the AI, by the human, or both?

[SamBarker]

The AI tools.

Readme/developer guides are for humans. Agents.md is for them (thus the content might overlap but its intended for different audiences).

[tombentley]

My understanding of a .github repo is that it serves as the default for other repos in the org. This is most relevant for those files which GitHub treats specially (like CONTRIBUTING.md). AFAIK AGENTS.md is not on that list (but maybe it will be added in the future).

So I don't know quite how to interpret this file:

• It is really intended to apply to all our other repos? Probably yes? But it's insufficient on its own to be useful.
• If yes, then do we know agents will actually find it (especially if the user has not checked out this repo).
• But if another repo has its own AGENTS.md file (which by the first point is necessary), won't that override this file (at least from a GitHub PoV).

It all just seems confusing how the various parties (AI, GitHub, Humans) are supposed to construct the full AGENTS.md context.

[tombentley]

Why repeat this here when it's mentioned in the CONTRIBUTING.md?

[tombentley]

We need to think what this means. My understanding is that an AI cannot do the DCO signoff, because it's not a legal entity. I would also contend that it should not be signing off on behalf of the person which we're assuming to be in the loop.

So the instruction should be the a coding agent or AI should not be signing off. And then we need a complementart instruction in CONTRIBUTING.md telling the human that they need to review and sign off on their genAI's commits.

[fvaleri]

I agree that a human sign-off is necessary. From a legal perspective, it provides a much safer layer of accountability.

[tombentley]

What does 'atomic' mean in this context? It sounds like it has a technical meaning, but you don't explain what it is.

[tombentley]

Do we do this ourselves? I've been seeing some humongous PRs recently >5kLOC.

[SamBarker]

We are not great at it no, but the more nudges we have in the right direction the better.

[fvaleri]

IMO PR size is not a good indicator of the time it takes to review.

Suggestion:

Focus on making commits small enough to be reviewed quickly, though keep in mind that logical complexity matters more than line count.

[tombentley]

This feels like it should be the first item in the list. Or I think it could be taken as read.

[tombentley]

This PR, not being in the kroxylicious repo, might not have crossed the radar of some people involved in the project. So I think it's worth getting wider community engagement on this PR via an email to the dev mailing list plus a mention on Slack.

[tombentley]

This is really a policy we're applying to committers. It's not relevant for non-committer contributors whether/how AI might be used in code review, nor the gating requirements. So I think we can take this out.

[tombentley]

We should also say something about the acceptable licenses of dependencies.

[tombentley]

I think this is actually subtle, and also highlights a way that our own IP handling could be better.

I'm not a lawyer, but my understanding the problem arises not from the reproduction of code that is copyrighted, but rather how that code is licensed. For example, I think it would be perfectly fine to copy code verbatim from Apache Kafka, because its license allows that, subject to things like preserving copyright information.

The improvement we could make concerns how we're enforcing source code copyright headers. Currently we insist that our header is used, and that header says "copyright Kroxylicious Authors", and has an ASL license. By insisting on that header we aren't able to copy ASL licensed code from other projects. But this problem comes from our own requirement to have that header, rather than being something that's actually legally necessary. IIRC Richard Fontana has said that copyright headers are not necessary, that copyright exists without them.

[k-wall]

"They must also note any AI tool involvement."

Firstly, there's duplication here with the Assisted-by header of the commit message. So do we really need both? What are we trying to achieve by having AI usage called out in the PR too? Is it just informational for the reviewers? Or is it record keeping?

If we decide we want AI usage called out on the PR, we should guide what we actually expect the contributors to do.

Would a tick box suffice?

[ ] If AI is used, I've added the Assisted-by header to my commit, stating the model used`

or do you want something more narrative?

Alternatively, we could use a workflow to detect the "Assisted-by" header on the commit, and flag that on PR in some systematic way (label?/description?)

[k-wall]

One question, but LGTM

[fvaleri]

Interesting. I left a few comments.

[fvaleri]

So if I want to work on repo X I also need to go and manually copy this AGENTS.md file content from this repo? Not the best experience IMO and something people will probably skip.

[fvaleri]

I agree that a human sign-off is necessary. From a legal perspective, it provides a much safer layer of accountability.

[fvaleri]

IMO PR size is not a good indicator of the time it takes to review.

Suggestion:

Focus on making commits small enough to be reviewed quickly, though keep in mind that logical complexity matters more than line count.

[fvaleri]

Commits of this PR do not respect the policy as Assisted-by is added before Signed-off-by. Anyway, why do we need to specify the exact ordering?

[fvaleri]

Do we also want to say something about refactoring? Should they always be separate PRs or only when they hide the actual changes.