glennfaison/agent-workflow-protocol

Protocolo de flujo de trabajo de GitHub

Compartido por cada habilidad en este paquete. Cada una de ellas apunta aquí. Lee este archivo una vez por ejecución, luego abre los archivos de referencia que nombra solo cuando un paso te lo indique. Para saber qué habilidad ejecutar, consulta pipeline-guide.

Contratos

Cada habilidad comienza con un ## Contract: un bloque YAML que define qué es la habilidad como función. Las habilidades de utilidad que aún no tienen uno se enumeran en CONTRACT_PENDING en el validador, y esa lista solo se reduce. Process dice cómo. Cuando ambos discrepan, el contrato gana, y npm run validate verifica las partes que puede. Una habilidad se evalúa contra su contrato: dale un estado del mundo y entradas, luego verifica qué devolvió y qué escribió.

• kind: item (trabaja en un issue o PR, o en un lote de hallazgos), group (selecciona trabajo y despacha una habilidad de ítem), sweep (repara el estado en muchos elementos sin reclamarlos: solo reconcile-github-issues), utility (un bloque de construcción que otras habilidades llaman a través de la herramienta Skill y que devuelve un documento: un informe, un comentario de resultado, una ronda de preguntas) o reference (material que se lee y nunca se ejecuta: esta habilidad, pipeline-guide, runner-prompts)
• step: Explorando, Triando, Implementando, Acompañando o Revisando. Obligatorio para item, group y sweep. Una habilidad utility puede omitirlo, porque no pertenece a ningún paso
• target: qué se le da a la habilidad: {param: issue|pr} para una habilidad de ítem, o {from: free-text, type: …}
• params: cada entrada que acepta la habilidad, exactamente las filas de su tabla ## Inputs. Los valores predeterminados y significados permanecen en esa tabla
• dispatches: habilidades de grupo: la habilidad de ítem a la que va cada elemento seleccionado
• used_by: habilidades de utilidad: las habilidades que la llaman, que deben enumerarla en calls. Una habilidad que tiene calls: [x] debe estar en el used_by de x. Una habilidad de utilidad invocada por el usuario no es llamada por nadie, por lo que su used_by es []
• requires: condiciones previas. Si una es falsa, no reclames nada y devuelve skipped. Una habilidad de grupo aplica el requires de la habilidad de ítem al seleccionar
• returns: El conjunto cerrado de líneas de resultado. Una habilidad devuelve una de estas y nada más. Una habilidad de grupo devuelve los resultados de los ítems que recopiló, o nothing eligible. Una habilidad de utilidad devuelve un documento, por lo que su returns describe la forma de ese documento: sus secciones nombradas, o los veredictos que puede dar. No usa líneas #N
• ensures: postcondiciones: verdaderas en cada salida, incluyendo salida condicional, escalamiento y fallo
• effects.reads: lo que la habilidad examina
• effects.writes: todo lo que la habilidad puede cambiar, por ámbito: claimed (el elemento sobre el que tiene una concesión), repository (ramas, commits, PRs y fusiones, y ajustes del repositorio como el conjunto de etiquetas y el archivo de instrucciones del agente), other (cualquier otro issue o PR), shared (el registro de ejecución) y unmodelled (un cambio que el verificador de escenarios no puede expresar como un efecto, como una edición a un título o un cuerpo; ninguna habilidad lo enumera hoy, y un escenario que encuentre uno es rechazado). Cualquier cosa no listada está prohibida. Las habilidades de grupo nunca escriben claimed
• effects.external: efectos no relacionados con GitHub: una sesión de navegador, una compilación, una ejecución de pruebas
• never: las cosas tentadoras que permanecen prohibidas diga lo que diga el elemento o el repositorio
• calls: habilidades llamadas a través de la herramienta Skill. Cada una que esté en este paquete debe tener un contrato, para que un llamador pueda confiar en lo que devuelve y escribe. Las habilidades de external-skills.json están exentas
• idempotent: Por qué es seguro ejecutarlo de nuevo
• terminates: qué limita el trabajo: un límite, un contador, una sola pasada

Pureza. npm run validate imprime una clase de pureza para cada contrato, solo a partir de effects.writes. pure: está vacío, por lo que la habilidad solo lee, y una habilidad de utilidad que devuelve un documento suele serlo. claimed: escribe solo el elemento sobre el que la habilidad tiene una concesión. writes elsewhere: escribe other, repository o shared, y ahí es donde las pruebas buscan efectos secundarios. Una escritura que es condicional a una entrada se escribe de esa manera: (unless dry_run).

