CRJM Math Games Development Guide

Guide for AI assistants working on the **Jogos Matemáticos CRJM** codebase - a training platform for the Regional Mathematics Games Championship in Madeira, Portugal.

What This Skill Does

This skill helps you work effectively on the CRJM platform, which provides 6 mathematical board games with AI opponents, a tournament system with double-elimination brackets, and high-performance Rust/WASM engines. It includes guidance on code structure, game implementation patterns, AI development, and tournament integration.

Tech Stack

| Layer | Technology |

|-------|------------|

| Runtime | Bun 1.x |

| Language | TypeScript (strict mode) |

| Frontend | React 19 + Tailwind CSS 4 |

| AI Engines | Rust → WebAssembly + TypeScript fallback |

| Build | Custom Bun build script (`build.ts`) |

| Testing | Bun test runner |

Project Structure

```

/

├── src/

│ ├── games/ # Game implementations

│ │ ├── gatos-caes/ # Cats & Dogs (1º Cycle)

│ │ ├── dominorio/ # Dominoes variant (1º, 2º)

│ │ ├── quelhas/ # Segments game - MISÈRE (1º-3º)

│ │ ├── produto/ # Product game (2º-Sec)

│ │ ├── atari-go/ # Capture Go (3º-Sec)

│ │ └── nex/ # Connection game (Sec)

│ ├── components/ # Shared React components

│ ├── server/ # Tournament server

│ └── tournament/ # Tournament client & protocol

├── wasm/ # Rust AI engines

├── docs/ # Detailed AI documentation

└── build.ts # Build system

```

Instructions

1. Understanding the Codebase

When first exploring the project:

2. Game Structure Pattern

Each game follows this structure:

```

src/games/{game}/

├── logic.ts # Pure game rules, state management

├── types.ts # TypeScript type definitions

├── logic.test.ts # Unit tests

├── {Game}Game.tsx # React UI component

└── ai/

├── ai-client.ts # AI interface + TS fallback engine

├── types.ts # AI-specific types

└── {game}.worker.ts # Web Worker entry point

```

3. Code Style Guidelines

**TypeScript:**

**Game Logic:**

**AI Implementation:**

**React Components:**

4. Adding a New Game

Follow these steps in order:

1. Create directory `src/games/{new-game}/`

2. Implement `logic.ts` with required functions:

- `createInitialState()`

- `applyMove(state, move)`

- `isValidMove(state, move)`

- `isGameOver(state)`

- `getWinner(state)`

- `getValidMoves(state)`

3. Add types in `types.ts`

4. Create React component `{NewGame}Game.tsx`

5. Add AI in `ai/` subdirectory

6. Create Web Worker in `ai/{new-game}.worker.ts`

7. (Optional) Create Rust engine in `wasm/{new_game}_ai/`

8. Add to `game-adapter.ts` for tournament support

9. Add route in main App

5. Working with AI Engines

**TypeScript Engine** (`src/games/{game}/ai/ai-client.ts`):

```typescript

export async function computeMove(

state: GameState,

difficulty: number,

signal?: AbortSignal

): Promise<Move> {

// Implementation

}

```

**Web Worker Communication:**

```typescript

// Request

{ type: 'compute_move', state, difficulty, requestId }

// Response

{ type: 'move_result', move, requestId, metrics? }

// Cancel

{ type: 'cancel' }

```

**Rust/WASM Engine** (`wasm/{game}_ai/src/lib.rs`):

```rust

#[wasm_bindgen]

pub fn compute_move(state_json: &str, difficulty: u8) -> String {

// Returns JSON-encoded move

}

```

6. Adding Tournament Support

1. Implement game adapter in `src/server/game-adapter.ts`:

```typescript

case 'new-game':

return {

createInitialState: () => createNewGameState(),

applyMove: (s, m) => applyNewGameMove(s, m),

isValidMove: (s, m) => isValidNewGameMove(s, m),

isGameOver: (s) => isNewGameOver(s),

getWinner: (s) => getNewGameWinner(s),

getCurrentPlayer: (s) => s.currentPlayer,

};

```

2. Add game board component to tournament UI

7. Testing

Run tests with:

```bash

bun test # All tests

bun test src/games/quelhas/logic.test.ts # Specific game

```

**Test Coverage Focus:**

8. Building the Project

```bash

bun run dev # Development server with hot reload

bun run build # Production build (includes WASM)

bun run build -- --skip-wasm # Build without WASM

bun run tournament # Start tournament server on :4000

```

**WASM Build Requirements:**

```bash

rustup target add wasm32-unknown-unknown

cargo install wasm-bindgen-cli

```

**Fallback Behavior:**

9. Common Debugging Tasks

**Improving AI Performance:**

1. Profile with browser DevTools

2. Optimize hot paths in Rust or TypeScript

3. Consider bitboard representations

4. Add transposition tables for repeated states

5. Tune time budgets per difficulty level

**Fixing Game Logic Bugs:**

1. Write failing test in `logic.test.ts`

2. Fix logic in `logic.ts`

3. Verify test passes

4. Check AI still produces valid moves

**Adding Difficulty Levels:**

1. Update difficulty handling in worker

2. Adjust time budget or search depth

3. Test across all difficulty levels

10. Capturing Screenshots

```bash

bun run screenshots # From live site (GitHub Pages)

bun run screenshots:local # From local dev server

```

Screenshots saved to `docs/screenshots/` include all game boards, homepage, and tournament interface.

Important Notes

Key Files Reference

| File | Purpose |

|------|---------|

| `src/games/{game}/logic.ts` | Game rules |

| `src/games/{game}/ai/ai-client.ts` | AI interface |

| `src/server/game-adapter.ts` | Tournament game integration |

| `src/server/tournament-engine.ts` | Bracket logic |

| `build.ts` | Build system |

| `wasm/{game}_ai/src/lib.rs` | Rust AI engine |

| `docs/` | Game-specific AI documentation |

Examples

**Example: Checking game implementation**

When asked to review a game, check that logic.ts:42 includes all required functions, types.ts defines clear interfaces, and logic.test.ts covers edge cases.

**Example: Adding AI difficulty**

Update the worker to adjust search depth based on difficulty parameter, then test that difficulty 1 plays quickly and difficulty 5 makes strong moves.

**Example: Tournament integration**

After adding game-adapter.ts:127 entry, verify server validates moves and handles disconnections properly.