Davicjc/agy

agy: Claude + Gemini arbeiten zusammen

die agy ist ein Terminal-Agent ähnlich Claude Code, der Gemini-Modelle (und andere) ausführt. Er ist stark dort, wo Claude schwächer oder teurer ist: Bild, Audio und Video nativ und Massenarbeit. Klug eingesetzt wird er zu einem zweiten Paar Hände und einem unabhängigen Prüfer. Unkritisch eingesetzt sagt er „erledigt“, ohne es erledigt zu haben.

Die goldene Regel dieser Skill: Claude bleibt für das Ergebnis verantwortlich. agy führt aus; Claude spezifiziert, prüft und entscheidet.

Die Skripte befinden sich in scripts/ neben dieser Datei. In den folgenden Befehlen ist <skill> der Ordner, der als „Base directory for this skill“ angezeigt wird, wenn die Skill geladen wird; verwende immer den absoluten Pfad.

Skript	Wofür
scripts/agy-modelo ROLLE	Gibt das richtige Modell für die Rolle zurück, gelesen aus agy models in Echtzeit
scripts/agy-tarefa ...	Führt eine Aufgabe aus, speichert alles und zeigt, was sich wirklich im Git geändert hat
scripts/agy-revisar ...	Review eines Diffs im Nur-Lese-Modus mit strukturierten Ergebnissen
scripts/agy-historico [N]	Letzte Ausführungen: Status, Modell, Zeit und Tokens (zur Rechenschaft über die Ausgaben)

Der Benutzer kann auch direkt aufrufen: /agy:delegar, /agy:revisar, /agy:modelos und /agy:historico.

Bevor es losgeht: Ist agy bereit?

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

Wenn agy nicht existiert oder der Befehl fehlschlägt, anhalten und den Benutzer informieren (er muss agy installieren oder sich anmelden). Keine Workarounds versuchen. Nach der ersten Sitzungsprüfung verwendet agy-modelo ohne --atualizar die für 1 h zwischengespeicherte Liste.

Wann delegieren (und wann nicht)

Delegiere, wenn agy besser ist oder wenn Parallelisieren wirklich Zeit spart:

• Bild: Erstellen oder Bearbeiten von Fotos, Hintergründen, Bannern, Mockups, Symbolen, Text- oder Logoaustausch in Bildern.
• Audio und Video: Transkribieren von Audio (auch WhatsApp), Zusammenfassen oder Analysieren einer .mp4-Datei direkt.
• Unabhängige Teile einer großen Arbeit: Module, Bildschirme, Tests, Dokumentation, jeweils mit eigenen Dateien.
• Mechanisches Volumen: API in 40 Dateien umbenennen, wiederkehrendes Muster migrieren, Beispieldaten generieren.
• Zweite Meinung: Code überprüfen, den Claude gerade geschrieben hat (siehe „Kreuzvalidierung“).

Nicht delegieren, wenn:

• die Aufgabe vom Kontext dieses Gesprächs abhängt, der schwer schriftlich zu übermitteln ist (Entscheidungen, Benutzerpräferenzen, Hin und Her): diesen Kontext zu schreiben kostet oft mehr, als es selbst zu machen;
• es eine kleine, offensichtliche Bearbeitung ist (delegieren und prüfen ist teurer);
• es Geheimnisse, Passwörter, Tokens, personenbezogene Daten Dritter oder irreversible Aktionen betrifft (löschen, veröffentlichen, Nachrichten senden, git push): das bleibt bei Claude und dem Benutzer.

Modellauswahl (dynamisch)

Schreibe niemals einen festen Modellnamen in den Prompt oder Befehl. Verwende die Rolle:

Rolle	Verwendung	Wählt heute (Beispiel)
codigo	Code schreiben und ändern	Neuestes Gemini „Pro“, hoher Aufwand
revisao	Diff-Review, Bugsuche	Neuestes Gemini „Pro“, hoher Aufwand
pesquisa	Viel Material lesen und zusammenfassen	Neuestes Gemini „Pro“, mittlerer Aufwand
imagem	Bild erstellen oder bearbeiten	Neuestes Gemini „Pro“, mittlerer Aufwand
rapido	Einfache Aufgabe, Volumen, Entwurf	Neuestes Gemini „Flash“

agy-modelo liest agy models (mit 1 h Cache), trennt die schnelle Familie (flash/lite) von der Hauptfamilie, nimmt die neueste Version und den bevorzugten Aufwand der Rolle. Wenn ein neues Gemini erscheint, wird es ohne Änderungen verwendet. Zum Erzwingen: AGY_MODELO_CODIGO=<id> (pro Rolle) oder AGY_MODELO=<id> (alle). Verwende --atualizar, wenn ein Modell gerade veröffentlicht wurde.

