asset-inventory-manager

Gestor de Inventario de Activos

Mantén una Lista de Activos autoritativa y auditable por proyecto. Los datos residen en la carpeta .asset-inventory/ del proyecto (un archivo JSON por activo) y una vista Markdown generada (ASSET_LIST.md por defecto). Nunca edites la vista Markdown a mano: cambia los registros mediante la CLI, que la regenera.

La CLI

Todas las operaciones pasan por un único script de Python 3.9+ (solo stdlib) contenido en esta habilidad:

python <directorio-de-esta-habilidad>/scripts/asset_inventory.py <comando> [opciones]

En adelante, aim representa ese comando. Si python falta o no es Python 3, prueba python3, luego py -3 (Windows), luego uv run --no-project python. Ejecútalo desde cualquier lugar dentro del proyecto, o pasa -C <proyecto>. Añade --json para salida legible por máquina. El historial registra el agente actuante: pasa --agent <nombre> o establece AIM_AGENT si la detección automática es incorrecta.

Tarea	Comando
Iniciar un inventario	aim init --profile juego|vr|web|software|generico [--git-setup]
Registrar un activo	aim add --name "Arco" --category modelo --path assets/arco.glb --origin terceros --license CC-BY-4.0 --source-url URL --attribution requerida --credit "..."
Cambiar un activo	aim update ID --status final --verification aprobado --note "motivo"
Retirar / eliminar	aim remove ID --note "reemplazado por X" (mantiene el registro) / --purge
Buscar activos	aim query --category modelo --status placeholder, --path assets/ui/, --text arco, --format json|csv|ids
Un registro	aim get ID
Buscar archivos no registrados	aim scan (añade --register para crear registros necesita-triaje)
Comprobar todo	aim audit (--strict hace fallar las advertencias)
Reconstruir el Markdown	aim render (--check para CI)
Contexto (rama, worktree, bloqueo)	aim info
Migrar una tabla Markdown antigua	aim import-markdown lista_antigua.md
Tras un conflicto de Git	aim resolve, luego aim audit

Vocabulario (consulta el esquema para cada campo):

• status: planned (planificado), placeholder (placeholder, calidad de prototipo), integrated (integrado), final (final), retired (retirado).
• verification: unverified (sin verificar), pending (pendiente), verified (verificado, comprobaciones técnicas superadas), approved (aprobado, aprobado por el propietario). Nunca marques approved a menos que el usuario o revisor lo haya aprobado.
• origin: original (original), third-party (terceros), procedural (procedimental), ai-generated (generado por IA), unknown (desconocido). Los activos de terceros y generados por IA requieren una licencia.

Flujo de trabajo

1. Localizar. Ejecuta aim info. Si no existe inventario y el usuario desea uno, ejecuta aim init con el perfil más cercano (perfiles), luego aim scan para ver qué existe ya. Para una lista hecha a mano existente, usa aim import-markdown y revisa los registros etiquetados imported.
2. Registra cada cambio de activo en el mismo conjunto de cambios. Cuando añadas, reemplaces, modifiques, muevas o elimines un archivo de activo, actualiza su registro en el mismo commit: add para archivos nuevos, update --add-path/--remove-path para movimientos, update --modifications para ediciones en archivos de terceros, remove cuando no se use.
3. Registra la procedencia honestamente. Captura la URL de origen real, el autor, la licencia y el texto de crédito requerido en el momento de la descarga. Si se desconoce, usa --origin unknown y dilo; nunca adivines una licencia. Señala conflictos de licencia al usuario.
4. Mantén los estados veraces. Distingue entre planificado, implementado, verificado y aprobado. Coloca la siguiente comprobación pendiente en --next; aparece bajo "Necesita revisión" al principio de la lista.
5. Audita antes de finalizar. Ejecuta aim audit. Corrige errores; informa de las advertencias restantes al usuario. Menciona la ruta de la lista en tu resumen.

Reglas de colaboración (varios agentes, ramas, worktrees)

Detalles: colaboración.

• Cada worktree de Git tiene su propia copia del inventario; edita la del worktree en el que estés trabajando. Nunca edites el worktree de otro agente.
• Las escrituras toman un bloqueo breve (.asset-inventory/.lock), por lo que los agentes que compartan una misma carpeta no pueden corromper archivos. Si se informa de un bloqueo, espera y reintenta; elimínalo solo si aim info muestra que el proceso propietario ya no existe.
• Para evitar actualizaciones perdidas, lee con aim get ID, luego aim update ID --expect-revision N. El código de salida 3 significa que alguien más lo cambió: relee y reaplica.
• Un archivo por activo significa que las ramas paralelas rara vez entran en conflicto. Ejecuta aim git-setup una vez por clon para instalar el controlador de fusión a nivel de campo.
• Después de cualquier merge, rebase o cherry-pick: aim resolve (si los registros muestran marcadores de conflicto o _conflicts), luego aim render, luego aim audit, luego commit. Nunca fusiones ASSET_LIST.md a mano; regenéralo.
• Los IDs explícitos como M01 son válidos en una sola rama; los IDs predeterminados (<prefijo>-<slug-nombre>) evitan colisiones de numeración entre ramas.

Códigos de salida

0 ok · 1 error o auditoría fallida · 2 uso incorrecto/valor desconocido · 3 conflicto de revisión o fusión que necesita atención.