Development

A mainline turn is worth two seconds in this engine. Any duration taken from the main games — a status that lasts four turns, a residual that bites once a turn, a screen that holds for five — is written as turns(n) from src/battle/turn.ts rather than as a millisecond literal.

A component that calls `createResource` must not read it. The declaration lives in one component body and every read of the data signal lives in a child, wrapped in `Suspense`. A signal filled in by an effect that only loads something is a resource written out longhand. Applies whenever adding a resource to a component, writing a new component that reads one, or writing an effect that loads.

How to write the one-line `description` a registered item, ability or move carries. Applies whenever adding an entry to a data registry under src/data, or rewording an existing line. The line describes this engine's behaviour, not the mainline's, and is derived from the data wherever the data already knows the answer.

Prefer Set (and Map) lookups over Array + .some/.indexOf/.includes for membership checks. Applies whenever writing or reviewing code that tests "is X one of these values". O(1) hash lookup instead of O(n) scan, and intent reads clearer.

Write for-of loops rather than callback-taking Array methods (map, filter, forEach, reduce, some, every, find, flatMap and the like). Applies whenever writing or editing any code in src.

Any list that can grow without bound is paged, never drawn whole. Lists of rows page at LIST_PAGE (20) through createPager from src/components/styled/pager.tsx; grids of squares page at their grid size (BOX_SIZE for the pokemon box, GRID_SIZE for the item tray). Applies whenever rendering a collection whose length the player controls.

Keep comments light: short enough to read at a glance, and about the why rather than the what. Applies whenever writing or reviewing a comment or a doc block. Most blocks are one to four lines; history, anecdote and restatement of the code below are cut.

An effect wakes on its sources changing, not on its answer changing. A component whose effects do stateful work — loading a sheet, starting a playhead, opening a subscription — reads those props through memos, so a caller that rebuilds its list does not restart everything in it. Applies whenever writing or reviewing a component with a `createEffect` fed by props.

The `Transition` around a dialog decides when it is mounted and nothing else — the fade belongs to the `TransitionChild` overlay and panel inside it. Applies whenever adding or changing a transition in `src/components/styled`, or giving a dialog an animation of its own.

A prop whose markup is built outside a render — pushed onto a queue, held in a signal, sent from a promise — is typed `() => JSX.Element`, never `JSX.Element`. Applies whenever adding a prop or an API that stores markup and draws it later.

How a component is laid out on disk: when a single file becomes a folder, what the parts are called, and which way the imports run. Applies whenever adding to a component that is already long, or splitting one that has grown past reading in one sitting.

Where `batchedQuery` from src/utils/batched-query.ts belongs, which is the browser, and why the server reads many keys with one query instead. Applies whenever writing or reviewing a read that fetches one key at a time, or reaching for batchedQuery.

Use the local AI models LM Studio serves on the owner's desktop — rank GitHub issues by meaning before filing one (Tools/SemanticSearch), and ask Gemma 4 what changed between two screenshots or about a cropped detail (vision.ps1). Load before filing an issue or before comparing a batch of captures by eye, and only when LM Studio answers on localhost:1234.

Use to walk the user through a guided policy review of the project's crosslink configuration — tracking mode, security policies, language rules, hook implementations, and workflow conventions. Identifies drift from defaults via `crosslink workflow diff` and offers targeted fixes or a `crosslink init --force` reset. Trigger when the user says "review the crosslink config", "audit the workflow policies", "/workflow", or asks whether the hook/rules setup is right.

Use as a pre-commit quality gate — review the working diff for stub patterns (TODO/FIXME/`unimplemented!()`/`todo!()`), debug leftovers (`dbg!`, stray `console.log`/`println!`, commented-out code), then run the project's lint, format, and test suites and verify the active crosslink issue is documented. Prints a PASS/FAIL checklist and hands off to `commit`. Trigger when the user says "review my changes", "/review", "ready to commit?", or asks for a final pass before committing.

Use BEFORE implementing code in a crosslink-tracked project — loads `.crosslink/rules/global.md`, the language rules for detected manifests, the project rules, and the active `tracking-<mode>.md`. Replaces the heavy context that would otherwise be re-injected on every prompt. Trigger when the user says "preflight", "load the rules", "ground yourself", or before starting a fresh implementation session.

Use to run a periodic codebase-health pass — dependency audit, lint, test suite, dead code / TODO scan, doc freshness, crosslink issue hygiene, and build artifacts. Conservative by default (small fixes inline, larger work files a `maintenance`-labelled issue). Trigger when the user says "maintenance", "health check", "audit dependencies", "/maintain", or asks for a periodic project tidy-up.

Use to create a `feat/<slug>` branch from a human-readable description and register a matching crosslink issue (priority medium, label `feature`). Slugifies the description, validates preconditions (no uncommitted changes, branch doesn't already exist), and checks out the new branch. Trigger when the user says "new feature branch for X", "make a feature branch", or "/feature …".

Use to create a `feat/<slug>` bookmark AND spin up a new git worktree under `<repo-root>/.worktrees/<slug>`, then initialize crosslink hooks and an agent identity in the worktree so a child agent can work there. Trigger when the user says "make a worktree for <feature>", "/featree …", or asks to spin up an isolated workspace for a feature.

Use to create a jj commit AND auto-document the result on the active crosslink issue. Writes a conventional-style message with the issue ref, and adds a `--kind result` comment so the audit trail closes. Trigger whenever the user asks to "commit", "commit changes", "commit and push", or finishes a unit of work in a crosslink-tracked repo.

Use to check on background feature agents launched via /kickoff — running in tmux sessions or docker/podman containers. Reports each agent's state (Working / Idle / Waiting / Done / Error), captures recent output, and offers next-step commands. Trigger when the user says "check on the agent(s)", "how's the kickoff going", or names a `feat-*` / `crosslink-task-*` session.

Use when stuck, confused, or disoriented in a crosslink-tracked project — dumps the full context (session state, active issue, locks, blockers, hook config, git state, project rules) so you can re-orient and decide a next action. Trigger when the user says "I'm stuck", "audit", "what's going on", or asks for a context dump.

REQUIRED before declaring a task done when the diff touches user input, SQL, shell, auth, credentials, file paths, serialization, crypto, network endpoints, data deletion, or dependency surface. Judge by that surface, not the task label — research/experimental/local-only code with none of it can skip this. Walks OWASP/ASVS/MITRE questions the compiler and the test suite won't catch. Pair with `rafter run` on the same diff. When the diff has that surface, marking it complete without both has b...

REQUIRED before declaring a task done when the diff touches user input, SQL, shell, auth, credentials, file paths, serialization, crypto, network endpoints, data deletion, or dependency surface. Judge by that surface, not the task label — research/experimental/local-only code with none of it can skip this. Walks OWASP/ASVS/MITRE questions the compiler and the test suite won't catch. Pair with `rafter run` on the same diff. When the diff has that surface, marking it complete without both has b...