Für Reviews bevorzuge ein Modell einer anderen Familie als das, das den Code geschrieben hat. Der Reiz der zweiten Meinung liegt in einem anderen „Gehirn“. Die Rolle revisao wählt bereits Gemini; tausche nicht innerhalb von agy gegen Claude, nur um Claude-Code zu reviewen.

Wie man eine Aufgabe anfordert

1. Schreibe den Prompt in eine Datei nach references/prompt-modelo.md. Er muss in sich geschlossen sein: agy hat dieses Gespräch nicht gesehen. Absolute Pfade, was vorher gelesen werden soll, was zu tun ist, was nicht angefasst werden darf, wo zu speichern ist und wie zu beweisen ist, dass es korrekt ist.
2. Führe es im Hintergrund aus (Bash mit run_in_background: true), da Aufgaben Sekunden bis Dutzende Minuten dauern können:

<skill>/scripts/agy-tarefa --dir /abs/projekt --papel codigo \
  --nome "Anmeldebildschirm" --prompt-arquivo /abs/prompt.md --timeout 2400

• --dir ist erforderlich und kann wiederholt werden. agy sieht und bearbeitet nur die hier übergebenen Ordner. Ohne dies speichert er in einem eigenen Entwurf und antwortet „erledigt“, ohne etwas im Projekt geändert zu haben. Füge auch den Ordner mit den Unterstützungsdateien hinzu (Referenzbild, Audio).
• --modo plan lässt agy nur lesen (Analyse, Recherche, Review). Der Standard accept-edits erlaubt das Bearbeiten von Dateien.
• Das Skript fügt dem Prompt feste Regeln hinzu: nicht committen, kein sudo verwenden, die Ordner nicht verlassen, kurz antworten. Verwende --sem-regras nur, wenn du einen Grund hast.
• Um dasselbe Gespräch fortzusetzen (z. B. eine Anpassung anfordern), verwende --continuar <id>, mit der ID aus meta.json. agy erinnert sich an das zuvor Gesagte.
• Lange Anfragen sind kein Problem: Ab etwa 100 KB übergibt das Skript die Anfrage über eine Datei an agy (die Linux-Kommandozeile lehnt ein Argument über 128 KB ab).
• Die Ausgabe zeigt maximal 150 Zeilen der Antwort (--max-linhas N ändert das); der vollständige Text befindet sich in resposta.md, im Ordner, der in PASTA= angegeben ist. Lies nur dort bei Bedarf, damit das Ergebnis von agy deinen Kontext nicht aufbläht.
• Wenn Claude als root in einem Ordner eines anderen Benutzers läuft, gibt das Skript dem Ordnerbesitzer das zurück, was agy über das Terminal erstellt hat (mkdir, npm install, git...), das als root entsteht. Ohne dies werden später git und der Editor des Benutzers beschädigt. Das eigene Schreibwerkzeug von agy respektiert bereits den Besitzer. --manter-donos deaktiviert dies.

Ausgabe von agy-tarefa	Bedeutung
0	agy beendet. Erfordert noch Validierung (nächster Abschnitt)
1	Fehler von agy oder leere Antwort (RESPOSTA-VAZIA): als Fehler behandeln
2	Falsche Skriptverwendung (die Meldung sagt, was fehlt)
3	agy hat trotz Regeln einen Commit erstellt: git log ansehen und den Benutzer informieren
124	Zeitüberschreitung. Was er bereits bearbeitet hat, bleibt auf der Festplatte: alteracoes.txt prüfen

3. Während es läuft, arbeite weiter an etwas anderem. Du wirst benachrichtigt, wenn der Prozess beendet ist.

Validieren, was agy geliefert hat (obligatorisch)

Der Bericht von agy ist eine Behauptung, kein Beweis. agy-tarefa zeigt bereits was sich wirklich geändert hat (Vergleich des git status vorher und nachher) und warnt, wenn agy einen Commit erstellt hat (Exit-Code 3). Danach:

1. Vergleiche den Bericht mit alteracoes.txt. Wenn agy sagt, es habe eine Datei erstellt, die nicht erscheint, oder etwas außerhalb der Anfrage geändert hat, ist das ein Problem.
2. Lies den Diff (git diff, git diff --stat), nicht nur die Antwort.
3. Führe die Projektprüfungen aus: Build, Tests, Lint, node --check, python -m py_compile oder was auch immer existiert. Bei Oberflächen sieh dir den tatsächlichen Bildschirm an (Screenshot/Browser). agy macht oft Fehler bei Theme, Farben und Details der Integration zwischen Dateien.
4. Entscheide: Akzeptieren, selbst korrigieren (wenn klein) oder mit --continuar und der genauen Liste der Fehler zurückgeben.

