# AGENTS.md — animation repo

Entry point for AI agents working in `local.repo/animation` (all tools: pi,
Claude Code, Cursor). This repo is Jeremy's animation-pipeline hub **and** the
Mac↔PC bridge that carries iClone/mocap exports into `ariki-game`. iClone 8 +
Video Mocap live on the PC; Blender 5, the retarget tools, and the game repo
live on both machines.

Read `.agents/SOUL.md` at session start, then use the knowledge map below —
this file stays thin; the operational detail lives in `.claude/skills/` and
`.agents/`.

## Knowledge map

| Category | Path | When |
|---|---|---|
| Identity | `.agents/SOUL.md` | always-on |
| Batch workflow, canonical retarget command, naming, loop QC, gotchas, repo etiquette | `.claude/skills/animation/SKILL.md` | always-on — read before any batch or clip work |
| Architecture (pipeline stages, canonical rig, tool provenance) | `.agents/wiki/ARCHITECTURE.md` | consult when touching the pipeline |
| Per-system architecture detail | `.agents/wiki/architecture/` | consult-when |
| In-flight work + recently shipped | `.agents/wiki/master-plan.md` | check before starting new work |
| Dance/clip naming registry (source of truth for names) | `.agents/wiki/dances/REGISTRY.md` | always-on when naming or shipping a clip |
| PC-lane routing stub | `.agents/wiki/iclone-bridge.md` | consult-when |
| Point-in-time audits / convergence reports | `.agents/wiki/devops-reports/` | consult-when |
| Open/executing plans | `.agents/plans/` | consult-when |
| Other operator playbooks (iClone/mocap, clip authoring, pose estimation) | `.claude/skills/` (index: `.agents/skills/README.md`) | consult-when |
| Loop-QC sub-agent | `.claude/agents/loop-qc.md` | consult-when |
| Repo-wide conventions | `.agents/rules/` | always-on |
| Exchange-folder operator guide (which folder, when files move/archive) | `exchange/GUIDE.md` | consult-when doing a batch |

## Layout

```
AGENTS.md          ← you are here
.agents/           ← agent context: SOUL, wiki (architecture/master-plan/registry/
                     devops-reports), plans, rules, skills-pointer
.claude/           ← Claude-Code-native skills + agents (auto-discovered)
tools/             ← Blender-headless retargeters, loop tools, prop export
exchange/          ← files in flight between Mac and PC (see exchange/GUIDE.md)
archive/           ← retired takes — never deleted, never renumbered
```

## Git

- Branch is **`main`**. Sync via **`tinqs push`/`tinqs pull`** (not raw git —
  this repo uses Git LFS for `.fbx/.glb/.mp4/.task`; a plain `git pull` hangs).
  Report the commit hash after pushing.
- **Stage explicit paths, never `git add -A`** — ariki-game and this repo often
  carry unrelated in-flight files.
- Never commit secrets.

## The rule that bites most often

**Green verify ≠ correct.** An agent-authored gate once passed an upside-down
boat export. Always render and eyeball a new visual asset before shipping —
full gotcha list in `.claude/skills/animation/SKILL.md`.