Create AGENTS.md

Author: Frotty

AGENTS.md

@@ -0,0 +1,189 @@
+# AGENTS.md
+
+This document defines how automated coding assistants (“agents”) should interact with this repository.
+
+## 1. Repository Overview
+
+This repository contains the **WurstScript compiler**. Its main code lives in:
+
+```
+de.peeeq.wurstscript/
+```
+
+Other directories like `WurstPack` and `HelperScripts` exist but are largely **deprecated** and should not be modified unless explicitly requested.
+
+### Compiler layout
+
+Inside `de.peeeq.wurstscript`:
+
+* **`src/main/antlr/de/peeeq/wurstscript/antlr/`**
+  Contains the **ANTLR grammars** (`.g4`) for Wurst and Jass.
+  These produce concrete syntax trees (CSTs).
+
+* **`parserspec/`**
+  Contains **.parseq grammars** for `abstractsyntaxgen`
+  ([https://github.com/peterzeller/abstractsyntaxgen](https://github.com/peterzeller/abstractsyntaxgen)).
+  These define the AST structure used by the compiler.
+  Code is generated via the Gradle task:
+
+  ```
+  ./gradlew :gen
+  ```
+
+* **`src/main/java/de/peeeq/`**
+  Main compiler sources:
+
+  * Parsing and AST infrastructure
+  * Type checking
+  * Intermediate language (**IM**)
+  * Jass and Lua backends
+  * Interpreter for executing IM at compile time
+    (used for specific compile-time evaluations)
+
+### Compilation pipeline (simplified)
+
+1. Parse Wurst/Jass with ANTLR → CST
+2. Abstractsyntaxgen → AST
+3. Transform AST → IM
+4. Optionally: Run IM in the interpreter, Optimize
+5. Transform IM → Backend (Jass or Lua)
+
+
+### Language and tooling
+
+* **Java 25**
+* **Gradle (9.2.1)**
+* Unit tests define many entry points and expected behaviors.
+
+---
+
+## 2. Agent Expectations
+
+Changes made by agents must follow these principles:
+
+### Compatibility first
+
+* **All existing tests must continue to pass.**
+* If behavior changes intentionally, provide **new tests** that define the updated semantics.
+
+### Minimal, well-scoped edits
+
+Agents should:
+
+* Fix concrete bugs with **small, local patches**.
+* Add missing null-checks, defensive checks, or diagnostics where appropriate.
+* Add tests when resolving issues or implementing requested features.
+
+Agents should avoid:
+
+* Large refactors (renaming packages, structural moves, mass rewrites).
+* Modifying deprecated folders unless explicitly instructed.
+* Altering public semantics or language rules without tests demonstrating the intended outcome.
+
+### Test-driven
+
+* Any new behavior requires tests showing failure before the change and success after.
+* Use existing test style and harnesses.
+
+### Generated code
+
+* Do **not** modify files generated by `:gen`.
+* If modifying `.parseq` files or grammars, regenerate via:
+
+  ```
+  ./gradlew :gen
+  ```
+
+---
+
+## 3. Coding Guidelines
+
+### Follow existing style
+
+Use the conventions already present in the file you edit. Avoid introducing new patterns without reason.
+
+### Compiler structure expectations
+
+* The IM is the central intermediate representation.
+* Transformations should keep IM consistent and valid.
+* Backends (Jass/Lua) expect well-formed IM; avoid breaking invariants.
+* Interpreter should remain deterministic and side-effect free.
+
+### Error handling
+
+* Prefer explicit, descriptive diagnostic messages.
+* Avoid silent fallbacks or suppressed exceptions.
+* Don’t change the meaning of existing error messages unless required.
+
+### Performance
+
+* Avoid algorithmic regressions in parsing, type checking, or transforms.
+* Consider memory impact when manipulating large ASTs or IM graphs.
+
+---
+
+## 4. Allowed vs. Disallowed Changes
+
+### Allowed
+
+* Fix a crash or incorrect behavior in a specific compiler pass.
+* Add a regression test that demonstrates a known issue.
+* Improve clarity of error messages.
+* Add a small new feature when fully specified by the user and backed by tests.
+* Update Gradle/JDK usage only if part of a requested task.
+
+### Disallowed
+
+* Unsolicited rewrites of ANTLR grammars.
+* Modifying deprecated folders.
+* Changing code generation semantics without explicit tests.
+* Changing IM behavior without test coverage.
+* Introducing new external dependencies unless requested.
+
+---
+
+## 5. How to Run Tests and Code Generation
+
+Inside
+
+```
+de.peeeq.wurstscript/
+```
+
+run:
+
+### Run all tests
+
+```
+./gradlew test
+```
+
+### Run a specific test
+
+```
+./gradlew test --tests "tests.wurstscript.tests.GenericsWithTypeclassesTests.identity"
+```
+
+### Generate AST code via ANTLR & abstractsyntaxgen
+
+```
+./gradlew :gen
+```
+
+### Build the compiler
+
+```
+./gradlew build
+```
+
+---
+
+## 6. Summary for Agents
+
+* Keep changes **minimal**, **compatible**, and **tested**.
+* The authoritative behavior is defined by the **existing test suite**.
+* The compiler architecture relies on CST → AST → IM → Backend; treat each stage carefully.
+* Never modify generated files; modify the sources that generate them instead.
+* New behavior must be documented through tests.
+
+