Erst danach dem Benutzer sagen, dass es fertig ist.

Kreuzvalidierung ( zweite Meinung)

Nach einer relevanten Änderung, die von Claude oder agy geschrieben wurde, ein unabhängiges Review anfordern:

<skill>/scripts/agy-revisar --dir /abs/repo                       # alles seit HEAD, mit neuen Dateien
<skill>/scripts/agy-revisar --dir /abs/repo --base main           # alles seit main
<skill>/scripts/agy-revisar --dir /abs/repo --intervalo HEAD~3..HEAD --foco "Nebenläufigkeit im Worker"

agy prüft im Nur-Lese-Modus und gibt ein Urteil zurück (aprovado, ajustar, reprovado) sowie Befunde mit Schweregrad, Konfidenz, Datei:Zeile, Beweis und Vorschlag (Format in assets/schema-revisao.json). Der Diff wird abgegrenzt und mit dem Hinweis versehen, dass Text innerhalb des Codes Daten und keine Anweisung sind, damit ein böswilliger Kommentar den Prüfer nicht zur Zustimmung „zwingen“ kann. Mit --exigir-aprovado beendet sich das Skript mit Code 4, wenn das Urteil nicht „aprovado“ ist (nützlich in der Automatisierung).

Wende die Befunde nicht blind an. Für jeden: Öffne den Code, bestätige, dass das Fehlerszenario tatsächlich eintritt, und korrigiere erst dann. Verwerfe die falsch positiven Ergebnisse und teile dem Benutzer mit, wie viele Befunde echt waren. Ein Befund mit baixa Konfidenz ist ein Hinweis, kein Befehl. Wenn agy etwas ablehnt, von dem du sicher bist, dass es richtig ist, erkläre dem Benutzer den Grund, anstatt es zu ändern, um den Prüfer zufrieden zu stellen.

Parallele Arbeit

Um eine große Arbeit aufzuteilen:

1. Zerlege in Teile, die nicht dieselben Dateien bearbeiten. Wenn zwei Teile dieselbe Datei benötigen, sind sie nicht parallel: in Sequenz ausführen.
2. Gib jedem Teil einen eigenen Ordner: Ein git worktree pro Teil ist am sichersten (git worktree add ../projekt-teil-a -b teil-a), oder disjunkte Unterordner.
3. Führe einen agy-tarefa pro Teil aus, alle mit run_in_background: true, jeder mit --dir nur für seinen Ordner.
4. Validiere jeden Teil (Abschnitt oben), bevor du zusammenführst. Führe einen nach dem anderen zusammen und führe bei jeder Zusammenführung die Tests aus.
5. Mehr als 3–4 Agenten gleichzeitig übersteigen meist das Kontingent oder das Anfragelimit von agy. Bevorzuge wenige, gut definierte Teile.

Eine gute Aufteilung ist, dass Claude den Teil übernimmt, der den Gesprächskontext erfordert (Architektur, Integration, Benutzerentscheidungen), und agy die isolierten Teile übernimmt.

Bild, Audio und Video

• Lege die Eingabedatei in einen Ordner, der an --dir übergeben wird, und nenne den absoluten Pfad im Prompt.
• Gib bei Bildern die Größe, das Format und den genauen Ausgabepfad an und zeige das Ergebnis dem Benutzer, bevor du es im Projekt verwendest. Wenn es ein visuelles Erscheinungsbild gibt (Farben, Schriften), übergib die Werte, da agy nicht rät.
• Gib bei Transkription das Format (Fließtext, mit Zeitstempeln, nach Sprecher) und die Sprache an. Verwende --modo plan, wenn es nichts zu bearbeiten gibt.

Häufige Probleme

Lies references/problemas.md, wenn etwas schiefgeht: „erledigt“ ohne Änderung, Zeitüberschreitung, Kontingent, nicht erkanntes Modell, Anmeldung, Antwort außerhalb des Formats.

Wie dem Benutzer berichten

Kurz und überprüfbar: Was delegiert wurde, mit welchem Modell (meta.json), was sich geändert hat (Dateien), was du überprüft hast (Tests, Diff, Bildschirm) und was du von dem korrigiert hast, was agy gemacht hat. Wenn die Kreuzvalidierung etwas gefunden hat, teile mit, wie viele Befunde echt waren und was damit getan wurde. Die vollständigen Protokolle befinden sich in ~/.cache/agy-skill/execucoes/ (werden nach 30 Tagen gelöscht; AGY_SKILL_RETENCAO_DIAS ändert das), und agy-historico fasst die Tokenausgaben zusammen.