agy

agy : Claude + Gemini travaillant ensemble

L'agy est un agent de terminal similaire à Claude Code, qui exécute les modèles Gemini (et autres). Il est fort là où Claude est plus faible ou plus cher : image, audio et vidéo natifs, et travail en volume. Utilisé avec discernement, il devient une seconde paire de mains et un relecteur indépendant. Utilisé sans discernement, il dit « fait » sans l'avoir fait.

La règle d'or de cette skill : Claude reste responsable du résultat. L'agy exécute ; Claude spécifie, vérifie et décide.

Les scripts se trouvent dans scripts/ à côté de ce fichier. Dans les commandes ci-dessous, <skill> est le dossier affiché comme « Base directory for this skill » lorsque la skill est chargée ; utilisez toujours le chemin absolu.

Script	À quoi ça sert
scripts/agy-modelo PAPEL	Retourne le bon modèle pour le rôle, lu depuis agy models à la volée
scripts/agy-tarefa ...	Exécute une tâche, sauvegarde tout et montre ce qui a vraiment changé dans git
scripts/agy-revisar ...	Révision d'un diff en lecture seule, avec des résultats structurés
scripts/agy-historico [N]	Dernières exécutions : statut, modèle, temps et tokens (pour justifier les dépenses)

L'utilisateur peut aussi appeler directement : /agy:delegar, /agy:revisar, /agy:modelos et /agy:historico.

Avant tout : l'agy est-il prêt ?

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

Si agy n'existe pas ou que la commande échoue, arrêtez-vous et avertissez l'utilisateur (il doit installer ou se connecter à agy). N'essayez pas de contourner. Après la première vérification de la session, agy-modelo sans --atualizar utilise la liste stockée pendant 1 h.

Quand déléguer (et quand ne pas le faire)

Déléguez lorsque l'agy est meilleur ou que la parallélisation fait vraiment gagner du temps :

• Image : générer ou éditer une photo, un fond, une bannière, une maquette, une icône, changer le texte ou un logo dans une image.
• Audio et vidéo : transcrire un fichier audio (y compris WhatsApp), résumer ou analyser un fichier .mp4 directement.
• Parties indépendantes d'un grand travail : modules, écrans, tests, documentation, chacun avec ses fichiers.
• Volume mécanique : renommer une API dans 40 fichiers, migrer un motif répétitif, générer des données d'exemple.
• Seconde opinion : réviser le code que Claude vient d'écrire (voir « Validation croisée »).

Ne déléguez pas lorsque :

