magicciv/tooling/claude/dot-claude/instructions/README.md

Project Instruction Files

Purpose: Modular, on-demand instruction files for Magic Civilization. The project router at tooling/claude/CLAUDE.md (reachable at repo root via CLAUDE.md symlink) dispatches to these by trigger.

Token efficiency: The router stays under ~2k tokens always-loaded; each module below loads only when its trigger fires. This reclaimed ~8k tokens of context per session vs the previous monolithic CLAUDE.md.

---

Directory layout

tooling/claude/
├── CLAUDE.md                              # Lightweight router (always loaded)
└── dot-claude/                            # ← symlinked from repo root as .claude
    ├── agents/                            # 11 specialist game-dev agents
    ├── hooks/                             # Write/Edit hooks (enforce-structure, etc.)
    ├── plans/                             # per-session plan files
    ├── projects/                          # Claude Code memory state
    ├── settings.json                      # harness settings (hooks config)
    ├── settings.local.json                # local-only permissions
    └── instructions/                      # ← you are here
        ├── README.md                      # this file
        ├── scope-game1-vs-game2.md
        ├── rust-source-of-truth.md
        ├── gdscript-conventions.md
        ├── file-organization.md
        ├── agents-task-map.md
        ├── two-host-workflow.md
        ├── canonical-commands.md
        ├── forgejo-vs-gitea.md
        ├── task-runner.md
        ├── dataloader-sprites.md
        ├── phase-gate-protocol.md
        ├── objective-integrity.md
        ├── team-leads.md
        ├── atomic-porting.md
        ├── headless-tests.md
        ├── scripts-extraction.md
        ├── build-output-locations.md
        ├── safety-rules-local.md
        └── language-standards.md

---

Modules (load on trigger)

File	Trigger	Approx tokens
scope-game1-vs-game2.md	Deciding whether a feature ships in Game 1 or defers to Game 2	~450
rust-source-of-truth.md	Rust crate work, GDExtension/WASM builds, simulation logic placement	~750
gdscript-conventions.md	Any .gd authoring — preload, signals, hex math, entities, IDs	~550
file-organization.md	Creating files, "where does this go?", src/ tree audit	~900
agents-task-map.md	Choosing which specialist to dispatch	~450
two-host-workflow.md	EDIT vs RUN host, env vars, rsync safety	~750
canonical-commands.md	Running tests, builds, sims via ssh to RUN host	~300
forgejo-vs-gitea.md	CI workflows, runner setup, forge terminology	~300
task-runner.md	./run commands, screenshots, .env.*	~300
dataloader-sprites.md	JSON data layout, sprite generation pipeline	~300
phase-gate-protocol.md	Declaring a phase/feature complete	~200
objective-integrity.md	Editing .project/objectives/*.md status frontmatter	~800
team-leads.md	Claiming objectives, team-lead files, owner: field	~900
atomic-porting.md	Porting code/data from @magic-civilization.messy/	~200
headless-tests.md	Writing GUT tests / --headless compatibility	~400
scripts-extraction.md	Inline pipelines → scripts/ rule	~300
build-output-locations.md	.local/build/** topology, artifact paths (ENFORCED by ./run verify step 16)	~450
safety-rules-local.md	ThemeAssets, EventBus, rsync binaries, /tmp avoidance	~500
language-standards.md	Which ~/.claude/instructions/<lang>-code-standards.md to load	~150

Total on-trigger corpus: ~9,700 tokens. None of it loads unless the trigger fires.

---

Pattern reference

This structure mirrors @lilith/lilith-platform.live/tooling/claude/ (same repo author). Router + modular instructions is the preferred layout across the workspace. Global equivalents live at ~/.claude/CLAUDE.md + ~/.claude/instructions/ for project-agnostic rules.

When to add a new module

• A new concern reaches >50 lines in CLAUDE.md — extract it into instructions/<concern>.md and add a row to the router table.
• A concern only fires for specific task types — never bloat the router with content that's only relevant to 1-in-20 tasks.

When to delete a module

• The system it described no longer exists in the repo (e.g. a retired subsystem).
• It was superseded by a more specific module — and no router table row still points to it.