atishaytuli07/versioning-ai-work

Versionado de trabajo con IA

Las personas que iteran con IA pierden buenas versiones: una regeneración las sobrescribe, un deshacer va demasiado lejos o la conversación se desvía. Esta habilidad hace que cada cambio sea una versión numerada que permanece hasta que el usuario la elimina, para que pueda ver, comparar y regresar a cualquier estado anterior.

Las tres reglas

1. Cada cambio obtiene una versión. Una solicitud del usuario que cambia archivos es una versión, guardada al final de ese turno, antes de que respondas. Guardar por solicitud, no por edición de archivo, mantiene el historial legible.
2. Retroceder nunca elimina una versión. Solo el script escribe en .ai-versions/. Nunca edites, muevas ni elimines nada allí, incluso si te piden limpiar. Indica al usuario que use backup en su lugar.
3. Retroceder es una nueva versión. Restaura con el script; nunca reconstruyas trabajo antiguo de memoria. Una restauración se guarda como una nueva versión, para que también se pueda deshacer.

El script elige cada número de versión. Nunca adivines uno; informa el número que imprime.

Elige el modo una vez por proyecto

• Puedes ejecutar comandos y editar archivos (Claude Code, Cursor, Codex, Windsurf, Copilot, Gemini CLI, Replit Agent, claude.ai con ejecución de código): usa el modo de archivos a continuación.
• El proyecto tiene .github/workflows/ai-versions.yml: usa la capa de versión de GitHub. No ejecutes init. En su lugar, con cada cambio, sobrescribe .ai-versions/pending.json, y para retroceder, escribe .ai-versions/restore.json. Ambos están descritos en assets/rules/github-layer-rules.md.
• No puedes ejecutar comandos (un chat simple): sigue references/chat-mode.md.
• El usuario construye en Lovable, Bolt o v0 (Bolt y v0 están en beta: no probados en vivo aún), o Figma Make y pregunta cómo versionar allí: lee references/app-builders.md.

Modo de archivos

El script es scripts/aiv.py dentro de la carpeta de esta habilidad (la carpeta que contiene este SKILL.md). Llámalo con su ruta completa y apúntalo al proyecto con --root:

python3 "<ruta de la carpeta de esta habilidad>/scripts/aiv.py" --root "<carpeta del proyecto>" <comando>
# Windows: py en lugar de python3

Después de init, cada proyecto también tiene su propia copia, así que desde la carpeta del proyecto python3 .ai-versions/aiv.py <comando> funciona igual. Abajo, aiv significa cualquiera de las dos formas. Si Python no está instalado, dile al usuario que es necesario (python.org) y usa el modo de chat hasta que lo esté.

Inicio

Antes de tu primera edición en un proyecto sin .ai-versions/, ejecuta init. Guarda los archivos actuales como v1.0.0, para que el usuario siempre pueda regresar a cómo estaban las cosas antes de que las tocaras.

Si la carpeta contiene más que el proyecto (un sandbox, una carpeta de inicio, una carpeta de Descargas), delimítala: init --only poster.html assets/. init rechaza carpetas con más de 5,000 archivos porque eso generalmente significa que es la carpeta equivocada.

Después de cada cambio

aiv save --bump minor --summary "Agregué una sección de precios con 3 planes" \
  --reason "Sección nueva; diseño y estilo sin cambios" --prompt "agregar precios con 3 planes"

--bump	Mostrado al usuario como	Cuándo
patch	Pequeño ajuste	Mismas funciones, pequeño ajuste: texto, color, espaciado, tamaño, una pequeña corrección
minor	Nueva función	Algo nuevo, misma dirección: una sección, página, componente, funcionalidad
major	Cambio grande	La dirección cambió: rediseño, nuevo diseño, nuevo sistema de estilo, eliminación de una función

Una solicitud con varios cambios toma el nivel más alto. Si no estás seguro entre dos niveles: toma el más bajo y dilo en --reason. Los casos límite (documentos, refactorizaciones, actualizaciones de contenido) están en references/bump-levels.md.

Escribe --summary para el usuario, no para un desarrollador: "Hice la imagen del héroe más grande", no "Actualizar Hero.tsx". Pon la solicitud del usuario, acortada a una línea, en --prompt.

Luego termina tu respuesta con una línea, por ejemplo: Guardado v1.3.0 (Nueva función): Agregué una sección de precios con 3 planes.

Si save dice que los archivos coinciden exactamente con una versión anterior, registra el guardado como un retorno a esa versión. Dile al usuario que eso es lo que pasó.

