docs: add initial design bundle

2026-09-04 11:02:53 -04:00
commit a16559c9c5
8 changed files with 185 additions and 0 deletions
@@ -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)