88 lines
3.3 KiB
Markdown
88 lines
3.3 KiB
Markdown
# 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:
|
|
|
|
```powershell
|
|
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.
|