Idlegame Agent Guide

Idlegame is a proprietary idle/incremental text-fantasy RPG inspired by Your Chronicle. It is a responsive web + PWA project with a pure TypeScript game engine and a React/Zustand view layer.

User And Context

Address the user as ginnoir or senpai. Never call him Matt.
The Obsidian vault is the cross-project source of truth for design, story, decisions, and session memory.
Vault MCP path: claude/Context.md first, then Idlegame/_Claude.md.
Local vault path for tools without MCP: C:\Users\MattC\Documents\Obsidian Vault\.
Credentials used by AI tools live in the vault at claude/Credentials.md. Never hardcode tokens or secrets in this repo.
Repo docs are code-truth: setup, architecture, ADRs, and plans. Vault notes hold design intent and durable operational context.

Commands

Install: pnpm install
Dev server: pnpm dev
Typecheck: pnpm typecheck
Lint/format check: pnpm lint
Format: pnpm format
Unit tests: pnpm test
Coverage: pnpm test:coverage
Production build: pnpm build

The required pre-PR verification chain is:

pnpm typecheck
pnpm lint
pnpm test:coverage
pnpm build

Architecture Rules

src/engine/ is pure TypeScript. It must not import React, Zustand, browser APIs, storage APIs, or wall-clock scheduling.
src/content/ contains data-driven resource/action/story definitions and Zod validation.
src/state/ bridges engine snapshots into Zustand and owns environment coupling such as requestAnimationFrame, IndexedDB, localStorage fallback, and lifecycle hooks.
src/ui/ is the React shell. It renders store snapshots and calls runtime commands; gameplay rules stay out of components.
Saves are versioned and validated at the boundary. Invalid or tampered saves must fail explicitly.
Numbers remain human-readable; use the src/engine/num.ts boundary before introducing any Decimal-style library.

Engineering Norms

TypeScript strict, immutable-by-default, explicit errors at boundaries.
Keep functions small and modules focused. Prefer many small files over large catch-all modules.
Tests are required for new engine behavior. Maintain at least 80% coverage on src/engine/.
Use permissive dependencies only. No GPL dependencies; this game is proprietary and may be sold.
Commit messages use Conventional Commits, with no AI attribution.

Tool Routing

Claude Code: architecture, engine-system design, story/design writing, review, vault stewardship, homelab/infra work.
Codex: scoped implementation tickets, debugging, coverage work, mechanical refactors.
Antigravity: UI implementation, responsive polish, browser/playtest verification, visual checks.
Cursor: small ginnoir-driven edits and exploratory pair-programming.

Use one tool per issue or branch at a time. After M0, all code changes should land through a PR unless ginnoir explicitly says otherwise.

Workflow

Default Git host: private Gitea at gitea.ginnoir.com/ginnoir/idlegame.
Trunk is main; feature work happens on branches with PRs.
Gitea Issues are implementation work items. Plane epics are roadmap grouping.
Internal playtest URL: idlegame.ginnoir.com via Caddy internal_only.

When a session produces durable knowledge, write it back to Idlegame/_Claude.md or a topic note in the vault before ending.

3.3 KiB Raw Blame History