commit

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Commit (submódulos primeiro)

Commita as alterações pendentes: primeiro cada submódulo sujo, depois o repositório principal. Em repositórios com artefatos SDD, oferece também a remoção dos artefatos de features concluídas, num commit próprio.

Ligue o **modo push** sempre que a mensagem que invocou a skill contiver as palavras `push`, `--push`, `enviar` ou `--enviar` — seja como argumento de slash command (`/commit --push`), seja em texto livre ("commita e dá push", "pode enviar"). Não há substituição automática de variável: o texto digitado depois de `/commit` é só contexto anexado à mensagem, então basta ler a própria mensagem do usuário para decidir. Em modo push, depois de commitar, envia ao remoto (passo 8). Sem nenhuma dessas palavras, a skill para nos commits locais.

## Regras invioláveis

- Rede só no **modo push**, e só com `git push`, `git fetch` e `git pull --rebase` (nunca `git merge` nem pull com merge). Fora do modo push, nada de rede.
- **NUNCA** usar `--no-verify` ou `--no-gpg-sign`. Se um hook falhar, investigar e reportar, não contornar.
- Preferir commit novo a `--amend`. Única exceção: corrigir a mensagem do commit recém-criado no passo 5, antes de qualquer push.
- Não criar branch, não fazer checkout, não alterar o estado do working tree além do `git add` acordado e da remoção de artefatos SDD que o usuário escolher no passo 2.

## Procedimento

### 1. Levantar o estado

```bash
git submodule status
git status --porcelain
git symbolic-ref -q --short HEAD   # vazio/erro = HEAD destacado
```

Sem `.gitmodules`/submódulos, o passo 3 não se aplica: depois do passo 2, vá ao passo 6 (repositório principal).

### 2. Artefatos SDD concluídos

Rode uma vez, antes de qualquer commit, sobre todo repositório com pastas `tasks/prd-*/`: o principal e cada submódulo (`git -C <sub>`). Sem essas pastas em nenhum deles, pule.

Os artefatos SDD (PRD, TechSpec, `tasks.md`, tasks, handoffs, revisões, `checkpoint.json`, `workflow.md`, `snapshot-contexto.md`) são o contrato da feature enquanto ela está em andamento, e versioná-los nesse período é esperado. Concluída a feature, a fonte de verdade passa a ser o código, os testes e a documentação durável; os artefatos envelhecem a cada mudança posterior, e mantê-los no repositório convida agentes a tratá-los como especificação vigente ou a gastar esforço sincronizando-os. Por isso, a limpeza acontece aqui, no commit, e não durante a execução de outra feature.

Classifique cada `tasks/prd-[slug]/` pela primeira linha que decidir:

| Evidência | Classe |
|---|---|
| `checkpoint.json` com `status` ou `phase` igual a `concluido` | concluída |
| `snapshot-contexto.md` com `status: encerrado` e `etapa: aceite` | concluída |
| Sem `checkpoint.json`: nenhuma `task_*.md` na raiz da pasta, tasks em `done/`, e o `codereview_[maior num]/codereview.md` com status `APROVADO`, ou `APROVADO COM RESSALVAS` com a decisão do usuário sobre as ressalvas registrada, sem tasks de correção na raiz dessa revisão | concluída |
| `checkpoint.json` em outra fase, task pendente na raiz, última revisão `REPROVADO` ou correção pendente | em andamento |
| Qualquer outra combinação (ex.: só `prd.md`, recorte planejado ainda não iniciado, pasta só com snapshot, ressalvas sem decisão registrada) | indeterminada |

Feature em andamento nunca é oferecida. Para cada concluída ou indeterminada, levante antes de perguntar o que a remoção levaria embora sem registro em outro lugar:

- ADRs da pasta: candidatas nos handoffs de tasks e correções (`### Candidatas a ADR` com conteúdo diferente de `Nenhuma`) e arquivos de ADR soltos na pasta, com ID e título; elas não se perdem, porque o passo 7 as move para `docs/adr/` antes da remoção, e a pergunta informa o número que cada uma vai receber;
- ressalvas aceitas e pendências registradas na última revisão ou em `workflow.md`;
- arquivos não versionados na pasta (`git status --porcelain -- tasks/prd-[slug]/`), que a remoção apaga sem volta;
- arquivos versionados fora da pasta que a citam (`git grep -lF "prd-[slug]" -- ":!tasks/prd-[slug]/"`; o slug sem barra também pega citações soltas), como README ou docs, que ficariam com links quebrados; recomende manter a feature ou levar antes o conteúdo citado para a documentação;
- `checkpoint.json` com `mode: auto`: o aceite foi automático e nenhum humano viu a entrega; aponte o log de decisões (`decision_log`) para revisar antes de remover.

