Description

Restructures the AI/agent guidance for this repo around three changes:

1. Promotes AGENTS.md to the source of truth for agent instructions; reduces GEMINI.md to a redirect stub.
2. Adds a mistake-reflection workflow — a cross-agent SKILL.md plus an evidence_rules.md for graduated learnings.
3. Trims mandatory_checks.md to use the existing scripts/lint.sh instead of restating its commands.

Why move from GEMINI.md to AGENTS.md

AGENTS.md is the cross-agent convention now supported by Gemini, Claude Code, OpenCode, Cursor, Codex CLI, etc. — a single file every modern agent auto-loads. GEMINI.md is Gemini-specific.

Mistake reflection workflow

When you notice the agent made a mistake:

1. Tell it. A simple "no, that's wrong" or "where do you see this?" should auto-trigger the mistake-reflection skill. If it doesn't, ask explicitly: "load the mistake-reflection skill."
   If you're using OpenCode (or a similar agent CLI that supports skills), you'll see mistake-reflection listed under /skills once the session has discovered it.
2. Review the new entry the agent appends to docs/ai/ai_learnings.md (gitignored, local-only). Make sure the root cause and proposed rule actually match the mistake.
3. If the rule is generally useful, ask the agent to promote it to docs/ai/evidence_rules.md (or another tracked file) so future sessions see it. Otherwise leave it in the journal — or delete it if it's a one-off.