🪐

AGY Research Lab

Breadbox VPS // Google Antigravity & Gemini Exploration Hub

Connecting...
TRACK A // BENCHMARKED & VERIFIED

Antigravity Rules Architecture & GEMINI.md Hierarchies

Comprehensive empirical findings on how Google Antigravity discovers rules, traverses directory trees, resolves subfolder conflicts, expands modular transclusions, and enforces token budget boundaries.

24,000 B
Per-File Hard Limit (Line Truncated)
20,000
Aggregate Rules Token Budget
Top-Down
Inheritance Traversal (Root → CWD)
5 / 5
Automated Regression Tests Passing

🧭 1. Rule Discovery & Hierarchy Walk-Up

When an Antigravity agent executes in any directory, the runtime walks up the filesystem tree from the Current Working Directory (CWD) up to the Repository Root (the directory containing .git). In addition, machine-level global rules in ~/.gemini/config/ are loaded.

1

Global Rules (~/.gemini/config/)

Applied machine-wide across all repositories and workspaces.

2

Workspace Root (/home/mark/projects/agy/GEMINI.md)

Injected first as baseline project guardrails, mission parameters, and repository conventions.

3

Intermediate Subdirectories (e.g. tests/rules/scope-test/GEMINI.md)

Layered on top of root rules, narrowing constraints for parent directories.

4

Active Leaf Directory (e.g. .../nested/GEMINI.md)

Injected last, representing the most specific instructions for the agent's immediate workspace.

Injected Context Structure

Discovered rules are assembled into the agent's system prompt inside a reserved <user_rules> block. Each rule file is wrapped in an XML-style tag indicating its canonical path:

System Prompt Injected Format XML Enclosure 
<user_rules>
The following are user-defined rules that you MUST ALWAYS FOLLOW WITHOUT ANY EXCEPTION.
These rules take precedence over any other instructions.
Review them carefully and always take them into account when you generate responses and code:

<RULE[/home/mark/projects/agy/GEMINI.md]>
# agy // Antigravity & Gemini Research Lab
...
</RULE[/home/mark/projects/agy/GEMINI.md]>

<RULE[/home/mark/projects/agy/tests/rules/scope-test/nested/GEMINI.md]>
# Scope Level 2 Nested Rule
...
</RULE[/home/mark/projects/agy/tests/rules/scope-test/nested/GEMINI.md]>
</user_rules>
Verified Traversal Order: Our test suite confirmed that rules are stacked top-down (root first, leaf last). Rules are deduplicated by canonical file path, ensuring identical rules are never inlined twice in a turn.

⚔️ 2. Subfolder Overrides & Conflict Resolution

A common question is: What happens when a child folder rule contradicts a parent or root rule? We empirically benchmarked this in tests/rules/override-test/.

Scope Tier File Location Prescribed Directives Observed Precedence
Parent Folder tests/rules/override-test/GEMINI.md Format: JSON ONLY
Designation: ALPHA_PARENT		 Overridden
Child Folder tests/rules/override-test/sub/GEMINI.md Format: Markdown bullets ONLY
Designation: BETA_CHILD		 WINNER (100% Selected)
Verified CLI Agent Output (from tests/rules/override-test/sub) agy -p 
* **Designation**: BETA_CHILD (overriding ALPHA_PARENT)
* **Format Requirement**: Responses must NOT use JSON and must ONLY be output as plain Markdown
  bullets, adhering to the subfolder rule override in
  /home/mark/projects/agy/tests/rules/override-test/sub/GEMINI.md.

Why this works: Antigravity places child rules later in the prompt sequence. Combined with the narrower directory scope, modern LLMs reliably interpret downstream subfolder instructions as local overrides to higher-level generic guidelines.

📄 3. File Formats & Frontmatter Matrix

Antigravity supports both headerless standalone Markdown files and frontmatter-driven rules:

