diff --git a/AGENTS.md b/AGENTS.md index 21993af..d7d5e18 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,37 +1,9 @@ -# Project Agent Instructions +# spigot-inventory-helper agent entrypoint -## Project +The canonical stories, engineering guidance, and **all process documents** are in the private [SoMC OKF wiki](https://git.garvis.dev/dmg/somc-okf/src/branch/main/index.md). -- 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. +Before work, read the sibling `../somc-okf/index.md`, `../somc-okf/processes/index.md`, `../somc-okf/projects/spigot-inventory-helper/index.md`, `engineering.md` in that project section, and relevant `../somc-okf/user-stories/spigot-inventory-helper/` stories. Also follow the parent workspace `AGENTS.md` when present. -## Knowledge bundle +For standalone checkouts, start at the [project page](https://git.garvis.dev/dmg/somc-okf/src/branch/main/projects/spigot-inventory-helper/index.md) and [shared process](https://git.garvis.dev/dmg/somc-okf/src/branch/main/processes/development.md). Obtain wiki access before feature work; do not recreate a local knowledge bundle. Source builds do not require private wiki access. -- `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. +Development follows [Development cycle](https://git.garvis.dev/dmg/somc-okf/src/branch/main/runbooks/development-cycle.md): approved stories, failing tests, passing implementation, verification, then source/wiki commit and push. GitOps updates are committed locally **without pushing**; only [Do release](https://git.garvis.dev/dmg/somc-okf/src/branch/main/runbooks/do-release.md) authorizes a reviewed GitOps push. diff --git a/README.md b/README.md index 7645846..f8d695d 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ A Purpur 26.2 plugin that sorts inventories with a craftable Sorting Stick and automatically replaces broken tools with equivalent tools from the player's inventory. -The approved behavior is specified in the [OKF design bundle](design/index.md). +The approved behavior is specified in the [SoMC OKF wiki](https://git.garvis.dev/dmg/somc-okf/src/branch/main/projects/spigot-inventory-helper/index.md). ## Requirements diff --git a/design/index.md b/design/index.md deleted file mode 100644 index e8f63f5..0000000 --- a/design/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -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 deleted file mode 100644 index 04dba1b..0000000 --- a/design/log.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -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. - -## 2026-09-04 — Sorting Stick recipe - -- The Sorting Stick uses a vertical recipe in the crafting grid's center column: a Chest or Barrel above Redstone Dust, with a Stick at the bottom. -- Either storage-block variant produces one Sorting Stick. - -## 2026-09-04 — Build and release foundation completed - -- Added the Java 25 Gradle build, Purpur API dependency, strict compiler linting, JUnit 5 lifecycle, plugin metadata, and initial plugin entry point. -- Added Gitea CI, conventional-commit validation for pull requests, development artifacts, semantic releases, and release-asset upload. -- Verified `./gradlew clean check jar`, successful main and tag CI runs, and release `v1.0.0` with `spigot-inventory-helper-1.0.0.jar` attached. - -## 2026-09-04 — Sorting Stick completed - -- Added a gold-named, glinting Sorting Stick authenticated by persistent item metadata. -- Registered equivalent chest and barrel recipe variants matching the approved center-column shape. -- Verified recipe specification, registration, output, item appearance, identity, and renamed-stick rejection with automated tests and `./gradlew clean check jar`. - -## 2026-09-04 — Inventory sorting completed - -- Added metadata-preserving stack consolidation and stable alphabetical ordering by Minecraft material. -- Added Sorting Stick interactions for single and double chests, barrels, and player main-storage slots while preserving hotbar, armor, and off-hand slots. -- Rejected locked containers, cancelled protection events, non-right-click interactions, and unauthenticated sticks without changing inventories. -- Added action-bar feedback, documented player behavior, and verified the complete feature with `./gradlew clean check jar`. - -## 2026-09-04 — Automatic tool replacement completed - -- Added next-tick replacement of broken main-hand tools with exact-material matches from player storage. -- Main storage is searched before other hotbar slots, and the replacement item is moved intact into the captured selected slot without overwriting a newly occupied slot. -- Off-hand breaks and unavailable or mismatched replacements leave inventory unchanged. -- Added player feedback and verified matching, source priority, metadata-preserving movement, safety, and off-hand behavior with automated tests and `./gradlew clean check jar`. - -## 2026-09-04 — Implementation started - -- Approved implementation begins with the tested Gradle and Purpur foundation, followed by the Sorting Stick, inventory sorting, and automatic tool replacement. -- Work proceeds one user story at a time using red-green-refactor cycles and a verified commit and push after each completed story. diff --git a/design/user-stories/index.md b/design/user-stories/index.md deleted file mode 100644 index 23212d2..0000000 --- a/design/user-stories/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -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 deleted file mode 100644 index 5c541be..0000000 --- a/design/user-stories/us-001-build-and-release-plugin.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -type: User Story -title: "US-001: Build and release the plugin" -description: Give maintainers repeatable Purpur builds, automated verification, and versioned Gitea releases. -status: done ---- - -# 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 - -- [x] The Gradle project compiles against Purpur API `26.2.build.2618-stable` using a Java 25 toolchain. -- [x] Compiler lint warnings fail the build. -- [x] Automated JUnit 5 tests run as part of the Gradle check lifecycle. -- [x] Pushes and pull requests build and test the plugin in Gitea Actions. -- [x] Pull requests validate conventional commit messages. -- [x] CI stores a development JAR as a workflow artifact. -- [x] Main-branch conventional commits drive semantic versioning. -- [x] A successful release builds a versioned JAR and attaches it to the corresponding Gitea release. -- [x] 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 deleted file mode 100644 index 04218e1..0000000 --- a/design/user-stories/us-002-craft-sorting-stick.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -type: User Story -title: "US-002: Craft a Sorting Stick" -description: Let players craft a recognizable utility item that invokes inventory sorting. -status: done ---- - -# 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 - -- [x] The plugin registers a vertical shaped recipe with a Chest or Barrel above Redstone Dust and Redstone Dust above a Stick. -- [x] The three ingredients occupy the center column of the 3×3 crafting grid. -- [x] Either the Chest or Barrel recipe variant produces one Sorting Stick. -- [x] The Sorting Stick has a distinct player-facing name and appearance. -- [x] The item is identified using persistent item metadata rather than its display name alone. -- [x] Renamed ordinary sticks cannot trigger sorting. -- [x] Automated tests cover recipe registration, the exact shape, both storage-block variants, output quantity, and resulting item identity. -- [x] The crafting recipe and both accepted variants are 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 deleted file mode 100644 index 66dd92b..0000000 --- a/design/user-stories/us-003-sort-inventories.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -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: done ---- - -# 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 - -- [x] Using the Sorting Stick on a chest sorts the complete chest inventory. -- [x] Using it on either half of a double chest sorts the combined inventory. -- [x] Using it on a barrel sorts that barrel. -- [x] Using it without targeting a supported container sorts the player's main storage slots. -- [x] Player hotbar, armor, and off-hand slots are not changed during player-inventory sorting. -- [x] Compatible partial stacks are consolidated without exceeding item stack limits. -- [x] Remaining stacks are placed in a deterministic, documented order. -- [x] Sorting preserves item quantities and all item metadata exactly. -- [x] Sorting respects cancelled interactions and normal container-access protections. -- [x] Unsupported or inaccessible targets fail safely without changing an inventory. -- [x] Sorting provides concise player feedback without opening the target container. -- [x] 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 deleted file mode 100644 index 59231bc..0000000 --- a/design/user-stories/us-004-replace-broken-tools.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -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: done ---- - -# 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 - -- [x] When a player's main-hand tool breaks, the plugin searches the player's inventory for a replacement. -- [x] A replacement must have the same tool type and material as the broken tool; for example, a diamond pickaxe replaces only a diamond pickaxe. -- [x] Eligible replacements may come from the main storage inventory or another hotbar slot. -- [x] The replacement is moved into the currently selected hotbar slot. -- [x] Existing durability, enchantments, custom names, persistent data, and other metadata on the replacement are preserved. -- [x] No unrelated item is moved when an equivalent replacement is unavailable. -- [x] Off-hand tool breakage does not replace the main-hand item. -- [x] Cancelled damage or break events do not trigger replacement. -- [x] Automated tests cover matching, unavailable replacements, hotbar and main-storage candidates, metadata preservation, and off-hand behavior. - -## Related - -- [User-story catalog](index.md)