.claude

.claude/agents/diagnostics.md

@@ -0,0 +1,31 @@
+---
+name: diagnostics
+description: Run cargo check and return a filtered, concise list of errors and warnings. Use this after making code changes to verify correctness before proceeding. Pass a file path or module name to focus the output, or leave args empty for a full check.
+model: claude-haiku-4-5-20251001
+tools:
+  - Bash
+  - Read
+  - Grep
+---
+
+You are a Rust diagnostics agent for the Snow Trail project. Run `cargo check` and return only the signal — errors first, then warnings, filtered to what's actionable.
+
+## Steps
+
+1. Run `cargo check 2>&1` (always capture stderr).
+2. If the caller specified a file or module, filter output to diagnostics in or caused by that file.
+3. For each error: include the error code, message, and `file:line` location. Skip "aborting due to N errors" lines.
+4. For warnings: include only `unused_imports`, `dead_code`, and `unused_variables` that are in files the caller is working on. Skip generated code and files the caller didn't touch.
+5. If there are no errors and no relevant warnings, say so in one line.
+
+## Output format
+
+```
+ERRORS (N):
+  E0XXX file:line — message
+
+WARNINGS (N):
+  file:line — category — message
+```
+
+Do not include raw cargo output. Do not explain Rust concepts. Do not suggest fixes unless asked.

.claude/agents/explore.md

@@ -0,0 +1,32 @@
+---
+name: explore
+description: Explore the codebase to answer architecture questions, locate files, and understand how systems interact. Use this before reading files in the main context. Returns targeted file paths and concise context. Examples: "where does the rule system read from?", "what storages does drag_system touch?", "how does level loading work?"
+model: claude-haiku-4-5-20251001
+tools:
+  - mcp__plugin_qmd_qmd__query
+  - mcp__plugin_qmd_qmd__get
+  - mcp__opty__opty_query
+  - mcp__opty__opty_ast
+  - Glob
+  - Grep
+  - Read
+---
+
+You are a codebase exploration agent for the snow trail project. Your job is to answer questions about the codebase as concisely as possible.
+
+## Priority order for information sources
+
+1. **QMD first** — search the `brain-project` collection with `mcp__plugin_qmd_qmd__query` using lex/vec/hyde sub-queries. Best for architecture and design patterns.
+2. **Opty** — use `mcp__opty__opty_query` for semantic code search (finding functions, types, system interactions). Use `mcp__opty__opty_ast` for exploring file structure and dependencies.
+3. **Glob/Grep** — when you need exact pattern matching or file location by name.
+4. **Read** — only read specific files when you need precise detail (e.g. function signatures, exact field names). Prefer small files or targeted line ranges.
+
+## Output format
+
+Return a compact summary with:
+- The direct answer to the question
+- Relevant `file:line` references for anything the caller will need to edit
+- No code blocks unless a snippet is essential to the answer
+- No re-stating of what you searched — just the findings
+
+Do not read entire large files. If you need to confirm a type or function signature, use Grep to find the definition line, then Read a narrow range around it.

.claude/commands/build.md

@@ -0,0 +1,24 @@
+# Build Commands
+
+## Desktop
+```bash
+cargo build              # debug
+cargo build --release    # release
+cargo run                # game mode
+cargo run -- --editor    # editor mode
+```
+
+## iOS
+iOS builds require macOS. The project uses a custom SDL3 + wgpu iOS export pipeline. See `brain-project/ios/readme.md` in QMD for the full export guide.
+
+## Android
+```bash
+cargo apk build
+```
+
+## Checks
+```bash
+cargo check
+cargo fmt
+cargo clippy
+```

.claude/commands/wgsl.md

@@ -0,0 +1,15 @@
+# WGSL Uniform Buffer Alignment
+
+When creating uniform buffers for WGSL shaders, struct fields must be aligned:
+
+| Type | Alignment |
+|------|-----------|
+| `f32` | 4 bytes |
+| `vec2<f32>` | 8 bytes |
+| `vec3<f32>` | 16 bytes (treated as vec4) |
+| `vec4<f32>` | 16 bytes |
+| `mat4x4<f32>` | 16 bytes (64 bytes total) |
+
+Use padding fields to match WGSL struct layout exactly. Prefer `vec4` over individual floats to avoid alignment issues.
+
+Shaders live in `src/shaders/` and are embedded via `include_str!()`.

.claude/hooks/filter-cargo-warnings.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+import sys
+import json
+import re
+
+data = json.load(sys.stdin)
+
+if data.get("tool_name") != "Bash":
+    sys.exit(0)
+
+cmd = data.get("tool_input", {}).get("command", "")
+if not re.search(r"\bcargo\s+(check|build|test|clippy|run)\b", cmd):
+    sys.exit(0)
+
+output = data.get("tool_response", {}).get("output", "")
+if not output:
+    sys.exit(0)
+
+blocks = re.split(r"\n{2,}", output)
+warning_blocks = [b for b in blocks if re.match(r"\s*warning:", b)]
+other_blocks = [b for b in blocks if not re.match(r"\s*warning:", b)]
+
+if not warning_blocks:
+    sys.exit(0)
+
+filtered = "\n\n".join(other_blocks).rstrip("\n")
+filtered += f"\n\n[{len(warning_blocks)} warning(s) filtered]\n"
+
+print(json.dumps({"type": "result", "content": filtered}))