ScoreKeeper/AGENTS.md

Score Keeper: Shared Working Rules

These rules apply to agents and human contributors. Start with CONTRIBUTING.md for setup, tasks, server safety, and release procedures; README.md is the user-facing behavior reference.

Quick orientation

• Java 25, Gradle 9.8.0 wrapper, Paper 26.2/26.3 only; no Bukkit/Spigot target.
• ScoreKeeperPlugin.java owns lifecycle, buckets, UUID-keyed scores, YAML persistence, archives, reporting, and scheduled high-score runs.
• ScoreBucket.java validates immutable definitions; ScoreReporting.java defines audiences. commands/ contains eight executors wired in onEnable and plugin.yml.
• CONTRIBUTING.md owns the source map and architecture overview. Consult the domain reference or integration reference only when the task needs their detail. There are no built-in gameplay listeners or registered API service.

Change discipline

• Inspect the source and current diff before editing. Preserve unrelated work; make scoped, complete changes and document intentional behavior changes.
• Use Score Keeper in human-facing prose/display text. Keep ScoreKeeper for repository URLs, plugin ID/data folder, Gradle/artifact names, and Java symbols. Preserve scraper identifiers exactly as currently stored in project-description.json. Ask before renaming existing files or changing these integration identifiers.
• Follow existing Java patterns, Adventure components, UUID identity, and plugin logging. Use Spotless rather than hand-formatting Java; preserve the AGPL header. Do not add silent error recovery or success messages for failed operations.
• Keep state and Paper API calls on the main thread. Do not introduce async map access; marshal asynchronous results through Paper's synchronous scheduler.
• Wire command/API changes across executors, manifest, lifecycle, reporting, persistence, and documentation as applicable. Preserve existing public overloads and legacy YAML loading unless a migration is explicitly agreed.
• Preserve documented quirks until intentionally changed: unguarded score mutations, signed integer arithmetic, lazy score entries, case-sensitive bucket IDs, shutdown-only saves, and run snapshot restoration. Do not "fix" these as incidental cleanup.
• Prefer existing helpers and dependencies. Do not introduce a service layer, test harness, runtime dependency, or supported platform without a task need.
• Edit source, not generated build/, bin/, or .gradle/ files. Never read, expose, or commit .env credentials, server player data, or publishing tokens.

Validation

• With JDK 25/JAVA_HOME configured, use ./gradlew spotlessCheck build for Java changes (.\gradlew.bat on Windows). For macOS/Linux bootstrapping, use ./tools/build-plugin.sh spotlessCheck. Run narrower relevant tasks when enough.
• ./gradlew spotlessApply applies Java style; review the resulting diff and avoid unrelated formatting churn.
• There are currently no Java test sources/dependencies; test is NO-SOURCE, and no integrationTest task exists. Never claim a build proves behavior or claim JUnit coverage. When tests are added, keep normal tests server-free; real Paper integration tests should be explicit/opt-in.
• Use human-tests.md for affected runtime scenarios and pre-release testing. Report checks actually run and any remaining unverified behavior. For docs-only work, check relative links and metadata instead of building.

Documentation and operational safety

• Keep README.md, Modrinth description, project-description.md, and project-description.json aligned with source. Validate the JSON as a slug-keyed object against projects.schema.json. Keep manual scenarios separate from automated coverage claims.
• When updating project-description.json, preserve the existing top-level project key, id, title, docId, and all image URLs (image.url and headerImage.url, when present). These are fixed in the consuming project; routine metadata updates must not reset them. Preserve a null or absent headerImage as well. Image paths such as /projects/score-keeper/logo.png are relative to the consuming project's root, not this repository: do not resolve them locally, rewrite them as repository URLs, or replace them with generated/remote image URLs. Change these protected fields only when the user explicitly requests it.
• New project plans belong in docs/; use checkboxes for actionable work only. Modernize.md supersedes the historical .cursor plan/rules. Planning/documentation tasks should not opportunistically implement the plan's code changes.
• Do not run server start/stop, deploy, restore, tagging, or publishing operations without explicit authorization. Bash start/stop currently match all local Java paper-*.jar processes; restore replaces archived top-level items. PowerShell start/stop can force termination. Prefer a clean console stop and inspect exact server paths/processes on isolated test machines.