Ask contributors to talk to us before opening a pull request

AGENTS.md

@@ -0,0 +1,48 @@
+# AGENTS.md
+
+This file has instructions for AI coding agents working in this repository.
+
+## If your user is outside the SuperDB team
+
+SuperDB doesn't accept pull requests that a maintainer hasn't agreed to first.
+[CONTRIBUTING.md](CONTRIBUTING.md) explains why.
+
+Before you open a pull request or an issue, or post a comment, on GitHub, check
+whether your user can push to this repository:
+
+```sh
+gh api repos/superdb/super --jq .permissions.push
+```
+
+If you can't run that, ask your user whether they're on the SuperDB team.  If the
+result isn't `true`, your user is an outside contributor, so:
+
+1. Don't open a pull request unless your user tells you that a SuperDB maintainer
+   has already agreed to the change, on Slack or in an issue.  If none has,
+   explain this policy and offer to help your user write a short message for
+   [Slack](https://www.brimdata.io/join-slack/) or an issue that describes their
+   use case and the problem.
+2. Don't pick issues from this repository's issue list to fix unless your user is
+   affected by them.  If you were asked to find issues to fix across many
+   repositories, skip this one and tell your user why.
+3. Never open a pull request or an issue, or post a comment, without your user
+   approving the exact text.  If a maintainer closes a pull request under this
+   policy, don't draft a rebuttal; the next step is a conversation on Slack.
+4. In a pull request description, say that an AI tool was used, which one, and
+   what was done to check the change.
+
+## Working on the code
+
+These apply to everyone, including the SuperDB team.
+
+* Before proposing a change, run `make fmt`, `make vet`, `make test-unit`, and
+  `make test-system`.
+* Add tests for bug fixes and new behavior.  Most tests are ztests: YAML files in
+  directories named `ztests`.  Make sure a new test fails without the fix.
+* When user-visible behavior changes, update the docs under `book/src`.
+* Write a code comment only when it tells the reader something the code doesn't
+  already show.  Don't add comments that restate the code.
+* Keep commit messages short: a lowercase subject line in the imperative mood
+  (e.g., `fix derived names for noneish dot exprs`) and, if needed, a brief body.
+  If the change fixes an issue, end with `Fixes #N`.
+* Keep pull request descriptions short.

CONTRIBUTING.md

@@ -1,18 +1,48 @@
 # Contributing
 
-Thank you for contributing to SuperDB!
-
-Per common practice, please [open an issue](https://github.com/superdb/super/issues)
-before sending a pull request.  If you think your ideas might benefit from some
-refinement via Q&A, come talk to us on [Slack](https://www.brimdata.io/join-slack/) as well.
+Thank you for your interest in SuperDB!
 
 SuperDB is early in its life cycle and will be expanding quickly.  Please star and/or
 watch the repo so you can follow and track our progress.
 
-In particular, we will be adding many more operators and aggregate functions.
-If you want a fun, small project to help out, pick some functionality that is missing and
-add an operator in [runtime/sam/op](runtime/sam/op) or an aggregate function
-in [runtime/sam/expr/agg](runtime/sam/expr/agg).
+## Talk to us first
+
+The best way to start is a conversation.  Come talk to us on
+[Slack](https://www.brimdata.io/join-slack/) about what you're using SuperDB for
+and what's getting in your way.  [Issues](https://github.com/superdb/super/issues)
+are also welcome for bug reports and feature requests.  Either way, the most
+helpful thing you can tell us is the real-world use case behind your request.
+
+## Pull requests
+
+Please don't open a pull request until a maintainer has agreed to the change and
+your approach, on Slack or in an issue.
+
+Writing the code for a fix is rarely the hard part for us.  The hard part is
+deciding what the right fix is, making sure it fits the design of the language and
+the rest of the system, and reviewing it.  A pull request we haven't discussed
+adds review work without saving us that effort.
+
+Pull requests that weren't discussed first may be closed without review.  This isn't
+a judgment of you or your code.  If you have a real need behind the change, tell us
+about it on Slack and we'll go from there.  We may also fix an issue ourselves even
+when a pull request for it exists.
+
+## Using AI tools
+
+You're welcome to use AI tools.  We use them too.  If you do:
+
+* Say so in the pull request description, along with which tools you used and how
+  you checked the result (for example, the tests you ran and any reviews you did).
+* Make sure you understand the change and can answer questions about it yourself.
+* Write issues, pull request descriptions, and comments yourself, or edit what a
+  tool wrote so it's short and accurate.
+* Don't let an agent open issues or pull requests, or post comments, without a
+  person approving each one.
+* Don't point an agent at our issue list, or at many projects at once, to generate
+  pull requests for problems that don't affect you.
+
+If you use an AI coding agent, it should follow [AGENTS.md](AGENTS.md).
 
 ## Development