Faça uma única pergunta para todos os repositórios, pela tool de perguntas disponível (`AskUserQuestion` em `multiSelect`) ou, sem ela, em texto com as mesmas opções. Uma opção por feature: repositório quando não for o principal, slug, classe com a evidência que a decidiu e, na descrição, os itens levantados acima. Indeterminada nunca vem marcada como recomendada. Com mais features do que cabem na ferramenta, pergunte em texto listando todas. Nenhuma seleção, "nenhuma" ou silêncio mantém tudo. Guarde a escolha para o passo 7; a pergunta acontece agora para que o resto da skill siga sem nova interrupção.

### 3. Para cada submódulo com alterações pendentes

Detectar sujeira em `<sub>` com `git -C <sub> status --porcelain`. Vazio = pular.

Para cada submódulo sujo, executar os passos 4 e 5 **dentro dele** (`git -C <sub> ...`) antes de tocar no principal.

### 4. Decidir o que entra no stage

Compare `git status --porcelain` (coluna 1 = staged, coluna 2 = working tree):

| Situação | Ação |
|---|---|
| Nada staged | `git add -A` direto, sem perguntar |
| Tudo já staged | Prossegue, sem perguntar |
| Único item fora do stage é o gitlink de um submódulo recém-commitado (resto já staged) | `git add <submódulo>` direto, sem perguntar |
| Parcialmente staged | Perguntar (ver abaixo) |

No caso parcial, use a tool de perguntas (`AskUserQuestion`) mostrando o que está staged e o que está de fora, com as opções:

- **Sim** — `git add -A` e commitar tudo
- **Não** — commitar apenas o que já está staged
- **Abortar** — encerrar sem commitar, para o usuário refazer o staging

### 5. Gerar a mensagem e commitar

**Use o contexto da sessão atual como fonte primária.** Se as alterações pendentes vieram do trabalho feito nesta conversa, você já sabe o *porquê* — o bug relatado, a decisão tomada, o ticket citado, a alternativa descartada. Isso vale mais que o diff: escreva a mensagem a partir desse contexto e use o diff só para conferir cobertura (nada relevante ficou de fora, nada alheio entrou junto). Se o diff contiver mudanças que **não** são da sessão, trate-as pelo diff normalmente.

Antes de escrever, leia o que vai ser commitado e o estilo do repositório:

```bash
git diff --staged --stat
git diff --staged
git log -8 --format="%s%n%b%n---"
```

Formato da mensagem (padrão GitHub / conventional commits):

```
tipo(escopo): resumo no imperativo, minúsculo, sem ponto final

- Alteração relevante 1
- Alteração relevante 2
- Alteração relevante 3
```

- **Uma linha em branco entre o título e os bullets.** Sem ela, o Git lê a mensagem inteira como título (`%s`), e depois do push só reescrevendo o histórico se corrige.
- Título ≤ 72 caracteres. Tipos: `feat`, `fix`, `refactor`, `perf`, `test`, `docs`, `chore`, `build`, `ci`, `style`.
- **Idioma e escopo seguem o `git log` do repositório em questão** — cada repo pode ter convenção própria; o submódulo pode diferir do principal.
- Bullets descrevem *o que mudou e por quê*, não arquivo por arquivo. Um commit trivial (ex.: bump de referência de submódulo) pode ter só o título.
- Sem trailer `Co-Authored-By`.

Commitar sem confirmação prévia. No PowerShell, use here-string literal (o `'@` de fechamento precisa estar na coluna 0):

```powershell
git commit -m @'
tipo(escopo): resumo

- Bullet 1
- Bullet 2
'@
```

No Bash, use heredoc equivalente, com a mesma linha em branco:

```bash
git commit -F - <<'EOF'
tipo(escopo): resumo

From ColibriAgile/agents-instructions, MIT.

More from ColibriAgile/agents-instructions