Habilidades de referencia. Una habilidad reference lleva kind: reference y ninguna otra clave: sin efectos, sin retornos, sin escenarios, porque nunca se ejecuta. El bloque es cómo se declara la exención, por lo que una habilidad no puede quedar fuera por accidente. Una habilidad que tiene otras claves no es una habilidad de referencia.

Habilidades de grupo y habilidades de ítem

El flujo de trabajo tiene cinco pasos: Explorando, Triando, Implementando, Acompañando, Revisando. Cada paso tiene una habilidad de grupo que selecciona el trabajo y una habilidad de ítem que realiza el trabajo en un elemento.

Las habilidades de grupo encuentran candidatos, les aplican el requires del contrato de la habilidad de ítem, toman el primer batch que pase (los más antiguos primero; los elementos que fallan no cuentan para el lote), despachan cada uno a la habilidad de ítem mediante su URL, y escriben una entrada en el registro de ejecución. Nunca hacen trabajo de ítem ellos mismos. Nada elegible: registra nothing eligible y detente. Nunca inventes trabajo.

Las habilidades de ítem toman exactamente un issue o PR, como URL o número (N es el último segmento de ruta de una URL). Cada habilidad de ítem tiene el mismo marco, y su propio Process llena el medio:

1. Elegibilidad. Verifica el requires del contrato tú mismo, para que una llamada directa o un doble despacho sea seguro. Un issue etiquetado con agent:log o agent:difficulty es administrativo, nunca elegible para ningún paso. Si falla, no reclames nada y devuelve #N skipped: <reason>. Una habilidad verifica todo lo que puede leyendo antes de reclamar, por lo que un elemento que solo puede esperar se omite sin un comentario de concesión.
2. Reclamación. claim N issue|pr LABEL STEP TTL (el TTL de concesión del paso). Salta esto cuando lease_held sea true: el llamador ya posee la concesión. Si failures N STEP es al menos max_item_failures, sigue references/escalate.md y detente.
3. Lee las reglas propias del repositorio. references/client-guidance.md: los archivos AGENTS.md del cliente y otros archivos orientados al agente, y las descripciones de las etiquetas del elemento. Tienen prioridad sobre los valores predeterminados de este paquete (no sus reglas de Confianza o listas de Nunca).
4. Trabajo. Los propios pasos de la habilidad.
5. Escribe el estado de salida, luego libera (release N issue|pr LABEL), en cada salida: éxito, salida condicional, escalamiento, fallo. Cuando lease_held sea true no liberes: el llamador lo hace.
6. Fallo. Si un paso falla, deja las etiquetas de estado como estaban, ejecuta fail_item N issue|pr STEP "<reason>", libera y devuelve #N failed: <reason>.
7. Resultado. Una línea, y solo una de las líneas en los returns del contrato: #N <outcome>, #N skipped: <reason>, #N noop: <reason> o #N failed: <reason>. skipped significa que no se reclamó nada y no se escribió nada. noop significa que el elemento fue reclamado, no se encontró nada que hacer y fue liberado, por lo que su comentario de concesión permanece. Cualquier otra cosa que la habilidad haya hecho al elemento tiene una línea de resultado propia. Por ejemplo #31 ready-for-agent, #35 skipped: leased, #44 failed: could not read ADR link (404). Una habilidad de grupo registra los resultados de los elementos que despachó. Una habilidad de ítem escribe su propia entrada en el registro de ejecución (references/log.md) solo cuando write_log es true, que es el valor predeterminado. Una habilidad de grupo lo establece en false cuando despacha.

Despacho. Llama a la herramienta Skill con el nombre de la habilidad de ítem y dale tres cosas: la URL del elemento, write_log=false (el grupo escribe la entrada de registro), y cada par clave-valor de entrada de esta ejecución que la habilidad de ítem también enumere bajo params en su contrato (por ejemplo runner, unattended, trusted_authors, repo_guidance, pr_base_branch y los TTL de concesión). Un subagente comienza sin ninguna de las entradas de esta ejecución, por lo que cualquier cosa que no se le dé vuelve a su valor predeterminado. Si tu corredor puede iniciar subagentes, ejecuta cada elemento como su propio subagente, para que el contexto se mantenga pequeño y un elemento fallido no pueda afectar al resto. De lo contrario, ejecuta los elementos uno tras otro. De cualquier manera, recoge el resultado de cada elemento.

Los pasos son independientes. No asumas que otro paso se ha ejecutado, se ejecutará o se está ejecutando.

Llamar a otras habilidades

