commit a16559c9c579b79eec1659c89678df7c2564ab10 Author: Dylan Garvis Date: Fri Sep 4 11:02:53 2026 -0400 docs: add initial design bundle diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..21993af --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,37 @@ +# Project Agent Instructions + +## Project + +- This repository contains the Spigot Inventory Helper plugin. +- Target Purpur `26.2.build.2618-stable` with Java 25, matching `../spigot-base/` unless an approved user story changes the target. +- Use Gradle with Kotlin DSL and the Gradle wrapper. +- Keep compiler lint warnings enabled and fail builds on warnings, excluding only warnings explicitly justified by the supported API. + +## Knowledge bundle + +- `design/` is the canonical OKF v0.1 knowledge bundle. Do not create a parallel `knowledge/` bundle. +- Read `design/index.md`, the user-story catalog, relevant stories, and relevant implementation before changing behavior. +- Every feature or behavior change must have a corresponding story under `design/user-stories/`. +- Present proposed story additions or changes for review and wait for explicit approval before modifying stories or code. +- Stories must have OKF frontmatter with `type: User Story`, a descriptive `title`, concise `description`, and one of `backlog`, `in-progress`, or `done` as `status`. +- Stories must contain acceptance criteria using Markdown task-list items. +- Set approved work to `in-progress` when implementation begins. Set it to `done` and check criteria only after implementation and verification. +- Maintain standard Markdown links between the root index, story catalog, related stories, and other concepts. +- Record material design and implementation decisions in `design/log.md`. Verify the current date before adding entries. + +## Development + +- Use test-driven development where practical: write a failing test, implement the minimum behavior, and refactor only while tests remain green. +- Prefer small, cohesive Java types and server-independent logic that can be unit tested without a running Minecraft server. +- Identify custom plugin items with persistent metadata rather than display names alone. +- Preserve item quantities and metadata during inventory operations. +- Respect Bukkit/Purpur event cancellation and protection-plugin decisions. +- Run `./gradlew clean check jar` before marking implementation criteria complete. + +## Delivery + +- Model Gradle and Gitea Actions configuration on `../spigot-base/`, adapted to this plugin's names and identifiers. +- Gitea workflows belong in `.gitea/workflows/`. +- Pull requests must validate conventional commits, and main-branch conventional commits drive semantic releases. +- Never commit generated Gradle output or plugin JARs. +- Use conventional commit messages in the form `type(scope): description`, with a concise summary under 72 characters. diff --git a/design/index.md b/design/index.md new file mode 100644 index 0000000..e8f63f5 --- /dev/null +++ b/design/index.md @@ -0,0 +1,15 @@ +--- +type: Index +title: Spigot Inventory Helper Design +description: Entry point for the Spigot Inventory Helper OKF knowledge bundle. +okf_version: "0.1" +--- + +# Spigot Inventory Helper Design + +This bundle documents inventory sorting, custom utility items, automatic tool replacement, and delivery requirements for the Spigot Inventory Helper plugin. + +## Explore + +- [User stories](user-stories/index.md) +- [Design log](log.md) diff --git a/design/log.md b/design/log.md new file mode 100644 index 0000000..b26c16e --- /dev/null +++ b/design/log.md @@ -0,0 +1,15 @@ +--- +type: Log +title: Spigot Inventory Helper Design Log +description: Chronological record of material decisions affecting the Spigot Inventory Helper design. +--- + +# Spigot Inventory Helper Design Log + +## 2026-09-04 — Initial inventory-helper design + +- Players will be able to craft a metadata-authenticated Sorting Stick. +- The Sorting Stick will sort chests, double chests, barrels, or the player's main storage inventory depending on the interaction target. +- Player-inventory sorting will leave the hotbar, armor, and off-hand slots unchanged. +- When a main-hand tool breaks, an equivalent tool with the same material and tool type will be moved from the player's inventory into the selected hotbar slot when available. +- The knowledge bundle and eventual Gradle, Purpur, Gitea CI, and semantic-release setup will follow the neighboring Spigot Base project where applicable. diff --git a/design/user-stories/index.md b/design/user-stories/index.md new file mode 100644 index 0000000..23212d2 --- /dev/null +++ b/design/user-stories/index.md @@ -0,0 +1,12 @@ +--- +type: Index +title: Spigot Inventory Helper User Stories +description: Catalog of user stories for the Spigot Inventory Helper plugin. +--- + +# Spigot Inventory Helper User Stories + +1. [US-001: Build and release the plugin](us-001-build-and-release-plugin.md) +2. [US-002: Craft a Sorting Stick](us-002-craft-sorting-stick.md) +3. [US-003: Sort containers and player inventory](us-003-sort-inventories.md) +4. [US-004: Automatically replace broken tools](us-004-replace-broken-tools.md) diff --git a/design/user-stories/us-001-build-and-release-plugin.md b/design/user-stories/us-001-build-and-release-plugin.md new file mode 100644 index 0000000..b79f0b9 --- /dev/null +++ b/design/user-stories/us-001-build-and-release-plugin.md @@ -0,0 +1,26 @@ +--- +type: User Story +title: "US-001: Build and release the plugin" +description: Give maintainers repeatable Purpur builds, automated verification, and versioned Gitea releases. +status: backlog +--- + +# US-001: Build and release the plugin + +As a **plugin maintainer**, I want repeatable builds and automated releases 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. +- [ ] 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. +- [ ] Build files, Gradle wrapper, workflows, and release behavior follow `../spigot-base/` where applicable while using Spigot Inventory Helper names and identifiers. + +## Related + +- [User-story catalog](index.md) diff --git a/design/user-stories/us-002-craft-sorting-stick.md b/design/user-stories/us-002-craft-sorting-stick.md new file mode 100644 index 0000000..c683a9d --- /dev/null +++ b/design/user-stories/us-002-craft-sorting-stick.md @@ -0,0 +1,24 @@ +--- +type: User Story +title: "US-002: Craft a Sorting Stick" +description: Let players craft a recognizable utility item that invokes inventory sorting. +status: backlog +--- + +# US-002: Craft a Sorting Stick + +As a **player**, I want to craft a recognizable Sorting Stick so that I can invoke inventory sorting during normal gameplay. + +## Acceptance criteria + +- [ ] The plugin registers a documented shaped crafting recipe for the Sorting Stick. +- [ ] The Sorting Stick has a distinct player-facing name and appearance. +- [ ] The item is identified using persistent item metadata rather than its display name alone. +- [ ] Renamed ordinary sticks cannot trigger sorting. +- [ ] Recipe registration, recipe shape, and resulting item identity are covered by automated tests. +- [ ] The crafting recipe is documented for players. + +## Related + +- [US-003: Sort containers and player inventory](us-003-sort-inventories.md) +- [User-story catalog](index.md) diff --git a/design/user-stories/us-003-sort-inventories.md b/design/user-stories/us-003-sort-inventories.md new file mode 100644 index 0000000..c46d64d --- /dev/null +++ b/design/user-stories/us-003-sort-inventories.md @@ -0,0 +1,30 @@ +--- +type: User Story +title: "US-003: Sort containers and player inventory" +description: Let players use a Sorting Stick to consolidate and organize supported storage or their main inventory. +status: backlog +--- + +# US-003: Sort containers and player inventory + +As a **player holding a Sorting Stick**, I want to sort storage containers or my main inventory so that related items are consolidated and organized automatically. + +## Acceptance criteria + +- [ ] Using the Sorting Stick on a chest sorts the complete chest inventory. +- [ ] Using it on either half of a double chest sorts the combined inventory. +- [ ] Using it on a barrel sorts that barrel. +- [ ] Using it without targeting a supported container sorts the player's main storage slots. +- [ ] Player hotbar, armor, and off-hand slots are not changed during player-inventory sorting. +- [ ] Compatible partial stacks are consolidated without exceeding item stack limits. +- [ ] Remaining stacks are placed in a deterministic, documented order. +- [ ] Sorting preserves item quantities and all item metadata exactly. +- [ ] Sorting respects cancelled interactions and normal container-access protections. +- [ ] Unsupported or inaccessible targets fail safely without changing an inventory. +- [ ] Sorting provides concise player feedback without opening the target container. +- [ ] Automated tests cover single chests, double chests, barrels, player inventory boundaries, stack consolidation, metadata preservation, and rejected interactions. + +## Related + +- [US-002: Craft a Sorting Stick](us-002-craft-sorting-stick.md) +- [User-story catalog](index.md) diff --git a/design/user-stories/us-004-replace-broken-tools.md b/design/user-stories/us-004-replace-broken-tools.md new file mode 100644 index 0000000..180fc8f --- /dev/null +++ b/design/user-stories/us-004-replace-broken-tools.md @@ -0,0 +1,26 @@ +--- +type: User Story +title: "US-004: Automatically replace broken tools" +description: Move an equivalent inventory tool into the player's hand when their current main-hand tool breaks. +status: backlog +--- + +# US-004: Automatically replace broken tools + +As a **player**, I want an equivalent tool moved into my hand when my current tool breaks so that I can continue working without searching my inventory. + +## Acceptance criteria + +- [ ] When a player's main-hand tool breaks, the plugin searches the player's inventory for a replacement. +- [ ] A replacement must have the same tool type and material as the broken tool; for example, a diamond pickaxe replaces only a diamond pickaxe. +- [ ] Eligible replacements may come from the main storage inventory or another hotbar slot. +- [ ] The replacement is moved into the currently selected hotbar slot. +- [ ] Existing durability, enchantments, custom names, persistent data, and other metadata on the replacement are preserved. +- [ ] No unrelated item is moved when an equivalent replacement is unavailable. +- [ ] Off-hand tool breakage does not replace the main-hand item. +- [ ] Cancelled damage or break events do not trigger replacement. +- [ ] Automated tests cover matching, unavailable replacements, hotbar and main-storage candidates, metadata preservation, and off-hand behavior. + +## Related + +- [User-story catalog](index.md)