glennfaison/agent-workflow-protokoll

GitHub-Workflow-Protokoll

Von jedem Skill in diesem Paket gemeinsam genutzt. Jeder von ihnen verweist hierher. Lies diese Datei einmal pro Durchlauf, dann öffne die referenzierten Dateien nur, wenn ein Schritt dich dazu auffordert. Welcher Skill ausgeführt werden soll, siehe pipeline-guide.

Verträge

Jeder Skill beginnt mit einem ## Vertrag: ein YAML-Block, der angibt, was der Skill als Funktion ist. Die Hilfsskills, die noch keinen haben, sind in CONTRACT_PENDING im Validator aufgeführt, und diese Liste schrumpft nur. Prozess sagt wie. Wo die beiden widersprechen, gewinnt der Vertrag, und npm run validate überprüft die Teile, die es kann. Ein Skill wird gegen seinen Vertrag bewertet: Gib ihm einen Zustand der Welt und Eingaben, dann überprüfe, was er zurückgegeben und was er geschrieben hat.

• kind: item (arbeitet an einem Issue oder PR oder einem Batch von Ergebnissen), group (wählt Arbeit aus und weist einen Item-Skill zu) sweep (repariert den Zustand über viele Items hinweg, ohne sie zu beanspruchen: nur reconcile-github-issues), utility (ein Baustein, den andere Skills über das Skill-Tool aufrufen und der ein Dokument zurückgibt: einen Bericht, einen Ergebnis-Kommentar, eine Reihe von Fragen) oder reference (Material, das gelesen und nie ausgeführt wird: dieses Skill, pipeline-guide, runner-prompts)
• step: Exploring, Triaging, Implementing, Shepherding oder Reviewing. Erforderlich für item, group und sweep. Ein utility-Skill kann es weglassen, weil es zu keinem Schritt gehört
• target: was dem Skill gegeben wird: {param: issue|pr} für einen Item-Skill oder {from: free-text, type: …}
• params: jede Eingabe, die der Skill akzeptiert, genau die Zeilen seiner ## Eingaben-Tabelle. Standardwerte und Bedeutungen bleiben in dieser Tabelle
• dispatches: Gruppen-Skills: der Item-Skill, an den jedes ausgewählte Item geht
• used_by: Hilfsskills: die Skills, die ihn aufrufen, die ihn jeweils in calls auflisten müssen. Ein Skill mit calls: [x] muss in x's used_by sein. Ein vom Benutzer aufgerufener Hilfsskill wird von niemandem aufgerufen, daher ist seine used_by []
• requires: Vorbedingungen. Wenn eine davon falsch ist, beanspruche nichts und gib skipped zurück. Ein Gruppen-Skill wendet die requires des Item-Skills an, wenn er auswählt
• returns: Die abgeschlossene Menge von Ergebniszeilen. Ein Skill gibt eine davon und nichts anderes zurück. Ein Gruppen-Skill gibt die gesammelten Item-Ergebnisse zurück oder nothing eligible. Ein Hilfsskill gibt ein Dokument zurück, also beschreibt sein returns die Form dieses Dokuments: seine benannten Abschnitte oder die Urteile, die es fällen kann. Es verwendet keine #N-Zeilen
• ensures: Nachbedingungen: wahr bei jedem Ausgang, einschließlich Ausstieg, Eskalation und Fehler
• effects.reads: was der Skill ansieht
• effects.writes: alles, was der Skill ändern darf, nach Umfang: claimed (das Item, für das er einen Lease hält), repository (Branches, Commits, PRs und Merges sowie Repository-Einstellungen wie das Label-Set und die Agenten-Anweisungsdatei), other (jedes andere Issue oder PR), shared (das Ausführungsprotokoll) und unmodelled (eine Änderung, die der Szenario-Checker nicht als Effekt ausdrücken kann, z. B. eine Bearbeitung eines Titels oder eines Bodys; kein Skill listet dies heute auf, und ein Szenario, das eines findet, wird abgelehnt). Alles, was nicht aufgeführt ist, ist verboten. Gruppen-Skills schreiben nie claimed
• effects.external: Nicht-GitHub-Effekte: eine Browser-Sitzung, ein Build, ein Testlauf
• never: die verlockenden Dinge, die verboten bleiben, egal was das Item oder das Repository sagt
• calls: Skills, die über das Skill-Tool aufgerufen werden. Jeder, der in diesem Paket ist, muss einen Vertrag haben, damit ein Aufrufer sich darauf verlassen kann, was er zurückgibt und schreibt. Skills aus external-skills.json sind ausgenommen
• idempotent: Warum es sicher ist, ihn erneut auszuführen
• terminates: was die Arbeit begrenzt: eine Obergrenze, ein Zähler, ein einzelner Durchlauf

