AGENTS.md for Roblox

# AGENTS.md

Instructions for coding agents working in this Roblox repository. Cursor, Claude Code, Codex, Copilot, and other agents should follow this file before they guess.

## Stack

This repository is a Roblox experience in Luau. The server owns the truth. Clients request actions through remotes, and every remote validates its arguments.

## Layout

- Server scripts live under ServerScriptService or the Rojo path that maps there.
- Client scripts live under StarterPlayer or the mapped client folder.
- Shared modules that both sides can require live in ReplicatedStorage. Secrets do not.

## Commands

- Serve: `rojo serve`
- Analyze: `Run the project's Luau analyzer, such as selene, if one is configured`

Use the script the repo already defines when it differs from the command above.

## Conventions

- Use `--!strict` when the neighboring module is strict.
- The server decides currency, inventory, and combat results.
- Validate remote argument types and ranges before mutating state.
- Disconnect connections you create on instances that can be destroyed.
- Prefer the project's module style over a new framework.
- Name remotes for the action, not `RemoteEvent1`.

## Testing

Add or update tests when behavior changes.

Test pure module functions with the project's TestEZ or similar runner if it exists. Otherwise state the remote case you simulated.

## Style

- Optimize for the next reader over the shortest diff.
- Comment only when the why is non-obvious.
- Name things the way neighboring files already do.
- Do not reformat code you did not change.

## Errors

- Fail at the boundary. Do not swallow errors.
- Reject a bad remote with a warn that includes the player and the reason, then return. Do not kick for a single bad packet unless the project already does.

## Scope

- Do the requested task. Do not refactor unrelated code.
- Treat every instruction here as a constraint, not a suggestion.
- Ask one clarifying question only when the task cannot be finished without it. Otherwise state the assumption and continue.

## Avoid

- Do not trust the client to say what item it received.
- Do not require a server-only module from a client script.
- Do not `wait()` in a loop. Use events or task.delay.
- Do not store unbounded player data on the instance without cleaning it up.

## Done when

- The requested behavior works.
- The server script rejects a wrong-typed remote argument, and the client path you changed still fires.
- The diff stays inside the task.
- You list anything you could not run.