# 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/<owner>/<repo>`), 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.