• la tâche dépend du contexte de cette conversation difficile à transmettre par écrit (décisions, préférences de l'utilisateur, allers-retours) : écrire ce contexte coûte souvent plus cher que de le faire ;
• il s'agit d'une modification petite et évidente (déléguer et vérifier coûte plus cher) ;
• cela implique un secret, un mot de passe, un token, des données personnelles de tiers ou une action irréversible (supprimer, publier, envoyer un message, git push) : cela reste avec Claude et l'utilisateur.

Choix du modèle (dynamique)

N'écrivez jamais un nom de modèle fixe dans le prompt ou la commande. Utilisez le rôle :

Rôle	Usage	Choisit aujourd'hui (exemple)
codigo	écrire et modifier du code	Gemini "pro" le plus récent, effort élevé
revisao	révision de diff, chasse aux bugs	Gemini "pro" le plus récent, effort élevé
pesquisa	lire beaucoup de matériel et résumer	Gemini "pro" le plus récent, effort moyen
imagem	générer ou éditer une image	Gemini "pro" le plus récent, effort moyen
rapido	tâche simple, volume, brouillon	Gemini "flash" le plus récent

agy-modelo lit agy models (avec cache de 1 h), sépare la famille rapide (flash/lite) de la principale, prend la version la plus récente et l'effort préféré du rôle. Quand un nouveau Gemini sort, il est utilisé sans rien changer. Pour forcer : AGY_MODELO_CODIGO=<id> (par rôle) ou AGY_MODELO=<id> (tous). Utilisez --atualizar si un modèle vient d'être lancé.

Pour une révision, préférez un modèle de famille différente de celui qui a écrit le code. L'intérêt de la seconde opinion est d'avoir un autre « cerveau ». Le rôle revisao choisit déjà Gemini ; ne le remplacez pas par Claude dans agy juste pour réviser le code de Claude lui-même.

Comment demander une tâche

1. Écrivez le prompt dans un fichier en suivant references/prompt-modelo.md. Il doit être autonome : l'agy n'a pas vu cette conversation. Chemins absolus, quoi lire avant, quoi faire, quoi ne pas toucher, où sauvegarder et comment prouver que c'est correct.
2. Exécutez en arrière-plan (Bash avec run_in_background: true), car les tâches prennent de quelques secondes à des dizaines de minutes :

<skill>/scripts/agy-tarefa --dir /abs/projet --papel codigo \
  --nome "écran de connexion" --prompt-arquivo /abs/prompt.md --timeout 2400

• --dir est obligatoire et peut être répété. L'agy voit et édite uniquement les dossiers passés ici. Sans cela, il enregistre dans un brouillon personnel et répond « fait » sans avoir rien changé au projet. Incluez également le dossier des fichiers de support (image de référence, audio).
• --modo plan laisse l'agy uniquement lire (analyse, recherche, révision). Par défaut, accept-edits permet d'éditer des fichiers.
• Le script ajoute des règles fixes au prompt : ne pas commiter, ne pas utiliser sudo, ne pas sortir des dossiers, répondre court. Utilisez --sem-regras seulement si vous avez une raison.
• Pour continuer une même conversation (ex. : demander un ajustement), utilisez --continuar <id>, avec l'id présent dans meta.json. L'agy se souvient de ce qui a été dit.
• Une longue demande n'est pas un problème : au-delà d'environ 100 Ko, le script transmet la demande à agy par fichier (la ligne de commande Linux refuse un argument de plus de 128 Ko).
• La sortie montre au maximum 150 lignes de la réponse (--max-linhas N change cela) ; le texte complet se trouve dans resposta.md, dans le dossier indiqué par PASTA=. Ne le lisez que si nécessaire : ainsi le résultat d'agy n'encombre pas votre contexte.
• Si Claude s'exécute en tant que root dans un dossier d'un autre utilisateur, le script redonne au propriétaire du dossier ce qu'agy a créé via le terminal (mkdir, npm install, git...), qui naît en tant que root. Sans cela, git et l'éditeur de l'utilisateur cassent ensuite. L'outil d'écriture d'agy respecte déjà le propriétaire. --manter-donos désactive cela.

Sortie de agy-tarefa	Signification
0	L'agy a terminé. Une validation est encore nécessaire (section suivante)
1	Erreur de l'agy ou réponse vide (RESPOSTA-VAZIA) : traiter comme un échec
2	Mauvaise utilisation du script (le message dit ce qui manque)
3	L'agy a fait un commit, malgré les règles : voir git log et avertir l'utilisateur
124	Temps écoulé. Ce qu'il a déjà édité reste sur le disque : vérifier alteracoes.txt

3. Pendant qu'il s'exécute, continuez à travailler sur autre chose. Vous êtes averti lorsque le processus se termine.

Valider ce que l'agy a livré (obligatoire)

Le rapport de l'agy est une allégation, pas une preuve. agy-tarefa montre déjà ce qui a vraiment changé (comparaison de git status avant et après) et alerte si l'agy a fait un commit (code de sortie 3). Ensuite :

1. Comparez le rapport avec alteracoes.txt. S'il dit avoir créé un fichier qui n'apparaît pas, ou avoir touché à quelque chose en dehors de la demande, c'est un problème.
2. Lisez le diff (git diff, git diff --stat), pas seulement la réponse.
3. Exécutez les vérifications du projet : build, tests, lint, node --check, python -m py_compile, ou ce qui existe. Pour l'interface, regardez l'écran réel (capture d'écran/navigateur). L'agy a tendance à se tromper sur les thèmes, les couleurs et les détails d'intégration entre fichiers.
4. Décidez : accepter, corriger vous-même (si c'est petit) ou renvoyer avec --continuar et la liste exacte de ce qui est faux.

Ne dites à l'utilisateur que c'est prêt qu'après cela.

Validation croisée (seconde opinion)

Après un changement pertinent, écrit par Claude ou par l'agy, demandez une révision indépendante :

<skill>/scripts/agy-revisar --dir /abs/repo                       # tout depuis HEAD, avec les nouveaux fichiers
<skill>/scripts/agy-revisar --dir /abs/repo --base main           # tout depuis main
<skill>/scripts/agy-revisar --dir /abs/repo --intervalo HEAD~3..HEAD --foco "concurrence dans le worker"

L'agy révise en mode lecture seule et renvoie un verdict (approuve, ajuster, rejeter) et des résultats avec gravité, confiance, fichier:ligne, preuve et suggestion (format dans assets/schema-revisao.json). Le diff est délimité et accompagné d'un avertissement indiquant que le texte à l'intérieur du code est une donnée, pas une instruction, pour qu'un commentaire malveillant ne « force » pas l'approbation. Avec --exigir-aprovado, le script se termine avec le code 4 lorsque le verdict n'est pas « approuvé » (utile en automatisation).

N'appliquez pas les résultats les yeux fermés. Pour chacun : ouvrez le code, confirmez que le scénario de défaillance se produit vraiment et corrigez alors seulement. Écartez les faux positifs et dites à l'utilisateur combien de résultats étaient réels. Un résultat de confiance faible est un indice, pas un ordre. Si l'agy rejette quelque chose dont vous êtes certain qu'il est correct, expliquez la raison à l'utilisateur plutôt que de modifier pour plaire au relecteur.

Travail en parallèle

Pour diviser un grand travail :

1. Divisez en parties qui ne touchent pas aux mêmes fichiers. Si deux parties ont besoin du même fichier, elles ne sont pas parallèles : faites-les en séquence.
2. Donnez à chaque partie son propre dossier : un git worktree par partie est le plus sûr (git worktree add ../projet-partie-a -b partie-a), ou des sous-dossiers disjoints.
3. Exécutez un agy-tarefa par partie, tous avec run_in_background: true, chacun avec --dir uniquement pour son dossier.
4. Validez chaque partie (section ci-dessus) avant de les assembler. Assemblez une par une, en exécutant les tests à chaque assemblage.
5. Plus de 3 à 4 agents en même temps épuise généralement le quota ou la limite de requêtes de l'agy. Préférez peu de parties bien définies.

Une bonne division est que Claude s'occupe de la partie qui nécessite le contexte de la conversation (architecture, intégration, décisions de l'utilisateur) et que l'agy s'occupe des parties isolées.

Image, audio et vidéo

• Placez le fichier d'entrée dans un dossier passé via --dir et citez le chemin absolu dans le prompt.
• Pour une image, précisez la taille, le format et le chemin exact de sortie, et montrez le résultat à l'utilisateur avant de l'utiliser dans le projet. S'il existe une identité visuelle (couleurs, polices), transmettez les valeurs, car agy ne devine pas.
• Pour une transcription, demandez le format (texte brut, avec horodatage, par locuteur) et la langue. Utilisez --modo plan s'il n'y a rien à éditer.

Problèmes courants

Lisez references/problemas.md quand quelque chose ne va pas : « fait » sans changement, temps écoulé, quota, modèle non reconnu, connexion, réponse hors format.

Comment faire un rapport à l'utilisateur

Court et vérifiable : ce qui a été délégué, avec quel modèle (meta.json), ce qui a changé (fichiers), ce que vous avez vérifié (tests, diff, écran) et ce que vous avez corrigé de ce qu'agy a fait. Si la validation croisée a trouvé quelque chose, dites combien de résultats étaient réels et ce qui a été fait avec. Les enregistrements complets se trouvent dans ~/.cache/agy-skill/execucoes/ (supprimés après 30 jours ; AGY_SKILL_RETENCAO_DIAS change cela), et agy-historico résume la dépense de tokens.