docs: add initial design bundle

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)

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)

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)

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)

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)