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,37 @@
+# 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.