# 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:

```bash
./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.