glennfaison/agent-workflow-protocol

Protocolo de fluxo de trabalho GitHub

Compartilhado por todas as habilidades neste pacote. Cada uma delas aponta para este arquivo. Leia este arquivo uma vez por execução, depois abra os arquivos de referência que ele nomeia apenas quando uma etapa mandar. Para saber qual habilidade executar, veja pipeline-guide.

Contratos

Toda habilidade começa com um ## Contract: um bloco YAML que define o que a habilidade é como função. As habilidades utilitárias que ainda não têm um estão listadas em CONTRACT_PENDING no validador, e essa lista só diminui. Process diz como. Onde os dois discordam, o contrato vence, e npm run validate verifica as partes que pode. Uma habilidade é avaliada em relação ao seu contrato: dê a ela um estado do mundo e entradas, depois verifique o que ela retornou e o que escreveu.

• kind: item (trabalha em uma issue ou PR, ou em um lote de descobertas), group (seleciona trabalho e despacha uma habilidade item), sweep (repara estado em muitos itens sem reivindicá-los: apenas reconcile-github-issues), utility (um bloco de construção que outras habilidades chamam através da ferramenta Skill e que retorna um documento: um relatório, um comentário de resultado, uma rodada de perguntas) ou reference (material que é lido e nunca executado: esta habilidade, pipeline-guide, runner-prompts)
• step: Explorando, Triando, Implementando, Pastoreando ou Revisando. Obrigatório para item, group e sweep. Uma habilidade utility pode deixá-lo de fora, porque não pertence a nenhuma etapa
• target: o que é dado à habilidade: {param: issue|pr} para uma habilidade item, ou {from: free-text, type: …}
• params: toda entrada que a habilidade aceita, exatamente as linhas de sua tabela ## Inputs. Padrões e significados permanecem nessa tabela
• dispatches: habilidades de grupo: a habilidade item para a qual cada item selecionado vai
• used_by: habilidades utilitárias: as habilidades que a chamam, que devem listá-la em calls. Uma habilidade que tem calls: [x] deve estar em used_by de x. Uma habilidade utilitária invocada pelo usuário não é chamada por ninguém, então seu used_by é []
• requires: pré-condições. Se uma for falsa, não reivindique nada e retorne skipped. Uma habilidade de grupo aplica o requires da habilidade item ao selecionar
• returns: O conjunto fechado de linhas de resultado. Uma habilidade retorna uma delas e nada mais. Uma habilidade de grupo retorna os resultados dos itens que coletou, ou nothing eligible. Uma habilidade utilitária retorna um documento, então seu returns descreve a forma desse documento: suas seções nomeadas, ou os veredictos que pode dar. Ela não usa linhas #N
• ensures: pós-condições: verdadeiras em cada saída, incluindo desistência, escalonamento e falha
• effects.reads: o que a habilidade examina
• effects.writes: tudo que a habilidade pode alterar, por escopo: claimed (o item sobre o qual detém um lease), repository (branches, commits, PRs e merges, e configurações do repositório como o conjunto de rótulos e o arquivo de instruções do agente), other (qualquer outra issue ou PR), shared (o registro de execução) e unmodelled (uma alteração que o verificador de cenários não pode expressar como um efeito, como uma edição em um título ou corpo; nenhuma habilidade lista isso hoje, e um cenário que encontrar um é rejeitado). Qualquer coisa não listada é proibida. Habilidades de grupo nunca escrevem claimed
• effects.external: efeitos não-GitHub: uma sessão de navegador, uma compilação, uma execução de teste
• never: as coisas tentadoras que permanecem proibidas independentemente do que o item ou o repositório diga
• calls: habilidades chamadas através da ferramenta Skill. Cada uma que está neste pacote deve ter um contrato, para que um chamador possa confiar no que ela retorna e escreve. Habilidades de external-skills.json são isentas
• idempotent: Por que executá-la novamente é seguro
• terminates: o que limita o trabalho: um limite, um contador, uma única passagem

