Imported from WestsideSage/TFM2-Draft-Assistant (AGENTS.md). Install upstream with npx skills add WestsideSage/TFM2-Draft-Assistant. Copyright stays with the author.

AGENTS.md — Agent Operating Manual

The operating manual for every model/agent in this repo (Claude and others). CLAUDE.md imports this file. Keep it lean — this is a checklist, not an essay.

For what the project is and how to run it, see README.md. For behavior truth, see SPEC.md. For the codebase map, see ARCHITECTURE.md.

Before coding

• Read README.md (pitch, status, how-to-run), SPEC.md (behavior, KB schema, rules), and ARCHITECTURE.md (structure, the SDK boundary).
• Reuse before you add: check existing patterns and .claude/ (agents, skills, hooks, settings) before introducing new tooling or conventions.
• ⚠️ Report-vs-DESIGN warning. docs/TFM2-Research-Report.md describes a Next.js + Supabase fan website — that is not the product. We build the Rust in-game mod described in docs/DESIGN.md. When they conflict, DESIGN wins.

Coding rules

Hard invariants (non-negotiable — invariant #1 is auto-enforced by .claude/hooks/guard-sdk-boundary.ps1):

1. SDK boundary. Only crates/tfm2-draft-mod may import the Mod SDK (mod_api). tfm2-engine and tfm2-data stay pure Rust with zero game deps — they compile and test without the game.
2. Panic safety. Wrap every hook body in catch_unwind. No unwrap/expect/panic!/unchecked indexing on game data. Hooks are strictly read-only — a panic in a hook crashes the user's live match.
3. Patch-resilience. Data, not code, absorbs balance patches. Every KB row carries patch_version + source + confidence. Never silently show stale data — show the staleness banner.
4. Determinism. Identical DraftState ⇒ identical recommendations (the replay/golden harness depends on it).
5. No fabricated data. Hard wall between canonical (verifiable game facts) and opinion (tier/counter/synergy — attributed, dated, confidence-tagged). Never invent champions, stats, tiers, counters, or synergies.
6. Licensing. Reimplement from the official schema; don't copy unlicensed code. Attribute CC-BY-SA (Miraheze) and MIT sources.

Generic rules: prefer small files; prefer boring solutions; no dependencies without a reason; don't rewrite working code unless asked.

Required after changes

• Run cargo test, cargo clippy, and cargo fmt (see TESTING.md for exact commands).
• Run the rust-safety-reviewer subagent on SDK-facing changes; run kb-data-validator on KB data.
• Update SPEC.md if product behavior changed, DECISIONS.md if a decision changed, and TASKS.md to reflect progress.

Working agreement (owner: Maurice)

1. Ask, don't assume. If intent/architecture/requirements are unclear, ask before writing code. Running unattended? Pick the most reasonable interpretation, proceed, and record the assumption.
2. Simplest solution for simple problems, better solutions for harder ones. Don't over-engineer or add flexibility that isn't needed yet.
3. Don't touch unrelated code — but do surface bad code / design smells you find, as a separate issue to discuss.
4. Flag uncertainty explicitly. Unsure? See #1. Where sensible, run a small, low-risk experiment and bring the hypothesis + results to discuss. Confidence without certainty causes more damage than admitting a gap.
5. Suggest better ways. Open to ideas — prefer approaches with lasting impact over tactical patches when it makes sense.