cloud-minestom: Instructions file for Claude Code

CLAUDE.md

Conventions for working in cloud-minestom. Read spec.md for the architecture and roadmap.md for what's next before making changes — this file is how to build it, those are what to build. CONTRIBUTING.md owns the commit/branch/PR/workflow rules; don't duplicate those here.

Architecture principles (non-negotiable)

These come straight out of spec.md's design decisions. Don't "improve" around them without updating the spec and writing an ADR — they're the reason this is a full implementation and not another greedy-string bridge.

• Cloud is the only parser, always (spec §5.4 / ADR-0001). A syntax executor never reads Minestom's own parsed argument values into the handler — it re-joins the raw input and re-dispatches through commandExecutor().executeCommand(...). Native Minestom Argument nodes exist purely for client-side shape (coloring, tab-complete structure), never as a second opinion on what a command means. If you're tempted to read a value straight off a Minestom Argument, stop — that's the bug class this rule exists to prevent.
• Native argument-tree mirroring is the default, not the exception. Every Cloud component gets a real Minestom node via ArgumentMapperRegistry (spec §5.2); the flattened greedy-string fallback is only for parsers with no sane native equivalent and for flag subtrees (spec §5.5). If you're adding a new parser type, add a mapper — don't let it silently fall back.
• ExecutionCoordinator.simpleCoordinator() is the default and stays the default (spec §4.1). It's a correctness requirement (handlers touch thread-confined Minestom game state), not a performance knob. Never change the default to an async coordinator to "speed things up" — that's a footgun for every consumer who doesn't read the fine print.
• No new module without a second real consumer on the other side of the split. cloud-annotations and cloud-minecraft-extras are already platform-agnostic upstream, which is why there's no cloud-minestom-annotations/cloud-minestom-extras (spec §3 / ADR-0003). Don't add a module because it "feels cleaner" — add it when something else besides cloud-minestom would actually depend on it.
• The library is generic over the sender type C via SenderMapper<CommandSender, C> (spec §4). Never hardcode a specific project's player/permission model into cloud-minestom itself — the identity case (C = CommandSender) is the only sender type the library may assume.
• The library never talks to an external system. No bundled permission backend, no bundled auth service, no network calls. Permission resolution, sender mapping and exception formatting are all pluggable through the builder (spec §6, §7) with a sane Minestom-native default; the plug points are the product, not a workaround.