Rule Type File Location Frontmatter Loading Mode Use Case
Directory Rule GEMINI.md None (Headerless) Always-On (when in scope) Folder-level instructions, team standards
Alternative Alias AGENTS.md None (Headerless) Always-On (when in scope) Universal agent standards
Workspace Rule .agents/rules/*.md trigger: always_on Always-On (in budget) Workspace-wide mandatory policies
Conditional Rule .agents/rules/*.md trigger: model_decision Progressive (On-Demand) Domain-specific guidelines (e.g. SQL, CSS, C++)

Co-located AGENTS.md and GEMINI.md

We tested placing both AGENTS.md and GEMINI.md in the same folder. Finding: Both files were discovered and injected simultaneously into <user_rules> alphabetically (AGENTS.md first, then GEMINI.md). Neither file shadowed or discarded the other.

Conditional Rules (trigger: model_decision)

To prevent context bloat, rules with trigger: model_decision are not inlined in full by default. Instead, Antigravity injects a lightweight pointer:

Conditional Rule Injection Schema Progressive Disclosure 
The following are conditional rules, formatted as: - [absolute path]: [description].
The description provides conditions under which the rule applies. If you believe a rule should
apply, view the file for further instructions.
- file:///home/mark/projects/agy/.agents/rules/quantum-rule.md: Apply this rule only when user discusses quantum entanglement or qubits

🔗 4. Modular Transclusion Syntax: @[label](path)

Antigravity allows rule files to include modular snippets using the transclusion syntax: @[label](relative/path.md).

Example: Modular GEMINI.md Architecture GEMINI.md 
# AGY Project Guidelines

## Coding Style
@[style](rules/partials/style.md)

## Security Protocols
@[security](rules/partials/security.md)

## Deployment Checklist
@[deploy](rules/partials/deploy.md)
Verified In-Engine: Transclusion paths resolve relative to the directory containing the host rule file. The include is expanded inline before prompt compilation and before the 24KB limit is evaluated.

⚖️ 5. Limits & Token Budgeting Deep-Dive

Antigravity implements a two-tier safety system to prevent rules from overwhelming the model context:

A. Per-File Hard Limit: 24 KB (24,000 Bytes)

Every rule file (after expanding any @[label](path) includes) is capped at exactly 24,000 bytes. We tested this with a 27,191-byte rule file containing sequential padding.

Truncation Proof (Verified in tests/rules/size-limit-test) Math & Transcript Output 
PRE_CAP_0270: bytes nearing twenty four thousand limit.
<truncated 3224 bytes>

Math Check: 27,191 bytes (total) - 3,224 bytes (truncated) = 23,967 bytes (<= 24,000 bytes)
Line-Boundary Truncation: Antigravity does not perform an abrupt character slice. It scans backward to the nearest newline boundary, preserving markdown formatting and preventing half-broken syntax.

B. Aggregate 20,000-Token Rules Budget (defaultRulesBudget)

All always-on and global rules share an aggregate pool of 20,000 tokens. When the aggregate size of all discovered rules exceeds this budget, Antigravity performs Graceful Pointer Demotion:

A

Within 20,000 Tokens

Rules are fully inlined inside <RULE[...]> blocks in the system prompt.

B

Exceeding 20,000 Tokens

Remaining rules are demoted from inline text to file path references with their YAML descriptions.

Verified Demoted Rules Prompt Schema System Context 
The following user-defined rules exceeded the rules token budget and were excluded from inline injection.
View the file for further instructions when relevant:
- /home/mark/projects/agy/.agents/rules/budget_rule_01.md: Budget test rule number 1
- /home/mark/projects/agy/.agents/rules/budget_rule_02.md: Budget test rule number 2
- /home/mark/projects/agy/.agents/rules/budget_rule_03.md: Budget test rule number 3
Plugin Exemption: Rules packaged with built-in plugins are exempt from the 20,000-token rules budget and are always inlined in full.

🧪 6. Automated Test Suite & Reproduction

This repository includes an automated regression test script in tests/rules/run_rules_suite.py. You can re-run all Track A assertions at any time:

Run Regression Suite via Terminal CLI Command 
python3 /home/mark/projects/agy/tests/rules/run_rules_suite.py
Test Case Target Feature Directory Fixture Status
Test 1 Scope Hierarchy & Walk-Up Discovery tests/rules/scope-test/nested/ PASSED
Test 2 Subfolder Conflicting Directive Overrides tests/rules/override-test/sub/ PASSED
Test 3 Co-located AGENTS.md and GEMINI.md Simultaneous Loading tests/rules/agents-vs-gemini/ PASSED
Test 4 Transclusion Expansion @[label](path) tests/rules/includes-test/ PASSED
Test 5 Per-File 24KB Cap & Line-Boundary Truncation tests/rules/size-limit-test/ PASSED

Experiment Logs

Detailed trajectory logs and step transcripts are archived in the repository:

  • experiments/EXP-01-rules-inheritance.md: Walk-up traversal & child precedence.
  • experiments/EXP-02-rules-budget-and-limits.md: 24KB limit math & 20k token pointer demotion.
  • experiments/EXP-03-rules-transclusion-includes.md: Modular transclusion expansion.

💡 7. Rules of Thumb for Developers & Operators

DO

  • Keep individual rule files under 20 KB to avoid truncation surprises.
  • Always provide descriptive YAML frontmatter descriptions on .agents/rules/*.md files so the agent knows when to read demoted or conditional rules.
  • Break large project manuals into modular chunks with @[label](path).
  • Place directory-specific guidelines (e.g., test mocks, API patterns) inside subfolder GEMINI.md files.

DON'T

  • Don't create a monolithic 50KB root GEMINI.md; the engine will truncate everything after byte 24,000.
  • Don't assume child rules replace parent rules entirely; they are stacked top-down, so non-contradictory parent rules remain active.
  • Don't omit frontmatter descriptions on conditional rules, as the model cannot inspect contents without them.
  • Don't use absolute paths in @[label](path) transclusions.