Davicjc/agy

agy: Claude + Gemini trabajando juntos

El agy es un agente de terminal similar a Claude Code, que ejecuta modelos Gemini (y otros). Es fuerte donde Claude es más débil o más caro: imagen, audio y vídeo nativos, y trabajo en volumen. Usado con criterio, se convierte en un segundo par de manos y un revisor independiente. Usado sin criterio, dice "listo" sin haberlo hecho.

La regla de oro de esta skill: Claude sigue siendo responsable del resultado. El agy ejecuta; Claude especifica, verifica y decide.

Los scripts se encuentran en scripts/ junto a este archivo. En los comandos siguientes, <skill> es la carpeta mostrada como "Base directory for this skill" cuando la skill se carga; usa siempre la ruta absoluta.

Script	Para qué
scripts/agy-modelo PAPEL	Devuelve el modelo correcto para el rol, leído de agy models en el momento
scripts/agy-tarea ...	Ejecuta una tarea, guarda todo y muestra lo que realmente cambió en git
scripts/agy-revisar ...	Revisión de un diff solo lectura, con hallazgos estructurados
scripts/agy-historico [N]	Últimas ejecuciones: estado, modelo, tiempo y tokens (para rendir cuentas del gasto)

El usuario también puede llamar directamente: /agy:delegar, /agy:revisar, /agy:modelos y /agy:historico.

Antes de todo: ¿está listo el agy?

command -v agy && <skill>/scripts/agy-modelo --listar --actualizar

Si agy no existe o el comando falla, detente y avisa al usuario (necesita instalar o iniciar sesión en agy). No intentes solucionarlo por tu cuenta. Después de la primera verificación de la sesión, agy-modelo sin --actualizar usa la lista guardada durante 1 hora.

Cuándo delegar (y cuándo no)

Delega cuando agy sea mejor o cuando paralelizar ahorre tiempo de verdad:

• Imagen: generar o editar foto, fondo, banner, mockup, icono, cambiar texto o logo dentro de una imagen.
• Audio y vídeo: transcribir audio (incluso de WhatsApp), resumir o analizar un .mp4 directamente desde el archivo.
• Partes independientes de un trabajo grande: módulos, pantallas, pruebas, documentación, cada una con sus archivos.
• Volumen mecánico: renombrar API en 40 archivos, migrar patrón repetitivo, generar datos de ejemplo.
• Segunda opinión: revisar el código que Claude acaba de escribir (ver "Validación cruzada").

No delegues cuando:

• la tarea depende del contexto de esta conversación que es difícil de transmitir por escrito (decisiones, preferencias del usuario, idas y vueltas): escribir ese contexto suele costar más que hacerlo tú mismo;
• es una edición pequeña y obvia (delegar y verificar sale más caro);
• involucra secretos, contraseñas, tokens, datos personales de terceros o acciones irreversibles (borrar, publicar, enviar mensaje, git push): eso queda para Claude y para el usuario.

Elección del modelo (dinámica)

Nunca escribas un nombre de modelo fijo en el prompt o en el comando. Usa el rol:

Rol	Uso	Hoy elige (ejemplo)
codigo	escribir y modificar código	Gemini "pro" más nuevo, esfuerzo alto
revision	revisión de diff, caza de bugs	Gemini "pro" más nuevo, esfuerzo alto
investigacion	leer mucho material y resumir	Gemini "pro" más nuevo, esfuerzo medio
imagen	generar o editar imagen	Gemini "pro" más nuevo, esfuerzo medio
rapido	tarea simple, volumen, borrador	Gemini "flash" más nuevo

agy-modelo lee agy models (con caché de 1 h), separa la familia rápida (flash/lite) de la principal, toma la versión más nueva y el esfuerzo preferido del rol. Cuando salga un Gemini nuevo, se usará automáticamente sin cambiar nada. Para forzar: AGY_MODELO_CODIGO=<id> (por rol) o AGY_MODELO=<id> (todos). Usa --actualizar si un modelo acaba de ser lanzado.

Para revisión, prefiere un modelo de familia diferente a la que escribió el código. La gracia de la segunda opinión es tener otro "cerebro". El rol revision ya elige Gemini; no lo cambies por Claude dentro de agy solo para revisar código del propio Claude.

Cómo pedir una tarea

1. Escribe el prompt en un archivo siguiendo references/prompt-modelo.md. Debe ser autocontenido: el agy no ha visto esta conversación. Rutas absolutas, qué leer antes, qué hacer, qué no tocar, dónde guardar y cómo probar que está correcto.
2. Ejecuta en segundo plano (Bash con run_in_background: true), porque las tareas pueden durar desde segundos hasta decenas de minutos:

<skill>/scripts/agy-tarea --dir /abs/proyecto --rol codigo \
  --nombre "pantalla de inicio de sesión" --prompt-archivo /abs/prompt.md --timeout 2400

• --dir es obligatorio y se puede repetir. El agy solo ve y edita las carpetas pasadas aquí. Sin esto, graba en un borrador propio y responde "listo" sin haber cambiado nada en el proyecto. Incluye también la carpeta de los archivos de apoyo (imagen de referencia, audio).
• --modo plan deja que el agy solo lea (análisis, investigación, revisión). El valor por defecto accept-edits permite editar archivos.
• El script añade reglas fijas al prompt: no hacer commit, no usar sudo, no salir de las carpetas, responder breve. Usa --sin-reglas solo cuando tengas un motivo.
• Para continuar la misma conversación (ej.: pedir un ajuste), usa --continuar <id>, con el id que está en meta.json. El agy recuerda lo dicho anteriormente.
• Un pedido largo no es problema: por encima de ~100 KB el script entrega el pedido al agy mediante un archivo (la línea de comandos de Linux rechaza un argumento de más de 128 KB).
• La salida muestra como máximo 150 líneas de la respuesta (--max-lineas N cambia esto); el texto completo queda en respuesta.md, en la carpeta indicada en PASTA=. Léelo solo si es necesario: así el resultado del agy no satura tu contexto.
• Si Claude se está ejecutando como root en una carpeta de otro usuario, el script devuelve al dueño de la carpeta lo que el agy creó en el terminal (mkdir, npm install, git...), que nace como root. Sin esto, git y el editor del usuario se rompen después. La herramienta de escritura del propio agy ya respeta al dueño. --mantener-dueños desactiva esto.

