lguidolin/ship-it

Ship It

Gerencia o ciclo de vida completo de entrega: stage, commit, push, abrir um PR, arquivar registros de decisão pós-merge e limpeza.

Visão Geral

Toda alteração passa por um branch e PR. Nunca faça push diretamente para a main. Esta habilidade gerencia o ciclo de finalização completo, incluindo o arquivamento da documentação pós-merge.

As mensagens de commit são documentação. O título do PR se torna o commit squash-merge na main e aparece no changelog. Acertá-lo no momento da criação do PR.

Arquive após o merge, nunca antes. Especificações e planos permanecem acessíveis até o merge do PR. Somente após o merge eles são convertidos em registros de decisão compactos.

Quando Usar

• O usuário diz "push", "ship it", "vamos finalizar", "abrir um PR", "criar um PR"
• O usuário diz "merge feito", "está mergeado", "puxar e limpar" após um PR ter sido aberto
• O usuário concluiu a implementação e quer finalizar
• Após concluir um plano onde o próximo passo é submeter o trabalho

Quando NÃO Usar

• O usuário explicitamente quer fazer push diretamente para a main (confirme que isso é intencional primeiro)
• O repositório não tem remote configurado
• As alterações são work-in-progress que o usuário não está pronto para enviar
• O usuário quer apenas fazer commit sem finalizar (use conventional-commits-and-releases)

Processo

Fase 0: Verificar e Detectar

Uma suíte vermelha nunca se torna um PR. Execute a suíte de testes completa do projeto primeiro. Se algo falhar, reporte as falhas e pare — não faça commit, push ou abra um PR. Esta verificação é política do projeto e não é delegada.

A detecção de ambiente (repositório normal vs. worktree nomeado vs. HEAD destacado) e a determinação da branch base são delegadas a superpowers:finishing-a-development-branch, que já lida com todos os três casos.

Verifique a disponibilidade da maneira correta: procure por finishing-a-development-branch na sua própria lista de habilidades disponíveis. Se estiver listada, é invocável. Se não estiver listada, não é — prossiga para o fallback.

Não vasculhe o sistema de arquivos em busca dela. ~/.claude/plugins/cache/ contém todas as versões já buscadas, incluindo plugins que estão instalados mas desabilitados, e habilidades podem ser fornecidas por outros mecanismos além do cache de plugins. Um caminho existindo no cache não prova nada sobre se você pode invocar a habilidade.

Se disponível — invoque-a para verificação de testes, detecção de ambiente e determinação da branch base, então pare antes do menu de opções dela.

A decisão de integração já foi tomada pela política do projeto e não cabe ao usuário redefini-la aqui: este projeto faz merge apenas através de um PR, porque o PR é o que produz a implantação de preview e o que o CI valida. A opção "merge back to <base> locally" está indisponível. A opção "keep the branch as-is" permanece válida — essa é uma decisão de adiar, não de pular a validação.

Se ausente — recorra e não perca nada que bloqueie a correção:

• Execute a suíte de testes diretamente.
• Trate o upstream do branch, ou main, como base; confirme com o usuário antes de prosseguir.
• Pule a limpeza de worktree na Fase 6; delete o branch normalmente.

Fase 1: Stage e Commit

git status --short
git branch --show-current
git log --oneline @{upstream}..HEAD 2>/dev/null || echo "Nenhum upstream configurado"

Árvore de decisão:

• Na main com alterações não staged → criar branch, commit, push, PR
• Em branch de feature com alterações não staged → commit, push, PR (ou atualizar PR existente)
• Em branch de feature com commits não enviados → push, PR (ou atualizar PR existente)
• Em branch de feature com PR existente → push (PR já existe)

Se houver alterações não staged:

• Pergunte ao usuário se todas as alterações devem ser incluídas ou arquivos específicos
• Se as alterações abrangerem múltiplos escopos, sugira dividir

Elabore a mensagem de commit:

Tipo	Quando
feat	Nova funcionalidade
fix	Correções de bugs
docs	Apenas documentação
chore	Configuração, dependências, ferramentas
refactor	Reestruturação de código, sem mudança de comportamento
test	Adição ou modificação de testes
ci	Alterações em fluxos CI/CD

Formato: <tipo>[escopo opcional]: <descrição imperativa>

Regras:

• Modo imperativo ("add", não "added" ou "adds")
• Primeira palavra após dois pontos em minúsculo
• Sem ponto final
• Curto (50 caracteres ou menos para o assunto)
• Descreva o que o commit faz, não como

Apresente a mensagem de commit proposta ao usuário e confirme antes de commitar.

Fase 2: Branch e Push

Se estiver na main, crie um branch:

<tipo>/<descrição-curta>

Exemplos:

• feat/oauth-login
• fix/null-response-handling
• docs/release-workflow-permissions

Push:

git push -u origin $(git branch --show-current)

Fase 3: Abrir PR

Título do PR = mensagem de commit convencional (usada para squash-merge na main).

Estrutura do corpo do PR:

## O que mudou

