GravionLabs/entregar

Entrega os PBIs e Bugs abertos de uma issue (um item de trabalho = issue aberta com label pbi ou bug; um Bug executa o mesmo loop, tipo de branch fix, Closes #<nr>) um após o outro: um subagente implementa, um subagente revisa, esta sessão abre o PR, aguarda o CI e mescla. Os mesmos passos em qualquer harness (Claude Code, OpenCode, Copilot CLI). O estado vive apenas no GitHub (issues, sub-issues, branches, PRs), portanto uma execução pode parar a qualquer momento e /deliver <nr> continua de onde parou. A trava rígida é o conjunto de regras em release/next: uma verificação obrigatória vermelha ou ausente bloqueia a mesclagem independentemente do que esta sessão fizer.

Entrada

help (ou --help, -h): imprime references/help.md sem alterações, nada mais.

/deliver status --milestone <nome>: imprime o bloco de status (## Bloco de status) e para, nada é entregue.

/deliver <nr> [<nr> …] [--milestone <nome>] [--unattended] [--inline] [--max <n>]: cada número é um PBI, Bug, Feature ou Epic; --milestone <nome> (uma release, M<n> ou um título legado) adiciona os itens de trabalho abertos daquele milestone (uma leitura em lote do milestone (pwsh <skill-dir>/../github-milestone/scripts/Get-Milestones.ps1 -Mode issues -Name <nome> -State open: REST, todas as páginas, sem PRs; a consulta github-milestone resolve M4 para o título M4 ou, após close, M4 (0.2.0); filtra a lista retornada por label: pbi, bug), mais os itens de trabalho abaixo das Features e Epics nele). O milestone.title dessa leitura é o título para gh issue create --milestone; <chave> é seu M<n> ou subnúmero M<n>.<m> (legado: o título) e nomeia o arquivo de estado e as dicas. Ausente: pergunta uma vez. --max <n> para após n PBIs entregues, bloqueados ou pausados e imprime o relatório (scripts/Invoke-DeliverLoop.ps1 usa --max 1 por sessão nova, references/loop.md).

• Interativo (padrão): uma regra de pausa pergunta ao usuário no chat; um PBI bloqueado pergunta: tentar novamente, pular ou uma instrução.
• Sessão de controle: interativo com mais PBIs que deliver.loopThreshold (padrão 3), por exemplo, todo --milestone: não os entregue aqui, inicie Invoke-DeliverLoop.ps1 e permaneça uma sessão leve para decisões, PBIs interactive e passo 9 (references/control.md). --inline entrega todos nesta sessão (passos 1 a 9). --no-preflight pula o Início 3.
• --unattended (claude -p, opencode run, copilot -p): nunca pergunta. Uma pausa comenta na issue, adiciona a label needs-decision e continua com o próximo PBI que não depende dela.

Início

1. gh auth status funciona e o repositório tem release/next.
2. gh api repos/{owner}/{repo}/rules/branches/release/next --jq '.[].type': nenhum required_status_checks na saída → avisar que CI vermelho é mesclável aqui (conjunto de regras de github-release), então prosseguir.
3. Pré-verificação (pulado por --no-preflight): pwsh <skill-dir>/scripts/Test-DeliverPreflight.ps1 -Harness <claude|opencode|copilot> [-Unattended] -Text imprime uma linha por verificação, ok / corrigido / ação necessária: skills empilhadas, lista de permissões (git, gh, pwsh <skill-dir>/scripts/*, os comandos de verificação de AGENTS.md; entradas por harness: references/permissions.md, caso contrário uma execução não acompanhada trava em um prompt), worktrees obsoletos; reações em references/preflight.md. Escreva comandos sem $(…) entre aspas; a verificação de permissão não consegue ver através deles.
4. Eventos de progresso: sem AGENT_EVENTS_RUN execute pwsh <skill-dir>/scripts/Report-Progress.ps1 -Type run.started -Source session e mantenha o id da execução impresso. Adicione -Run <id> a cada chamada posterior (step.finished, attention, issue.finished, run.finished): chamadas Bash não compartilham estado do shell, e AGENT_EVENTS_RUN como prefixo não corresponderia à lista de permissões. Cada linha de progresso, motivo de atenção e o final passam por Report-Progress.ps1; ele os exibe em qualquer terminal em que a sessão esteja sendo executada (references/terminal-backends.md).

Passos

Imprima uma linha por passo no chat: #<nr> <passo>: <resultado> (#12 revisão: 1 bloqueante → corrigir 1/2). Relate cada linha: pwsh <skill-dir>/scripts/Report-Progress.ps1 -Type step.finished -Issue <nr> -Step <passo> -Result "<resultado>" [-Pr <url>]. Também -Type attention (-Kind pr_opened com -Pr <url> após o passo 6, review_fix quando uma revisão ou rodada de CI inicia uma rodada de correção, ci_red quando o passo 7 está vermelho; -Reason): as notificações do loop vêm apenas desses eventos. Uma pausa, um PBI bloqueado ou um ponto que precisa do usuário: -Type attention (-Kind paused, blocked ou needs_you, -Reason) em vez disso. Após cada PBI -Type issue.finished -Issue <nr> -Outcome <resultado>.

Todo PR e issue que o chat nomeia é escrito como sua URL completa (https://github.com/<owner>/<repo>/pull/<n>, .../issues/<n>), não como um #<n> simples: um número simples não é um link no terminal. Isso vale para as linhas de progresso, as perguntas ao usuário e o relatório, em particular para o PR de release (passo 9), que o usuário precisa mesclar. Obtenha a URL de gh (html_url), nunca a construa de memória.

1. Selecionar. gh api repos/{owner}/{repo}/issues/<nr> --jq '{number,title,state,labels:[.labels[].name],body}' para cada número e suas sub-issues (github-issue references/sub-issues.md, recursivamente até PBIs e Bugs). Colete os itens de trabalho abertos (pbi ou bug) de todos os números e do milestone, remova duplicatas, mantenha aqueles sem needs-decision (aquele cujo corpo tem o critério ADR é relatado #<nr> selecionar: decisão, escreva o ADR com adr); ordene-os por seus links blocked-by entre todos eles, empates mantêm a ordem dos argumentos. Com --milestone, um PBI ou Bug alcançado através de uma Feature ou Epic do milestone que não tem ou tem outro milestone não é entregue (#<nr> selecionar: fora de M<n>, pulado, dica: defina o milestone, github-issue references/milestones.md); /deliver <feature> sem --milestone entrega todos os seus PBIs. Um PBI cujo bloqueador ainda está aberto e não está no conjunto espera e é relatado (um bloqueador fora do milestone nunca é entregue). Um PBI ou Bug com needs-refinement, ou um Bug sem repro ou critérios de aceitação, é pulado (#<nr> selecionar: precisa de refinamento, pulado, dica planner refine <nr>); /deliver <nr> em tal item recusa. Não acompanhado, um PBI com interactive é pulado (#<nr> selecionar: interativo, pulado, dica /deliver <nr> em uma sessão); modo interativo o entrega, também através de uma Feature, Epic ou milestone. Um PBI aberto com release-test (o teste RC do milestone) nunca é selecionado como trabalho, não nos passos 1 a 8 e não na sessão de controle, também não com interactive ou como um <nr> explícito: #<nr> selecionar: teste de release, deixado para o passo 9 (com itens abertos antes: teste de release, aguarda <n> itens abertos; aguardando, não precisa de você; references/loop.md). Ele permanece aberto para o passo 9 e o humano (o teste RC é executado no RC). Pule um PBI que outra sessão reivindicou (#<nr> selecionar: reivindicado, pulado), assuma uma reivindicação obsoleta (references/claim.md); /deliver <nr> no próprio PBI o continua independentemente da reivindicação. Anuncie o próximo PBI e o reivindique: gh issue edit <nr> --add-assignee @me; a linha de seleção nomeia seu nível e modelo (#<nr> selecionar: próximo (nível padrão → sonnet/médio); sem uma linha Tier: nível do tamanho M ou padrão; references/roles.md).
   • Uma Feature ou Epic filho sem PBIs: carregue planner (interativo) e grill-me nesta sessão, crie as issues, então selecione novamente. Não acompanhado: comente e marque com label needs-decision em vez disso.
2. Retomar. Branch <tipo>/<nr>-<slug> (github-issue). git ls-remote --heads origin <branch> e gh api "repos/{owner}/{repo}/pulls?head=<owner>:<branch>&state=open" --jq '.[].number' (a cabeça precisa do prefixo do proprietário): uma branch existente é continuada, um PR existente pula para o passo 7.
3. Implementar. Um subagente com um contexto novo: "Carregue implementation, função implement. Implemente o PBI # (um Bug: carregue diagnose primeiro, depois implementation) em seu próprio worktree em <branch> a partir de origin/release/next (uma branch existente: mude para ela e faça rebase). Critérios de aceitação: . Commit, push, relate em no máximo 10 linhas: concluído ou bloqueado, commits, testes executados e notes[] (um por linha); uma entrada specMap correspondente sem uma alteração de especificação dá a nota nenhuma mudança de spec necessária: <spec> — <motivo> (implementation references/specs.md)."
4. Revisar. Um subagente com um contexto novo: "Carregue code-review, função review. Revise git diff origin/release/next...origin/<branch> em relação a estes critérios de aceitação: <critérios>. Com governance: execute Get-GovernanceMatches.ps1 -Head origin/<branch>; labels da issue e notes[] do implementador . Somente leitura: sem stash, checkout, switch ou commit em qualquer checkout existente; se precisar de arquivos, use seu próprio worktree temporário. Retorne apenas JSON: o resultado por review.schema.json de code-review (blocking[] com file, line, title, why; notes[], até 5) mais unmet[] (critérios não atendidos)." Apenas constatações bloqueantes e critérios não atendidos contam. Após cada rodada esta sessão (não o subagente) escreve o arquivo <git-common-dir>/.agents/state/review-<nr>.json (git rev-parse --git-common-dir, o mesmo arquivo de cada worktree, nunca commitado), sobrescrevendo a rodada anterior: { pbi, branch, sha, round, unmet, review }, sha = git rev-parse origin/<branch>, round = rodada de revisão baseada em 1, review = o resultado do subagente; esquema schema/deliver-review.schema.json. Também pwsh <skill-dir>/../code-review/scripts/ConvertTo-Findings.ps1 -Review <resultado com unmet> -Sha <sha> -Worktree <pbi-worktree> escreve <pbi-worktree>/.agents/state/findings.json para poimen (nunca commitado, excluído localmente; references/findings.md).
5. Corrigir. Algo conta: um subagente com um contexto novo carrega implementation com função fix, muda seu próprio worktree para <branch> (git fetch origin <branch>, git switch -C <branch> origin/<branch>), obtém exatamente essas constatações (blocking[] e unmet[]), commita e faz push. Então passo 4 novamente. No máximo 2 rodadas de correção por PBI, compartilhadas por revisão e CI; uma terceira é uma pausa.
6. PR. github-pull-request (seu título é o título da issue sem o prefixo de nível, (#<nr>) anexado) com issue_number, branch: <branch> (o trabalho foi enviado de outro worktree, este checkout permanece como está), review_notes (notes[] do passo 4), com governance spec_notes (as linhas notes[] do implementador começando com nenhuma mudança de spec necessária:) e o resultado do teste do subagente.
7. CI. Execute gh pr checks <pr> --watch --required --interval 60 diretamente (cada poll é uma consulta GraphQL; o padrão de 10 s drena o orçamento), sem pipe ou filtro de saída (como tail, head ou grep), para que o progresso da observação alcance a sessão.
   • Vermelho por esta alteração (erro de teste, lint ou build em arquivos do diff): rodada de correção (passo 5), então passo 4 e 7 novamente.
   • Vermelho por outro motivo (flake, vermelho em release/next também): comente no PR, o PBI está bloqueado.
8. Mesclar. Sem perguntar, em ambos os modos: a última revisão não teve constatação bloqueante ou critério não atendido e as verificações obrigatórias estão verdes. gh pr merge <pr> --squash --delete-branch, então gh issue close <nr> --comment "Entregue em #<pr>" (Closes não dispara em release/next); sub-issues legadas [Task] abertas do PBI são fechadas com ele (github-issue references/sub-issues.md, "Issues de Tarefa legadas"); então gh issue edit <nr> --remove-assignee @me. Limpe os worktrees e branches dos subagentes com o script desta skill, scripts/Remove-PbiWorktrees.ps1 no diretório da skill (~/.claude/skills/deliver/ global, .claude/skills/deliver/ instalação do projeto), execute a partir do repositório: pwsh <skill-dir>/scripts/Remove-PbiWorktrees.ps1 -Pr <pr> -Issue <nr>; imprima #<nr> limpeza: <n> removidos e mantenha suas entradas left (caminho ou branch, motivo, comando) para o relatório. Próximo PBI: passo 1.
9. Release. Apenas com --milestone, antes do relatório (também após --max), quando nenhum PBI resta para selecionar. Leia o milestone uma vez, Get-Milestones.ps1 -Mode issues -Name <nome> -State all (abertos e fechados); a verificação de trabalho aberto, o marcador, a contagem de rodadas e os critérios das issues fechadas vêm dessa lista. Nenhuma issue aberta rotulada pbi ou bug nele exceto a issue release-test (nada bloqueado, pausado, esperando ou pulado); o teste RC nunca bloqueia.
   • Um PBI ou Bug fechado do milestone rotulado needs-decision é o marcador de pausa de uma revisão de release de rodada 3: pule a revisão, imprima release: pausado na rodada 3, aguarda uma decisão.
   • Revisão de release (references/release-review.md): um subagente com um contexto novo carrega code-review, função review, em git diff origin/main...origin/release/next com os critérios de aceitação dos PBIs e Bugs fechados do milestone, foco na consistência entre PBIs, e retorna JSON por review.schema.json, somente leitura (sem stash, checkout, switch ou commit em qualquer checkout existente; próprio worktree temporário se precisar de arquivos); esta sessão escreve <git-common-dir>/.agents/state/release-review-<chave>.json.
   • Constatações bloqueantes: uma issue [Bug] corrigir: … por constatação no milestone (interativo: mostre-as e pergunte primeiro), sem PR de release; imprima release: <n> bloqueando → #a, #b. No máximo 2 rodadas de revisão de release por milestone; uma terceira com constatações bloqueantes é uma pausa, registrada com esse marcador e um comentário nomeando as duas formas de prosseguir (references/release-review.md, "Marcador de pausa").
   • Limpo (nenhum bloqueante): corte o RC, poste-o na issue release-test e feche as mais antigas (references/release-review.md, "Teste RC"); release.test.gate: true para aí com precisa de você: teste RC <URL da issue> até que a issue seja fechada. Caso contrário, carregue github-release e execute finish com release_review_notes (as notes[], até 5): ele abre o PR de release de release/next para main (auto_merge: false) ou relata o existente; ele para quando main não é um ancestral de release/next (mesclagem reversa primeiro, github-release), relate essa parada. Imprima release: <n> bloqueando → #a, #b. No máximo 2 rodadas de revisão de release por milestone; uma terceira com constatações bloqueantes é uma pausa, registrada com esse marcador e um comentário nomeando as duas formas de prosseguir (references/release-review.md, "Marcador de pausa").