Git Flow Delivery

Fluxo baseado no Git Flow, padrão de mercado, para levar um card do quadro até produção com rastreabilidade total: todo commit, branch e PR carrega o número do card, e o histórico do repositório conta a mesma história que o quadro de tarefas.

Ferramenta-agnóstico: funciona com Jira, Linear, GitHub Issues, Azure Boards etc. Onde aparecer ABC-123, leia "o identificador do card no seu tracker".

Se existir .claude/board-workflow.md (criado pela skill board-workflow), ele é a fonte da verdade para nomes de status, ids de campo e o momento de preencher cada um: leia esse arquivo e use o que está lá em vez de perguntar de novo ou supor nomes. As duas skills se dividem assim — board-workflow cuida do board e dos campos; esta cuida de branch, commit, PR, release e hotfix; e o card acompanha o trabalho nos dois pontos de contato abaixo.

Toda branch de trabalho nasce de develop. Só hotfix nasce de main.

tipo/ABC-123-short-description-in-english

• tipo ∈ feat · fix · chore · refactor · docs · test
• Criada a partir de develop atualizada: git checkout develop && git pull && git checkout -b feat/ABC-123-...
• Nome em inglês, kebab-case, curto. O card já tem o título completo em português.

Ao criar a branch, mova o card para o status de desenvolvimento — o status do card sempre reflete a etapa real do trabalho. Preencha antes os campos daquele momento (ex.: assignee, estimativa, data de entrega) e só então transicione; ver a seção de integração com Jira. Card parado atrás da realidade é erro, não detalhe.

tipo(ABC-123) - Description in English

Exemplo: fix(ABC-123) - Browser tab title shows wrong page name

Regras que não se negociam:

• Inglês. Português fica no card; a mensagem de commit é para o histórico do repositório.

• Número do card entre parênteses, sem : depois. Nunca tipo(escopo):.

• 1 branch = 1 commit — sempre. Qualquer ajuste depois do primeiro commit (correção de review, typo, lint) entra via amend, nunca como commit novo:

  git add -A
  git commit --amend --no-edit
  git push --force-with-lease

  Antes de qualquer push, confira que há exatamente 1 commit: git log --oneline develop..HEAD

⚠️ O PR só é aberto DEPOIS de um humano validar. Não abra PR nem mova o card para "Revisão de Código" antes do OK explícito.

1. Terminar o trabalho do card com testes verdes; commit no padrão; git push -u origin <branch>.

2. Sinalizar que está pronto para validação e esperar o OK. Se vierem ajustes, iterar (via amend) — sem abrir PR nesse vai-e-volta.

3. Com o OK, abrir o PR para develop:

   gh pr create --base develop \
     --title "tipo(ABC-123) - Description in English" \
     --body "$(cat <<'EOF'
   Card: <link do card>
   
   - O que foi feito, em bullets técnicos
   - Decisões relevantes e por quê
   - Como testar
   EOF
   )"

   • Título do PR = mensagem do commit.
   • Body em português, com o link do card e bullets técnicos.
   • Labels quando existirem no repo: Bug fixes · Improvements · Breaking Changes.

1. Registrar o link do PR no card (campo/comentário de "PRs" do seu tracker), no formato:

   tipo(ABC-123) - Título
   PR #N → https://github.com/<org>/<repo>/pull/N
   

2. Mover o card para "Revisão de Código" (ou o status equivalente do seu quadro).

3. Acompanhar o code review (bot e/ou humanos) — o que olhar está na seção Code review: o que olhar, adiante. Se o repo tem review automático, aguardar no máximo 1 minuto — nunca em loop além disso. Para cada thread aberto:

   Comentário	Ação
   Procedente	Corrigir → incorporar ao commit único (amend + --force-with-lease) → responder no thread dizendo o que foi feito → Resolve conversation
   Não procedente	Responder no thread com a justificativa técnica → Resolve conversation

   • Sempre responder antes de resolver. Nunca feche um thread mudo.
   • Com revisor humano, o reply é diálogo: pode-se discordar com respeito e alinhar antes de mexer no código. Em dúvida se o ajuste estoura o escopo do card, pergunte.
   • Se corrigiu e o bot re-revisou, repetir no máximo mais 1 vez. Persistindo, parar e reportar — não entrar em ciclo infinito de correção.

   # threads abertos
   gh api graphql -f owner=<org> -f repo=<repo> -F pr=<N> -f query='
     query($owner:String!,$repo:String!,$pr:Int!){ repository(owner:$owner,name:$repo){
       pullRequest(number:$pr){ reviewThreads(first:50){ nodes{
         id isResolved comments(first:10){ nodes{ databaseId path body } } } } } } }'
   # responder num comentário
   gh api repos/<org>/<repo>/pulls/<N>/comments -f body='...' -F in_reply_to=<databaseId>
   # resolver o thread (id do THREAD, não do comentário)
   gh api graphql -f id=<threadId> -f query='
     mutation($id:ID!){ resolveReviewThread(input:{threadId:$id}){ thread{ isResolved } } }'

