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.

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.

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.

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.