spigot-heights/AGENTS.md

Spigot Heights Agent Guide

Canonical design

• design/ is the canonical OKF v0.1 knowledge bundle.
• Read relevant user stories before implementation and keep acceptance criteria and design/log.md synchronized with verified behavior.

Engineering

• Target Java 25 and Purpur 26.2.build.2618-stable.
• Use Gradle Kotlin DSL and JUnit 5.
• Prefer small, server-independent domain classes with Bukkit adapters at the boundary.
• Develop test-first where practical and verify with ./gradlew clean check jar.
• Treat custom item identity as persistent metadata; never trust display names.
• Validate all configuration before enabling gameplay behavior.
• Persist player data by UUID and use atomic replacement where supported.
• Keep event handlers on the server thread and avoid unnecessary work on player movement.
• Use conventional commits in the form type(scope): description.