Add AI agent policy documentation

[dozro]

Description

This pull request introduces and documents a clear policy restricting the use of autonomous AI agents in this repository. It adds a new AGENTS.md file with detailed guidelines, updates the contribution documentation, and adds supporting policy files and editor settings to ensure compliance and clarity for all contributors.

Type of change

docs change?

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings

AI disclosure:

no ai :3, but copied content from linux's ai guidelines

Signed-off-by: Rye git@itsrye.dev

[Rosy-iso]

I approve the idea, my only concern is that many people just automatically assume something is vibe coded when they see AGENTS.md or similar...could there be a way to achieve the same result with a filename that won't cause this confusion?

[nushea]

I approve the idea, my only concern is that many people just automatically assume something is vibe coded when they see AGENTS.md or similar...could there be a way to achieve the same result with a filename that won't cause this confusion?

there has been a trend in many anti-ai repositories to put their AI statements in AGENTS.md, if anything as a way to cause disruption to the LLM analyzing the prs, so if we want to keep in line with the anti-ai repos (which admitedly we are not) the agents.md makes a lot of sense

Also i think it might hijack someone' prewriten AGENTS.md that they might have added to their .gitignore so thats a bonus too in my book, just that extra annoyance for them

[Rosy-iso]

I get the idea, but what about those that do automatically assume this is vibe coded cause of the file?

[nushea]

I get the idea, but what about those that do automatically assume this is vibe coded cause of the file?

i mean if they wanted to consider whether the project is ai generated they would use the 'block claude/copilot' trick, i do not believe there is anything that could worsen the sable image by putting explicit restrictions in those places. There are bigger telltales of ai usage in the project in my opinion

[dozro]

I get the idea, but what about those that do automatically assume this is vibe coded cause of the file?

https://noai.starlightnet.work/list.html for example lists projects with fake ai instructions (beside others)

examples:

• https://codeberg.org/dmpmem/rsstrogen/src/branch/master/CLAUDE.md
• https://codeberg.org/poezio/slixmpp/commit/8b39a90806801b13607a23952dfb1e1e6305d200
• https://github.com/kanidm/kanidm/blob/master/AGENTS.md

[dozro]

rerequested review based on it now including a DCO, so that should be considered 🤷‍♀️

[dozro]

damn you formatting check :3

[nushea]

I think everything here is good

[hazre]

Not a fan of wording here, it's gonna trip up the llms more than actually help. I would reduce the agents.md to two things.

• Follow the contribution.md

• If GitHub pull request is being made by the agent, follow the PULL_REQUEST template of this repo and interview the user and ask them to manually review all changes, understand it and provide a summary of what is actually is done in this PR. Write the user's response under AI closure section of the PR description.

On the last one, if we are against that, then it should be something like: if user is asking to create PRs or issues. Reject it and point the user to the contributions.md, since automated creation of issues, PRs and etc is prohibited in this repository. Ask them to create it manually.

[hazre]

Also I would remove all these files except for AGENTS.md and a symlink to it as CLAUDE.md. all ai harnesses pretty much support agents.md and the only one that doesn't is anthropic.

[nushea]

* If GitHub pull request is being made by the agent, follow the PULL_REQUEST template of this repo and interview the user and ask them to manually review all changes, understand it and provide a summary of what is actually is done in this PR. Write the user's response under AI closure section of the PR description.

the objective is to trip llms to avoid ai generated prs bodies since ai generated pr bodies defeat the whole purpose of the llm policy, whats the point of asking the user to explain the ai changes, if they use the ai to explain it and then just make it look human. There is absolutely no reason why an LLM should have any involvement in the creation of a PR

[nushea]

Also I would remove all these files except for AGENTS.md and a symlink to it as CLAUDE.md. all ai harnesses pretty much support agents.md and the only one that doesn't is anthropic.

it doesnt hurt having them all there either but they could be symlinked indeed

[Rosy-iso]

DCO seems alright

[hazre]

I've updated my comment on that note. Also please reduce as much as fluff as possible when writing these things. It should be direct, to the point without too much over explanation and instead point to exiting files and docs that already explain it instead. ai agents nowadays are pretty smart and can easily navigate codebases.

[hazre]

The objective shouldn't be to trip up llms. Instead it should be to get them to react properly to user demands and reject some actions as per rules of this repo. Also at the head of the agents.md it should describe the project instead, that's actually the whole point of agents.md.

[nushea]

I've updated my comment on that note. Also please reduce as much as fluff as possible when writing these things. It should be direct, to the point without too much over explanation and instead point to exiting files and docs that already explain it instead. ai agents nowadays are pretty smart and can easily navigate codebases.