Pureza. npm run validate imprime uma classe de pureza para cada contrato, apenas de effects.writes. pure: está vazio, então a habilidade apenas lê, e uma habilidade utilitária que retorna um documento geralmente é. claimed: escreve apenas o item sobre o qual a habilidade detém um lease. writes elsewhere: escreve other, repository ou shared, e é aí que os testes procuram efeitos colaterais. Uma escrita que é condicional a uma entrada é escrita dessa forma: (unless dry_run).

Habilidades de referência. Uma habilidade reference carrega kind: reference e nenhuma outra chave: sem efeitos, sem retornos, sem cenários, porque nunca é executada. O bloco é como a isenção é declarada, então uma habilidade não pode ser deixada de fora por acidente. Uma habilidade que tem outras chaves não é uma habilidade de referência.

Habilidades de grupo e habilidades de item

O fluxo de trabalho tem cinco etapas: Explorando, Triando, Implementando, Pastoreando, Revisando. Cada etapa tem uma habilidade de grupo que seleciona trabalho e uma habilidade de item que realiza o trabalho em um item.

Habilidades de grupo encontram candidatos, aplicam os requires do contrato da habilidade de item a eles, pegam o primeiro batch que passar (mais antigo primeiro; itens que falham não contam para o lote), despacham cada um para a habilidade de item por sua URL, e escrevem uma entrada no registro de execução. Elas nunca fazem trabalho de item elas mesmas. Nothing eligible: registre nothing eligible e pare. Nunca invente trabalho.

Habilidades de item recebem exatamente uma issue ou PR, como uma URL ou um número (N é o último segmento de caminho de uma URL). Toda habilidade de item tem o mesmo quadro, e seu próprio Process preenche o meio:

1. Elegibilidade. Verifique os requires do contrato você mesmo, para que uma chamada direta ou um despacho duplo seja seguro. Uma issue rotulada agent:log ou agent:difficulty é contabilidade, nunca elegível para nenhuma etapa. Se falhar, não reivindique nada e retorne #N skipped: <reason>. Uma habilidade verifica tudo que pode lendo antes de reivindicar, para que um item que só pode esperar seja pulado sem um comentário de lease.
2. Reivindicação. claim N issue|pr LABEL STEP TTL (o TTL do lease da etapa). Pule isso quando lease_held for true: o chamador já detém o lease. Se failures N STEP for pelo menos max_item_failures, siga references/escalate.md e pare.
3. Leia as regras do próprio repositório. references/client-guidance.md: o AGENTS.md do cliente e outros arquivos voltados para agentes, e as descrições dos rótulos do item. Eles superam os padrões deste pacote (não suas regras de Confiança ou listas Nunca).
4. Trabalho. As próprias etapas da habilidade.
5. Escreva o estado de saída, depois libere (release N issue|pr LABEL), em cada saída: sucesso, desistência, escalonamento, falha. Quando lease_held for true não libere: o chamador faz isso.
6. Falha. Se uma etapa falhar, deixe os rótulos de estado como estavam, execute fail_item N issue|pr STEP "<reason>", libere e retorne #N failed: <reason>.
7. Resultado. Uma linha, e apenas uma das linhas nos returns do contrato: #N <outcome>, #N skipped: <reason>, #N noop: <reason> ou #N failed: <reason>. skipped significa que nada foi reivindicado e nada foi escrito. noop significa que o item foi reivindicado, não encontrou nada para fazer e foi liberado, então seu comentário de lease permanece. Qualquer outra coisa que a habilidade fez ao item tem uma linha de resultado própria. Por exemplo #31 ready-for-agent, #35 skipped: leased, #44 failed: could not read ADR link (404). Uma habilidade de grupo registra os resultados dos itens que despachou. Uma habilidade de item escreve sua própria entrada de registro de execução (references/log.md) apenas quando write_log for true, que é o padrão. Uma habilidade de grupo define como false quando despacha.

Despacho. Chame a ferramenta Skill com o nome da habilidade de item e dê a ela três coisas: a URL do item, write_log=false (o grupo escreve a entrada de log), e cada entrada chave-valor desta execução que a habilidade de item também lista sob params em seu contrato (por exemplo runner, unattended, trusted_authors, repo_guidance, pr_base_branch e os TTLs de lease). Um subagente começa sem nenhuma das entradas desta execução, então qualquer coisa que não lhe for dada volta ao seu padrão. Se seu runner puder iniciar subagentes, execute cada item como seu próprio subagente, para que o contexto permaneça pequeno e um item com falha não afete o resto. Caso contrário, execute os itens um após o outro. De qualquer forma, colete o resultado de cada item.

