arena-of-shinuwa/.local/AGENTS.md

AGENTS.md — Arena Mod

Mission

Build a server-first NeoForge 1.21.1 PvE arena mod. The mod must remain usable without Cobblemon, EasyNPC, Create, or any boss mod.

Working rules

1. SPEC.md is the functional source of truth. ARCHITECTURE.md is the technical source of truth.
2. Work only on the current unchecked phase in TODO.md, unless explicitly asked otherwise.
3. Inspect the existing project and dependency versions before coding. Never invent an API.
4. For optional integrations (Cobblemon/EasyNPC/third-party entities), verify the actual installed API/source before writing integration code.
5. Keep optional integrations isolated; absence of an optional mod MUST NOT prevent startup.
6. Prefer Minecraft/NeoForge registries and resource IDs (namespace:path) over hard-coded vanilla lists.
7. Content must be data-driven where specified. Invalid content disables only the affected definition and produces a useful diagnostic; it must not crash the server.
8. Inventory safety is critical. Never clear a player's original inventory until its recovery snapshot has been durably persisted.
9. Avoid unrelated refactors. Keep commits/changes scoped and easy to review.
10. Compile/test after each phase. Fix compilation errors before declaring a phase complete.
11. Add focused tests where practical, especially for pure logic (wave budgeting, rank thresholds, validation, state transitions).
12. If implementation must diverge from these docs, document the reason in ARCHITECTURE.md before proceeding.
13. Update TODO.md only for work actually completed.

Definition of done for a phase

• Project compiles.
• Existing tests still pass.
• New behavior has a minimal test or reproducible manual test procedure.
• No optional dependency became mandatory.
• No known inventory-loss/duplication path was introduced.
• TODO.md reflects reality.