diff --git a/.agents/AGENTS.md b/.agents/AGENTS.md new file mode 100644 index 0000000..220305a --- /dev/null +++ b/.agents/AGENTS.md @@ -0,0 +1,11 @@ +# .agents/AGENTS.md — registry + delegation + +Detailed layer behind root `AGENTS.md`. This repo has no repo-specific +multi-agent registry beyond: + +- **`loop-qc`** (`.claude/agents/loop-qc.md`) — sub-agent for the loop-QC pass + on converted GLBs; use it instead of hand-running `tools/loop_qc.py` when + checking a batch of clips. + +For cross-repo agent roster, MCP services, and delegation rules, see the hub: +`tinqs-ltd/docs/.agents/AGENTS.md`. diff --git a/.agents/SOUL.md b/.agents/SOUL.md new file mode 100644 index 0000000..124a78a --- /dev/null +++ b/.agents/SOUL.md @@ -0,0 +1,26 @@ +# SOUL.md — animation repo identity + +Inherits the shared identity, values, and confidentiality rules from the hub: +`tinqs-ltd/docs/.agents/SOUL.md`. Read that first if this is your first session +on any Tinqs repo. + +## What this repo is + +The animation-pipeline hub and Mac↔PC bridge for Ariki. iClone 8 + Video Mocap +run on Jeremy's Windows PC; Blender 5, the retarget tools, and `ariki-game` live +on both machines. This repo carries the skills, tools, and files-in-flight that +turn PC-side motion capture (iClone renders, video mocap) into game-ready +Quaternius-rig GLB clips consumed by `ariki-game`. + +## Scope + +- **In scope:** FBX→GLB retargeting (Blender headless), loop QC and loop-fixing, + dance/clip naming and the registry, boat/prop export, the exchange-folder + bridge protocol, and the skills that encode iClone/mocap operator knowledge. +- **Out of scope:** game-side rendering, ClipCatalog code, dance ceremony + design (owned by `ariki-game`) — this repo only produces and ships the assets. + +## Confidentiality + +Same as the hub: this repo is private/internal. No special classified material +lives here (Cosmos-related confidentiality does not apply to animation tooling). diff --git a/plans/animation-gen-pipeline-2026-07-13.md b/.agents/plans/animation-gen-pipeline-2026-07-13.md similarity index 100% rename from plans/animation-gen-pipeline-2026-07-13.md rename to .agents/plans/animation-gen-pipeline-2026-07-13.md diff --git a/plans/animation-skills-adoption-2026-07-13.md b/.agents/plans/animation-skills-adoption-2026-07-13.md similarity index 100% rename from plans/animation-skills-adoption-2026-07-13.md rename to .agents/plans/animation-skills-adoption-2026-07-13.md diff --git a/plans/boat-prop-export-fixes-2026-07-17.md b/.agents/plans/boat-prop-export-fixes-2026-07-17.md similarity index 100% rename from plans/boat-prop-export-fixes-2026-07-17.md rename to .agents/plans/boat-prop-export-fixes-2026-07-17.md diff --git a/plans/boat-prop-export-plan-2026-07-17.md b/.agents/plans/boat-prop-export-plan-2026-07-17.md similarity index 100% rename from plans/boat-prop-export-plan-2026-07-17.md rename to .agents/plans/boat-prop-export-plan-2026-07-17.md diff --git a/plans/boat-prop-export-results-2026-07-17.md b/.agents/plans/boat-prop-export-results-2026-07-17.md similarity index 100% rename from plans/boat-prop-export-results-2026-07-17.md rename to .agents/plans/boat-prop-export-results-2026-07-17.md diff --git a/plans/loop-fix-plan-2026-07-16.md b/.agents/plans/loop-fix-plan-2026-07-16.md similarity index 100% rename from plans/loop-fix-plan-2026-07-16.md rename to .agents/plans/loop-fix-plan-2026-07-16.md diff --git a/plans/loop-fix-results-2026-07-16.md b/.agents/plans/loop-fix-results-2026-07-16.md similarity index 100% rename from plans/loop-fix-results-2026-07-16.md rename to .agents/plans/loop-fix-results-2026-07-16.md diff --git a/.agents/rules/README.md b/.agents/rules/README.md new file mode 100644 index 0000000..d8eaf32 --- /dev/null +++ b/.agents/rules/README.md @@ -0,0 +1,7 @@ +# rules/ — always-on conventions for this repo + +No repo-specific rules beyond what's already always-on in root `AGENTS.md` +(git via `tinqs push`/`tinqs pull`, stage-by-explicit-path, naming law) and the +shared hub rules at `tinqs-ltd/docs/.agents/rules/`. Add a file here when a +convention needs to be enforced repo-wide and doesn't fit in `AGENTS.md`'s +thin-entry budget. diff --git a/.agents/skills/README.md b/.agents/skills/README.md new file mode 100644 index 0000000..eb60faa --- /dev/null +++ b/.agents/skills/README.md @@ -0,0 +1,18 @@ +# skills/ — playbooks + +This repo's operator playbooks are Claude-Code-native skills and live at +`.claude/skills/` (auto-discovered by Claude Code), not duplicated here: + +| Skill | Covers | +|---|---| +| `animation` | Operator playbook — the batch workflow, naming, loop QC, gotchas | +| `animation-creation` | Authoring new clips on the shared Quaternius skeleton | +| `iclone-video-mocap` | iClone 8 + Video Mocap: filming, cleanup, FBX export | +| `pose-estimation` | Video→pose-landmark extraction (MediaPipe) | +| `retarget-animations` | Deprecated early retarget notes, kept for history | + +An agent-level playbook (`loop-qc`) lives at `.claude/agents/loop-qc.md`. Follow +the per-repo convention (`.agents/skills/` as the canonical location) once this +repo's skills are ported off `.claude/`; until then this file is the pointer so +there's a single place agents look, per the SoT rule (no second source of +truth). diff --git a/.agents/wiki/ARCHITECTURE.md b/.agents/wiki/ARCHITECTURE.md new file mode 100644 index 0000000..42714d1 --- /dev/null +++ b/.agents/wiki/ARCHITECTURE.md @@ -0,0 +1,90 @@ +# Architecture — animation pipeline + +Entry point to architecture law for this repo. Per-system detail lives in +`.agents/wiki/architecture/`. + +## The one-sentence shape + +PC-side motion capture (iClone 8 + Video Mocap) → this repo (Mac↔PC bridge, +Blender-headless retargeting, loop QC) → `ariki-game` (Quaternius-rig GLB +consumption via ClipCatalog). + +## Machines and where things live + +| Machine | Owns | +|---|---| +| PC (Windows) | iClone 8 + Video Mocap plugin — authors motion, exports FBX | +| Mac (and PC) | Blender 5.1.2, this repo's retarget tools, `ariki-game` checkout | + +Files move machine-to-machine only through `exchange/` in this repo, synced +with `tinqs push`/`tinqs pull` (Git LFS for `.fbx/.glb/.mp4/.task` — see +`.gitattributes`). Raw `git pull` hangs on LFS in tinqs.com repos. + +## Pipeline stages + +1. **Capture (PC)** — iClone export, Blender preset, Range=All, Preserve Bone + Names ON → `exchange/incoming-fbx/`. +2. **Retarget (either machine)** — Blender-headless, source-specific retargeter + in `tools/`, all bake onto the shared Quaternius rig and export a + mesh-stripped GLB with one NLA track per clip: + - `cc_retarget.py` — Reallusion CC/iClone `CC_Base_*` FBX (60fps; rejects + 2-frame `_TempMotion` exports as a guard against motion-less takes) + - `mixamo_retarget.py` — Mixamo FBX (prefix auto-detect) + - `kevin_retarget.py` — Kevin Iglesias Unity FBX (`B-*` rig; hardcoded + target path, non-portable) + - `mocap_retarget.py` — MediaPipe pose JSON → GLB (rotation solving, no + source armature) + → `exchange/converted-glb/`. +3. **Loop QC** — `tools/loop_qc.py` (pre-commit gate: pose/velocity/root-drift + continuity across the seam, exit 0 = smooth). Fixers when it fails: + `tools/loop_fix.py` (de-drift/trim/seam-blend → `exchange/looped-glb/`) and + `tools/pingpong_bake.py` (palindrome bake, seam-perfect but motion reverses + at the turn → `exchange/pingpong-glb/`, clip suffix `PP`). Every adopted + dance ships as a base clip + `_pp` pair. +4. **Ship** — commit + `tinqs push` the GLBs in this repo, then copy into + `ariki-game/assets/quaternius/dancegen/` (auto-discovered by ClipCatalog as + `/` — also watches `kevin/`, `mixamo/`), write one dance JSON + per clip in `ariki-game/assets/dances/`, `game.sh import`, verify clip names + match GLB `animations[].name` exactly, commit in ariki-game (push only when + Jeremy asks). +5. **Post-ingest QC (game side, out of this repo)** — `ariki-game/tools/anim_qc.py` + re-checks world-space seam continuity + renders a seam-cross video for eye + review. Two QC tools by design: this repo's gate is pre-commit/local-space, + the game's is post-ingest/world-space. + +## Naming law + +Full detail: `.agents/wiki/dances/REGISTRY.md` (source of truth — do not +duplicate its content elsewhere). Summary: new takes get a provisional `nd_##` +id (never a content-derived name); a take is renamed to its ceremony code +(snake_case of the sim's `DanceType` enum + index) only once Jeremy assigns it +to a specific ceremony, via `tools/rename_clip.py`. Rejected/superseded takes +are archived (`archive/`), never deleted; numbers are never reused. + +## Canonical target rig + +All retargeters bake onto ariki-game's +`assets/quaternius/base-characters/.../Godot - UE/Superhero_Male_FullBody.gltf`. +Run from this repo, `--target` must be passed explicitly (the tool's default +path is ariki-relative and won't resolve here). The rig/pack standard itself +(65-bone Quaternius UE-named skeleton, hero body `Ariki_Female_QuatSkin.glb`) is +governed by `ariki-game/.humans/animation-bone-sources.html` and +`ariki-game/.agents/wiki/quaternius-ual-packs.md` — this repo's iClone/mocap +lane is explicitly a separate clip source (not UAL1/UAL2/Kevin/Mixamo), landing +in `dancegen/` only. + +## Tool provenance / mirroring + +`tools/cc_retarget.py`, `mixamo_retarget.py`, `kevin_retarget.py`, +`mocap_retarget.py` are **mirrors of `ariki-game/tools/`** — the game copies are +authoritative; re-copy from ariki-game when they change (they have silently +diverged before). `.claude/skills/` here mirror a subset of `ariki-game/.claude/skills/` +plus `~/.claude/skills/pose-estimation` — see `README.md` Provenance section. + +## See also + +- `.agents/wiki/architecture/` — per-system detail (currently: this file covers + the whole pipeline; split out if a subsystem grows its own doc). +- `.agents/wiki/dances/REGISTRY.md` — naming/registry source of truth. +- `.agents/wiki/iclone-bridge.md` — PC-lane routing stub. +- `.agents/wiki/devops-reports/` — point-in-time audits and convergence reports. diff --git a/.agents/wiki/architecture/README.md b/.agents/wiki/architecture/README.md new file mode 100644 index 0000000..0546704 --- /dev/null +++ b/.agents/wiki/architecture/README.md @@ -0,0 +1,12 @@ +# architecture/ — per-system detail + +This repo's pipeline is small enough that `.agents/wiki/ARCHITECTURE.md` covers +it end to end today; nothing has grown large enough yet to need its own +per-system doc here. Split a topic out into this folder (and link it from +`ARCHITECTURE.md`) when it does — likely candidates as the repo grows: + +- Retarget-tool internals (per-source rig mapping, bone-name conventions). +- Loop QC/fix algorithms (pose-gap, velocity-gap, root-drift math). +- The exchange-folder state machine (`exchange/GUIDE.md` currently owns this — + promote here if it needs architecture-level treatment beyond an operator + guide). diff --git a/docs/dances/REGISTRY.md b/.agents/wiki/dances/REGISTRY.md similarity index 100% rename from docs/dances/REGISTRY.md rename to .agents/wiki/dances/REGISTRY.md diff --git a/docs/dances/dance1.md b/.agents/wiki/dances/dance1.md similarity index 100% rename from docs/dances/dance1.md rename to .agents/wiki/dances/dance1.md diff --git a/docs/dances/profiles/fertility_dance_01-profile.json b/.agents/wiki/dances/profiles/fertility_dance_01-profile.json similarity index 100% rename from docs/dances/profiles/fertility_dance_01-profile.json rename to .agents/wiki/dances/profiles/fertility_dance_01-profile.json diff --git a/docs/dances/profiles/taming_dance_01-profile.json b/.agents/wiki/dances/profiles/taming_dance_01-profile.json similarity index 100% rename from docs/dances/profiles/taming_dance_01-profile.json rename to .agents/wiki/dances/profiles/taming_dance_01-profile.json diff --git a/docs/dances/profiles/war_dance_01-profile.json b/.agents/wiki/dances/profiles/war_dance_01-profile.json similarity index 100% rename from docs/dances/profiles/war_dance_01-profile.json rename to .agents/wiki/dances/profiles/war_dance_01-profile.json diff --git a/devops-reports/2026-07-24-animation-standard-convergence.md b/.agents/wiki/devops-reports/2026-07-24-animation-standard-convergence.md similarity index 100% rename from devops-reports/2026-07-24-animation-standard-convergence.md rename to .agents/wiki/devops-reports/2026-07-24-animation-standard-convergence.md diff --git a/docs/iclone-bridge.md b/.agents/wiki/iclone-bridge.md similarity index 97% rename from docs/iclone-bridge.md rename to .agents/wiki/iclone-bridge.md index 995e170..e47efab 100644 --- a/docs/iclone-bridge.md +++ b/.agents/wiki/iclone-bridge.md @@ -10,7 +10,7 @@ GLBs. | Need | Go to | |---|---| | Which exchange/ folder to use, when files move/archive | `exchange/GUIDE.md` | -| Naming (nd_## → ceremony codes), loop-pair rule, registry | `docs/dances/REGISTRY.md` | +| Naming (nd_## → ceremony codes), loop-pair rule, registry | `.agents/wiki/dances/REGISTRY.md` | | Filming rules, iClone/AccuFACE settings, mocap cleanup, FBX export | `iclone-video-mocap` skill (`.claude/skills/` here and in ariki-game) | | CC FBX → Quaternius GLB conversion | `tools/cc_retarget.py` (mirror of ariki-game — game copy is authoritative) | | Looping (`_pp`) + QC gates | `tools/pingpong_bake.py` + `tools/loop_qc.py`; game-side `anim_qc.py` (split documented in REGISTRY.md) | diff --git a/.agents/wiki/master-plan.md b/.agents/wiki/master-plan.md new file mode 100644 index 0000000..b88c65c --- /dev/null +++ b/.agents/wiki/master-plan.md @@ -0,0 +1,56 @@ +# Master plan — animation repo + +What's in flight and recently shipped. See `.agents/plans/` for the closed-out +plan/results docs behind these items; see `.agents/wiki/dances/REGISTRY.md` for +the live per-clip status table (source of truth, not duplicated here). + +## Recently shipped (closed plans, folded into wiki) + +- **Animation-gen pipeline** (2026-07-13) — the FBX→Blender-retarget→GLB→dance-JSON + bridge itself; core of `.agents/wiki/ARCHITECTURE.md` today. +- **Animation skills adoption** (2026-07-13) — `.claude/skills/animation*`, + `iclone-video-mocap`, `pose-estimation` brought in as repo skills. +- **Loop fix** (2026-07-16, plan + results) — `tools/loop_fix.py` (de-drift/trim/ + seam-blend) and `tools/pingpong_bake.py` shipped; every adopted dance now ships + as a base clip + `_pp` pair, gated by `tools/loop_qc.py`. +- **Boat prop export** (2026-07-17, plan + fixes + results) — `tools/export_boat_prop.py` + staging pipeline for the boat action-clip set (see "Boat actions" below). +- **Animation-standard convergence** (2026-07-23/24, `.agents/wiki/devops-reports/`) — + full audit against ariki-game's animation-standardization contract. Result: + pipeline core already conformant (100% of runtime clip GLBs on the 65-bone + Quaternius rig, all `_pp` pairs present, dance JSONs clean). Fixes landed: + registry corrections (`tide_dance_01` has no sim enum entry — flag before + filming; `rain_dance_01` confirmed in-enum), `iclone-bridge.md` written + (previously a dead reference), QC-tool split documented (`loop_qc.py` here = + pre-commit gate, `ariki-game/tools/anim_qc.py` = post-ingest gate). +- **agents.md migration** (2026-07-24, this change) — repo restructured onto the + open agent protocol: root `AGENTS.md` (thin) + `.agents/` (SOUL, wiki, plans, + skills-pointer). `docs/` and root `plans/`/`devops-reports/` folded into + `.agents/wiki/`. + +## In flight — ceremony dance slots awaiting a take + +Per `.agents/wiki/dances/REGISTRY.md`, adopted so far: `fertility_dance_01` +(hula), `taming_dance_01`, `war_dance_01` (haka) — each shipped with its `_pp` +loop. One provisional take (`nd_01`, baraka1) is filmed and QC-passed but not +yet assigned to a ceremony. Still **awaiting a take**: `water_dance_01`, +`fire_dance_01`, `food_dance_01`, `sailing_dance_01`, `building_dance_01`, +`colony_shield_dance_01`, `age_progression_dance_01`, `star_watching_dance_01`, +`rain_dance_01`. `tide_dance_01` has no confirmed sim `DanceType` entry — resolve +with Ozan before filming. + +## In flight — boat action clips + +Staging tooling (`tools/export_boat_prop.py`) is built and the boat prop rig +verified; the action-clip set itself is **awaiting takes**: `boat_dive`, +`boat_climb`, `boat_collect`, `boat_row_loop`, `boat_fish_loop`, +`boat_sail_idle`. Two boat-adjacent clips are already live in-game +(`CanoeDismount`/`CanoeSitIdle`, `run_to_dive`) but predate this registry and +need a `boat_*` code assigned at the next adoption pass. + +## Open threads + +- `tools/kevin_retarget.py` has a hardcoded, non-portable target path — fine for + now, flagged in `AGENTS.md` gotchas. +- `.claude/skills/retarget-animations/` is kept only for history (deprecated, + superseded by the per-source retargeters in `tools/`). diff --git a/.claude/skills/animation/SKILL.md b/.claude/skills/animation/SKILL.md index 6e1b123..c578733 100644 --- a/.claude/skills/animation/SKILL.md +++ b/.claude/skills/animation/SKILL.md @@ -33,7 +33,7 @@ This skill is the accumulated **do-it-this-way** knowledge from real runs. ``` Blender here is **5.1.2**. When running from this repo the `--target` is **required** — the tool's default target path is ariki-relative and won't resolve. -## Naming system (registry: `docs/dances/REGISTRY.md` — read it, it is the source of truth) +## Naming system (registry: `.agents/wiki/dances/REGISTRY.md` — read it, it is the source of truth) Two-stage names, following the **game's item-id convention (lowercase snake_case)**. **New dances get a provisional id, never a content name**: at conversion, assign the next free `nd_##` from the registry — pack `nd_08`, clip `ND08`, JSON `nd_08.json`, diff --git a/AGENTS.md b/AGENTS.md index 3b5cfc2..c142325 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,112 +1,56 @@ # AGENTS.md — animation repo -Guidance for AI agents working in `local.repo/animation`. This repo is Jeremy's -animation-pipeline hub **and** the Mac↔PC bridge that carries iClone 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. +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. -Deeper knowledge lives in the repo skills (`.claude/skills/`): use **`animation`** -for the operator's playbook and hard-won lessons, **`animation-creation`** for -authoring new clips, **`iclone-video-mocap`** for iClone-side "how do I X", and -**`pose-estimation`** for video→pose extraction. `docs/dances/REGISTRY.md` is the -source of truth for clip names. This file is the fast orientation; the skills and -registry are authoritative. +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/`. -## The batch workflow ("process the incoming animations") +## Knowledge map -1. **Pull first** — `tinqs pull` (raw `git pull` hangs on LFS in tinqs.com repos). - Incoming FBX + textures + JSON land in `exchange/incoming-fbx/`. -2. **Retarget each FBX** → GLB in `exchange/converted-glb/` (command below). - Every dance ships as a **pair**: also bake its loop variant with - `tools/pingpong_bake.py` → `exchange/pingpong-glb/_pp.glb` (clip `PP`). -3. **Commit + push the GLBs in this repo** with `tinqs push` (self-heals auth, - uploads LFS direct-to-S3). Report the commit hash. -4. **Copy GLBs into ariki-game** `assets/quaternius/dancegen/`, write one dance - JSON per clip in `ariki-game/assets/dances/`. -5. **Loop QC gate** — run `loop_qc.py` on each GLB; flag anything not smooth - *before* it ships. -6. **Import** so Godot generates sidecars: `bash tools/game.sh import` (ariki root). -7. **Verify** clip names, then commit in ariki-game. -8. **Launch the test bed only after asking Jeremy.** -9. Leave `exchange/` cleanup until Jeremy confirms the batch looks right in-game. - -### Canonical retarget command -```bash -/Applications/Blender.app/Contents/MacOS/Blender --background --python tools/cc_retarget.py -- \ - --src exchange/incoming-fbx/.fbx \ - --out exchange/converted-glb/.glb --name \ - --target "/Users/jeremykashkett/Tinqs/local.repo/ariki-game/assets/quaternius/base-characters/Universal Base Characters[Standard]/Base Characters/Godot - UE/Superhero_Male_FullBody.gltf" -``` -Blender is **5.1.2**. `--target` is **required** when running from this repo (the -tool's default target path is ariki-relative and won't resolve here). Other -retargeters: `mixamo_retarget.py` (Mixamo), `kevin_retarget.py` (Kevin Iglesias -`B-*` rig, hardcoded target), `mocap_retarget.py` (MediaPipe pose JSON). - -## Naming (see `docs/dances/REGISTRY.md`) - -Lowercase snake_case, matching the game's item-id convention. **New takes get a -provisional `nd_##` id, never a content name** — pack `nd_08`, clip `ND08`, JSON -`nd_08.json`, variants `nd_08_pp` / `ND08PP`. Only when Jeremy **adopts** a take -for a ceremony is it renamed to its dance code (snake_case of the sim's `DanceType` -enum + index, e.g. `war_dance_01` / `WarDance01`). Never guess the ceremony — -Jeremy assigns it. Rename via `tools/rename_clip.py` + JSON + registry update. -Rejected takes are **archived, never deleted**; numbers are never reused. Update -the registry row on every convert/adopt/archive. - -- Pack name = GLB basename (lowercase); clip name = `--name` baked into the GLB. -- Clip ref in JSON = `/` (e.g. `nd08/ND08`). -- ClipCatalog auto-discovers anything in `dancegen/` (also `kevin/`, `mixamo/`) — - no code change needed. - -## Loop QC - -The game loops with Godot `LoopMode.Linear` (last keyframe → frame 0). A clip only -looks right if pose, motion velocity, and root position are continuous across the -seam — raw takes rarely are. QC every clip: -```bash -/Applications/Blender.app/Contents/MacOS/Blender --background --python tools/loop_qc.py -- \ - --src exchange/converted-glb/.glb # exit 0 = SMOOTH, 1 = NOT SMOOTH, 2 = error -``` -Fixers (no iClone round-trip): `tools/loop_fix.py` (de-drift + trim + seam blend → -`exchange/looped-glb/`) and `tools/pingpong_bake.py` (palindrome bake, seam-perfect -but motion reverses at the turn — prefer for sway-heavy dances). Re-run `loop_qc.py` -to confirm exit 0. Or use the `loop-qc` agent. - -## Gotchas that have actually bitten - -- **2-frame `_TempMotion` FBX = no motion.** The tool rejects by frame count, not - name; that's the guard working. Re-export from iClone with Include/Export Motion. -- **A-pose arms.** CC/iClone bind in A-pose. Eyeball arm orientation in the test - bed on the first clip of any new source; re-export with *Use T-Pose As Bind Pose* - if wrong. -- **Verify GLB `animations[].name` == JSON clip ref** before shipping — a mismatch - is a silent no-play. -- **Commit the `.glb.import` sidecar with the GLB** (Godot embeds `uid://` there; - no separate `.uid`). GLB + `.import` + JSON go together. -- **`game.sh import` warnings are pre-existing noise** — only `errors` matter. -- **Green verify ≠ correct.** An agent-authored gate once passed an upside-down - boat export. Always render and eyeball a new visual asset before shipping. - -## Repo etiquette - -- **Don't touch unrelated uncommitted work.** ariki-game often has in-flight files; - stage only this batch's files **by explicit path**, never `git add -A`. -- Use **`tinqs push` / `tinqs pull`**, not raw git — this repo uses Git LFS for - `.fbx/.glb/.mp4/.task`. Report the commit hash after pushing. -- Commit co-author line: `Co-Authored-By: Claude Fable 5 `. -- **ariki-game commits stay local until Jeremy asks to push** — pushing the game - repo is not part of the bridge steps. -- **Ask before launching the game.** `SCENE=dance_test_bed bash tools/game.sh spawn` - (from ariki root); `animation_showcase` pages every clip. Never use `*RM` / - `*RootMotion` variants — everything is in-place. If you pipe spawn through `tail`, - the log stays 0 bytes until exit — confirm via the lease file + `pgrep`, don't - assume it failed. +| 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 -- `.claude/skills/` — repo skills (see intro); `.claude/agents/loop-qc.md`. -- `tools/` — Blender-headless retargeters, loop tools, prop export, `rename_clip.py`. -- `exchange/` — files in flight: `incoming-fbx/`, `converted-glb/`, `looped-glb/`, - `pingpong-glb/`, `outgoing-props/`, `reference-video/`, `INBOX/`. -- `docs/` — `dances/REGISTRY.md`, `iclone-bridge.md`. -- `plans/` — pipeline design docs. `archive/` — retired takes. `devops-reports/`. +``` +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`. diff --git a/README.md b/README.md index f87665a..afcbf8d 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ into the game repo. - `kevin_retarget.py` — Kevin Iglesias Unity FBX (`B-*` rig; hardcoded target path — non-portable) - `mocap_retarget.py` — MediaPipe pose JSON → GLB (rotation solving, no source armature) - `bake_run_punch.mjs` — composite upper/lower clip baking reference -- `plans/` — pipeline design docs (animation generation pipeline, skills adoption) +- `AGENTS.md` / `.agents/` — agent context (identity, wiki, plans, rules); see `AGENTS.md` for the knowledge map ## Canonical target rig diff --git a/exchange/GUIDE.md b/exchange/GUIDE.md index be2304c..cec976c 100644 --- a/exchange/GUIDE.md +++ b/exchange/GUIDE.md @@ -6,8 +6,8 @@ below. If you are an agent dropping files into this repo, or processing a batch, this file tells you which folder to use, when a file moves to the next stage, and when the previous version gets archived. -Related docs: `docs/dances/REGISTRY.md` (naming — the source of truth), -`docs/iclone-bridge.md` (PC-lane overview), and the `animation` skill (batch workflow details). +Related docs: `.agents/wiki/dances/REGISTRY.md` (naming — the source of truth), +`.agents/wiki/iclone-bridge.md` (PC-lane overview), and the `animation` skill (batch workflow details). **Tool mirroring rule (audit 2026-07-23):** the retargeters in `tools/` (`cc_retarget.py`, `mixamo_retarget.py`, `kevin_retarget.py`, `mocap_retarget.py`) are @@ -79,7 +79,7 @@ always. | `PINGPONG_GLB` / `LOOPED_GLB` | The loop variant (`_pp` / seam-fixed). **Every shipped dance is a pair: base + loop.** Must pass `tools/loop_qc.py` (exit 0) | Copied into `GAME_DANCEGEN` alongside the base clip | Rules on this track: -- **Naming:** new takes get the next free `nd_##` from `docs/dances/REGISTRY.md` +- **Naming:** new takes get the next free `nd_##` from `.agents/wiki/dances/REGISTRY.md` at conversion — never a content name. Update the registry row at every conversion/adoption/archive. - **FBX stays in `INCOMING_FBX` after conversion** (it's the re-export source) @@ -151,7 +151,7 @@ These are big (100 MB+) LFS blobs. `ARCHIVE` is ever renamed or reused. 3. **Registry numbers are never reused.** An archived `nd_03` retires the number forever. -4. Every archive action gets a **registry update** (`docs/dances/REGISTRY.md`) +4. Every archive action gets a **registry update** (`.agents/wiki/dances/REGISTRY.md`) when it involves a tracked dance. 5. Game-side counterparts (GLBs/JSON already copied into ariki-game) archive to `/archive/dances/` (which is `.gdignore`d), in the same commit