[Descrição específica das adições/modificações/remoções]

## Por quê

[Motivação — qual problema isso resolve?]

Criar usando gh CLI:

gh pr create --title "<mensagem de commit convencional>" --body "<corpo do PR>"

Se gh não estiver disponível, forneça a URL do PR a partir da saída do git push ou construa-a.

Verifique se o ambiente de preview foi criado. Se o projeto implantar previews por PR, aguarde esse workflow e confirme que o ambiente está acessível antes de entregar o PR:

gh pr checks --watch

Se o preview falhar ao implantar, reporte e pare. Um PR que ninguém pode revisar não foi finalizado.

Onde esta habilidade para. O ship-it encerra sua consciência de implantação no preview. A promoção para staging e produção não é sua responsabilidade — elas pertencem à habilidade de entrega do projeto (cloud-delivery-aks, ou seu equivalente). As Fases 4-6 abaixo são higiene de git e documentação, não implantação.

Fase 4: Aguardar Merge

Após o PR ser criado, pergunte: "Avise-me quando o merge for feito que eu cuido da limpeza e arquivamento."

Aguarde a confirmação do usuário (ex.: "merged", "done", "it's merged").

Fase 5: Pós-Merge — Arquivar Registros de Decisão

Especificações e planos são verbosos por design — bons para um humano ler o histórico, caros toda vez que Claude carrega um. Convertê-los em registros de decisão compactos mantém as decisões essenciais baratas de ler enquanto a narrativa completa permanece em disco, arquivada, sem custar nada até que alguém a abra deliberadamente.

Somente após o merge do PR, verifique se há specs/planos não convertidos:

ls docs/superpowers/specs/ 2>/dev/null
ls docs/superpowers/decisions/ 2>/dev/null

A habilidade recording-decisions fornece dois helpers para isso. Localize-os — a habilidade pode estar instalada no projeto ou globalmente:

for base in .claude/skills ~/.claude/skills; do
  d="$base/recording-decisions/scripts"
  [ -d "$d" ] && echo "$d" && break
done

Se encontrado, $d/doc-archive.sh lista specs não convertidos e imprime um prompt de conversão, e $d/index-rebuild.sh regenera o índice. Se não encontrado, faça o mesmo trabalho manualmente usando os passos abaixo — eles são autocontidos.

Se existirem specs/planos não convertidos:

1. Pergunte ao usuário: "Encontrei specs/planos que podem corresponder a este trabalho. Deseja que eu os converta em registros de decisão compactos e arquive os originais?"

2. Se sim, para cada spec:

   • Leia o conteúdo do spec
   • Gere um registro de decisão com frontmatter YAML:

     ---
     title: <extraído do spec>
     date: <do nome do arquivo do spec>
     component: <inferido do conteúdo>
     status: implemented
     supersedes: null
     dependencies: [<inferido>]
     ---
     

   • Escreva ~30-50 linhas capturando: decisões principais, interfaces, restrições
   • Salve em docs/superpowers/decisions/<data>-<tópico>.md
   • Mova o spec original para docs/superpowers/archive/specs/
   • Mova o plano correspondente para docs/superpowers/archive/plans/

3. Reconstrua o índice mestre — regenere docs/superpowers/index.md a partir do frontmatter de cada registro de decisão, agrupado em uma tabela de Decisões Ativas (componente, título, data, dependências) e uma tabela de Substituídas (componente, título, substituída por). Execute $d/index-rebuild.sh se o localizou acima; caso contrário, escreva o arquivo diretamente.

4. Faça commit do arquivamento:

   git add docs/superpowers/
   git commit -m "docs: arquivar specs e atualizar índice de decisões"
   git push
   

Fase 6: Limpeza

git checkout main
git pull
git branch -d <nome-do-branch>
git push origin --delete <nome-do-branch> 2>/dev/null || true
git fetch --prune

Verifique o estado limpo:

git branch --show-current
git log --oneline -3

Se o trabalho aconteceu em um git worktree, delegue a desmontagem a superpowers:finishing-a-development-branch (sua limpeza baseada em proveniência — ela sabe quais worktrees possui e deixa os gerenciados externamente em paz). Se essa habilidade não estiver disponível, remova o worktree manualmente com git worktree remove <caminho> e confirme com o usuário primeiro.

Princípios Chave

• Uma suíte vermelha nunca se torna um PR — verifique antes de qualquer outra coisa (Fase 0)
• Nunca faça push diretamente para a main — sempre branch + PR. O PR é a implantação de preview e a validação do CI; um merge local pula ambos. Isso substitui qualquer fluxo que ofereça merge local como uma opção.
• A finalização termina no preview — merge, arquivamento e limpeza são higiene; promoção para staging e produção é trabalho de uma habilidade separada
• Commits convencionais — o título do PR é a entrada do changelog
• Arquive apenas após o merge — specs permanecem acessíveis durante a revisão
• Registros de decisão são compactos — ~30-50 linhas, indexados por YAML, otimizados para LLM
• Limpe completamente — sem branches obsoletos ou refs de rastreamento