chore(agents): migrate to agents.md protocol — .agents/ wiki/plans/rules/skills
Root AGENTS.md is now a thin entry point + knowledge map; the batch-workflow detail it duplicated already lived in .claude/skills/animation/SKILL.md. Folded docs/ (dances registry + iclone-bridge stub), root plans/, and devops-reports/ into .agents/wiki/ and .agents/plans/ per the per-repo .agents/ convention. Added .agents/SOUL.md, .agents/AGENTS.md, wiki/ARCHITECTURE.md, wiki/architecture/, and wiki/master-plan.md (derived from the closed plans + the dance registry's live ceremony-slot table). Fixed doc-path references in exchange/GUIDE.md, the animation skill, and the iclone-bridge stub. All moves via mv (git detected as renames) — no content deleted. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@@ -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/<id>_pp.glb` (clip `<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/<take>.fbx \
|
||||
--out exchange/converted-glb/<pack>.glb --name <ClipName> \
|
||||
--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 = `<pack>/<ClipName>` (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/<pack>.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 <noreply@anthropic.com>`.
|
||||
- **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`.
|
||||
|
||||
Reference in New Issue
Block a user