Skip to content

Commit a6b0a16

Browse files
committed
docs(agents): forbid at-mentions in anything written in this repo
An at-mention in an issue, comment, PR body, or commit message sends a real notification, and quoting does not suppress it: a draft inside a block quote still pulls the person in, and so does one under a heading that says "do not post". Draft collateral that sat inert in a git-ignored file for weeks became live the moment it was pasted into an issue, and notified an upstream maintainer about a reply nobody had approved sending. That is the same harm the upstream rules exist to prevent, reached by a route those rules did not cover — they governed writing to other repositories, not writing about other people in this one. The mitigation is to write the name without the at sign, or wrap the token in a code span, since GitHub does not create mentions inside code. Also records the milder neighbour, verified rather than assumed: referencing an upstream issue posts a visible cross-reference on their tracker. That is worth it for a genuine tracking link and this repo has always done it, so the guidance is to keep such references where they belong rather than to avoid them. And tightens the closing-keyword rule. A keyword fires on merge and will close an issue that someone has deliberately reopened, so it belongs only on issues the merge genuinely resolves. Assisted-by: Claude:claude-opus-5
1 parent a0c60af commit a6b0a16

1 file changed

Lines changed: 3 additions & 1 deletion

File tree

‎AGENTS.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,8 @@ tinydantic — a Pydantic v2 ODM for TinyDB. `TinydanticModel` subclasses are py
4040
- Before filing anything, search open **and** closed issues (`gh issue list --state all --search "<terms>"`). A finding already reported — by a human or an agent — gets a comment on that issue, never a duplicate.
4141
- When a review turns up something not already tracked, open an issue for it. Re-verify the finding against the current tree first, and record the evidence in the body: what you ran, at which commit, on what date. A finding that no longer reproduces is not filed.
4242
- Every issue carries a type label (`bug`, `enhancement`, `documentation`) plus a topic label where one fits (`performance`, `api-design`, `polish`). Priority, size, and status live on the [project board](https://github.com/orgs/tinydantic/projects/1), not in labels. Milestones name the release the work is intended for.
43-
- A PR that addresses an issue must link it with a closing keyword (`Closes #123`, `Fixes #123`) in the PR body, so merging the PR closes the issue.
43+
- A PR that addresses an issue must link it with a closing keyword (`Closes #123`, `Fixes #123`) in the PR body, so merging the PR closes the issue. Only use a closing keyword when merging genuinely resolves that issue — it fires on merge and will close an issue someone has deliberately reopened.
44+
- **Never write an `@` mention anywhere in this repo** — issue bodies, comments, PR bodies, commit messages. GitHub turns it into a real notification to that person, and **quoting does not suppress it**: a draft inside a `>` quote still pulls them in, and so does one under a heading that says "do not post". This is not hypothetical; it has happened here, when draft collateral moved out of a git-ignored file into an issue and notified an upstream maintainer about a reply that was never sent. Text that is inert in a scratch file goes live the moment it is pasted into GitHub. When draft material has to quote a conversation, write the name without the `@`, or wrap the whole token in a code span — GitHub does not create mentions inside code.
4445
- **Any issue an agent helped write or investigate carries the `ai-assisted` label and an `Assisted-by:` trailer**, following the [kernel's convention](https://docs.kernel.org/process/coding-assistants.html). Last line of the body, own paragraph:
4546

4647
```text
@@ -57,6 +58,7 @@ tinydantic — a Pydantic v2 ODM for TinyDB. `TinydanticModel` subclasses are py
5758

5859
- **NEVER write to any repository outside `tinydantic/tinydantic`.** No issues, no comments or replies, no edits, no closing or reopening, no reactions, no reviews, no pull requests — not on `msiemens/tinydb`, `pydantic/pydantic`, `mkdocstrings/python`, nor anywhere else. The _only_ exception is an explicit instruction from a tinydantic maintainer to take that specific action at that moment. Approval is never durable and never implied: permission to file an issue is not permission to answer the maintainer's reply, and permission once is not permission again. If you believe an upstream action is warranted, prepare it and ask.
5960
- **Reading upstream is unrestricted** and encouraged — fetch issue threads, PRs, release notes, and source whenever it helps. The prohibition is on writing, not on looking.
61+
- Referencing an upstream issue (`owner/repo#123`, or its URL) posts a visible cross-reference on **their** tracker. A genuine tracking link is worth that and this repo has always done it — but it is not invisible, so keep upstream references to the places that need them and use a code span in quoted draft text. Combined with the `@handle` rule above: assume anything you paste into a public issue here can reach the people it names.
6062
- An `upstream`-labelled issue in this repo is a **drafting workspace**: where an agent and a maintainer iterate on the text of an upstream report until it is good enough to send. It is also the one place that context lives, so tinydantic issues held up by the upstream fix point at it with a relationship instead of each repeating the problem.
6163
- The draft carries what filing needs: target repo, affected version, reproduction, expected behavior, and the ready-to-post title and body — plus the patch or draft reply where one applies. Fence the ready-to-post text under a clear "do not post without approval" heading, so no reader mistakes a draft for something already sent.
6264
- **Once it is filed upstream, decide case by case whether the tracking issue still has work to do.** If the draft is spent, close it and re-point the dependent tinydantic issues at the upstream URL directly — one less place to keep current. Keep it open only when something here is still being iterated on: a follow-up reply in progress, a workaround to land, or several tinydantic issues whose shared context lives in it. While it stays open, mirror upstream state into it (filed, answered, merged, closed) — one-directional, and our issue is never written back to upstream.

0 commit comments

Comments
 (0)