Skill: Setup Projeto Qualidade

Organizadora e criadora de projetos. Pega um repositório (novo ou já em andamento, qualquer stack) e implanta uma arquitetura de engenharia robusta: constituição (CLAUDE.md) equalizada com as rules, fluxo de PR com review automático, merge seguro com duplo gate, deploy sincronizado com o GitHub, agentes worktree-isolados pra paralelismo, catalisação obrigatória de lições. Tudo genérico e adaptável, sem amarração a nenhum projeto ou pessoa.

Quando o usuário invoca

Trigger: /setup-projeto-qualidade no projeto-alvo, ou ele descreve querer "arquitetura sólida", "PR flow", "GitHub Actions com auto-review", "rules vivas", "deploy automático", "catalisação de lições".

Princípios não-negociáveis

1. Análise antes de execução. Nunca toca em nada sem antes detectar stack, ler o que existe, mapear. Fase 0 jamais é pulada.
2. Aprovação por onda. Cada fase precisa ok explícito. Fase 1 (git/repo) é destrutiva, cuidado extra.
3. Validação dupla. Após cada fase, smoke test confirma que nada quebrou.
4. Preserva histórico. Sub-repos com .git próprio nunca são absorvidos sem confirmação dupla.
5. Sem secrets commitados. Antes de cada commit, grep agressivo: pk_live_, sk_live_, sbp_, EAA…{60+}, ghp_, sk-ant-, sk-ant-oat01-.
6. Equalização do CLAUDE.md. Toda rule criada ganha ponteiro no CLAUDE.md no mesmo passo. Um validador quebra o CI se dessincronizar.
7. Commits nunca atribuem a IA. includeCoAuthoredBy: false + attribution vazia no settings.json do projeto. Autor é sempre o mantenedor humano.

Equalização do CLAUDE.md (peça central)

O CLAUDE.md é sempre carregado pela IA; as rules em .claude/rules/ não. Por isso o CLAUDE.md é a constituição: índice que aponta pra todas as rules + os invariantes mais críticos escritos no corpo (merge seguro, hierarquia epistêmica, princípio de catalisação) pra serem impossíveis de ignorar. Camada de segurança em profundidade: o invariante vive no CLAUDE.md (sempre lido) E na rule (detalhe) E no validador (gate duro).

Regra dura: rule nova sem ponteiro no CLAUDE.md = rule invisível. O validate-claude-md-sync falha o CI nesse caso, e também em ponteiro morto.

Autenticação Claude (OAuth prioritário)

Os workflows de IA (pr-auto-review job Claude, claude-mention) autenticam por OAuth token, prioridade sobre API key:

# 1. gerar o token (no terminal, uma vez)
claude setup-token            # gera sk-ant-oat01-...

# 2. setar como secret do repo
gh secret set CLAUDE_CODE_OAUTH_TOKEN -R <owner>/<repo>

Sem o secret, os jobs de IA skipam sem quebrar o PR (graceful degradation). A skill instrui isso no fim do setup. API key (ANTHROPIC_API_KEY) é fallback documentado, não o caminho recomendado.

Fluxo da skill

Fase 0 — Mapeamento do projeto-alvo

1. Stack: package.json → Node/TS/Next | pyproject/requirements → Python |
   deno.json → Deno | go.mod → Go | Cargo.toml → Rust | múltiplos → monorepo
2. Git: .git na raiz? sub-repos? remote? GitHub/GitLab?
3. Claude: CLAUDE.md / AGENTS.md / .claude/ já existem? rules/settings?
4. CI/CD: .github/workflows/? lefthook/.husky/pre-commit?
5. Deploy: Vercel? Supabase? Docker? npm pkg? site estático? (define o
   template de deploy a usar na Fase 4)
6. Tooling: bun/deno/npm? linter? typecheck?

Reportar em tabela compacta. Pedir confirmação do que pode mexer.

Fase 1 — Setup base do repositório git (destrutivo, ok explícito)

• Sem .git na raiz: git init + git config init.defaultBranch main
• Sub-repos com .git próprio: escolher A) git subtree preservando histórico, B) submodules, C) .gitignore (seguem independentes)
• .gitignore cobrindo deps, builds, caches, secrets, editor, OS
• gh repo create <owner>/<nome> --private + git remote add origin + push

Fase 2 — Estrutura .claude/ + constituição