As etapas são independentes. Não assuma que outra etapa foi executada, será executada ou está sendo executada.

Chamando outras habilidades

Habilidades neste pacote chamam umas às outras através da ferramenta Skill: "Chame a ferramenta Skill com" e então o nome da habilidade. Não siga caminhos para outras habilidades: onde uma habilidade reside depende de como o pacote foi instalado. Os arquivos de uma habilidade (references/, scripts/) são lidos relativos ao diretório que contém seu SKILL.md. Para abrir um arquivo desta habilidade a partir de outra habilidade, encontre este diretório da mesma forma que a ferramenta Skill o encontrou. Se o runner não disser de onde carregou a habilidade, procure em seus diretórios de habilidades aquele chamado agent-workflow-protocol. Se seu runner não tiver ferramenta Skill, encontre o SKILL.md da habilidade nomeada lá e siga-o como escrito.

Duas habilidades não fazem parte deste pacote e devem ser instaladas com ele. Ambas vêm de mattpocock/skills, fixadas em external-skills.json:

• tdd: usado por implement-github-issue para construir test-first. Se estiver faltando, construa test-first de qualquer forma e diga que não conseguiu carregar a habilidade.
• code-review: usado por implement-github-issue e review-github-pr. Se um repositório tiver sua própria habilidade com esse nome, essa será usada. Se nenhuma estiver instalada, revise o diff você mesmo quanto a correção, regressões e testes faltantes.

Como uma habilidade recebe sua entrada

Toda habilidade lista suas entradas em uma seção ## Inputs. Duas formas são aceitas e podem ser misturadas em uma única invocação:

• Pares chave-valor. key=value em uma linha própria, por exemplo issue=123 ou app_url=https://staging.example.com. Uma chave dada desta forma substitui o padrão dessa habilidade.
• Texto livre. Qualquer outra coisa. Cada habilidade diz o que lê de seu próprio texto livre: explore-github-repo pega a primeira URL que vê, uma habilidade de item pega o primeiro número ou URL simples, e assim por diante.

Um par chave-valor e texto livre que nomeiam a mesma coisa resolvem para o par. Uma entrada que uma habilidade não lista é ignorada, não um erro.

Entradas comuns. Toda habilidade de pipeline lista runner e unattended, e toda habilidade que lê marcadores lista trusted_authors, em sua própria tabela de Entradas. Eles significam o mesmo em todos os lugares: runner é o nome registrado no id de execução e no registro de execução; unattended diz se um humano está presente (Execuções desassistidas); trusted_authors estende Confiança. Toda habilidade de pipeline que escreve uma entrada de registro de execução também lista log_window_days, para que todas as etapas concordem sobre quando uma issue de log gira.

Durações (lease_ttl_*) aceitam 1 hour, 3 hours, 30m, 2d ou ISO 8601 (PT1H).

Entradas renomeadas. groom_batch agora é triage_batch, issues_per_run agora é explore_batch e log_lookback_days agora é log_window_days. Os nomes antigos ainda são lidos quando o novo não está definido e serão removidos na próxima versão principal.

Padrões

Não há arquivo de configuração. Todo padrão é declarado aqui e na seção de Entradas de cada habilidade que o usa, e implementado em scripts/lib.sh. npm run validate verifica se os três concordam, incluindo quais habilidades usam qual entrada. Substitua um por execução com um par chave-valor. Deixe um valor de fora e a habilidade volta ao seu padrão, então nenhuma porta, host, caminho ou comando é jamais assumido.

Nome	Padrão	Onde é usado
app_url	(none)	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	(none)	shepherd-github-pr, review-github-pr, setup-github-agent-workflow
build_cmd	(none)	implement-github-issue, setup-github-agent-workflow
git_hooks_path	(none)	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	(none)	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	(none)	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