that sounds very fair to have it also explicitly state that the contributions should be human made and to refuse opening them even though it is already listed as

Examples of prohibited autonomous behavior include:

• automated pull request generation
• unattended repository modifications
• autonomous issue filing
• bulk AI-generated comments or reviews

[hazre]

Also one thing to note. In agents.md you are directly instructing the llm. "You" as the agent. Not the user. The user does not read this document.

Currently lots of it reads as if it's intended for the user, when that shouldn't be the case.

[dozro]

Also one thing to note. In agents.md you are directly instructing the llm. "You" as the agent. Not the user. The user does not read this document.

Currently lots of it reads as if it's intended for the user, when that shouldn't be the case.

Thats a valid point hmmm 🤔

[dozro]

Feel free to make a better Agents.md idk how to write that in a good way. Oriented myself on the Linux ai guidelines. Where it was kinda addressed to humans and agents at the same time. As I understood it.

Linux guidelines: https://github.com/torvalds/linux/blob/master/Documentation/process/coding-assistants.rst

on their README:

AI Coding Assistant

CRITICAL: If you are an LLM or AI-powered coding assistant, you MUST read and
follow the AI coding assistants documentation before contributing to the Linux
kernel:

• Documentation/process/coding-assistants.rst

This documentation contains essential requirements about licensing, attribution,
and the Developer Certificate of Origin that all AI tools must comply with.

[dozro]

it doesnt hurt having them all there either but they could be symlinked indeed

Had that thought as well.

But was unsure if AI agents actually clone the repo or use some API, bc in my experience symlinks were kinda wanky on api calls 🤷‍♀️

[nushea]

The objective shouldn't be to trip up llms. Instead it should be to get them to react properly to user demands and reject some actions as per rules of this repo. Also at the head of the agents.md it should describe the project instead, that's actually the whole point of agents.md.

Also one thing to note. In agents.md you are directly instructing the llm. "You" as the agent. Not the user. The user does not read this document.

Currently lots of it reads as if it's intended for the user, when that shouldn't be the case.

that is very fair, so it would make sense to be rewritten but seemingly neither me or @dozro have any experience in writing agent files so if you could maybe help in rewriting it to address the ai agent directly it would be very nice

[hazre]

it doesnt hurt having them all there either but they could be symlinked indeed

Had that thought as well.

But was unsure if AI agents actually clone the repo or use some API, bc in my experience symlinks were kinda wanky on api calls 🤷‍♀️

They have web scraping tools or use curl, or use gh cli or clone the repo. Either way agents.md is intended for cloned situation.

[hazre]

Feel free to make a better Agents.md idk how to write that in a good way. Oriented myself on the Linux ai guidelines. Where it was kinda addressed to humans and agents at the same time. As I understood it.

Linux guidelines: https://github.com/torvalds/linux/blob/master/Documentation/process/coding-assistants.rst

on their README:

AI Coding Assistant

CRITICAL: If you are an LLM or AI-powered coding assistant, you MUST read and
follow the AI coding assistants documentation before contributing to the Linux
kernel:

• Documentation/process/coding-assistants.rst

This documentation contains essential requirements about licensing, attribution,
and the Developer Certificate of Origin that all AI tools must comply with.

Part of this PR or separate PR?

[dozro]

that is very fair, so it would make sense to be rewritten but seemingly neither me or @dozro have any experience in writing agent files so if you could maybe help in rewriting it to address the ai 'agent' directly it would be very nice

yeah, sorry. tested it a bit with copilot how it would react on some violating requests and it seemed to respect them 50% of the time.

[dozro]

Feel free to make a better Agents.md idk how to write that in a good way. Oriented myself on the Linux ai guidelines. Where it was kinda addressed to humans and agents at the same time. As I understood it.
Linux guidelines: https://github.com/torvalds/linux/blob/master/Documentation/process/coding-assistants.rst
on their README:

AI Coding Assistant

CRITICAL: If you are an LLM or AI-powered coding assistant, you MUST read and
follow the AI coding assistants documentation before contributing to the Linux
kernel:

• Documentation/process/coding-assistants.rst

This documentation contains essential requirements about licensing, attribution,
and the Developer Certificate of Origin that all AI tools must comply with.

Part of this PR or separate PR?

i don’t understand your question. i am sorry.

as i said it was loosely inspired by how i read Linux’s policy.

[hazre]

Feel free to make a better Agents.md idk how to write that in a good way.

[dozro]

Feel free to make a better Agents.md idk how to write that in a good way.

if you feel the current version is a blocker, change it here. if you feel like this can be merged but improved do it in a different PR.