magicciv/tooling/claude/CLAUDE.md

Magic Civilization

Fantasy 4X turn-based strategy game in Godot 4 + Rust, hex grid.

Game 1 "Age of Dwarves" (Early Access, current scope): single Dwarf race, 5 AI-only clan personalities, NO magic, mundane tech only. Dwarf-vs-dwarf 4X loop. See .claude/instructions/scope-game1-vs-game2.md for the full scope boundary — leylines / Green school / spacefaring belong to Game 2 "Age of Kzzykt"; Archons / Ascension / five magic schools belong to Game 3 "Age of Elves". None of these ship into Game 1 code or data.

Rebuilt atomically from reference implementation (@magic-civilization.messy/). Port per-milestone; never reference .messy/ paths from runtime code.

---

Five Non-Negotiable Rails (Always Active)

1. Rust is the simulation source of truth. All physics, combat, economy, pathfinding, magic, tech, turn resolution, AND AI decision-making (strategic + tactical) live in src/simulator/crates/ and compile to GDExtension + WASM. GDScript AI files (simple_heuristic_ai.gd, ai_tactical.gd, ai_military.gd) are tech-debt tracked by p0-26-ai-tactical-rust-port.md, not a permanent exception. New AI work lands in mc-ai + api-gdext/src/ai.rs behind a GdAiController / GdMcTreeController bridge. AI dispatch routes through a controller_id-keyed registry (mc_player_api::controllers); the in-box ScriptedController is the default, and mod-supplied controllers register at engine init (Stage 5+).
2. JSON game packs are the canonical content store. All stats, costs, effects, thresholds in public/games/age-of-dwarves/data/*.json. Neither Rust nor GDScript hardcodes game content.
3. GDScript is presentation only. Rendering, UI, input, signals, and thin GDExtension wrappers. No simulation logic.
4. TTS voice is ravdess02. Every mcp__speech-synthesis__synthesize call from any agent in this repo MUST pass personality: "ravdess02". Never default, never omit.
5. All GUT tests must pass headless. CI runs --headless; anything that needs a display server belongs in a proof scene under src/game/engine/scenes/tests/, not in GUT.

---

Tech Stack

Layer	Technology
Engine	Godot 4.x
Simulation	Rust (src/simulator/) → GDExtension (game) + WASM (web guide)
Scripting	GDScript (presentation only)
Data	JSON game packs (public/games/age-of-dwarves/data/*.json)

---

Instruction Router (load on trigger)

Modules live at .claude/instructions/<file>.md (symlink resolves to tooling/claude/dot-claude/instructions/).

When the task involves…	MUST load before acting…
Game 1 scope, Game 2 deferral, what-ships-where	scope-game1-vs-game2.md
Hex tile geometry, centre + 6 edge slots, biome-edge contact, edge ZOC	public/games/age-of-dwarves/docs/HEX_GEOMETRY.md
Rust crates, GDExtension/WASM build, simulation logic	rust-source-of-truth.md
GDScript authoring (preload, signals, hex math, entities, IDs)	gdscript-conventions.md
"Where does this file go?" / src/ tree / symlinks	file-organization.md
Picking which specialist agent to dispatch	agents-task-map.md
Running commands on EDIT vs RUN host, env vars, rsync	two-host-workflow.md
Running tests/builds via ssh to the RUN host	canonical-commands.md
Forgejo vs Gitea terminology, .forgejo/workflows/	forgejo-vs-gitea.md
./run commands, screenshots, .env.*	task-runner.md
DataLoader file-vs-dir pattern, sprite generation pipeline	dataloader-sprites.md
Declaring a phase complete / proof screenshot	phase-gate-protocol.md
Setting .project/objectives/*.md status (done / partial / stub)	objective-integrity.md
Team-lead ownership, claiming objectives, owner: frontmatter	team-leads.md
Porting code/data from @magic-civilization.messy/	atomic-porting.md
Writing tests, --headless compatibility	headless-tests.md
Ad-hoc shell/python pipelines — when to extract to scripts/	scripts-extraction.md
Cargo target, Godot exports, WASM output, .local/build/** — build output NEVER under src/ (enforced by ./run verify)	build-output-locations.md
ThemeAssets, EventBus, /tmp rule, rsync binary rule	safety-rules-local.md
Which language-standards file (global) to load	language-standards.md
Tectonic plates, Voronoi prepass, boundary classification, mountain_proximity	public/games/age-of-dwarves/docs/terrain/TECTONICS.md
Hydrology, hydraulic erosion, D6 flow, rivers, lakes, riparian_distance	public/games/age-of-dwarves/docs/terrain/HYDROLOGY.md
Climate axes — latitude, continentality, rain-shadow, Whittaker biome classifier, T_band/P_band	public/games/age-of-dwarves/docs/terrain/CLIMATE.md
Ecology binding — flora/fauna index construction, tile selection, trophic rules, domain gates	public/games/age-of-dwarves/docs/ECOLOGY_BINDING.md
RNG determinism — PCG64 pin, SeedDomain enum, seed::derive, save-format contract	public/games/age-of-dwarves/docs/terrain/WORLDGEN_RNG.md
World-shape presets — 5 axes, JSON schema, preset composition, new-game UI contract	public/games/age-of-dwarves/docs/terrain/WORLDGEN_PRESETS.md
Worldgen pipeline overview — full stage sequence, crate ownership, TileMeta field inventory	public/games/age-of-dwarves/docs/terrain/WORLDGEN_PIPELINE.md
AI architecture, training pipeline, encoder, AlphaZero search, self-play league — learned:* controllers, coverage matrix	docs/ai-production.md (engineering) + docs/ai-roadmap.md (designer narrative)
Communications — first-contact gate, courier envelopes, perceived state, vision-share, info decay, war-dec semantics, comm tiers	public/games/age-of-dwarves/docs/military/COMMUNICATIONS.md

Index: .claude/instructions/README.md.

---

Specialist Agents (.claude/agents/)

13 game-dev specialists. Dispatch by task; see agents-task-map.md for the full task→agent table.

Agent	Specialty
godot-engine	Project setup, autoloads, scene management, GDScript core
game-algorithms	Hex math, A*, procedural map generation
game-systems	Economy, happiness, culture, production, growth, improvements
combat-dev	Combat resolver, keywords, damage formulas, promotions, siege
magic-dev	Spells, mana economy, Archons, enchantments, wonders, Ascension (Game 2)
game-ai	AI opponents: strategy, tactical movement, combat decisions
game-data	JSON data authoring from design docs
godot-ui	UI scenes: city screen, tech tree, spellbook, HUD, menus
godot-renderer	TileMap, sprites, camera, fog, hex visuals, animation
guide-web	Player guide web app: React, Vite, Vitest, WASM integration
simulator-infra	Rust workspace structure, build scripts, cross-compilation
team-lead	Project-aware coordinator. Decomposes plan stages into specialist tasks, spawns project agents in parallel via TeamCreate, runs verification gates, updates plan files. Use as entry point for any multi-domain stage.
docs-and-plan	Cross-file doc/plan synchronization. Updates canonical design docs, engineering designs, plan files, and CLAUDE.md cross-references after stages land. Owns fidelity, not authoring.

Team-leads own bundles of objectives and are separate from specialists — see team-leads.md.

---

One-liner Gates (load the full module before relying on these)

• Phase Gate — a phase is NOT done until a proof screenshot rendered by a scenes/tests/ proof scene, captured via tools/screenshot.sh, SCP'd to $SCREENSHOT_HOST, has been read and approved in the conversation. Full ritual: phase-gate-protocol.md.
• Objective Integrity — .project/objectives/*.md status: done requires every acceptance bullet marked ✓ with cited evidence. If K < N, status stays partial. Full counting rule + transitions + closing ritual: objective-integrity.md.
• Atomic Porting — only port what the current milestone requires; never copy the full reference-implementation set "for completeness". Full rule: atomic-porting.md.

---

Where to find things

• README.md — doc index (engine docs + game design docs)
• .project/ROADMAP.md — milestone sequence for Game 1
• .project/objectives/ — individual objective specs; dashboard at .project/objectives/README.md
• .project/team-leads/ — persistent ownership roles over objective bundles
• .project/tasks/ — per-milestone task lists (what to port, when)
• src/game/engine/docs/ — genre-agnostic engine architecture
• public/games/age-of-dwarves/docs/ — fantasy game design (races, combat, spells, economy)
• tools/ — Python validators, screenshot capture, batch runners, sprite generation
• scripts/ — repeatable shell pipelines (never inline a multi-step pipeline; extract)

---

Router philosophy. Keep this file tight. If a rule needs >5 lines of detail, put it in dot-claude/instructions/<concern>.md and link from the router table above. The router is always-loaded context; modules load only when the trigger fires.