From 97ad506ba7631842841fe8ad85ae183c21698169 Mon Sep 17 00:00:00 2001 From: Dylan Garvis Date: Fri, 4 Sep 2026 23:21:53 -0400 Subject: [PATCH] docs: define initial quest board stories --- AGENTS.md | 40 +++++++++++++++++++ knowledge/index.md | 15 +++++++ knowledge/log.md | 22 ++++++++++ knowledge/user-stories/index.md | 16 ++++++++ .../us-001-build-and-release-plugin.md | 28 +++++++++++++ ...-002-create-and-use-shared-quest-boards.md | 27 +++++++++++++ .../us-003-create-a-block-delivery-quest.md | 28 +++++++++++++ .../us-004-browse-available-quests.md | 25 ++++++++++++ ...005-deliver-blocks-and-complete-a-quest.md | 29 ++++++++++++++ .../us-006-cancel-an-owned-quest.md | 27 +++++++++++++ ...-007-expire-quests-and-claim-held-items.md | 30 ++++++++++++++ .../us-008-control-player-quest-commands.md | 27 +++++++++++++ 12 files changed, 314 insertions(+) create mode 100644 AGENTS.md create mode 100644 knowledge/index.md create mode 100644 knowledge/log.md create mode 100644 knowledge/user-stories/index.md create mode 100644 knowledge/user-stories/us-001-build-and-release-plugin.md create mode 100644 knowledge/user-stories/us-002-create-and-use-shared-quest-boards.md create mode 100644 knowledge/user-stories/us-003-create-a-block-delivery-quest.md create mode 100644 knowledge/user-stories/us-004-browse-available-quests.md create mode 100644 knowledge/user-stories/us-005-deliver-blocks-and-complete-a-quest.md create mode 100644 knowledge/user-stories/us-006-cancel-an-owned-quest.md create mode 100644 knowledge/user-stories/us-007-expire-quests-and-claim-held-items.md create mode 100644 knowledge/user-stories/us-008-control-player-quest-commands.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..f17ae4a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,40 @@ +# 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. diff --git a/knowledge/index.md b/knowledge/index.md new file mode 100644 index 0000000..33a95f5 --- /dev/null +++ b/knowledge/index.md @@ -0,0 +1,15 @@ +--- +type: Index +title: Spigot Quest Board Knowledge +description: Entry point for the Spigot Quest Board OKF knowledge bundle. +okf_version: "0.1" +--- + +# Spigot Quest Board Knowledge + +This bundle specifies shared physical quest boards, reward escrow, block deliveries, item claims, player commands, administration, persistence, and plugin delivery requirements. + +## Explore + +- [User stories](user-stories/index.md) +- [Knowledge log](log.md) diff --git a/knowledge/log.md b/knowledge/log.md new file mode 100644 index 0000000..0b9e850 --- /dev/null +++ b/knowledge/log.md @@ -0,0 +1,22 @@ +--- +type: Log +title: Spigot Quest Board Knowledge Log +description: Chronological record of material decisions affecting Spigot Quest Board. +--- + +# Spigot Quest Board Knowledge Log + +## 2026-09-05 — Initial quest-board design + +- Administrators create physical quest boards, and every board exposes the same global quests and claims. +- Players create quests by selecting a requested block material and quantity and escrowing reward items from their inventory. +- Completing players deliver the requested block items at a board and immediately receive the escrowed reward. +- Delivered blocks remain held by the quest system until the issuer claims them at a board. +- Cancelled and seven-day-expired quests return escrowed rewards through the same claim system rather than direct inventory delivery. +- Inventory overflow from rewards or claims is dropped at the receiving player's feet. +- Player `/quests` commands are disabled by default so administrators can require physical-board interaction. +- The board interface follows Spigot Base by using Purpur's supported native dialog API. + +## 2026-09-05 — Foundation started + +- Approved work begins with an OKF knowledge bundle, Java 25/Purpur 26.2 Gradle foundation, automated verification, and a public Gitea repository. diff --git a/knowledge/user-stories/index.md b/knowledge/user-stories/index.md new file mode 100644 index 0000000..42ef580 --- /dev/null +++ b/knowledge/user-stories/index.md @@ -0,0 +1,16 @@ +--- +type: Index +title: Spigot Quest Board User Stories +description: Catalog of user stories for the Spigot Quest Board plugin. +--- + +# Spigot Quest Board User Stories + +1. [US-001: Build and release the plugin](us-001-build-and-release-plugin.md) +2. [US-002: Create and use shared quest boards](us-002-create-and-use-shared-quest-boards.md) +3. [US-003: Create a block-delivery quest](us-003-create-a-block-delivery-quest.md) +4. [US-004: Browse available quests](us-004-browse-available-quests.md) +5. [US-005: Deliver blocks and complete a quest](us-005-deliver-blocks-and-complete-a-quest.md) +6. [US-006: Cancel an owned quest](us-006-cancel-an-owned-quest.md) +7. [US-007: Expire quests and claim held items](us-007-expire-quests-and-claim-held-items.md) +8. [US-008: Control player quest commands](us-008-control-player-quest-commands.md) diff --git a/knowledge/user-stories/us-001-build-and-release-plugin.md b/knowledge/user-stories/us-001-build-and-release-plugin.md new file mode 100644 index 0000000..ae32b03 --- /dev/null +++ b/knowledge/user-stories/us-001-build-and-release-plugin.md @@ -0,0 +1,28 @@ +--- +type: User Story +title: "US-001: Build and release the plugin" +description: Give maintainers repeatable Purpur builds, automated verification, and versioned public Gitea releases. +status: in-progress +--- + +# US-001: Build and release the plugin + +As a **plugin maintainer**, I want automated builds and releases modeled on Spigot Base so that tested, correctly versioned artifacts can be distributed consistently. + +## Acceptance criteria + +- [ ] The Gradle project compiles against Purpur API `26.2.build.2618-stable` using a Java 25 toolchain. +- [ ] Compiler lint warnings fail the build. +- [ ] Automated JUnit 5 tests run as part of the Gradle check lifecycle. +- [ ] Plugin metadata declares the entrypoint, player and admin commands, and permissions. +- [ ] Pushes and pull requests build and test the plugin in Gitea Actions. +- [ ] Pull requests validate conventional commit messages. +- [ ] CI stores a development JAR as a workflow artifact. +- [ ] Main-branch conventional commits drive semantic versioning. +- [ ] A successful release builds a versioned JAR and attaches it to the corresponding Gitea release. +- [ ] The project is published in the public `dmg/spigot-quest-board` Gitea repository. +- [ ] Build files, Gradle wrapper, workflows, and release behavior follow `../spigot-base/` where applicable while using Spigot Quest Board names and identifiers. + +## Related + +- [User-story catalog](index.md) diff --git a/knowledge/user-stories/us-002-create-and-use-shared-quest-boards.md b/knowledge/user-stories/us-002-create-and-use-shared-quest-boards.md new file mode 100644 index 0000000..ac0b878 --- /dev/null +++ b/knowledge/user-stories/us-002-create-and-use-shared-quest-boards.md @@ -0,0 +1,27 @@ +--- +type: User Story +title: "US-002: Create and use shared quest boards" +description: Let administrators establish persistent physical boards that expose one shared quest system. +status: backlog +--- + +# US-002: Create and use shared quest boards + +As an **administrator**, I want to turn a targeted block into a quest board so that players can interact with quests at controlled physical locations. + +## Acceptance criteria + +- [ ] An authorized administrator can use `/questadmin createboard` to register the block they are targeting. +- [ ] Creation rejects a missing, invalid, or already registered target without changing state. +- [ ] Registered boards persist across server restarts with their world and block coordinates. +- [ ] Interacting with any registered board opens the quest-board interface. +- [ ] Every registered board exposes the same global quests and claimable items. +- [ ] The interface uses Purpur's supported native dialog API and follows the interaction style of Spigot Base. +- [ ] Ordinary block interaction is not intercepted at unregistered locations. +- [ ] Administrative actions require the `spigotquestboard.admin` permission, granted to server operators by default. +- [ ] Automated tests verify board registration, persistence, shared visibility, authorization, and interaction routing. + +## Related + +- [US-003: Create a block-delivery quest](us-003-create-a-block-delivery-quest.md) +- [US-004: Browse available quests](us-004-browse-available-quests.md) diff --git a/knowledge/user-stories/us-003-create-a-block-delivery-quest.md b/knowledge/user-stories/us-003-create-a-block-delivery-quest.md new file mode 100644 index 0000000..1177c73 --- /dev/null +++ b/knowledge/user-stories/us-003-create-a-block-delivery-quest.md @@ -0,0 +1,28 @@ +--- +type: User Story +title: "US-003: Create a block-delivery quest" +description: Let a player request block items while safely escrowing an inventory-funded reward. +status: backlog +--- + +# US-003: Create a block-delivery quest + +As a **player**, I want to request a block material and quantity in exchange for items I already own so that another player can fulfill my request safely. + +## Acceptance criteria + +- [ ] A player can create a quest through a registered quest board by selecting a valid block material, a positive quantity, and reward items from their inventory. +- [ ] Reward items must exist in the issuer's inventory and are removed only when quest creation succeeds. +- [ ] Removed rewards are held durably in escrow by the quest system. +- [ ] A created quest records a unique identifier, issuer UUID and current name, requested material and quantity, exact reward items, creation time, and expiration time. +- [ ] Each quest expires exactly seven days after successful creation. +- [ ] Invalid input, insufficient reward items, or persistence failure leaves the issuer's inventory unchanged and creates no quest. +- [ ] When player commands are enabled, `/quests create ...` provides equivalent validated creation behavior with contextual autocomplete. +- [ ] Quest state and item metadata survive server restarts without duplication or loss. +- [ ] Automated tests verify validation, escrow, rollback, timestamps, command routing, and persistence. + +## Related + +- [US-002: Create and use shared quest boards](us-002-create-and-use-shared-quest-boards.md) +- [US-005: Deliver blocks and complete a quest](us-005-deliver-blocks-and-complete-a-quest.md) +- [US-007: Expire quests and claim held items](us-007-expire-quests-and-claim-held-items.md) diff --git a/knowledge/user-stories/us-004-browse-available-quests.md b/knowledge/user-stories/us-004-browse-available-quests.md new file mode 100644 index 0000000..9f43717 --- /dev/null +++ b/knowledge/user-stories/us-004-browse-available-quests.md @@ -0,0 +1,25 @@ +--- +type: User Story +title: "US-004: Browse available quests" +description: Let players inspect globally available quests and their essential terms. +status: backlog +--- + +# US-004: Browse available quests + +As a **player**, I want to browse current quests so that I can decide which block deliveries to fulfill. + +## Acceptance criteria + +- [ ] Every registered board lists the same active quests. +- [ ] Each listing shows the requested block material, quantity, reward, issuer, and time remaining. +- [ ] Remaining durations are clear and never display an expired quest as active. +- [ ] Completed, cancelled, and expired quests are excluded from the active listing. +- [ ] When player commands are enabled, `/quests` and `/quests list` provide the same active quest information in chat. +- [ ] Listing and autocomplete do not expose stale quest identifiers as completable or cancellable. +- [ ] Automated tests verify filtering, displayed fields, duration boundaries, and command aliases. + +## Related + +- [US-002: Create and use shared quest boards](us-002-create-and-use-shared-quest-boards.md) +- [US-005: Deliver blocks and complete a quest](us-005-deliver-blocks-and-complete-a-quest.md) diff --git a/knowledge/user-stories/us-005-deliver-blocks-and-complete-a-quest.md b/knowledge/user-stories/us-005-deliver-blocks-and-complete-a-quest.md new file mode 100644 index 0000000..f45f65d --- /dev/null +++ b/knowledge/user-stories/us-005-deliver-blocks-and-complete-a-quest.md @@ -0,0 +1,29 @@ +--- +type: User Story +title: "US-005: Deliver blocks and complete a quest" +description: Let a player deliver requested blocks at a quest board and receive the escrowed reward. +status: backlog +--- + +# US-005: Deliver blocks and complete a quest + +As a **player**, I want to deliver requested blocks to a quest board so that I receive the promised reward and the issuer can claim my delivery. + +## Acceptance criteria + +- [ ] An active quest offers a Complete Quest action through every registered board. +- [ ] Completion requires the delivering player to possess the full requested quantity of the exact block material. +- [ ] Successful completion removes the requested blocks from the delivering player's inventory and stores them as a claim for the issuer. +- [ ] Successful completion gives the exact escrowed reward items to the delivering player. +- [ ] Reward items that do not fit are dropped safely at the delivering player's feet with a clear message. +- [ ] The issuer is notified immediately when online or on their next login when offline that delivered blocks can be claimed at a quest board. +- [ ] When player commands are enabled, `/quests complete ` provides equivalent behavior with contextual autocomplete. +- [ ] Completion is atomic and exactly one player can complete a quest, including simultaneous attempts. +- [ ] Validation or persistence failure does not consume delivered blocks, release rewards, or change quest state. +- [ ] Completed quests are no longer shown as active or completable. +- [ ] Automated tests verify inventory validation, settlement, overflow, notifications, rollback, and concurrent completion protection. + +## Related + +- [US-003: Create a block-delivery quest](us-003-create-a-block-delivery-quest.md) +- [US-007: Expire quests and claim held items](us-007-expire-quests-and-claim-held-items.md) diff --git a/knowledge/user-stories/us-006-cancel-an-owned-quest.md b/knowledge/user-stories/us-006-cancel-an-owned-quest.md new file mode 100644 index 0000000..61a1e4c --- /dev/null +++ b/knowledge/user-stories/us-006-cancel-an-owned-quest.md @@ -0,0 +1,27 @@ +--- +type: User Story +title: "US-006: Cancel an owned quest" +description: Let an issuer cancel an active quest and reclaim its escrowed reward safely. +status: backlog +--- + +# US-006: Cancel an owned quest + +As a **quest issuer**, I want to cancel my active quest so that I can reclaim the reward when I no longer need the requested blocks. + +## Acceptance criteria + +- [ ] An issuer can cancel their own active quest through any registered board. +- [ ] A player cannot cancel a quest issued by another player. +- [ ] Completed, cancelled, and expired quests cannot be cancelled. +- [ ] Cancellation removes the quest from active listings and converts its exact escrowed reward into a claim for the issuer. +- [ ] The reward is not inserted directly into the issuer's inventory during cancellation. +- [ ] When player commands are enabled, `/quests cancel ` provides equivalent behavior and only autocompletes the player's cancellable quest identifiers. +- [ ] Cancellation and simultaneous completion are serialized so items cannot be duplicated or lost. +- [ ] Persistence failure leaves the quest active and its reward escrowed. +- [ ] Automated tests verify ownership, state validation, claim creation, autocomplete, rollback, and completion races. + +## Related + +- [US-003: Create a block-delivery quest](us-003-create-a-block-delivery-quest.md) +- [US-007: Expire quests and claim held items](us-007-expire-quests-and-claim-held-items.md) diff --git a/knowledge/user-stories/us-007-expire-quests-and-claim-held-items.md b/knowledge/user-stories/us-007-expire-quests-and-claim-held-items.md new file mode 100644 index 0000000..a842f3a --- /dev/null +++ b/knowledge/user-stories/us-007-expire-quests-and-claim-held-items.md @@ -0,0 +1,30 @@ +--- +type: User Story +title: "US-007: Expire quests and claim held items" +description: Hold delivered blocks and returned rewards until their owner safely claims them. +status: backlog +--- + +# US-007: Expire quests and claim held items + +As a **quest issuer**, I want delivered blocks and returned rewards held at the shared quest board so that I can retrieve them safely. + +## Acceptance criteria + +- [ ] An uncompleted quest expires seven days after its creation time. +- [ ] Expiration removes the quest from active listings and converts its exact escrowed reward into a claim for the issuer. +- [ ] Completed-quest claims contain the exact block items delivered by the completing player. +- [ ] Claims from completion, cancellation, and expiration can be collected through any registered board. +- [ ] The board clearly distinguishes delivered blocks from returned rewards. +- [ ] Online issuers receive a real-time message when items become claimable. +- [ ] Offline issuers receive a message on their next login. +- [ ] When player commands are enabled, `/quests claim` collects the same pending claims. +- [ ] Items are inserted into the claimant's inventory where space permits; overflow is dropped safely at their feet with a clear message. +- [ ] A claim is removed only after all of its items have been inserted or dropped successfully. +- [ ] Pending claims and notification state survive logout and server restart without duplication or loss. +- [ ] Automated tests verify expiry boundaries, each claim source, notifications, overflow, failure recovery, and persistence. + +## Related + +- [US-005: Deliver blocks and complete a quest](us-005-deliver-blocks-and-complete-a-quest.md) +- [US-006: Cancel an owned quest](us-006-cancel-an-owned-quest.md) diff --git a/knowledge/user-stories/us-008-control-player-quest-commands.md b/knowledge/user-stories/us-008-control-player-quest-commands.md new file mode 100644 index 0000000..25e2875 --- /dev/null +++ b/knowledge/user-stories/us-008-control-player-quest-commands.md @@ -0,0 +1,27 @@ +--- +type: User Story +title: "US-008: Control player quest commands" +description: Let administrators require physical-board interaction by controlling access to player quest commands. +status: backlog +--- + +# US-008: Control player quest commands + +As an **administrator**, I want to enable or disable player quest commands so that I can require players to use physical quest boards. + +## Acceptance criteria + +- [ ] Player `/quests` commands are disabled by default. +- [ ] An authorized administrator can use `/questadmin commands enable|disable` with contextual autocomplete. +- [ ] The command setting persists across server restarts. +- [ ] When disabled, `/quests`, `list`, `create`, `complete`, `cancel`, and `claim` reject execution with a clear message directing the player to a quest board. +- [ ] Disabling commands does not prevent any equivalent action through a registered board. +- [ ] `/questadmin` remains available to authorized administrators regardless of the player-command setting. +- [ ] Unauthorized users cannot change the setting. +- [ ] Automated tests verify the default, persistence, authorization, every gated subcommand, and autocomplete. + +## Related + +- [US-002: Create and use shared quest boards](us-002-create-and-use-shared-quest-boards.md) +- [US-003: Create a block-delivery quest](us-003-create-a-block-delivery-quest.md) +- [US-007: Expire quests and claim held items](us-007-expire-quests-and-claim-held-items.md)