spigot-stealth/AGENTS.md

Repository Agent Guidance

User-story-driven development

The design/ directory is the OKF v0.1 product record for this repository. Use user stories to plan, implement, verify, and track all behavior.

Before changing behavior:

1. Read design/index.md and every story related to the requested behavior.
2. Draft updates to an existing story or create a new design/user-stories/us-NNN-short-name.md story before implementation.
3. Define observable acceptance criteria using user or operator language.
4. Present the relevant new or updated stories and acceptance criteria to the user for review, and wait for explicit confirmation before changing implementation code.
5. Incorporate requested story changes before proceeding.
6. Set story status to in-progress while approved implementation is incomplete.

While implementing:

1. Work in vertical slices against the documented acceptance criteria.
2. Add tests for important behavior before implementation when practical.
3. Keep implementation references and related-story links current.
4. Do not mark an acceptance criterion complete until the behavior exists and has been validated.

Before completing or committing:

1. Set a completed story status to done only when all acceptance criteria are complete and verified.
2. Check completed acceptance criteria and record validation evidence where appropriate.
3. Update design/index.md and design/user-stories/index.md whenever stories are added, renamed, moved, or materially reclassified.
4. Add a high-level entry to design/log.md under the verified current date.
5. Run OKF validation along with relevant Gradle tests, lint checks, and builds.

OKF conventions

• Every non-reserved Markdown file in design/ must have YAML frontmatter with a non-empty type.
• User stories use type: User Story and include status, title, and description.
• Allowed story statuses are backlog, in-progress, and done.
• Every user story includes an acceptance-criteria section using Markdown task-list items.
• design/index.md and design/log.md are reserved OKF files and follow the OKF index/log structures.
• Store user stories in design/user-stories/ and keep their catalog current.
• Use standard Markdown links and keep repository-local links valid when files move.
• Preserve unknown frontmatter extensions.

Java and Spigot development

• Use the Java version and Spigot API version declared by the Gradle build.
• Treat compiler warnings as errors.
• Prefer test-first development for domain rules and state transitions when practical.
• Run ./gradlew clean check jar before completing implementation work.
• Keep Bukkit event handlers thin and move testable game rules into focused domain services.
• Do not perform blocking file or network operations on the server tick thread.

Timestamps

Always run date +%Y-%m-%d before adding or updating dates in stories or the design log. Use RFC 3339 UTC timestamps (YYYY-MM-DDTHH:MM:SSZ) when a date-time is required. Never guess dates.