# 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.