Working with agents

<!-- rogen -->
## Rogen

This repo uses Rogen. Each `*.rogen.json` generates the Rojo project file beside it (`game.rogen.json` → `game.project.json`) from folder and file names, so a file's path on disk is not its path in the game, and adding, moving or deleting a file can leave the project file out of date.

After you add, move, rename or delete files, or edit a `*.rogen.json`, run `rogen check <paths>` from the repo root. Fix each line it prints, or tell the user why it stays. When it says to run `rogen write`, run it.

### Placing code

- Name new files like their neighbours: same folders, `@` suffixes and casing. Run `rogen where <path>` to see where a file lands and how to require it.
- A folder or `@` suffix named after a key in `routes` routes its contents: `Shop/Server/`, `Save@Server.luau`.
- The outermost route wins, so `Shared/Server/Save.luau` ships to clients. Keep server-only code under a server route.
- In roblox-ts, import by relative path.

### Changing the setup

- Edit the `*.rogen.json`, never the generated `*.project.json`.
- Put what names can't place, such as packages, in the `tree`; Rogen adds the routed files to it.
- Configs share nothing: apply a change to `routes`, `sourcePaths` or `tree` to every `*.rogen.json` it concerns.
- Read `rogen doc routing` before adding a route or a new naming pattern.

### Commands

- In roblox-ts, check `projects/common` through a place that uses it: `rogen check projects/game`.
- Run other commands in the folder of the `*.rogen.json`, or name it: `rogen write projects/game`.
- To sync to Studio, run `rogen serve --json` in the background and leave it running. `rogen help serve` explains its output.
- `rogen doc <topic>` covers `routing`, `config`, `layout` and `output`; `rogen help <command> --json` lists a command's flags and JSON output.
<!-- /rogen -->

// Agent Stop hook: report new Rogen diagnostics about changed files before the agent ends its turn.
// Pass "cursor" as the first argument for Cursor, which replies with followup_message.
import { spawnSync } from "node:child_process";
import fs from "node:fs";
import path from "node:path";

const git = (...args) => {
	const run = spawnSync("git", args, { encoding: "utf8" });
	return run.status === 0 ? run.stdout : "";
};

let payload = {};
try {
	payload = JSON.parse(fs.readFileSync(0, "utf8"));
} catch {}
const session = String(
	payload.session_id ??
		payload.sessionId ??
		payload.conversation_id ??
		"agent",
).replace(/[^\w.-]/g, "_");
try {
	process.chdir(process.env.CLAUDE_PROJECT_DIR || payload.cwd || ".");
} catch {
	process.exit(0);
}

const changed = [
	...git(
		"diff",
		"-z",
		"--name-only",
		"--relative",
		"--diff-filter=d",
		"HEAD",
	).split("\0"),
	...git("ls-files", "-z", "--others", "--exclude-standard").split("\0"),
].filter(Boolean);
if (!changed.length) process.exit(0);

const seenFile = path.resolve(
	git("rev-parse", "--git-dir").trim(),
	`rogen-hook-${session}`,
);
const seen = fs.existsSync(seenFile)
	? fs.readFileSync(seenFile, "utf8").split("\n")
	: [];

const windows = process.platform === "win32";
const names = windows ? ["rogen.cmd", "rogen.exe"] : ["rogen"];
const locate = (dirs) =>
	dirs
		.flatMap((dir) => names.map((name) => path.join(dir, name)))
		.find((file) => fs.existsSync(file));
const rogen = locate([
	path.resolve("node_modules/.bin"),
	path.join(git("rev-parse", "--show-toplevel").trim(), "node_modules/.bin"),
	...(process.env.PATH ?? "").split(path.delimiter).filter(Boolean),
]);
if (!rogen) {
	const NONE = "# found no rogen";
	if (!seen.includes(NONE)) {
		console.error(
			"Rogen's hook found no rogen; install it in the project or globally",
		);
		fs.appendFileSync(seenFile, `${NONE}\n`);
	}
	process.exit(0);
}

const run = (command, args) =>
	windows && command.endsWith(".cmd")
		? spawnSync([command, ...args].map((part) => `"${part}"`).join(" "), {
				encoding: "utf8",
				stdio: ["ignore", "pipe", "ignore"],
				shell: true,
			})
		: spawnSync(command, args, {
				encoding: "utf8",
				stdio: ["ignore", "pipe", "ignore"],
			});
const check = run(rogen, ["check", ...changed]);
const report = (check.stdout ?? "")
	.split(/\r?\n/)
	.filter((line) => line && !seen.includes(line));
if (!report.length) process.exit(0);

const message = `Rogen warns about files you changed. Fix each, or tell the user why it stays:\n${report.join("\n")}`;
fs.appendFileSync(seenFile, `${report.join("\n")}\n`);
console.log(
	JSON.stringify(
		process.argv[2] === "cursor"
			? { followup_message: message }
			: { decision: "block", reason: message },
	),
);

npx skills add LDGerrits/rogen