41 lines
1.8 KiB
Markdown
41 lines
1.8 KiB
Markdown
# 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.
|