glennfaison/agent-workflow-protocol

Protocole du workflow GitHub

Partagé par chaque compétence de ce package. Chacune pointe ici. Lisez ce fichier une fois par exécution, puis ouvrez les fichiers de référence qu'il nomme uniquement lorsqu'une étape vous le demande. Pour savoir quelle compétence exécuter, consultez pipeline-guide.

Contrats

Chaque compétence commence par un ## Contrat : un bloc YAML qui décrit ce qu'est la compétence en tant que fonction. Les compétences utilitaires qui n'en n'ont pas encore sont listées dans CONTRACT_PENDING du validateur, et cette liste ne fait que diminuer. Process dit comment. Là où les deux divergent, le contrat l'emporte, et npm run validate vérifie les parties qu'il peut. Une compétence est évaluée par rapport à son contrat : donnez-lui un état du monde et des entrées, puis vérifiez ce qu'elle a retourné et ce qu'elle a écrit.

• kind : item (travaille sur un issue ou une PR, ou sur un lot de résultats), group (sélectionne le travail et dispatche une compétence élément), sweep (répare l'état sur plusieurs éléments sans les réclamer : seulement reconcile-github-issues), utility (un bloc de construction que d'autres compétences appellent via l'outil Skill et qui retourne un document : un rapport, un commentaire de résultat, un tour de questions) ou reference (documentation qui est lue et jamais exécutée : cette compétence, pipeline-guide, runner-prompts)
• step : Exploration, Tri, Implémentation, Shepherd ou Révision. Requis pour item, group et sweep. Une compétence utilitaire peut l'omettre, car elle n'appartient à aucune étape
• target : ce qui est donné à la compétence : {param: issue|pr} pour une compétence élément, ou {from: free-text, type: …}
• params : chaque entrée que la compétence accepte, exactement les lignes de son tableau ## Inputs. Les valeurs par défaut et les significations restent dans ce tableau
• dispatches : compétences de groupe : la compétence élément vers laquelle chaque élément sélectionné est envoyé
• used_by : compétences utilitaires : les compétences qui l'appellent, qui doivent chacune la lister dans calls. Une compétence qui a calls: [x] doit être dans used_by de x. Une compétence utilitaire invoquée par l'utilisateur n'est appelée par personne, donc son used_by est []
• requires : préconditions. Si l'une est fausse, ne réclamez rien et retournez skipped. Une compétence de groupe applique les requires de la compétence élément lors de la sélection
• returns : l'ensemble fermé des lignes de résultat. Une compétence retourne l'une d'elles et rien d'autre. Une compétence de groupe retourne les résultats des éléments qu'elle a collectés, ou nothing eligible. Une compétence utilitaire retourne un document, donc son returns décrit la forme de ce document : ses sections nommées, ou les verdicts qu'elle peut donner. Elle n'utilise pas les lignes #N
• ensures : postconditions : vraies sur toutes les sorties, y compris l'abandon, l'escalade et l'échec
• effects.reads : ce que la compétence examine
• effects.writes : tout ce que la compétence peut modifier, par portée : claimed (l'élément dont elle détient un bail), repository (branches, commits, PRs et merges, et paramètres du dépôt comme l'ensemble d'étiquettes et le fichier d'instructions agent), other (tout autre issue ou PR), shared (le journal d'exécution) et unmodelled (un changement que le vérificateur de scénario ne peut pas exprimer comme un effet, comme une modification d'un titre ou d'un corps ; aucune compétence ne le liste aujourd'hui, et un scénario qui en trouve un est rejeté). Tout ce qui n'est pas listé est interdit. Les compétences de groupe n'écrivent jamais claimed
• effects.external : effets non GitHub : une session navigateur, une construction, un test
• never : les choses tentantes qui restent interdites quoi que dise l'élément ou le dépôt
• calls : compétences appelées via l'outil Skill. Chacune qui est dans ce package doit avoir un contrat, afin qu'un appelant puisse se fier à ce qu'elle retourne et écrit. Les compétences de external-skills.json sont exemptées
• idempotent : pourquoi l'exécuter à nouveau est sûr
• terminates : ce qui borne le travail : un plafond, un compteur, un seul passage

Pureté. npm run validate imprime une classe de pureté pour chaque contrat, uniquement à partir de effects.writes. pure : il est vide, donc la compétence ne fait que lire, et une compétence utilitaire qui retourne un document l'est généralement. claimed : elle n'écrit que l'élément dont la compétence détient un bail. writes elsewhere : elle écrit other, repository ou shared, et c'est là que les tests recherchent les effets secondaires. Une écriture conditionnelle à une entrée est écrite de cette façon : (unless dry_run).

Compétences de référence. Une compétence reference porte kind: reference et aucune autre clé : pas d'effets, pas de retours, pas de scénarios, parce qu'elle n'est jamais exécutée. Le bloc est la manière dont l'exemption est déclarée, donc une compétence ne peut pas être omise par accident. Une compétence qui a d'autres clés n'est pas une compétence de référence.

Compétences de groupe et compétences élément

Le workflow comporte cinq étapes : Exploration, Tri, Implémentation, Shepherd, Révision. Chaque étape a une compétence de groupe qui sélectionne le travail et une compétence élément qui effectue le travail sur un élément.

Compétences de groupe trouvent les candidats, leur appliquent les requires du contrat de la compétence élément, prennent le premier batch qui réussit (les plus anciens d'abord ; les éléments qui échouent ne comptent pas dans le lot), dispatchent chacun vers la compétence élément par son URL, et écrivent une entrée dans le journal d'exécution. Elles n'effectuent jamais le travail des éléments elles-mêmes. Rien d'éligible : enregistrez nothing eligible et arrêtez. N'inventez jamais de travail.

Compétences élément prennent exactement un issue ou une PR, sous forme d'URL ou de nombre (N est le dernier segment de chemin d'une URL). Chaque compétence élément a le même cadre, et son propre Process remplit le milieu :

1. Éligibilité. Vérifiez vous-même les requires du contrat, afin qu'un appel direct ou un double dispatch soit sûr. Un issue étiqueté agent:log ou agent:difficulty est de la comptabilité, jamais éligible pour aucune étape. S'il échoue, ne réclamez rien et retournez #N skipped: <reason>. Une compétence vérifie tout ce qu'elle peut en lisant avant de réclamer, donc un élément qui ne peut qu'attendre est ignoré sans commentaire de bail.
2. Réclamation. claim N issue|pr LABEL STEP TTL (le TTL du bail de l'étape). Ignorez cette étape lorsque lease_held est true : l'appelant détient déjà le bail. Si failures N STEP est au moins max_item_failures, suivez references/escalate.md et arrêtez.
3. Lire les propres règles du dépôt. references/client-guidance.md : le AGENTS.md du client et autres fichiers destinés aux agents, ainsi que les descriptions des étiquettes de l'élément. Ils priment sur les valeurs par défaut de ce package (pas ses règles de Confiance ou ses listes Jamais).
4. Travail. Les propres étapes de la compétence.
5. Écrire l'état de sortie, puis libérer (release N issue|pr LABEL), sur toutes les sorties : succès, abandon, escalade, échec. Lorsque lease_held est true, ne libérez pas : l'appelant le fait.
6. Échec. Si une étape échoue, laissez les étiquettes d'état telles qu'elles étaient, exécutez fail_item N issue|pr STEP "<reason>", libérez, et retournez #N failed: <reason>.
7. Résultat. Une ligne, et seulement l'une des lignes dans les returns du contrat : #N <outcome>, #N skipped: <reason>, #N noop: <reason> ou #N failed: <reason>. skipped signifie que rien n'a été réclamé et rien n'a été écrit. noop signifie que l'élément a été réclamé, rien n'a été trouvé à faire et a été libéré, donc son commentaire de bail reste. Tout le reste que la compétence a fait à l'élément a sa propre ligne de résultat. Par exemple #31 ready-for-agent, #35 skipped: leased, #44 failed: could not read ADR link (404). Une compétence de groupe enregistre les résultats des éléments qu'elle a dispatchés. Une compétence élément écrit sa propre entrée dans le journal d'exécution (references/log.md) uniquement lorsque write_log est true, ce qui est la valeur par défaut. Une compétence de groupe le met à false lorsqu'elle dispatche.

Dispatch. Appelez l'outil Skill avec le nom de la compétence élément et donnez-lui trois choses : l'URL de l'élément, write_log=false (le groupe écrit l'entrée du journal), et chaque entrée clé-valeur de cette exécution que la compétence élément liste également sous params dans son contrat (par exemple runner, unattended, trusted_authors, repo_guidance, pr_base_branch et les TTL des baux). Un sous-agent commence sans aucune de ces entrées de l'exécution, donc tout ce qui ne lui est pas donné revient à sa valeur par défaut. Si votre exécuteur peut démarrer des sous-agents, exécutez chaque élément comme son propre sous-agent, afin que le contexte reste petit et qu'un élément en échec n'affecte pas les autres. Sinon, exécutez les éléments les uns après les autres. Dans les deux cas, collectez le résultat de chaque élément.

Les étapes sont indépendantes. Ne supposez pas qu'une autre étape a été exécutée, sera exécutée ou est en cours d'exécution.

Appeler d'autres compétences

Les compétences de ce package s'appellent mutuellement via l'outil Skill : "Appelez l'outil Skill avec" puis le nom de la compétence. Ne suivez pas les chemins vers d'autres compétences : l'endroit où vit une compétence dépend de la façon dont le package a été installé. Les propres fichiers d'une compétence (references/, scripts/) sont lus relativement au répertoire qui contient son SKILL.md. Pour ouvrir un fichier de cette compétence depuis une autre compétence, trouvez ce répertoire de la même manière que l'outil Skill l'a trouvé. Si l'exécuteur ne dit pas d'où il a chargé la compétence, cherchez dans vos répertoires de compétences celui nommé agent-workflow-protocol. Si votre exécuteur n'a pas d'outil Skill, trouvez le SKILL.md de la compétence nommée là et suivez-le tel qu'il est écrit.

Deux compétences ne font pas partie de ce package et doivent être installées avec lui. Les deux viennent de mattpocock/skills, épinglées dans external-skills.json :

• tdd : utilisée par implement-github-issue pour construire d'abord les tests. Si elle est manquante, construisez d'abord les tests quand même et dites que vous n'avez pas pu charger la compétence.
• code-review : utilisée par implement-github-issue et review-github-pr. Si un dépôt a sa propre compétence de ce nom, celle-ci est utilisée. Si aucune n'est installée, révisez le diff vous-même pour l'exactitude, les régressions et les tests manquants.

Comment une compétence prend ses entrées

Chaque compétence liste ses entrées dans une section ## Inputs. Deux formes sont acceptées et peuvent être mélangées dans une invocation :

• Paires clé-valeur. key=value sur sa propre ligne, par exemple issue=123 ou app_url=https://staging.example.com. Une clé donnée de cette façon remplace la valeur par défaut de cette compétence.
• Texte libre. Tout le reste. Chaque compétence dit ce qu'elle lit dans son propre texte libre : explore-github-repo prend la première URL qu'elle voit, une compétence élément prend le premier nombre nu ou URL, et ainsi de suite.

Une paire clé-valeur et un texte libre qui nomment la même chose se résolvent en la paire. Une entrée qu'une compétence ne liste pas est ignorée, pas une erreur.

Entrées communes. Chaque compétence du pipeline liste runner et unattended, et chaque compétence qui lit des marqueurs liste trusted_authors, dans son propre tableau Inputs. Elles signifient la même chose partout : runner est le nom enregistré dans l'identifiant d'exécution et le journal d'exécution ; unattended indique si un humain est présent (Exécutions non supervisées) ; trusted_authors étend la Confiance. Chaque compétence du pipeline qui écrit une entrée de journal d'exécution liste également log_window_days, afin que toutes les étapes s'accordent sur quand un problème de journal tourne.

Durées (lease_ttl_*) acceptent 1 hour, 3 hours, 30m, 2d ou ISO 8601 (PT1H).

Entrées renommées. groom_batch est maintenant triage_batch, issues_per_run est maintenant explore_batch et log_lookback_days est maintenant log_window_days. Les anciens noms sont toujours lus lorsque le nouveau n'est pas défini, et seront supprimés dans la prochaine version majeure.

Valeurs par défaut

Il n'y a pas de fichier de configuration. Chaque valeur par défaut est énoncée ici et dans la section Inputs de chaque compétence qui l'utilise, et implémentée dans scripts/lib.sh. npm run validate vérifie que les trois sont d'accord, y compris quelles compétences utilisent quelle entrée. Remplacez-en une par exécution avec une paire clé-valeur. Laissez une valeur de côté et la compétence revient à sa valeur par défaut, donc aucun port, hôte, chemin ou commande n'est jamais supposé.

Nom	Valeur par défaut	Où elle est utilisée
app_url	(aucun)	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	(aucun)	shepherd-github-pr, review-github-pr, setup-github-agent-workflow
build_cmd	(aucun)	implement-github-issue, setup-github-agent-workflow
git_hooks_path	(aucun)	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	(aucun)	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	(aucun)	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-issues, implement-github-issues, shepherd-github-prs, review-github-prs, reconcile-github-issues, explore-github-repo
triage_batch alias groom_batch	idem	idem
explore_batch alias issues_per_run	idem	idem
log_window_days alias log_lookback_days	idem	idem