Cuando el usuario pregunta

El usuario dice	Ejecuta	Luego
"muestra versiones", "historial"	list	Muestra una tabla breve. Para una línea de tiempo visual, ejecuta view y comparte el archivo HTML que escribe.
"qué cambió en v1.3.0"	diff v1.3.0^ v1.3.0	Explica en palabras simples. vX^ significa la versión anterior a vX.
"compara v1.2 y v2.0"	diff v1.2.0 v2.0.0 --stat, luego sin --stat para detalle	Di qué cambió, qué mejoró, qué empeoró. Si puedes renderizar el trabajo (HTML, imágenes), muestra ambos lado a lado.
"vuelve a v1.2.0", "deshaz eso"	restore v1.2.0, o restore prev para deshacer	Luego haz el paso a continuación.
"trae solo el antiguo encabezado", "diseño antiguo pero mantén el texto nuevo"	restore v1.2.0 --path <archivos>	Solo esos archivos cambian; se guarda como un Pequeño ajuste.
"prueba otra dirección desde v1.2.0"	restore v1.2.0	Luego haz el nuevo cambio y guárdalo como de costumbre.
"cuál es la versión actual", "algo sin guardar"	status
"dame v1.2.0 como archivos"	export v1.2.0 --out v1.2.0.zip
"continúa esto en otro chat o herramienta"	backup --out history.zip	En el nuevo lugar: import history.zip.

Cuando el usuario nombra una versión vagamente ("la azul", "antes del rediseño"), ejecuta list y relaciona los resúmenes. Si dos versiones encajan, pregunta cuál.

Después de retroceder

Una restauración completa devuelve todos los archivos del proyecto a como estaban, incluidos archivos que el usuario puede no considerar parte del trabajo, como notas o datos. Dile al usuario qué archivos cambiaron (el script los lista). Si primero guardó trabajo sin guardar, di qué versión lo contiene y ofrece traer archivos específicos de vuelta con restore <esa versión> --path <archivo>. Cuando la solicitud claramente apunta solo a parte del proyecto ("los colores antiguos"), usa --path desde el principio.

Ejecuta handoff <versión que restauraste> y trata su salida como la verdad actual antes de hacer el siguiente cambio. Lista solo las decisiones que llevaron a esa versión y nombra las descartadas, para que instrucciones de direcciones abandonadas no se filtren de vuelta. Si la conversación es larga, ofrece continuar en un nuevo chat y dale al usuario el texto de transferencia para pegar allí.

Red de seguridad para guardados olvidados

En Claude Code o Cursor, ofrece esto una vez por proyecto: install-hooks claude-code o install-hooks cursor. Agrega un gancho que guarda cualquier cambio que olvidaste guardar como un Pequeño ajuste cuando terminas. Instálalo solo después de que el usuario diga que sí, porque escribe en su configuración de herramientas.

Hablando sobre versiones

Usa las palabras del usuario: Pequeño ajuste, Nueva función, Cambio grande, Retrocedió. Menciona números de versión, no commits, archivos en .ai-versions/ ni hashes. Notas específicas de herramientas (claude.ai, Replit, Windows) están en references/tools.md.

Cuando un usuario retrocede, recuérdale una vez que solo los archivos vuelven: las filas de la base de datos y otros datos en vivo permanecen como están.

Todos los comandos

Comando	Qué hace
init [--only RUTA...]	Iniciar el historial y guardar v1.0.0
save --bump N --summary R [--reason Z] [--prompt P]	Guardar los archivos actuales como una nueva versión
status	Versión actual y cambios sin guardar
list [--all] [--json]	Versiones, más reciente primero
show V	Detalles de una versión y archivos cambiados
diff [A] [B] [--stat] [--path R...]	Sin argumentos: cambios sin guardar. Uno: A a la última. Dos: A a B
restore V [--path R...] [--note N]	Retroceder (todos los archivos, o solo algunos); guarda trabajo sin guardar primero, luego guarda la restauración como una nueva versión
handoff [V]	Contexto limpio para continuar desde V
view [--out ARCHIVO]	Línea de tiempo HTML de todas las versiones
export V --out DIR_o_ZIP	Los archivos de una versión
backup --out ARCHIVO.zip / import ARCHIVO.zip	Mover todo el historial
`install-hooks claude-code	cursor`
setup-github [--with-pill]	Agregar la capa de GitHub a un repositorio de creador de aplicaciones
doctor	Revisar el historial en busca de piezas faltantes

Las versiones se pueden escribir como v1.2.0, 1.2.0, latest, prev o v1.2.0^.