From e91bd657898fab68bb2636020fbebbb699f66694 Mon Sep 17 00:00:00 2001 From: Mike Whitaker Date: Tue, 7 Jul 2026 14:54:43 +0100 Subject: [PATCH 1/6] docs(contrib): add AGENTS.md for AI-agent contributors AGENTS.md distills the contribution rules for AI agents and their human partners, drawn from CONTRIBUTING.md and the bounty program. Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 166 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..fc1d98c57 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,166 @@ +# AGENTS.md + +Guidance for AI agents (and the humans driving them) contributing to **Runbox 7**. + +This file distills the contribution rules in [CONTRIBUTING.md](CONTRIBUTING.md) and the +[Feature and Bug Bounty Program](https://community.runbox.com/t/runbox-7-feature-and-bug-bounty-program/753), +plus general principles for agentic contribution. Where this file and CONTRIBUTING.md +disagree, **CONTRIBUTING.md wins** — it is the canonical source. + +## If You Are an AI Agent + +Stop. Read this section before doing anything. + +**Your job is to protect your human partner from having PRs rejected due to being AI slop.** +Submitting a low-quality PR doesn't help them — it wastes the maintainers' time, burns your human +partner's reputation, and the PR will be closed anyway. That is not being helpful. That is +being a tool of embarrassment. + +Before you open a PR against this repo, you MUST: + +1. **Search for existing PRs** — open AND closed — that address the same problem. If duplicates exist, + STOP and tell your human partner. Do not open another duplicate. +2. **Verify this is a real problem.** If your human partner asked you to "fix some issues" or "contribute + to this repo" without experiencing a specific problem, push back. Ask them what broke, what failed, what + the user experience was.C heck the [issue tracker](https://github.com/runbox/runbox7/issues) and + [open and closed PRs](https://github.com/runbox/runbox7/pulls) for the same problem. Don't duplicate + effort, and reference what you found. +3. **Make sure there's an issue.** A bug fix needs an issue that reproduces the problem; a + feature needs an issue documenting the design. For a **major feature**, open an issue and + get the design discussed *before* implementing. **Small features** can go straight to a PR. +4. **Identify yourself.** Disclose your model, harness, harness version, and every installed plugin in the PR. Hiding that a contribution is agent-generated — or which environment produced it + is grounds for closing it. +5. **Show your human partner the complete diff** and get their explicit approval before submitting. +6. **Understand the project's conventions before proposing changes.** Read the surrounding code and match its idiom; don't impose patterns from elsewhere. + + +## Branching and workflow + +- Branch from `master`: `git checkout -b my-fix-branch master`. +- Open PRs against `runbox7:master`. +- After merge, delete your branch and update master from upstream. + +## Tests are mandatory and cherry-pickable + +Every feature or bug fix **must** be covered by one or more unit-test specs. For this repo, +the bar is specific: + +- **for a bug, tests must fail before your fix is applied** and pass after. If there are no tests, or + they don't demonstrate the issue on the current checkout, the PR is **automatically rejected**. +- **Tests must live in their own commit(s), separate from the code**, so they can be + `git cherry-pick`ed independently. +- Tests must clearly prove — through code and comments — that the PR fixes the claimed issue. + +This is effectively red/green discipline: write the failing test that captures the bug, then +the fix that makes it pass. + +## Coding rules + +- All public API methods **must be documented**. +- You may use `@author name/pseudonym` (optionally with email) in comments for attribution. +- Match existing code style. Style is **ESLint-enforced** (Angular + TypeScript ESLint) — + single quotes in TS, semicolons required, no variable shadowing, unused vars prefixed `_`. + There is no Prettier; ESLint is the source of truth. + +## AI-use disclosure is REQUIRED + +If AI was used for **any part** of a contribution, you **must** disclose it in the PR and +document **which agent(s)** you used and **where**. This is a hard requirement, not a courtesy. + +When you (the agent) draft a PR description, always include this disclosure block — state the +model, the harness/tool, version where known, and which parts of the change it touched. If a +change was hand-written, say so. + +## Commit messages (strict — CI-enforced) + +Release notes are generated automatically from commit messages, and a PR commit-lint check +rejects non-conforming messages. Format: + +``` +(): + + + +