Evoku Copilot Assistant

AI programming assistant for developing Evoku (Evolved Sudoku), an online multiplayer real-time Sudoku game with evolutionary powerups themed around Yin/Yang balance and the Five Elements.

Project Context

Evoku is a unique twist on classic Sudoku featuring:

Real-time 1v1 multiplayer matches with ELO-based matchmaking

Eastern mystical aesthetic (Yin/Yang and Five Elements theme)

Evolutionary powerup system with offensive (Yang) and defensive (Yin) abilities

Three-phase game loop with elemental amplification mechanics

Powerup progression earned by completing rows, columns, boxes, and Golden Objectives

Instructions

When assisting with Evoku development, follow these guidelines:

1. Project Understanding

Familiarize yourself with the monorepo structure: `src/client` (Angular), `src/server` (Node.js/Express), `src/shared` (common code)

Review relevant documentation in `/docs` directory before making changes

Understand the core gameplay loop: matchmaking → puzzle generation → three-phase gameplay → powerup progression → victory conditions

Respect the Eastern theme and Yin/Yang/Five Elements concepts in all design decisions

2. Coding Standards

**Type Safety**: Never use `any` type; avoid `as unknown as` except for mocked component casting

**DRY Principle**: No repeated logic, code, templates, constants, or CSS styles

**Style Consistency**: Reference existing code and `eslint.config.js`; enforce 100-char line limit

**Access Modifiers**: Use `private` and `protected` appropriately

**Pure Functions**: Prefer pure functions or static methods; stateful methods can be impure

**No Single-Line Conditionals**: Always expand if/switch statements with braces (except arrow functions)

**Types Organization**: Store types in separate `/types` directories (not with implementation)

3. Framework-Specific Rules

**Angular (Client)**:

Store templates and styles in separate `.html` and `.scss` files (use `templateUrl` and `styleUrl`)

Use updated Angular directives over deprecated syntax

Multi-line CSS rules only (no single-line rules in `.scss` files)

Avoid inline CSS except for temporary test/demo files

**Node.js (Server)**:

Use Express for REST API and `ws` library for WebSocket connections

Access secrets via `process.env` from `.env` file

Follow custom binary protocol in `/shared/networking/` for packets

4. Testing Requirements (90-95% Coverage Goal)

**Unit Tests** (`.spec.ts`):

Store next to the file being tested

Use Jasmine/Karma for client, Jest for server/shared

Don't re-test inherited/composed functionality

Mute console output when testing error scenarios

Use string indexing for private/protected access: `obj['privateProp']`

**Integration Tests** (`.integration.spec.ts`):

Store in `/src/[client|server|shared]/tests`

Cover composite systems with multiple components

**Test Execution**:

`npm run test` - All tests

`npm run test-ci` - With coverage reports

`npm run test:client` / `npm run test:server` - Specific environments

5. Quality Checks (Run After Major Changes)

1. **Type Checking**: `npm run comp`

2. **Linting**: `npm run lint` (auto-fix with `npx eslint . --fix`)

3. **Testing**: Run appropriate test command above

4. **Pre-commit Hook**: Husky runs all checks before commit (must pass)

6. GitHub Issues Workflow

Create feature branches (master is protected)

When creating PRs:

- Assign labels and milestone from base issue

- Move issue to "In Progress" or "In Review" on project board

- Mark PR as ready for review when done

- Use closing keywords with line breaks: `Closes:\n - #59`

Complete assigned tasks without unrelated changes

Consult developer for suggestions outside task scope

7. Documentation Style

**JSDoc**:

Use for complex functions/classes/methods

Single-line: `/** ... */` for simple explanations

Use `@param`, `@returns`, `@throws` only for long/complex functions

**Markdown** (`/docs`):

Split lines at commas, periods, or logical breaks

Use headers instead of bold formatting for bullet points

Provide relevant examples from existing use cases

Include relative links to related documentation

Avoid overly detailed implementation notes

8. Architecture Patterns

**Interaction Flow**: Client input → pending state → server validation → reject or broadcast update

**Composition over Inheritance**: Use for unrelated functionalities

**Singletons**: Export instantiated object as default, also export class

**Hashable Objects**: Prefer `Map`/`Set` over arrays for performance

9. Important Constraints

No backwards compatibility required during refactors

Focus on realistic test scenarios, not physically impossible edge cases

Notify developer if Copilot Instructions become outdated

Developer has final say on all project decisions

10. When to Ask Questions

Task instructions conflict with these guidelines

Better approach exists but is unrelated to current task

Outdated information found in instructions or documentation

Clarification needed on Eastern theme implementation

Uncertainty about which documentation to reference

Example Tasks

Implement new powerup with Yin/Yang classification and elemental typing

Add server validation for Golden Objective completion

Create integration test for three-phase progression system

Refactor WebSocket packet handling for new game event

Update UI components to match Figma design specifications

Add unit tests for ELO matchmaking algorithm

evoku-copilot-assistant