llamamod/notes/dev/agent-brief.md

Common rules for LlamaMod mod agents (read fully)

Project: ~/projects/llamamod — Java 25 Swing mod manager "LlamaMod" for the PC game "Ein Königreich für ein Lama" (Emperor's New Groove, 2000, Argonaut/Croc-2 engine, 32-bit DirectX 6/7, German version). Git repo: DO NOT commit.

WORK IN YOUR OWN COPY (4 agents work in parallel; a half-written file in the shared tree would break the others' builds): rsync -a --exclude build --exclude .gradle --exclude re/proj --exclude out ~/projects/llamamod/ $CLAUDE_JOB_DIR/tmp//llamamod/ (re/groove_decomp.c and re/groove.exe come along; Ghidra project: copy re/proj too if you need headless Ghidra: /opt/ghidra_12.2_PUBLIC, JAVA_HOME=/opt/jdk-25.0.5+8; never run it on ~/projects/llamamod/re/proj directly.) Build/test there: ./gradlew spotlessApply build fatJar. When DONE, copy back ONLY your own new package directories (src/main/java/.../mods//, src/test/java/.../mods//, resources under your package) plus your notes file into ~/projects/llamamod, then run ./gradlew spotlessApply build in ~/projects/llamamod once (if it fails because of ANOTHER agent's in-progress package, re-run later; never edit other agents' packages). Your mod classes are ALREADY registered in mods/ModRegistry.java (reflection, skipped if absent) – do not edit ModRegistry. Avoid editing shared framework files (Mod, ModContext, ModManager, ModOption(s), exe/, ui/, platform/*). If you truly need a framework change, keep it minimal and backwards compatible, and list it explicitly in your report (it must then also be copied back; tell me).

READ: notes/llamamod-app.md (framework: options API, categories, ExeImage/code caves/X86 emitter, "Testing mods in game" with tools/apptest.py), notes/geometry.md, notes/objects.md, notes/strat_types_table.md, notes/levelbau.md, notes/debugviz.md. Format API: package com.eliasmueller.llamamod.format (Wad, Level, MapChunk, Trak/Model/Vertex/Face, TextChunk, Collision, Geometry, Stpc, Strats, Lin3, PyMath). Examples of mods: mods/debug/DebugWireframeMod, mods/testworld/TestWorldMod. Decompile of groove.exe: re/groove_decomp.c (grep, don't read whole). Save format: save/Ksv.java.

LANGUAGE: everything English (identifiers, comments, UI labels, messages). Only necessary comments (offsets, patch bytes, non-obvious engine facts). Each mod: id, name, description, category (Mod.LEVELS/GAMEPLAY/VISUAL/CHEATS), options().

IN-GAME TESTING is mandatory: tools/apptest.py from YOUR copy (it uses your copy's fat jar), with YOUR display number (given below) and session names prefixed with your agent name. It runs a private PulseAudio (silent) – never start the game any other way. Never use display :0, never touch ~/.wine-lama or the user's saves, never pkill -f patterns (they match your own shell) – use PIDs / apptest stop. Stop your sessions when done. Look at screenshots with Read (use montage/--small to save context). Disk is limited (~20 GB free): delete your copy's build dirs and session dirs at the end (keep the session template _llamamod-template).

REPORT BACK: what the mod does (options), how it works (offsets/patches/data changes), what was verified in game (which levels, screenshots paths – put 2–4 phone-friendly JPGs ≤1280px into ~/projects/llamamod/notes/img/mods/), known limits, any framework changes. Also write notes/mod-.md (English, concise).

Extra rules for EDITOR phase-3 agents (several agents edit the editor in parallel)

• Right after rsync, make a pristine baseline of your start state: cp -al <copy> <copy>.base (hard links, cheap) – actually use rsync -a <copy>/ <copy>.base/ so later edits in the copy don't change it.
• Put your work in your OWN plugin package (class name ending in EditorPlugin, see notes/editor-ui.md) – no shell edits needed.
• Shared files (editor.model, editor.io, editor.render, editor.ui shell, format, levelbuild, framework): only minimal, backwards-compatible additions. At copy-back, for every shared file you changed: if the main tree's version differs from your baseline (another agent changed it meanwhile), DO NOT overwrite – re-apply your diff (diff -u base copy | patch) onto the main tree's version and resolve conflicts by hand. New files of your own: copy directly.
• After copy-back: ./gradlew spotlessApply build in ~/projects/llamamod must pass (retry later if another agent's half-merged change breaks it; never edit their packages).
• Launch the editor: llamamod --editor [file|t1l1m001] (fat jar) on your UI display; screenshots via import -display :N.

SIMPLIFY agents (overnight review waves)

• Goal: make your assigned area simpler and cleaner WITHOUT changing behaviour: remove duplication (extract shared helpers), dead/unused code, needless indirection and over-engineering, overly long methods (split where it clarifies), inconsistent naming, unnecessary comments (keep only non-obvious ones), stray debug code; tidy APIs used only internally (make private/package-private).
• Do NOT: rewrite architectures, change file formats or byte output, change UI behaviour/labels, change public APIs used by other areas (if needed, list it instead), touch areas assigned to other agents.
• Every golden/byte-exact test and all 300+ tests must stay green; add tests if you touch untested logic. Commit nothing.
• Report: what was simplified (with rough LOC before/after for your area), anything risky you deliberately left alone, and suggestions outside your area.