.claude/
├── rules/
│   ├── 01-invariantes.md            (regras invioláveis, placeholders)
│   ├── 02-equalizacao-pipeline.md   (camadas adaptadas à estrutura real)
│   ├── 03-hierarquia-epistemica.md  (P1-P5)
│   ├── 04-pr-flow.md                (PR, review, merge)
│   ├── 05-catalisacao-licoes.md     (como/onde catalogar)
│   ├── 06-frentes-paralelas.md      (planos paralelos)
│   └── 07-merge-seguro.md           (duplo gate + mergeStateStatus CLEAN)
├── agents/
│   └── worker.md                    (isolation: worktree — paraleliza sem
│                                      sujar o working tree; git garantido)
└── settings.json                    (includeCoAuthoredBy:false +
                                       attribution vazia + allowlist Bash)

Templates pré-preenchidos em templates/. A skill personaliza: nome do projeto no título, stack nas rules, camadas geradas da estrutura real (src/, api/, lib/ viram camadas), invariantes ficam como placeholder pro mantenedor preencher. Placeholders: {{PROJETO}}, {{PROJETO_UPPER}}, {{REPO}}, {{REPO_OWNER}}, {{MANTENEDOR}}, {{STACK}}, etc.

Fase 3 — Constituição + documentação

• CLAUDE.md a partir de templates/CLAUDE.md.template: índice com ponteiro pras 7 rules + invariantes sempre-carregados (merge seguro, hierarquia, catalisação) no corpo. Equalizado: toda rule tem linha no índice.
• REVIEW.md raiz a partir de templates/REVIEW.md.template: single source of truth consumido pelo Claude AI review do pr-auto-review.yml. Contém 9 seções: sumário projeto (§1) + princípios canônicos catalisados (§2.X = lições L-XXX) + critérios merge (§3 críticos/ressalvas/aprovação
  • hierarquia epistêmica P1-P5) + frentes entregues (§4) + validators ativos (§5) + vocabulário canônico (§6) + endpoints+integrações (§7) + output format obrigatório do review (§8) + fallback canônico Code Review Diretor (§9). Começa com placeholders; mantenedor preenche §2.X conforme catalisa lições e §3-§9 conforme projeto amadurece. Workflow YAML referencia APENAS REVIEW.md + CLAUDE.md no prompt (reduz turns, evita AJV crash).
• AGENTS.md (diário vivo append-only) + registro-construcao.md (cronologia)
• docs/{casos-referencia,licoes,deploys,api,arquitetura}/

Fase 4 — GitHub Actions

• ci.yml — type check, lint, validators (PR + push main)
• pr-auto-review.yml — 3 jobs: heurística (sempre, sem custo) + check-key (graceful se CLAUDE_CODE_OAUTH_TOKEN ausente) + claude-review (Claude AI via OAuth, lê REVIEW.md raiz como single source of truth + rules, comenta). Estrutura resiliente: retry duplo (tentativa 1 + sleep 30s + tentativa 2, ambos continue-on-error: true)
  • fallback canônico se 2 tentativas falharem → posta comment sinalizando Code Review Diretor manual (4 sub-agents READ-ONLY paralelos via Task tool: architect / reviewer / quality-engineer / deep-research-agent). Mitiga bugs upstream conhecidos (claude-code-action: AJV crash, fd 4 mismatch, error_max_turns, App token 401)
• claude-mention.yml — @claude sob demanda em PR/issue/review. Autentica via CLAUDE_CODE_OAUTH_TOKEN. Sem o secret, skipa silencioso
• pr-auto-merge.yml — auto-approve+merge SÓ Tier S inerte (docs/, registro-construcao.md, .planning/frentes/), fail-safe por exclusão, dispara via workflow_run pós-CI verde. Tier H = humano (07-merge-seguro)
• deploy/<variante>.yml — deploy automático sincronizado com o GitHub, escolhido pela stack detectada na Fase 0 (matriz abaixo)

Ao final, instruir o setup do OAuth token (seção "Autenticação Claude").

Fase 4.5 — Rodar as GitHub Actions localmente (self-hosted, zera minutos)

GitHub Free dá 2000 min/mês de runner hospedado em repo privado. Acabou a cota, o CI para. Runner self-hosted não conta nesse limite (ilimitado, qualquer visibilidade de repo). A ideia: o GitHub continua orquestrando (triggers, secrets, UI, branch protection), mas a execução roda numa máquina sua.

Onde rodar. Qualquer