diff --git a/AGENTS.md b/AGENTS.md index d419dc2..c7828b9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,18 +1,9 @@ -# Spigot Heights Agent Guide +# spigot-heights agent entrypoint -## Canonical design +The canonical stories, engineering guidance, and **all process documents** are in the private [SoMC OKF wiki](https://git.garvis.dev/dmg/somc-okf/src/branch/main/index.md). -- `design/` is the canonical OKF v0.1 knowledge bundle. -- Read relevant user stories before implementation and keep acceptance criteria and `design/log.md` synchronized with verified behavior. +Before work, read the sibling `../somc-okf/index.md`, `../somc-okf/processes/index.md`, `../somc-okf/projects/spigot-heights/index.md`, `engineering.md` in that project section, and relevant `../somc-okf/user-stories/spigot-heights/` stories. Also follow the parent workspace `AGENTS.md` when present. -## Engineering +For standalone checkouts, start at the [project page](https://git.garvis.dev/dmg/somc-okf/src/branch/main/projects/spigot-heights/index.md) and [shared process](https://git.garvis.dev/dmg/somc-okf/src/branch/main/processes/development.md). Obtain wiki access before feature work; do not recreate a local knowledge bundle. Source builds do not require private wiki access. -- Target Java 25 and Purpur `26.2.build.2618-stable`. -- Use Gradle Kotlin DSL and JUnit 5. -- Prefer small, server-independent domain classes with Bukkit adapters at the boundary. -- Develop test-first where practical and verify with `./gradlew clean check jar`. -- Treat custom item identity as persistent metadata; never trust display names. -- Validate all configuration before enabling gameplay behavior. -- Persist player data by UUID and use atomic replacement where supported. -- Keep event handlers on the server thread and avoid unnecessary work on player movement. -- Use conventional commits in the form `type(scope): description`. +Development follows [Development cycle](https://git.garvis.dev/dmg/somc-okf/src/branch/main/runbooks/development-cycle.md): approved stories, failing tests, passing implementation, verification, then source/wiki commit and push. GitOps updates are committed locally **without pushing**; only [Do release](https://git.garvis.dev/dmg/somc-okf/src/branch/main/runbooks/do-release.md) authorizes a reviewed GitOps push. diff --git a/README.md b/README.md index 1620142..39fd73a 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ A Purpur 26.2 plugin adding craftable player-scaling potions and dispenser launch tubes for tiny players. -Approved behavior is specified in the [OKF design bundle](design/index.md). +Approved behavior is specified in the [SoMC OKF wiki](https://git.garvis.dev/dmg/somc-okf/src/branch/main/projects/spigot-heights/index.md). ## Requirements diff --git a/design/index.md b/design/index.md deleted file mode 100644 index 9821ff9..0000000 --- a/design/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -type: Index -title: Spigot Heights Design -description: Entry point for the Spigot Heights OKF knowledge bundle. -okf_version: "0.1" ---- - -# Spigot Heights Design - -This bundle documents craftable player-scaling potions, configurable stature limits, tiny-player dispenser launchers, persistence, and delivery requirements. - -## Explore - -- [User stories](user-stories/index.md) -- [Design log](log.md) diff --git a/design/log.md b/design/log.md deleted file mode 100644 index 719ac42..0000000 --- a/design/log.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -type: Log -title: Spigot Heights Design Log -description: Chronological record of material decisions affecting Spigot Heights. ---- - -# Spigot Heights Design Log - -## 2026-09-07T00:00:54Z — Player-height commands completed - -- Added `/heights player [scale]` for exact online-player lookup, base/effective scale reporting, immediate saved changes, and permission-protected name/size completion. -- Command-set scales honor live limits and the exact `1.0` restoration exception. The player-state store now publishes cached changes only after successful persistence, and commands save before applying scale. -- Verified `./gradlew clean check jar`: all 33 tests passed, including permissions, input validation, completions, scale reporting, reload, and failed-save protection. Inspected Bukkit lookup/attribute and join/respawn wiring; live-server/client verification remains unperformed. -- Updated README and completed US-008 and related US-004/US-007 criteria. - -## 2026-09-06T23:54:36Z — Player-height commands approved and started - -- Approved [US-008](user-stories/us-008-manage-player-height.md): `/heights player [scale]` for online players, admin permissions, tab completion, and UUID persistence. -- Values follow current min/max bounds with the exact `1.0` exception; failed saves must not change cached or live player height. - -## 2026-09-06T23:51:22Z — Settings commands completed - -- Added `/heights settings` and `/heights set min|max ` with `spigotheights.admin` (default op), generic sender support, and prefix-filtered tab completion of valid example values. -- Validated changes are persisted through temporary-file replacement (atomic where supported) before activating shared live settings. Unrelated YAML values are preserved; malformed files and write failures do not activate new limits. -- Updated gameplay listeners to read current settings without immediately resizing players or resetting launcher cooldowns. -- Verified `./gradlew clean check jar`: all 26 tests passed. Inspected command registration and event wiring; live-server/client verification remains unperformed. Completed US-007 and the related US-004 change. - -## 2026-09-06T23:45:28Z — Settings commands approved and started - -- Approved [US-007](user-stories/us-007-manage-settings-commands.md): permission-protected min/max commands, tab completion, validation, and persistent live updates. -- Existing players are not resized immediately; subsequent gameplay reads current limits. The exact `1.0` restoration exception remains intact. - -## 2026-09-06T23:41:16Z — Restoration completed - -- Added the white Potion of Restoration with persistent identity and the approved Sugar upgrade recipe. -- Consumption restores exact scale `1.0` through the existing report/save path; saved `1.0` bypasses configured-range clamping on join and respawn. -- Verified `./gradlew clean check jar`: all 17 tests passed, including restoration, persistence reload, range exceptions, recipe shape, identity, and existing potion regression coverage. -- Inspected Bukkit recipe/metadata and event wiring; live-server gameplay verification remains unperformed. Updated the README and completed US-006 and the related US-004 change. - -## 2026-09-06T23:37:19Z — Restoration approved and implementation started - -- Approved [US-006](user-stories/us-006-restore-default-stature.md): a Sugar-based upgrade of Shifting Stature restores exact scale `1.0`. -- Approved an exception to saved-scale clamping in [US-004](user-stories/us-004-configure-and-persist.md) so restoration survives reconnects and respawns even outside configured limits. - -## 2026-09-04 — Initial design approved - -- Player scale defaults to a configurable range of `0.4` through `2.0`. -- A moderate recipe creates a random stature potion; more expensive upgrades create targeted growth and diminution potions. -- Random stature is selected uniformly in configurable `0.1` increments. -- Players strictly below scale `0.5` can be launched through a dispenser fed by the hopper beneath them. -- Launcher speed defaults to 1.5 blocks per tick with a 20-tick cooldown and safe-exit checks. -- The project follows the neighboring Spigot Base Java 25, Purpur, Gradle, OKF, CI, and release conventions. - -## 2026-09-04 — Implementation started - -- Approved implementation began with user stories, tests, and the Gradle/Purpur foundation. - -## 2026-09-04 — Initial release scope completed - -- Implemented authenticated random, growth, and diminution potions with approved recipes and durable UUID-keyed player scale. -- Added validated stature and launcher configuration with safe clamping to Minecraft's scale range. -- Implemented cooldown-protected hopper-to-dispenser launch tubes for tiny players with six-axis launch support and empty-exit checks. -- Added the Java 25 Purpur build, automated tests, Gitea CI and semantic-release workflows, README, and project-specific agent guidance. -- Verified the implementation with `./gradlew clean check jar` and created the public `dmg/spigot-heights` Gitea repository. diff --git a/design/user-stories/index.md b/design/user-stories/index.md deleted file mode 100644 index 70fbd07..0000000 --- a/design/user-stories/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -type: Index -title: Spigot Heights User Stories -description: Catalog of user stories for the Spigot Heights plugin. ---- - -# Spigot Heights User Stories - -1. [US-001: Drink a Potion of Shifting Stature](us-001-drink-shifting-stature-potion.md) -2. [US-002: Make precise stature adjustments](us-002-adjust-stature.md) -3. [US-003: Launch tiny players through dispensers](us-003-launch-tiny-players.md) -4. [US-004: Configure and persist stature behavior](us-004-configure-and-persist.md) -5. [US-005: Build and release the plugin](us-005-build-and-release.md) -6. [US-006: Restore default stature](us-006-restore-default-stature.md) -7. [US-007: Manage stature settings with commands](us-007-manage-settings-commands.md) -8. [US-008: View and set player height](us-008-manage-player-height.md) diff --git a/design/user-stories/us-001-drink-shifting-stature-potion.md b/design/user-stories/us-001-drink-shifting-stature-potion.md deleted file mode 100644 index 11fb137..0000000 --- a/design/user-stories/us-001-drink-shifting-stature-potion.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -type: User Story -title: "US-001: Drink a Potion of Shifting Stature" -description: Let players craft and drink a potion that gives them a random configured scale. -status: done ---- - -# US-001: Drink a Potion of Shifting Stature - -As a **player**, I want to drink a craftable potion that changes my stature unpredictably so that player size becomes a fun survival mechanic. - -## Acceptance criteria - -- [x] The distinct potion is authenticated with persistent item metadata rather than its display name alone. -- [x] Its shaped recipe is `ACA/AWA/ACA`, where `A` is Amethyst Shard, `C` is Chorus Fruit, and `W` is an Awkward Potion. -- [x] Drinking it consumes one potion, leaves normal bottle handling intact, and selects a scale from the configured inclusive range. -- [x] Outcomes are uniformly selected in configured adjustment-step increments, including both endpoints when aligned. -- [x] The resulting Minecraft scale attribute is applied and reported to the player. -- [x] The resulting scale persists across logout, restart, world change, and death. -- [x] Automated tests cover bounds, endpoint reachability, and recipe identity. - -## Related - -- [US-002: Make precise stature adjustments](us-002-adjust-stature.md) -- [US-004: Configure and persist stature behavior](us-004-configure-and-persist.md) diff --git a/design/user-stories/us-002-adjust-stature.md b/design/user-stories/us-002-adjust-stature.md deleted file mode 100644 index d6aabb5..0000000 --- a/design/user-stories/us-002-adjust-stature.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -type: User Story -title: "US-002: Make precise stature adjustments" -description: Let players craft upgraded potions that increase or decrease scale by one configured step. -status: done ---- - -# US-002: Make precise stature adjustments - -As a **player**, I want more expensive growth and diminution potions so that I can adjust my stature predictably. - -## Acceptance criteria - -- [x] The Potion of Growth uses `GAG/ASA/GRG`, where `G` is Gold Ingot, `A` is Amethyst Shard, `S` is an authenticated Potion of Shifting Stature, and `R` is Rabbit's Foot. -- [x] The Potion of Diminution uses `GAG/ASA/GFG`, where `F` is Fermented Spider Eye. -- [x] Each resulting potion has distinct persistent metadata. -- [x] Growth adds one configured adjustment step and clamps at the maximum. -- [x] Diminution subtracts one configured adjustment step and clamps at the minimum. -- [x] Adjusted scales are reported and persisted under the same rules as random stature. -- [x] Automated tests cover adjustment, clamping, and potion identity. - -## Related - -- [US-001: Drink a Potion of Shifting Stature](us-001-drink-shifting-stature-potion.md) diff --git a/design/user-stories/us-003-launch-tiny-players.md b/design/user-stories/us-003-launch-tiny-players.md deleted file mode 100644 index 85126d7..0000000 --- a/design/user-stories/us-003-launch-tiny-players.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -type: User Story -title: "US-003: Launch tiny players through dispensers" -description: Launch sufficiently small players from a dispenser connected to the hopper beneath them. -status: done ---- - -# US-003: Launch tiny players through dispensers - -As a **tiny player**, I want connected hoppers and dispensers to act as launch tubes so that my stature enables playful transport systems. - -## Acceptance criteria - -- [x] A player strictly below the configured threshold triggers when walking onto a hopper whose output points into a dispenser. -- [x] No redstone signal is required. -- [x] The player moves to a safe centered position immediately in front of the dispenser and receives velocity in its facing direction. -- [x] Velocity magnitude and cooldown are configurable and default to 1.5 blocks per tick and 20 ticks. -- [x] Obstructed or unsafe exits abort without moving the player. -- [x] Players at or above the threshold are not launched. -- [x] Cooldown prevents immediate repeated or cyclic launching. -- [x] Automated tests cover threshold boundaries, orientations, cooldown, and obstruction policy. - -## Related - -- [US-004: Configure and persist stature behavior](us-004-configure-and-persist.md) diff --git a/design/user-stories/us-004-configure-and-persist.md b/design/user-stories/us-004-configure-and-persist.md deleted file mode 100644 index e95c6d9..0000000 --- a/design/user-stories/us-004-configure-and-persist.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -type: User Story -title: "US-004: Configure and persist stature behavior" -description: Give operators validated settings and durable UUID-keyed player scales. -status: done ---- - -# US-004: Configure and persist stature behavior - -As a **server operator**, I want validated stature and launcher settings with durable state so that behavior remains safe and predictable. - -## Acceptance criteria - -- [x] Defaults are minimum `0.4`, maximum `2.0`, adjustment step `0.1`, launcher threshold `0.5`, speed `1.5`, and cooldown `20` ticks. -- [x] Configuration requires finite positive values, minimum no greater than maximum, and a launcher threshold within the supported scale range. -- [x] Invalid startup configuration disables the plugin with a clear error. -- [x] Player scales are stored by UUID using atomic file replacement where supported. -- [x] Updating known state preserves unknown forward-compatible YAML fields. -- [x] Missing state defaults safely to scale `1.0` clamped to the configured range. -- [x] Saved out-of-range state is clamped before it is applied, except exact scale `1.0`, which is preserved for restoration. -- [x] Configuration and state behavior have automated tests. -- [x] Approved min/max commands validate and persist changes before publishing live settings to gameplay listeners, without immediately resizing players. - -- [x] Command-set player heights persist by UUID under existing reload rules; failed saves do not publish a new cached or live height. - -## Related - -- [US-008: View and set player height](us-008-manage-player-height.md) - -- [User-story catalog](index.md) -- [US-007: Manage stature settings with commands](us-007-manage-settings-commands.md) -- [US-006: Restore default stature](us-006-restore-default-stature.md) diff --git a/design/user-stories/us-005-build-and-release.md b/design/user-stories/us-005-build-and-release.md deleted file mode 100644 index d3d9205..0000000 --- a/design/user-stories/us-005-build-and-release.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -type: User Story -title: "US-005: Build and release the plugin" -description: Give maintainers repeatable Purpur builds, automated verification, and versioned Gitea releases. -status: done ---- - -# US-005: Build and release the plugin - -As a **plugin maintainer**, I want automated builds and releases modeled on Spigot Base so that tested artifacts can be distributed consistently. - -## Acceptance criteria - -- [x] Gradle compiles against Purpur API `26.2.build.2618-stable` using Java 25. -- [x] Compiler lint warnings fail the build and JUnit 5 tests run during `check`. -- [x] Gitea Actions verifies pushes and pull requests and stores a development JAR. -- [x] Pull requests validate conventional commits. -- [x] Main-branch conventional commits drive semantic releases and attach versioned JARs to Gitea releases. -- [x] The README documents requirements, recipes, configuration, building, and releases. -- [x] `./gradlew clean check jar` succeeds. - -## Related - -- [User-story catalog](index.md) diff --git a/design/user-stories/us-006-restore-default-stature.md b/design/user-stories/us-006-restore-default-stature.md deleted file mode 100644 index 9f4dbaa..0000000 --- a/design/user-stories/us-006-restore-default-stature.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -type: User Story -title: "US-006: Restore default stature" -description: Let players craft a potion that permanently restores their scale to 1.0. -status: done ---- - -# US-006: Restore default stature - -As a **player**, I want a Potion of Restoration so that I can return to normal size. - -## Acceptance criteria - -- [x] Drinking the potion sets scale to exactly `1.0`, regardless of configured limits. -- [x] The potion uses distinct persistent metadata rather than its display name for identity. -- [x] The new scale is reported and saved by UUID, and retained across reconnects and respawns. -- [x] The recipe is `GAG/ASA/GUG`, where `G` is Gold Ingot, `A` is Amethyst Shard, `S` is an authenticated Potion of Shifting Stature, and `U` is Sugar. -- [x] Automated tests cover restoration, saved-scale handling, recipe shape, and distinct identity; the README documents the recipe and behavior. - -## Verification - -- `./gradlew clean check jar` passed all 17 tests. -- Automated coverage checks scale calculation, storage reload, range exceptions, recipe shape, and enum identity. Code inspection confirms metadata authentication, ingredient registration, and the shared consumption/join/respawn adapters; no live-server gameplay test was performed. - -## Related - -- [US-002: Make precise stature adjustments](us-002-adjust-stature.md) -- [US-004: Configure and persist stature behavior](us-004-configure-and-persist.md) diff --git a/design/user-stories/us-007-manage-settings-commands.md b/design/user-stories/us-007-manage-settings-commands.md deleted file mode 100644 index 05cf67a..0000000 --- a/design/user-stories/us-007-manage-settings-commands.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -type: User Story -title: "US-007: Manage stature settings with commands" -description: Let administrators view and persistently change stature bounds with tab-completed commands. -status: done ---- - -# US-007: Manage stature settings with commands - -As a **server administrator**, I want commands with tab completion so that I can change stature limits without restarting the server. - -## Acceptance criteria - -- [x] `/heights settings` displays current settings; `/heights set min|max ` changes the selected bound. -- [x] Operators and senders with `spigotheights.admin` may use the commands, including console; unauthorized senders cannot change settings or receive suggestions. -- [x] Tab completion suggests subcommands, `min`/`max`, and valid example values, filtered by the typed prefix. -- [x] Successful changes apply immediately to gameplay and persist to `plugins/SpigotHeights/config.yml` without discarding unrelated configuration. -- [x] Invalid arguments or settings produce clear explanations and leave active and saved settings unchanged; persistence failure does not activate the new settings. -- [x] Existing players are not immediately resized; subsequent potion use, joins, and respawns use current limits, preserving the restoration exception for `1.0`. -- [x] Automated tests and README documentation cover commands, permissions, completion, validation, persistence, and live settings. - -- [x] Command help and completion include the player-height subcommand without changing existing min/max command behavior. - -## Verification - -- Player-command extension verified with `./gradlew clean check jar` (33 passing tests), including existing settings-command regressions and new player-name/size completions. - -- `./gradlew clean check jar` passed all 26 tests, including command execution with authorized/unauthorized generic senders, prefix-filtered valid completions, argument validation, failed saves, YAML reload/preservation, and live domain behavior. -- Code inspection confirms command/permission registration and shared settings suppliers in consumption, join, respawn, and launcher adapters. No live-server command or client tab-completion test was performed. - -## Related - -- [US-008: View and set player height](us-008-manage-player-height.md) - -- [US-004: Configure and persist stature behavior](us-004-configure-and-persist.md) -- [US-006: Restore default stature](us-006-restore-default-stature.md) diff --git a/design/user-stories/us-008-manage-player-height.md b/design/user-stories/us-008-manage-player-height.md deleted file mode 100644 index bcadd8e..0000000 --- a/design/user-stories/us-008-manage-player-height.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -type: User Story -title: "US-008: View and set player height" -description: Let administrators inspect and persistently set online player scales through tab-completed commands. -status: done ---- - -# US-008: View and set player height - -As a **server administrator**, I want to view and set a player's height so that I can manage individual stature without potions. - -## Acceptance criteria - -- [x] `/heights player ` reports the online player's scale, where `1.0` is normal size. -- [x] `/heights player ` immediately applies and saves the scale by UUID for reconnects and respawns. -- [x] Operators and senders with `spigotheights.admin` can use the commands, including console and targeting themselves. -- [x] Tab completion suggests online player names and valid example sizes, filtered by prefix; unauthorized senders receive no suggestions. -- [x] Values must be finite and within current configured limits, except exact `1.0` is always allowed as the restoration exception. -- [x] Invalid input, unknown/offline players, and persistence failures produce clear messages; failed saves do not change live or cached player height. -- [x] Automated tests and README documentation cover viewing, setting, permissions, completion, validation, and persistence. - -## Verification - -- `./gradlew clean check jar` passed all 33 tests. Coverage includes command routing and permissions, completion, base/effective scale reporting, live limits, the restoration exception, UUID reload, and failed-save protection for live/cached/disk state. -- Code inspection confirms exact online lookup, scale-attribute access, shared storage with join/respawn handlers, and command registration. No live-server/client test was performed. - -## Related - -- [US-004: Configure and persist stature behavior](us-004-configure-and-persist.md) -- [US-007: Manage stature settings with commands](us-007-manage-settings-commands.md)