AIGX Specification - v1.1

Design north star. An AI agent reads selectively at the edit site. The format MUST make the binding constraint for the file being edited reachable in one lookup, while keeping the source code untouched.

Quick start (under 60 seconds)

1. Copy the starter genome into your repo root: cp -r templates/starter/.aigx .aigx
2. Fill in files.aigx - one <file> entry per file an agent realistically edits.
3. Add the agent addendum (one line) to your AGENTS.md / CLAUDE.md / Cursor rule.
4. Run aigx-lint in CI so a moved file fails the build until its entry is fixed.

1. Directory layout

An AIGX genome is a directory named .aigx/ at the repository root, plus optional per-domain cards colocated with source folders.

<repo-root>/
├── .aigx/
│   ├── protocol.aigx        # REQUIRED - the read protocol
│   ├── product.aigx         # RECOMMENDED - product context + doc freshness
│   ├── files.aigx           # REQUIRED - the per-file boundary index
│   └── <concern>.aigx       # REQUIRED (≥1) - per-concern rule files
└── <any source dir>/
    └── <key>.aigx           # OPTIONAL - a per-domain card

• Files use the .aigx extension and UTF-8 encoding.
• The syntax is XML-style tags (chosen for parseability), but a genome is read by an LLM, not a strict XML parser; well-formedness SHOULD hold but is not schema-validated.
• Source code files MUST NOT be modified. AIGX is centralized; nothing is injected into source.

2. Rule identifiers

Every rule has a stable identifier of the form PREFIX-N (e.g. ARCH-2, DATA-1, ENG-10). The PREFIX names the concern. Ids MUST be stable across edits - they are the cross-reference backbone used by <check> lists, <fact>s, and gotchas. Ids are the unit of parity: any tool that re-renders a genome MUST preserve the full rule-id set.

3. The files

protocol.aigx (REQUIRED)

The read protocol - the first thing an agent reads. It MUST instruct the agent to consult files.aigx for each file it edits and to verify the file's <check> ids before finishing. It SHOULD be short (one screen).

<aigx-protocol>
  <read-first>Open .aigx/files.aigx and find the <file> entry for EACH file you will edit … obey its
   <forbid pri="CRIT"> and satisfy every id in its <check> before finishing.</read-first>
  <step n="1">Read the per-concern rule files in .aigx/ that the task touches.</step>
  <step n="2">Read .aigx/files.aigx for the per-file boundaries of files you edit.</step>
  <step n="3">Schema-first; failing test first; minimal change, local blast radius.</step>
  <step n="4">Run gates; verify each file's <check> ids hold.</step>
</aigx-protocol>

Per-concern rule files - <concern>.aigx (REQUIRED, ≥1)

Each concern file is a flat list of <rule> elements carrying the full rule text. Element name SHOULD be aigx-<concern>; child elements MUST be <rule id="…">.

<aigx-architecture>
  <rule id="ARCH-2">Every feature exposes ONE public API: its index.ts barrel. Deep imports are forbidden.</rule>
  <rule id="ARCH-6">TypeScript strict mode; the `any` type is forbidden in any form.</rule>
</aigx-architecture>

The per-file boundary index - files.aigx (REQUIRED) - the keystone

A flat list of <file> entries, one per source file an agent is likely to edit. This is what no other format has.

<aigx-files>
  <file path="src/features/meetings/bookMeeting.ts" domain="meetings">
    <role>Book a meeting (validate slot + contact)</role>
    <forbid pri="CRIT">NEVER import @/features/suppliers/internal/* (deep import = ARCH-2)</forbid>
    <gotcha pri="CRIT">get contact_email from the suppliers PUBLIC api, never the internal mapper</gotcha>
    <check>ARCH-2 ARCH-4 ARCH-5 DATA-2 TEST-1</check>
  </file>
</aigx-files>

Normative authoring constraints (these are what the benchmark validated):

• Scarcity. <forbid> SHOULD appear only on the few files that truly have an import boundary. Marking many files dilutes the signal and measurably reduces compliance.
• One gotcha. Each entry SHOULD carry at most one <gotcha> - the single worst pitfall.
• Terse fields only. The index SHOULD carry only role + forbid + gotcha + check.

Salience - the pri attribute

<forbid> and <gotcha> MAY carry pri="CRIT". In the validated design, all critical boundaries use a single uniform level. Graded scales (CRIT/WARN, CRIT/HIGH/NORM) were tested and did not help.

4. The agent addendum

To make any agent AIGX-aware, append this to its instructions. It is the only integration step required.

This repository uses AIGX - the AI Genome Exchange context format. The .aigx/ directory holds the context: read .aigx/protocol.aigx first; then the per-concern rule files your task touches. .aigx/files.aigx is the PER-FILE BOUNDARY INDEX: for EACH file you edit, find its <file path="…"> entry - obey its <forbid pri="CRIT">, heed its <gotcha>, and verify every id in its <check> before finishing. Keep blast radius local unless justified.

5. Semantic parity & conformance

Any transformation of a genome (re-rendering, exporting, compressing) MUST be semantics-preserving: it MUST preserve the complete set of rule ids and their full text, every <file> entry's path/forbid/gotcha/check, and every fact. A directory is a conforming AIGX genome if it has a protocol.aigx instructing per-file index lookup, at least one concern file with <rule id> rules, and a files.aigx whose <check> ids resolve to rules that exist.

8. Scaling to monorepos

A repository MAY contain multiple .aigx/ directories - one per package or subtree. Paths resolve relative to the repo root; the applicable genome for a file is the nearest ancestor .aigx/. The boundary index is meant to be looked up, not ingested: aigx-lint --resolve <path> returns exactly that file's entry, so an agent's context cost is O(1) per edited file, independent of index size.

This is a summary. The full normative text, including every grammar table and worked example, is the canonical record in the repository: SPEC.md on GitHub ↗, with a complete genome in examples/sourcing-app ↗.