# 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`.