4. Notificar o time no canal (Slack, Discord, Teams…) — sempre com confirmação explícita, pedida depois das etapas 1–3. Autorização antecipada ("já pode avisar") dada antes do PR existir não vale: complete as etapas, pergunte, e só envie com o "sim" na resposta seguinte. Formato:

   @<papel-do-time>
   PR: <url do PR>
   Card: <url do card>
   

Vale para revisar o PR de outra pessoa e para conferir o seu antes de pedir revisão.

• Padrão tipo(ABC-123) - Description in English, igual no commit e no título do PR.
• Identificador do card presente. O formato é o do tracker do time: ABC-123 (Jira, Linear), #1234 (GitHub Issues) ou o que estiver no mapa do board. Sem id, o histórico perde a rastreabilidade — é apontamento bloqueante.
• Tipo válido: feat · fix · chore · refactor · docs · test.
• Um commit por branch (git log --oneline develop..HEAD).

• A descrição explica o que foi feito e por quê, com link do card.
• Labels aplicadas, quando o repo usa (ex.: Bug fixes, Improvements, Breaking Changes).
• É hotfix? Então existem dois PRs: um para main e um para develop.
• É release? Então sem squash/rebase no merge — o histórico da develop se preserva.
• O card está na coluna que corresponde à etapa real (code review).

Sem severidade, todo comentário parece bloqueante e a revisão trava. Ao aprovar com apenas sugestões e nitpicks, deixe explícito que estão liberados para seguir.

A branch release é descartável: existe só para levar o estado da develop até um PR contra main.

git checkout develop && git pull
git checkout -B release                     # -B recria se já existir
git push -u origin release
gh pr create --base main --head release --title "Release" --body "Release"
git checkout develop && git branch -D release   # a remota o GitHub apaga no merge

Regras:

• Título e body: Release, sem número de versão. A versão vive na tag/release do GitHub (vX.Y.Z), não no título do PR.

• NUNCA squash/rebase no merge — release preserva o histórico da develop (merge commit).

• PR de release não tem card: as etapas de tracker da seção 4 não se aplicam. Só a notificação, com o mesmo pedido de confirmação:

  @<papel-do-time>
  Release 📢
  <url do PR>
  

• Após o merge, publicar a release final vX.Y.Z (sem -rc, apontando para main). Se o deploy de produção dispara pelo evento de release, conferir que todos os workflows rodaram (gh run list --workflow <arquivo>). Se um não disparou, deletar e recriar a release na mesma tag re-dispara o evento.

Durante um hotfix podem coexistir main: 1.2.1-rc.1 e develop: 1.3.0-rc.1. Conferir a última tag: git tag --sort=-creatordate | head -5.

Hotfix é a única branch que nasce de main.

git checkout main && git pull
git checkout -b fix/ABC-123-short-description
# ... corrigir, commit no padrão (1 commit), push ...
gh pr create --base main    --title "fix(ABC-123) - Description" --body "..."
gh pr create --base develop --title "fix(ABC-123) - Description" --body "..."

• Duas PRs, sempre: uma para main (vai para produção) e outra para develop (para a correção não se perder na próxima release). Registrar os dois links no card.
• Versão: patch com rc (1.2.0 → 1.2.1-rc.1), release final após o merge em main.

Se o projeto tem o board acessível (MCP do Atlassian para Jira, MCP ou API do Trello), as etapas de card das seções 1 e 4 podem ser feitas pelo agente. Sem acesso, faça-as manualmente — nunca com credenciais no prompt.

Regras que valem nos dois:

• Ler antes de escrever. Busque o card antes de atualizar, para acrescentar ao campo de PRs em vez de sobrescrever o que já está lá.
• Campos do momento antes de mover. No Jira é técnico: muitos workflows recusam campo setado dentro da transição ("not on the appropriate screen") — atualize, depois transicione. No Trello nada impede a movimentação, então a checagem é sua: confira os campos antes de trocar a lista.
• Nunca chumbe identificador. No Jira, descubra a transição com jira_get_transitions; no Trello, use o id da lista (nome muda e quebra silenciosamente).
• Marcar a origem. Se o time usa uma label para o que o agente toca, some-a às existentes.
• Hotfix registra os dois links de PR (main e develop) no mesmo card.

• [ ] Branch tipo/ABC-123-english-name, criada de develop (de main só se hotfix)
• [ ] Commit tipo(ABC-123) - Description in English — e só um commit
• [ ] Card movido para desenvolvimento ao criar a branch
• [ ] Humano validou antes do PR
• [ ] PR para develop, título = commit, body em português com link do card
• [ ] Link do PR registrado no card; card em "Revisão de Código"
• [ ] Threads de review: respondidos e resolvidos; correções via amend
• [ ] Revisão passou pelas 4 frentes (formato, estrutura, qualidade, severidade)
• [ ] Notificação ao time só depois de perguntar e receber "sim"
• [ ] Release: título Release, sem squash, tag vX.Y.Z
• [ ] Hotfix: PR para main e para develop, versão patch

Troque estes pontos e o resto do fluxo se mantém: