claudemon: Instructions file for Claude Code

AI Agent Guidelines

This document provides instructions for AI agents working on the claudemon codebase.

claudemon is a terminal Pokémon game driven by Claude Code activity: plain ESM Node, no build step, no runtime dependencies, rendered as ANSI lines into a terminal.

These rules are the house style. Where existing code contradicts them, the existing code is wrong and gets brought in line as it is touched — do NOT copy a violation because the file next to you has one, and do NOT cite existing code as precedent against a rule here.

Project shape

bin/claudemon        entry point, argument parsing, boot
src/                 the engine (battle, capture, exp, state, queue, sound, update)
src/ui/              rendering primitives (screen, ansi, sprite, grass, widgets)
src/ui/views/        one file per screen, each exporting draw() and onKey()
scripts/             Claude Code hook handlers and the status line
tools/               dev-time scripts (fetch data, fetch sprites, preview, capture, install)
test/                test suites
data/                generated dataset, checked in — never hand-edited

Everything is ESM, .mjs, Node >= 20.19. The runner is Vitest. Prettier owns formatting (no semicolons, single quotes, 80 columns) — write the code and run npm run format, never hand-align anything.

General Guidelines

General Rules

NO COMMENTS: NEVER add comments to the code. Code should be self-documenting and clear without them. If a block needs explaining, extract it into a named function instead. The only comments allowed anywhere are tooling directives (// prettier-ignore, // eslint-disable-next-line).

NAMING CONVENTIONS: Always use camelCase for naming variables, functions and files. Module-level constants use SCREAMING_SNAKE_CASE.

ARROW FUNCTIONS: Declare functions as arrows assigned to a const, and export the const. NEVER use function declarations.

// ✅ GOOD
export const partyIsWipedOut = (save) => {
  return save.party.length > 0 && save.party.every(isFainted)
}

// ❌ BAD
export function partyIsWipedOut(save) {
  return save.party.length > 0 && save.party.every(isFainted)
}