asset-inventory-manager

Asset Inventory Manager

Keep one authoritative, auditable Asset List per project. The data lives in the project's own .asset-inventory/ folder (one JSON file per asset) and a generated Markdown view (default ASSET_LIST.md). Never edit the Markdown view by hand: change records with the CLI, which regenerates it.

The CLI

All operations go through one stdlib-only Python 3.9+ script in this skill:

python <this-skill-dir>/scripts/asset_inventory.py <command> [options]

Below, aim stands for that command. If python is missing or not Python 3, try python3, then py -3 (Windows), then uv run --no-project python. Run it from anywhere inside the project, or pass -C <project>. Add --json for machine-readable output. History records the acting agent: pass --agent <name> or set AIM_AGENT when auto-detection is wrong.

Task	Command
Start an inventory	aim init --profile game|vr|web|software|generic [--git-setup]
Register an asset	aim add --name "Bow" --category model --path assets/bow.glb --origin third-party --license CC-BY-4.0 --source-url URL --attribution required --credit "..."
Change an asset	aim update ID --status final --verification approved --note "why"
Retire / delete	aim remove ID --note "replaced by X" (keeps the record) / --purge
Find assets	aim query --category model --status placeholder, --path assets/ui/, --text bow, --format json|csv|ids
One record	aim get ID
Find unregistered files	aim scan (add --register to create needs-triage records)
Check everything	aim audit (--strict makes warnings fail)
Rebuild the Markdown	aim render (--check for CI)
Context (branch, worktree, lock)	aim info
Migrate an old Markdown table	aim import-markdown old_list.md
After a Git conflict	aim resolve, then aim audit

Vocabulary (see schema for every field):

• status: planned, placeholder (works, prototype quality), integrated, final, retired.
• verification: unverified, pending, verified (technical checks passed), approved (owner approved). Never mark approved unless the user or reviewer approved it.
• origin: original, third-party, procedural, ai-generated, unknown. Third-party and AI-generated assets require a license.

Workflow

1. Locate. Run aim info. If no inventory exists and the user wants one, run aim init with the closest profile (profiles), then aim scan to see what already exists. For an existing hand-written list, use aim import-markdown and review records tagged imported.
2. Record every asset change in the same change set. When you add, replace, modify, move or delete an asset file, update its record in the same commit: add for new files, update --add-path/--remove-path for moves, update --modifications for edits to third-party files, remove when unused.
3. Record provenance honestly. Capture the real source URL, author, license and required credit text at download time. If unknown, use --origin unknown and say so; never guess a license. Flag license conflicts to the user.
4. Keep states truthful. Distinguish planned, implemented, verified and approved. Put the next pending check in --next; it appears under "Needs review" at the top of the list.
5. Audit before finishing. Run aim audit. Fix errors; report remaining warnings to the user. Mention the list path in your summary.

Collaboration rules (several agents, branches, worktrees)

Details: collaboration.

• Each Git worktree has its own copy of the inventory; edit the one in the worktree you are working in. Never edit another agent's worktree.
• Writes take a short lock (.asset-inventory/.lock), so agents sharing one folder cannot corrupt files. If a lock is reported, wait and retry; delete it only if aim info shows its owner process is gone.
• To avoid lost updates, read with aim get ID, then aim update ID --expect-revision N. Exit code 3 means someone else changed it: re-read and reapply.
• One file per asset means parallel branches rarely conflict. Run aim git-setup once per clone to install the field-level merge driver.
• After any merge, rebase or cherry-pick: aim resolve (if records show conflict markers or _conflicts), then aim render, then aim audit, then commit. Never hand-merge ASSET_LIST.md; regenerate it.
• Explicit IDs such as M01 are fine on one branch; default IDs (<prefix>-<name-slug>) avoid numbering collisions across branches.

Exit codes

0 ok · 1 error or failed audit · 2 bad usage/unknown value · 3 revision or merge conflict needing attention.