Las habilidades en este paquete se llaman entre sí a través de la herramienta Skill: "Llama a la herramienta Skill con" y luego el nombre de la habilidad. No sigas rutas a otras habilidades: dónde vive una habilidad depende de cómo se instaló el paquete. Los archivos propios de una habilidad (references/, scripts/) se leen en relación con el directorio que contiene su SKILL.md. Para abrir un archivo de esta habilidad desde otra habilidad, encuentra este directorio de la misma manera que la herramienta Skill lo encontró. Si el corredor no dice dónde cargó la habilidad, busca en tus directorios de habilidades el llamado agent-workflow-protocol. Si tu corredor no tiene una herramienta Skill, encuentra el SKILL.md de la habilidad nombrada allí y síguelo como está escrito.

Dos habilidades no forman parte de este paquete y deben instalarse con él. Ambas provienen de mattpocock/skills, fijadas en external-skills.json:

• tdd: utilizado por implement-github-issue para construir con pruebas primero. Si falta, construye con pruebas primero de todos modos y di que no pudiste cargar la habilidad.
• code-review: utilizado por implement-github-issue y review-github-pr. Si un repositorio tiene su propia habilidad con ese nombre, se usa esa. Si no hay ninguna instalada, revisa el diff tú mismo en busca de corrección, regresiones y pruebas faltantes.

Cómo una habilidad toma su entrada

Cada habilidad enumera sus entradas en una sección ## Inputs. Se aceptan dos formas y pueden mezclarse en una sola invocación:

• Pares clave-valor. clave=valor en una línea propia, por ejemplo issue=123 o app_url=https://staging.example.com. Una clave dada de esta manera anula el valor predeterminado de esa habilidad.
• Texto libre. Cualquier otra cosa. Cada habilidad dice qué lee de su propio texto libre: explore-github-repo toma la primera URL que ve, una habilidad de ítem toma el primer número desnudo o URL, y así sucesivamente.

Un par clave-valor y un texto libre que nombran lo mismo se resuelven al par. Una entrada que una habilidad no enumera se ignora, no es un error.

Entradas comunes. Cada habilidad de pipeline enumera runner y unattended, y cada habilidad que lee marcadores enumera trusted_authors, en su propia tabla de Entradas. Significan lo mismo en todas partes: runner es el nombre registrado en el id de ejecución y el registro de ejecución; unattended dice si hay un humano presente (Ejecuciones desatendidas); trusted_authors extiende la Confianza. Cada habilidad de pipeline que escribe una entrada en el registro de ejecución también enumera log_window_days, para que todos los pasos estén de acuerdo en cuándo rota un issue de registro.

Duraciones (lease_ttl_*) toman 1 hour, 3 hours, 30m, 2d o ISO 8601 (PT1H).

Entradas renombradas. groom_batch ahora es triage_batch, issues_per_run ahora es explore_batch y log_lookback_days ahora es log_window_days. Los nombres antiguos todavía se leen cuando el nuevo no está establecido, y se eliminarán en la próxima versión principal.

Valores predeterminados

No hay archivo de configuración. Cada valor predeterminado se indica aquí y en la sección de Entradas de cada habilidad que lo usa, y se implementa en scripts/lib.sh. npm run validate verifica que los tres coincidan, incluyendo qué habilidades usan qué entrada. Anula uno por ejecución con un par clave-valor. Deja un valor fuera y la habilidad vuelve a su valor predeterminado, por lo que nunca se asume un puerto, host, ruta o comando.

Nombre	Valor predeterminado	Dónde se usa
app_url	(ninguno)	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	(ninguno)	shepherd-github-pr, review-github-pr, setup-github-agent-workflow
build_cmd	(ninguno)	implement-github-issue, setup-github-agent-workflow
git_hooks_path	(ninguno)	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	(ninguno)	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	(ninguno)	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, implement-github-issue, shepherd-github-pr, review-github-pr

Guía del repositorio cliente (references/client-guidance.md)

El archivo references/client-guidance.md contiene las reglas que un repositorio puede establecer para anular los valores predeterminados de este paquete. Se lee en el paso 3 de cada habilidad de ítem.

No anula la confianza ni las listas de nunca. Los marcadores de confianza y las listas prohibidas están codificados en los contratos y no pueden ser anulados por ningún repositorio. Esto es por seguridad: un repositorio comprometido no puede autoconcederse privilegios de escritura o excluirse de la revisión.

Consulta references/client-guidance.md para más detalles.

Confianza (references/trust.md)

La confianza se establece a través de trusted_authors, una lista separada por comas de autores o equipos que pueden enviar issues y PRs sin pasar por pasos de seguridad adicionales. Por defecto, está vacía (sin confianza). Los autores confiados se marcan en los issues y PRs con la etiqueta agent:trusted.

Consulta references/trust.md para más detalles.

Etiquetas

El paquete define un conjunto de etiquetas de estado que se aplican a los issues y PRs para rastrear su progreso a través del flujo de trabajo:

