AGENTS.md

1# AGENTS.md
2 
3This repository uses **AIGX (AI Genome Exchange)** — its AI-agent rules live in a `.aigx/` directory with a
4per-file boundary index. You don't need to guess the conventions; they are in the genome. Read this section
5before editing.
6 
7## The reading protocol — do this for every task
8 
91. **Read `.aigx/protocol.aigx`** first — it is the authoritative reading sequence.
102. **For EACH file you will edit, open `.aigx/files.aigx`** and find its `<file path="...">` entry:
11 
12```xml
13   <file path="src/features/auth/login.ts" domain="auth">
14     <role>Handle login — validate credentials and issue a session</role>
15     <forbid pri="CRIT">NEVER read from another tenant's session store</forbid>
16     <gotcha>token expiry is checked at read-time, not issue-time</gotcha>
17     <check>ARCH-no-deep-imports ENG-tenant-scope</check>
18   </file>
19```
20 
21   - **`<role>`** — what this file is for; understand it before writing a line.
22   - **`<forbid pri="CRIT">`** — a hard constraint. Never violate it, no exceptions.
23   - **`<gotcha>`** — the single worst pitfall for this file; read it twice.
24   - **`<check>`** — space-separated rule ids. Look each up in its concern file and **verify they hold
25     before you finish.**
26 
273. **Read the concern files your check ids reference** — `.aigx/architecture.aigx` (`ARCH-*`),
28   `.aigx/engineering.aigx` (`ENG-*`), `.aigx/data.aigx` (`DATA-*`), etc. — *before* writing code.
294. **Make the minimal change** with a local blast radius, then **verify every `<check>` id** for each file
30   you touched.
31 
32## Keep the genome current (you are a steward of it)
33 
34- **Rename/move a file** that has a `files.aigx` entry → update its `path="..."` in the **same change-set**.
35- **Create a new file** other agents will edit → add a `<file>` entry (at least `<role>` + one `<check>`).
36- **Rule ids are permanent** (`ARCH-no-deep-imports`, `ENG-2`, …) — never rename or delete; edit text in place.
37- **A code change that makes a rule wrong** → fix the rule text in the same change-set. The genome describes
38  reality, not history.
39 
40## Validate
41 
42```bash
43aigx lint        # or: python tools/aigx-lint/aigx_lint.py --root .
44```
45 
46> Full format: <https://github.com/Lolner95/AIGX/blob/main/standard/AIGX-1.1.md>
47