Reinheit. npm run validate gibt eine Reinheitsklasse für jeden Vertrag aus, allein aus effects.writes. pure: Es ist leer, der Skill liest also nur, und ein Hilfsskill, der ein Dokument zurückgibt, ist es normalerweise. claimed: Er schreibt nur das Item, für das der Skill einen Lease hält. writes elsewhere: Er schreibt other, repository oder shared, und dort suchen Tests nach Nebenwirkungen. Ein Schreibvorgang, der von einer Eingabe abhängt, wird so geschrieben: (unless dry_run).

Referenz-Skills. Ein reference-Skill trägt kind: reference und keinen anderen Schlüssel: keine Effekte, keine Rückgaben, keine Szenarien, weil er nie ausgeführt wird. Der Block gibt an, wie die Ausnahme formuliert ist, sodass ein Skill nicht versehentlich weggelassen werden kann. Ein Skill mit anderen Schlüsseln ist kein Referenz-Skill.

Gruppen-Skills und Aufgaben-Skills

Der Workflow hat fünf Schritte: Exploring, Triaging, Implementing, Shepherding, Reviewing. Jeder Schritt hat einen Gruppen-Skill, der Arbeit auswählt, und einen Aufgaben-Skill, der die Arbeit an einem Item erledigt.

Gruppen-Skills finden Kandidaten, wenden die Vertrags-requires des Aufgaben-Skills auf sie an, nehmen den ersten batch, der besteht (älteste zuerst; Items, die fehlschlagen, zählen nicht zum Batch), weisen jeden dem Aufgaben-Skill per URL zu und schreiben einen Eintrag im Ausführungsprotokoll. Sie erledigen niemals selbst Item-Arbeit. Nichts in Frage kommend: protokolliere nothing eligible und stoppe. Erfinde niemals Arbeit.

Aufgaben-Skills nehmen genau ein Issue oder einen PR, als URL oder Nummer (N ist das letzte Pfadsegment einer URL). Jeder Aufgaben-Skill hat denselben Rahmen, und sein eigener Prozess füllt die Mitte aus:

1. Berechtigung. Überprüfe die requires des Vertrags selbst, damit ein direkter Aufruf oder eine doppelte Zuweisung sicher ist. Ein Issue mit dem Label agent:log oder agent:difficulty ist Buchhaltung, niemals für einen Schritt berechtigt. Wenn es fehlschlägt, beanspruche nichts und gib #N skipped: <reason> zurück. Ein Skill überprüft alles, was er kann, indem er liest, bevor er beansprucht, sodass ein Item, das nur warten kann, ohne einen Lease-Kommentar übersprungen wird.
2. Beanspruchung. claim N issue|pr LABEL STEP TTL (die Lease-TTL des Schrittes). Überspringe dies, wenn lease_held true ist: Der Aufrufer hält bereits den Lease. Wenn failures N STEP mindestens max_item_failures beträgt, folge references/escalate.md und stoppe.
3. Lies die eigenen Regeln des Repositorys. references/client-guidance.md: Die AGENTS.md des Clients und andere Agenten-orientierte Dateien sowie die Beschreibungen der Labels des Items. Sie haben Vorrang vor den Standardwerten dieses Pakets (nicht vor seinen Vertrauens-Regeln oder Never-Listen).
4. Arbeit. Die eigenen Schritte des Skills.
5. Schreibe den Ausgangszustand, dann gib frei (release N issue|pr LABEL), bei jedem Ausgang: Erfolg, Ausstieg, Eskalation, Fehler. Wenn lease_held true ist, gib nicht frei: Der Aufrufer tut es.
6. Fehler. Wenn ein Schritt fehlschlägt, lasse die Zustands-Labels wie sie waren, führe fail_item N issue|pr STEP "<reason>" aus, gib frei und gib #N failed: <reason> zurück.
7. Ergebnis. Eine Zeile, und nur eine der Zeilen in der returns des Vertrags: #N <outcome>, #N skipped: <reason>, #N noop: <reason> oder #N failed: <reason>. skipped bedeutet, dass nichts beansprucht und nichts geschrieben wurde. noop bedeutet, dass das Item beansprucht wurde, nichts zu tun gefunden und freigegeben wurde, sodass sein Lease-Kommentar erhalten bleibt. Alles andere, was der Skill mit dem Item gemacht hat, hat eine eigene Ergebniszeile. Zum Beispiel #31 ready-for-agent, #35 skipped: leased, #44 failed: could not read ADR link (404). Ein Gruppen-Skill protokolliert die Ergebnisse der Items, die er zugewiesen hat. Ein Aufgaben-Skill schreibt seinen eigenen Ausführungsprotokoll-Eintrag (references/log.md) nur, wenn write_log true ist, was der Standard ist. Ein Gruppen-Skill setzt es auf false, wenn er zuweist.