• agent:triaging - El issue está siendo triado
• agent:implementing - El issue está siendo implementado
• agent:shepherding - El PR está siendo acompañado
• agent:reviewing - El PR está siendo revisado
• agent:log - Issue de registro de ejecución, nunca elegible
• agent:difficulty - Issue de dificultad, nunca elegible
• agent:trusted - El autor es confiado
• agent:blocked - El elemento está bloqueado esperando una respuesta humana
• agent:failed - El elemento falló después de reintentos
• agent:skipped - El elemento fue omitido
• agent:noop - El elemento fue reclamado pero no se encontró trabajo

Las etiquetas se aplican y eliminan automáticamente por las habilidades de ítem. No las modifiques manualmente a menos que sepas lo que estás haciendo.

Concesiones (Leases)

Las concesiones evitan que múltiples ejecuciones del flujo de trabajo trabajen en el mismo elemento simultáneamente. Se implementan mediante comentarios en el issue o PR con un formato específico:

agent:lease <step> <ttl> <runner>

TTL (Time To Live) define cuánto tiempo es válida la concesión. Después de ese tiempo, otra ejecución puede reclamar el elemento. Los TTL predeterminados están en la tabla de valores predeterminados.

Las concesiones se liberan al finalizar el paso. Si una habilidad falla antes de liberar, la concesión expira después del TTL.

Marcadores (Markers)

Los marcadores son comentarios en issues o PRs que registran el estado y las decisiones de la habilidad. Se utilizan para:

• Registrar el resultado de un paso (agent:result <outcome>)
• Indicar que un elemento está esperando (agent:waiting)
• Señalar que se requiere intervención humana (agent:needs-human)

Los marcadores se leen y escriben automáticamente. No los modifiques a menos que sepas lo que estás haciendo.

Traspasos (Handoffs)

Un traspaso ocurre cuando una habilidad de ítem finaliza y pasa el elemento al siguiente paso. Por ejemplo, después de que implement-github-issue completa, el PR resultante se pasa a shepherd-github-pr.

El traspaso se realiza mediante la etiqueta de estado. La habilidad de ítem saliente deja el elemento con una etiqueta como agent:shepherding, que la siguiente habilidad de grupo detecta.

No se requiere acción manual para los traspasos.

Escalamiento (Escalation)

Si un elemento falla repetidamente, se escala a un humano. El umbral está definido por max_item_failures (predeterminado 3). Las fallas se rastrean por paso y elemento.

Cuando se alcanza el umbral:

1. Se ejecuta references/escalate.md para notificar al humano
2. El elemento se marca con la etiqueta agent:escalated
3. El elemento no se procesa más hasta que un humano lo revisa

Las fallas se cuentan por combinación de paso y elemento. Una falla en el triaje no cuenta para el límite de implementación.

Registro de ejecución (Run Log)

Cada ejecución del flujo de trabajo escribe una entrada en un issue de registro de ejecución (agent:log). El registro contiene:

• ID de ejecución
• Hora de inicio y fin
• Habilidad que se ejecutó
• Elementos procesados y sus resultados
• Errores o advertencias

El registro de ejecución rota según log_window_days (predeterminado 14 días). Los issues de registro más antiguos se cierran automáticamente.

Consulta references/log.md para el formato detallado.

Ejecución desatendida (Unattended Runs)

Cuando unattended es true, la habilidad asume que no hay un humano presente. Esto afecta:

• Sin preguntas. La habilidad no debe hacer preguntas al usuario; debe tomar decisiones basadas en reglas.
• Escalamiento limitado. Si un escalamiento requiere respuesta humana, la habilidad debe detenerse y esperar.
• Confirmaciones automáticas. Las confirmaciones de fusión y otros pasos que requieren aprobación humana se realizan automáticamente dentro de las reglas de confianza.

Cuando unattended es false, la habilidad puede pedir confirmación antes de acciones destructivas o inciertas.

Ejecución sin shell (No Shell Runs)

Algunos corredores no proporcionan un shell. Las habilidades en este paquete funcionan sin él, siempre que el corredor proporcione las herramientas necesarias (GitHub API, etc.). No se requieren scripts de shell para las operaciones básicas.

Las habilidades que necesitan un shell (por ejemplo, implement-github-issue para compilar y probar) lo requieren. Si el corredor no proporciona un shell, esas habilidades fallan con un mensaje claro.

Referencias

• pipeline-guide - Guía general del pipeline
• runner-prompts - Indicaciones para el corredor
• client-guidance.md - Guía del repositorio cliente
• trust.md - Reglas de confianza
• escalate.md - Procedimiento de escalamiento
• log.md - Formato del registro de ejecución

Todos los archivos de referencia están en el directorio references/ de esta habilidad.