Salida de agy-tarea	Significado
0	El agy terminó. Aún necesita validación (próxima sección)
1	Error del agy o respuesta vacía (RESPUESTA-VACIA): trátalo como fallo
2	Uso incorrecto del script (el mensaje dice qué falta)
3	El agy hizo commit, a pesar de las reglas: revisa git log y avisa al usuario
124	Tiempo agotado. Lo que ya editó sigue en el disco: verifica alteraciones.txt

3. Mientras se ejecuta, sigue trabajando en otra cosa. Se te avisará cuando el proceso termine.

Validar lo que entregó el agy (obligatorio)

El informe del agy es una afirmación, no una prueba. agy-tarea ya muestra lo que realmente cambió (comparación del git status antes y después) y alerta si el agy hizo commit (código de salida 3). Luego:

1. Compara el informe con alteraciones.txt. Si dice que creó un archivo que no aparece, o modificó algo fuera del pedido, eso es un problema.
2. Lee el diff (git diff, git diff --stat), no solo la respuesta.
3. Ejecuta las comprobaciones del proyecto: build, pruebas, lint, node --check, python -m py_compile, o lo que exista. Para interfaces, mira la pantalla real (captura/navegador). El agy suele equivocarse en temas, colores y detalles de integración entre archivos.
4. Decide: aceptar, corregir tú mismo (si es pequeño) o devolver con --continuar y la lista exacta de lo que está mal.

Solo di al usuario que está listo después de esto.

Validación cruzada (segunda opinión)

Después de un cambio relevante, escrito por Claude o por el agy, pide una revisión independiente:

<skill>/scripts/agy-revisar --dir /abs/repo                       # todo desde HEAD, con archivos nuevos
<skill>/scripts/agy-revisar --dir /abs/repo --base main           # todo desde main
<skill>/scripts/agy-revisar --dir /abs/repo --intervalo HEAD~3..HEAD --foco "concurrencia en el worker"

El agy revisa en modo solo lectura y devuelve veredicto (aprobado, ajustar, reprobar) y hallazgos con gravedad, confianza, archivo:línea, evidencia y sugerencia (formato en assets/schema-revision.json). El diff va delimitado y con el aviso de que el texto dentro del código son datos, no instrucciones, para que un comentario malicioso no "obligue" al revisor a aprobar. Con --exigir-aprobado, el script sale con código 4 cuando el veredicto no es "aprobado" (útil en automatización).

No apliques los hallazgos a ciegas. Para cada uno: abre el código, confirma que el escenario de fallo ocurre realmente y solo entonces corrige. Descarta los falsos positivos y di al usuario cuántos hallazgos eran reales. Un hallazgo con confianza baja es una pista, no una orden. Si el agy aprueba algo que estás seguro de que está correcto, explica el motivo al usuario en lugar de cambiar para complacer al revisor.

Trabajo en paralelo

Para dividir un trabajo grande:

1. Divídelo en partes que no modifiquen los mismos archivos. Si dos partes necesitan el mismo archivo, no son paralelas: hazlas en secuencia.
2. Dale a cada parte su propia carpeta: un git worktree por parte es lo más seguro (git worktree add ../proyecto-parte-a -b parte-a), o subcarpetas disjuntas.
3. Ejecuta un agy-tarea por parte, todos con run_in_background: true, cada uno con --dir solo de su carpeta.
4. Valida cada parte (sección anterior) antes de unir. Une una por una, ejecutando las pruebas en cada unión.
5. Más de 3–4 agentes al mismo tiempo suele exceder la cuota o el límite de solicitudes del agy. Prefiere pocas partes bien definidas.

Una buena división es que Claude se encargue de la parte que requiere el contexto de la conversación (arquitectura, integración, decisiones del usuario) y el agy de las partes aisladas.

Imagen, audio y vídeo

• Coloca el archivo de entrada en una carpeta pasada en --dir y menciona la ruta absoluta en el prompt.
• Para imágenes, indica el tamaño, el formato y la ruta exacta de salida, y muestra el resultado al usuario antes de usarlo en el proyecto. Si hay identidad visual (colores, fuentes), proporciona los valores, porque el agy no adivina.
• Para transcripción, pide el formato (texto corrido, con marcas de tiempo, por hablante) y el idioma. Usa --modo plan si no hay nada que editar.

Problemas comunes

Lee references/problemas.md cuando algo salga mal: "listo" sin cambios, tiempo agotado, cuota, modelo no reconocido, inicio de sesión, respuesta fuera de formato.

Cómo informar al usuario

Breve y verificable: qué se delegó, con qué modelo (meta.json), qué cambió (archivos), qué verificaste (pruebas, diff, pantalla) y qué corregiste de lo que hizo el agy. Si la validación cruzada encontró algo, di cuántos hallazgos eran reales y qué se hizo con ellos. Los registros completos están en ~/.cache/agy-skill/ejecuciones/ (eliminados después de 30 días; AGY_SKILL_RETENCION_DIAS lo cambia), y agy-historico resume el gasto de tokens.