From 2952ed78b2c53f94e102a880580d83303c6641d8 Mon Sep 17 00:00:00 2001 From: Ellison Date: Wed, 28 Oct 2026 15:23:50 -0300 Subject: [PATCH] add initial AGENTS.md file, change coderrabit (#484) --- .coderabbit.yml | 39 +++------------------- AGENTS.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 92 insertions(+), 34 deletions(-) create mode 100644 AGENTS.md diff --git a/.coderabbit.yml b/.coderabbit.yml index 6a4abe1..a20fc83 100644 --- a/.coderabbit.yml +++ b/.coderabbit.yml @@ -1,46 +1,17 @@ reviews: + auto_approvals: + enabled: true tools: github-checks: enabled: true path_instructions: - path: "README.md" instructions: | - When reviewing changes to README.md, only evaluate list entries/links that are newly added by this pull request (new lines in the diff). Do not re-validate or flag pre-existing entries that the PR did not touch, even if they would fail one of the checks below. + When reviewing changes to README.md, only evaluate list entries/links that are newly added by this pull request (new `- ` / `* ` lines introducing a link). Do not re-validate or flag pre-existing entries that the PR did not touch, even if they would fail one of the checks below. If an existing entry was only repositioned (e.g. as a side effect of inserting a new entry) without any content change, do not flag it, but still use it as context to confirm the resulting order is correct. - ## 1. Scope - New Links Only - - Identify only the list entries added by this PR (new `- ` / `* ` lines introducing a link). - - Entries that already existed before the PR, and were not modified, must be ignored even if they are out of order, missing an emoji, or otherwise non-compliant. - - If an existing entry was only repositioned (e.g. as a side effect of inserting a new entry) without any content change, do not flag it, but still use it as context to confirm the resulting order is correct. + Apply the full "Rules that apply to any change to README.md" checklist from AGENTS.md at the repo root to every newly added entry: alphabetical ordering within its section, required license emoji (with the documented exceptions for Blogs and Portals, Videos/Podcasts, Game Jams, and Communities), link validation (https:// only, well-formed, reachable, 100+ GitHub stars for repo links), and game-development relevance. - ## 2. Alphabetical Ordering - - Each section/subsection (e.g. `#### Assets/Placeholders`, `#### Spritesheet Tools`, `### Books`, etc.) must have its entries sorted A-Z by link text (the text inside `[]`). - - For every newly added entry, verify it was inserted in the correct alphabetical position relative to the other entries (new and pre-existing) already in that section. - - Flag a new entry if it is not in the correct alphabetical position. - - ## 3. License Emoji Validation - - Every newly added entry must start with one of these emojis: - - `:free:` - Free - - `:tada:` - Open Source - - `:moneybag:` - Paid - - `:money_with_wings:` - Partially Free - - Exception: new entries added under `### Blogs and Portals`, `### Videos/Podcasts`, `### Game Jams`, and `### Communities` are NOT required to have one of these emojis. - - For all other sections, flag any new entry that: - - Is missing an emoji entirely - - Uses an invalid/different emoji (not one of the four above) - - Uses an inconsistent emoji format (e.g. `🆓` instead of `:free:`) - - ## 4. Link Validation - - Every newly added link must be a valid, well-formed URL using the `https://` scheme only. Flag `http://` links and any other protocol (ftp, file, mailto, javascript, etc.). - - Flag malformed or unreachable (broken/dead) URLs. - - If a newly added link points to a GitHub repository (e.g. `https://github.com//`), look up the repository and flag it if it has fewer than 100 stars. - - ## 5. Game Development Relevance - - Every newly added link must be explicitly about game development (e.g. engines, game-specific tools, game art/audio assets, game tutorials/books, game-dev communities, etc). - - Flag new links to general-purpose tools or resources that are not specifically focused on game development, even if they could incidentally be used while making a game. - - ## 6. Reporting Failures - - If any check above fails for a newly added link, comment directly on that line, tag the PR author, and clearly explain which check(s) failed and what needs to be fixed. - - When any new link fails a check, request changes on the review instead of approving. + If any check fails for a newly added link, comment directly on that line, tag the PR author, and clearly explain which check(s) failed and what needs to be fixed. When any new link fails a check, request changes on the review instead of approving. pre_merge_checks: custom_checks: - name: "README New Links Validation" diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..709560a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,87 @@ +# AGENTS.md + +Instructions for any AI coding agent (Claude, Copilot, Cursor, OpenCode, etc.) working in this +repository. The checklist below is the canonical set of rules for changes to `README.md`. +CodeRabbit's `path_instructions` for `README.md` in `.coderabbit.yml` point back to this file, so +following it here is what makes generated changes pass review on the first try. The one place that +keeps its own independent copy of these rules is `pre_merge_checks.custom_checks` in +`.coderabbit.yml` — that check runs in a sandbox that can't read repo files, so if you change a +rule here, update that check's `instructions` to match. + +## What this repo is + +`magictools` is a curated, "awesome-list" style **README.md** of game development resources. There +is effectively no application code to build or test — the primary artifact an agent will touch is +`README.md`, and the main "feature work" in this repo is adding, editing, or reorganizing link +entries in it. + +## Rules that apply to any change to `README.md` + +These rules apply to **every new or modified list entry** (lines starting with `- ` or `* ` that +contain a `[text](url)` link). Pre-existing, untouched entries should be left alone even if they +would fail one of these checks — don't "fix" unrelated entries as a side effect of your change, +beyond re-sorting required to keep the list alphabetical. + +### 1. Scope — only touch what you're asked to change +- Only add/modify the entries relevant to the task. +- Do not reflow, re-emoji, or re-sort entries that are untouched and unrelated to your change. +- If inserting a new entry forces an existing entry to move position, that's fine — but don't alter + its content. + +### 2. Alphabetical ordering +- Every section/subsection (e.g. `#### Assets/Placeholders`, `#### Spritesheet Tools`, + `### Books`, etc.) is sorted A-Z by link text (the text inside `[]`). +- When adding a new entry, insert it at the correct alphabetical position within its section, + comparing against both existing and other newly added entries. +- Before finishing, double check the resulting section is still fully sorted A-Z. + +### 3. License emoji is required +- Every new entry must start with exactly one of: + - `:free:` — Free + - `:tada:` — Open Source + - `:moneybag:` — Paid + - `:money_with_wings:` — Partially Free +- Use the literal `:emoji_name:` shortcode text, not a unicode emoji character (e.g. not `🆓`). +- **Exception**: entries added under `### Blogs and Portals`, `### Videos/Podcasts`, + `### Game Jams`, and `### Communities` do **not** require a license emoji. + +### 4. Link validation +- Links must use `https://` only. Never add `http://`, `ftp://`, `file://`, `mailto:`, + `javascript:`, etc. +- Links must be well-formed and reachable (not a 404/dead domain). Check the URL before adding it + if at all possible. +- If a link points to a GitHub repo (`https://github.com//`), it must have **at least + 100 stars**. Verify star count before adding; don't add repos below that threshold. + +### 5. Game development relevance +- Every new link must be explicitly about game development (engines, game-specific tools, game + art/audio assets, game tutorials/books, game-dev communities, etc). +- Do not add general-purpose tools/sites that merely *could* be used while making a game but have + no game-dev-specific focus. + +### 6. Format of an entry +Match the existing style exactly: + +``` +- :free: [Tool Name](https://example.com/) - short description of what it does. +``` + +- One entry per line. +- Short, factual description after a ` - `. +- No trailing blank line changes inside a list unless adding/removing an entry requires it. + +## Other files +- `.github/CONTRIBUTING.md` and `.github/PULL_REQUEST_TEMPLATE.md` contain the human-facing + version of these same rules — keep them in sync if you change the rules here. +- `.coderabbit.yml` has two relevant parts: `reviews.path_instructions` for `README.md` defers to + this file plus a few reviewer-behavior directives (comment inline, tag the author, request + changes on failure); `reviews.pre_merge_checks.custom_checks` keeps a full, independent copy of + the checklist, since that merge-blocking check can't read `AGENTS.md`. Keep that copy in sync + with the checklist above. + +## Before finishing a change to README.md +1. Re-read the section(s) you edited top to bottom and confirm alphabetical order. +2. Confirm every new entry has a valid license emoji (or is in an exempt section). +3. Confirm every new link is `https://`, well-formed, and (if a GitHub repo) has 100+ stars. +4. Confirm every new link is genuinely game-dev relevant. +5. Confirm you haven't modified unrelated, pre-existing entries.