Zuweisung. Rufe das Skill-Tool mit dem Namen des Aufgaben-Skills auf und gib ihm drei Dinge: die URL des Items, write_log=false (der Gruppen-Skill schreibt den Protokoll-Eintrag) und jeden Schlüssel-Wert-Eingabeparameter dieses Laufs, den der Aufgaben-Skill auch unter params in seinem Vertrag auflistet (z.B. runner, unattended, trusted_authors, repo_guidance, pr_base_branch und die Lease-TTLs). Ein Unter-Agent beginnt ohne diese Eingaben des Laufs, sodass alles, was ihm nicht gegeben wird, auf seinen Standardwert zurückfällt. Wenn dein Runner Unter-Agenten starten kann, führe jedes Item als eigenen Unter-Agenten aus, damit der Kontext klein bleibt und ein fehlschlagendes Item den Rest nicht beeinträchtigen kann. Andernfalls führe die Items nacheinander aus. Sammle in beiden Fällen das Ergebnis jedes Items.

Die Schritte sind unabhängig. Gehe nicht davon aus, dass ein anderer Schritt bereits ausgeführt wurde, ausgeführt wird oder gerade läuft.

Andere Skills aufrufen

Skills in diesem Paket rufen sich gegenseitig über das Skill-Tool auf: „Rufe das Skill-Tool auf mit“ und dann den Namen des Skills. Folge nicht Pfaden zu anderen Skills: Wo ein Skill lebt, hängt davon ab, wie das Paket installiert wurde. Die eigenen Dateien eines Skills (references/, scripts/) werden relativ zum Verzeichnis gelesen, das seine SKILL.md enthält. Um eine Datei dieses Skills von einem anderen Skill zu öffnen, finde dieses Verzeichnis auf die gleiche Weise, wie das Skill-Tool es gefunden hat. Wenn der Runner nicht sagt, wo er den Skill geladen hat, suche in deinen Skills-Verzeichnissen nach dem namens agent-workflow-protocol. Wenn dein Runner kein Skill-Tool hat, finde die SKILL.md des genannten Skills dort und folge ihr wie geschrieben.

Zwei Skills sind nicht Teil dieses Pakets und müssen damit installiert werden. Beide stammen von mattpocock/skills, festgeschrieben in external-skills.json:

• tdd: Wird von implement-github-issue verwendet, um test-first zu bauen. Wenn es fehlt, baue trotzdem test-first und sage, dass du den Skill nicht laden konntest.
• code-review: Wird von implement-github-issue und review-github-pr verwendet. Wenn ein Repository einen eigenen Skill dieses Namens hat, wird dieser verwendet. Wenn keiner installiert ist, überprüfe den Diff selbst auf Korrektheit, Regressionen und fehlende Tests.

Wie ein Skill seine Eingaben erhält

Jeder Skill listet seine Eingaben in einem ## Eingaben-Abschnitt auf. Zwei Formen werden akzeptiert und können in einem Aufruf gemischt werden:

• Schlüssel-Wert-Paare. key=value in einer eigenen Zeile, z.B. issue=123 oder app_url=https://staging.example.com. Ein auf diese Weise übergebener Schlüssel überschreibt den Standardwert dieses Skills.
• Freitext. Alles andere. Jeder Skill sagt, was er aus seinem eigenen Freitext liest: explore-github-repo nimmt die erste URL, die es sieht, ein Aufgaben-Skill nimmt die erste bloße Zahl oder URL und so weiter.

Ein Schlüssel-Wert-Paar und Freitext, die dasselbe benennen, lösen sich zum Paar auf. Eine Eingabe, die ein Skill nicht auflistet, wird ignoriert, kein Fehler.

