spigot-quest-board/AGENTS.md

Spigot Quest Board Agent Guide

Project

Spigot Quest Board is a Java 25 plugin for Purpur 26.2. It provides shared physical quest boards where players escrow rewards, deliver requested block items, and claim delivered or returned items.

Canonical knowledge

• knowledge/ is the canonical OKF v0.1 knowledge bundle.
• Read knowledge/index.md and the relevant documents in knowledge/user-stories/ before changing behavior.
• Every feature or behavior change requires an approved user story with task-list acceptance criteria.
• Preserve unknown YAML frontmatter fields when editing knowledge documents.
• Keep knowledge/index.md, knowledge/log.md, and knowledge/user-stories/index.md current.

Development

• Compile against the Purpur API version declared in build.gradle.kts.
• Use Java 25 and enable strict compiler linting.
• Prefer small, server-independent domain objects and services that can be unit tested.
• Use test-driven development where practical: add a failing test, implement the minimum behavior, then refactor.
• Treat escrow, completion, cancellation, expiry, and claiming as atomic state transitions. Never duplicate or silently discard player items.
• Key players by UUID, not display name.
• Persist board, quest, escrow, and claim state safely across restarts using atomic file replacement where supported.
• Use UTC and RFC 3339 timestamps for persisted or documented date-times.
• Keep player-facing command autocomplete permission-aware and context-sensitive.
• Use Purpur's supported Paper dialog API for native dialog interfaces.

Verification

Run before completing a story:

./gradlew clean check jar

Mark acceptance criteria complete only after implementation and verification.

Git

Use conventional commits in the form type(scope): description, with summaries under 72 characters.