| name | finalize-implementation |
| description | Finaliza implementações com commit conventional, screenshots Playwright, checklist de qualidade e abertura de pull request via gh CLI usando o template da empresa. Use quando o usuário pedir para finalizar, commitar, abrir PR, capturar screenshots, encerrar implementação, ou mencionar "finalize", "commit final", "pull request", "gh" ou "conventional commits". |
Finalize Implementation
Encerra uma implementação com validação, screenshots Playwright, commit Conventional Commits e PR via gh CLI + TEMPLATE.md.
Só commitar ou abrir PR quando o usuário pedir explicitamente.
Ferramentas obrigatórias
| Ferramenta | Uso |
|---|
gh | Todas as operações GitHub: auth, repo, PR create/view/checks, labels, reviewers |
git | Apenas working tree local: status, diff, add, commit |
| Playwright | Screenshots da UI implementada (script em scripts/) |
Regra: nunca abrir PR pelo browser manualmente se gh estiver disponível. Nunca usar API REST/curl para GitHub quando existir comando gh equivalente.
Verificar antes de abrir PR:
gh auth status
gh repo view --json nameWithOwner,defaultBranchRef
Restrições do repositório
- Nunca executar:
git restore, git rm, git stash, git checkout
- Nunca alterar
git config
- Nunca
--no-verify, force-push em main/master, ou comandos destrutivos sem pedido explícito
- Nunca commitar
.env, credenciais ou secrets
- Nunca commitar
scripts/node_modules/ da skill
Fluxo
1. Pré-validação
2. Screenshots (Playwright) — se houver mudança visual/frontend
3. Commit final
4. Push (git) + PR (gh)
1. Pré-validação
| Alteração | Comandos |
|---|
| Backend | cd backend && npm test |
| Frontend | cd frontend && npm test && npm run lint && npm run typecheck |
Revisar contra code-standards, react e tests quando relevante.
Se algo falhar, corrigir antes de continuar.
2. Screenshots com Playwright
Obrigatório quando a implementação altera UI (frontend/src/pages, components, estilos). Para backend-only, pular e documentar evidência textual no template.
2.1 Preparar ambiente
- Backend rodando em
http://localhost:3000 (se a UI depende da API)
- Frontend acessível — preferir build estável:
cd frontend && npm run build && npm run preview -- --port 5173
Alternativa rápida: npm run dev na porta 5173.
- Instalar Playwright (primeira vez ou após limpar
node_modules):
cd .claude/skills/finalize-implementation/scripts
npm install
npm run install-browser
2.2 Capturar
Escolher --slug descritivo (kebab-case, ex.: weather-panel, api-status-indicator).
cd .claude/skills/finalize-implementation/scripts
node capture-screenshots.mjs \
--slug <feature-slug> \
--routes / \
--url http://localhost:5173 \
--mobile
| Flag | Descrição |
|---|
--slug | Pasta em .github/pr-screenshots/<slug>/ |
--routes | Rotas separadas por vírgula (/, /settings) |
--url | Base URL do app |
--mobile | Captura adicional 390×844 |
Saída: PNGs em .github/pr-screenshots/<slug>/ + manifest.json com markdownSection pronto para colar na PR.
2.3 Incluir na PR
- Commitar os PNGs na branch da feature (links relativos na description dependem disso)
- Copiar
markdownSection do manifest para a seção Screenshots / evidências do TEMPLATE.md
- Marcar checklist: "Screenshots Playwright capturados"
Paths na description usam formato:
GitHub renderiza imagens commitadas na mesma branch.
3. Commit final (Conventional Commits)
Formato
<type>(<scope>): <subject>
[body opcional — 1–3 frases explicando o porquê]
| Campo | Regra |
|---|
type | feat, fix, refactor, test, docs, chore, perf, ci, build |
scope | backend, frontend, auth, health, api, etc. |
subject | Imperativo, minúsculas, sem ponto final, máx. ~72 chars |
Incluir screenshots no mesmo commit da feature ou em commit chore imediatamente anterior ao PR — nunca deixar PNGs só locais.
Procedimento
- Em paralelo:
git status, git diff, git log -5 --oneline
- Staging dos arquivos relevantes +
.github/pr-screenshots/<slug>/
- Commit via HEREDOC:
git commit -m "$(cat <<'EOF'
feat(scope): subject here
Optional body explaining why.
EOF
)"
- Hook falhou → corrigir e novo commit (não
--amend salvo regras do usuário)
4. Push e Pull Request via gh
4.1 Coletar contexto com gh + git
Em paralelo:
git status
git diff
git log "$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)...HEAD" --oneline
git diff "$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)...HEAD"
gh pr list --head "$(git branch --show-current)" --json number,url
Entender todos os commits da branch. Se PR já existe, usar gh pr edit em vez de gh pr create.
4.2 Push
git push -u origin HEAD
gh pr create pode oferecer push interativo, mas em automação fazer push explícito antes.
4.3 Montar description
- Ler TEMPLATE.md
- Preencher todas as seções (sem placeholders)
- Colar
markdownSection do Playwright em Screenshots / evidências
- Marcar checklist verificado
Salvar body preenchido em arquivo temporário (ex.: /tmp/pr-body.md) — não alterar o TEMPLATE.md no repo.
4.4 Criar ou atualizar PR
Base branch via gh:
BASE=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)
Nova PR:
gh pr create \
--base "$BASE" \
--title "feat(scope): short description" \
--body-file /tmp/pr-body.md
PR já aberta:
gh pr edit <number> --body-file /tmp/pr-body.md
Comandos úteis pós-criação:
gh pr view --web
gh pr checks
gh pr status
Flags opcionais: --draft, --reviewer, --label, --assignee "@me".
4.5 Resposta ao usuário
Retornar URL da PR (gh pr view --json url -q .url). Resumir: validações, screenshots capturados, checklist pendente.
Checklist rápido do agente
Referência — gh vs git
| Ação | Comando |
|---|
| Branch default | gh repo view --json defaultBranchRef -q .defaultBranchRef.name |
| Criar PR | gh pr create --base ... --title ... --body-file ... |
| Editar PR | gh pr edit <n> --body-file ... |
| Ver PR atual | gh pr view |
| Listar PRs da branch | gh pr list --head "$(git branch --show-current)" |
| Status CI | gh pr checks |
| Auth | gh auth status |
| Status/diff/commit | git status, git diff, git commit |
| Push | git push -u origin HEAD |
Scopes comuns neste projeto
| Scope | Uso |
|---|
backend | Express, routes, services, data |
frontend | React, pages, components, hooks |
health | Endpoint /health e indicadores |
deps | Dependências npm |
ci | Pipelines e automação |