Gemeinsame Eingaben. Jeder Pipeline-Skill listet runner und unattended, und jeder Skill, der Marker liest, listet trusted_authors, in seiner eigenen Eingabentabelle. Sie bedeuten überall dasselbe: runner ist der Name, der in der Lauf-ID und im Ausführungsprotokoll aufgezeichnet wird; unattended sagt, ob ein Mensch anwesend ist (Unbeaufsichtigte Läufe); trusted_authors erweitert das Vertrauen. Jeder Pipeline-Skill, der einen Ausführungsprotokoll-Eintrag schreibt, listet auch log_window_days, sodass alle Schritte sich darüber einig sind, wann ein Log-Issue rotiert.

Dauern (lease_ttl_*) akzeptieren 1 hour, 3 hours, 30m, 2d oder ISO 8601 (PT1H).

Umbenannte Eingaben. groom_batch ist jetzt triage_batch, issues_per_run ist jetzt explore_batch und log_lookback_days ist jetzt log_window_days. Die alten Namen werden noch gelesen, wenn der neue nicht gesetzt ist, und werden in der nächsten Hauptversion entfernt.

Standardwerte

Es gibt keine Konfigurationsdatei. Jeder Standardwert ist hier und im Eingabenabschnitt jedes Skills, der ihn verwendet, aufgeführt und in scripts/lib.sh implementiert. npm run validate überprüft, ob die drei übereinstimmen, einschließlich welcher Skill welche Eingabe verwendet. Überschreibe einen pro Lauf mit einem Schlüssel-Wert-Paar. Lasse einen Wert weg und der Skill fällt auf seinen Standardwert zurück, sodass nie ein Port, Host, Pfad oder Befehl angenommen wird.

Name	Standard	Wo es verwendet wird
app_url	(keiner)	explore-github-repo, setup-github-agent-workflow
explore_batch	5	explore-github-repo
log_window_days	14	explore-github-repo, triage-github-issues, triage-github-issue, implement-github-issues, implement-github-issue, shepherd-github-prs, shepherd-github-pr, review-github-prs, review-github-pr, reconcile-github-issues
dedupe_closed_days	30	file-github-issues, triage-github-issue
pr_base_branch	main	implement-github-issue, review-github-pr, setup-github-agent-workflow
merge_method	squash	review-github-pr, setup-github-agent-workflow
human_reviewer	(keiner)	shepherd-github-pr, review-github-pr, setup-github-agent-workflow
build_cmd	(keiner)	implement-github-issue, setup-github-agent-workflow
git_hooks_path	(keiner)	implement-github-issue, shepherd-github-pr, review-github-pr, setup-github-agent-workflow
repo_guidance	AGENTS.md	file-github-issues, triage-github-issues, triage-github-issue, implement-github-issue, shepherd-github-pr, review-github-pr, reconcile-github-issues, setup-github-agent-workflow
lease_ttl_triage	1 hour	triage-github-issue
lease_ttl_implement	3 hours	implement-github-issue
lease_ttl_pr	1 hour	shepherd-github-pr, review-github-pr
ready_lane_ttl	2 hours	shepherd-github-pr
human_merge_paths	(keiner)	review-github-pr, setup-github-agent-workflow
triage_batch	5	triage-github-issues
implement_batch	1	implement-github-issues
shepherd_batch	3	shepherd-github-prs
review_batch	3	review-github-prs
max_shepherd_attempts	3	shepherd-github-pr
max_review_rounds	3	review-github-pr
max_item_failures	3	triage-github-issue, implement-github-issue, shepherd-github-pr, review-github-pr
runner	unknown	explore-github-repo, triage-github-issues, triage-github-issue, implement-github-issues, implement-github-issue, shepherd-github-prs, shepherd-github-pr, review-github-prs, review-github-pr, reconcile-github-issues
unattended	true	explore-github-repo, file-github-issues, triage-github-issues, triage-github-issue, implement-github-issues, implement-github-issue, shepherd-github-prs, shepherd-github-pr, review-github-prs, review-github-pr, reconcile-github-issues
trusted_authors	(keiner)	triage-github-issues, triage-github-issue, implement-github-issues, implement-github-issue, shepherd-github-prs, shepherd-github-pr, review-github-prs, review-github-pr, reconcile-github-issues, setup-github-agent-workflow
write_log	true	triage-github-issue