[philrz]

What's changing

• CONTRIBUTING.md: asks contributors to start with a conversation on Slack, and to get a maintainer's agreement, on Slack or in an issue, before opening a pull request. It says why, and that pull requests that skip this step may be closed without review. A new section on AI tools asks contributors to disclose their use, understand their change, approve every post themselves, and not point an agent at our issue list. It also drops the paragraph inviting people to pick missing functionality and add an operator in runtime/sam, which invites the kind of pull request this discourages.
• AGENTS.md (new): instructions for AI coding agents. An agent whose user can't push to this repo (gh api repos/superdb/super --jq .permissions.push) is told not to open a pull request without a maintainer's prior agreement, not to pick issues from our list that don't affect its user, and not to post anything without the user's approval. A short "Working on the code" section applies to everyone's agents, ours included, e.g., no comments that restate the code, and short commit messages.

Why

We keep getting unsolicited pull requests that look like an agent picked a recent issue from our list, often from accounts opening similar pull requests across many unrelated projects at once. Some are reasonable fixes, but writing the code is now the cheap part. The expensive part is review, and deciding whether a change fits the design, and an undiscussed pull request adds to that work. A written policy gives well-behaved agents a chance to steer their users away before opening a pull request. It also gives us something to link when we close one, instead of closing without comment.

Other projects have recently taken similar approaches, especially Sourcify (issues before pull requests, and an AGENTS.md that checks push access), LLVM (a human in the loop, and "extractive" contributions), and Kubernetes (disclosure in the PR description).

Closing comment

Once this merges, here's a comment we could use when closing a pull request under this policy (it could also be a GitHub saved reply):

Thanks for the pull request. We're closing it because it wasn't discussed with a maintainer first, as described in our contributing guidelines. This isn't a judgment of the code. If you have a use case this change would help with, please tell us about it on Slack and we'll go from there.

Notes

• GitHub now has repository settings that could back this up, such as a cap on how many pull requests a user without write access can have open, or limiting pull requests to collaborators. This PR doesn't change any settings, but we could discuss them separately.

This was drafted with Claude Code. I edited and reviewed it.

[mattnibs]

Idk maybe don't include this file so we are not ai vendor specific in this repo?

[philrz]

@mattnibs: Good call. I did a little digging and confirmed this was indeed a bit "belt & suspenders", so I just pushed a commit to drop the CLAUDE.md.

Per the Claude Code changelog I've confirmed that in recent versions, in absence of CLAUDE.md, a well-behaved agent should react to the AGENTS.md just the same. Having it in there would have covered corner cases like users on old Claude releases but that seems an unlikely exposure, so happy to spare us one more file in the repo.