@fontdata/ai-harness 2.0.0

package/templates/catalog.json

@@ -0,0 +1,124 @@
+{
+  "claudeMd": {
+    "file": "CLAUDE.md",
+    "target": "CLAUDE.md",
+    "title": "CLAUDE.md base",
+    "description": "Context file com a filosofia de orquestração, TDD e gates do harness."
+  },
+  "master": {
+    "id": "harness",
+    "file": "commands/harness.md",
+    "title": "/harness (comando-mestre)",
+    "description": "Conduz a sequência de setup em ordem: validar-ideia → gerar-spec → gerar-claude-md → nova-tarefa → scaffold → executar-plan.",
+    "requires": [
+      "validar-ideia",
+      "gerar-spec",
+      "gerar-claude-md",
+      "gerar-ignore",
+      "nova-tarefa",
+      "scaffold",
+      "configurar-comentarios",
+      "criar-skill",
+      "criar-agents",
+      "criar-code-reviewer",
+      "criar-rules",
+      "criar-hooks",
+      "configurar-orquestrador",
+      "executar-plan"
+    ]
+  },
+  "skills": [
+    { "id": "lgpd-checker", "dir": "skills/lgpd-checker", "title": "Skill lgpd-checker", "description": "Conformidade com a LGPD (Lei nº 13.709/2018) em 11 categorias, com checklist e template de relatório. Vendorizada de bittencourtthulio/lgpd-checker." }
+  ],
+  "groups": [
+    {
+      "id": "setup",
+      "title": "Setup inicial",
+      "commands": [
+        { "id": "validar-ideia", "file": "commands/validar-ideia.md", "title": "/validar-ideia", "description": "Valida se a ideia cabe em ~4h com multi-agents (entrevista + veredito).", "recommended": true },
+        { "id": "gerar-spec", "file": "commands/gerar-spec.md", "title": "/gerar-spec", "description": "Entrevista de requisitos e gera o SPEC.md principal na raiz.", "recommended": true },
+        { "id": "gerar-claude-md", "file": "commands/gerar-claude-md.md", "title": "/gerar-claude-md", "description": "Gera o CLAUDE.md (context file) a partir do SPEC.md.", "recommended": true },
+        { "id": "gerar-ignore", "file": "commands/gerar-ignore.md", "title": "/gerar-ignore", "description": "Gera .claudeignore e .gitignore conforme a stack.", "recommended": false },
+        { "id": "scaffold", "file": "commands/scaffold.md", "title": "/scaffold", "description": "Cria a estrutura inicial do projeto (pastas, configs, /health, testes de smoke).", "recommended": true }
+      ]
+    },
+    {
+      "id": "orquestracao",
+      "title": "Orquestração & implementação",
+      "commands": [
+        { "id": "executar-plan", "file": "commands/executar-plan.md", "title": "/executar-plan", "description": "Orquestra a execução do plano com sub-agents em paralelo, fase a fase.", "recommended": true },
+        { "id": "configurar-orquestrador", "file": "commands/configurar-orquestrador.md", "title": "/configurar-orquestrador", "description": "Configura o agente orquestrador de sub-agents no CLAUDE.md.", "recommended": false },
+        { "id": "corrigir-review", "file": "commands/corrigir-review.md", "title": "/corrigir-review", "description": "Organiza correções do review em sprints/fases/tasks com TDD e delega.", "recommended": false },
+        { "id": "review-por-task", "file": "commands/review-por-task.md", "title": "/review-por-task", "description": "Enforça implementação → review isolado → correção em cada task.", "recommended": false }
+      ]
+    },
+    {
+      "id": "harness",
+      "title": "Harness (agents/skills/hooks/rules)",
+      "commands": [
+        { "id": "criar-skill", "file": "commands/criar-skill.md", "title": "/criar-skill", "description": "Sugere e cria skills do projeto em .claude/skills/.", "recommended": false },
+        { "id": "criar-agents", "file": "commands/criar-agents.md", "title": "/criar-agents", "description": "Cria agents especializados em .claude/agents/ a partir do plano.", "recommended": false },
+        { "id": "criar-hooks", "file": "commands/criar-hooks.md", "title": "/criar-hooks", "description": "Cria hooks por agent em .claude/hooks/ conforme o escopo.", "recommended": false },
+        { "id": "criar-rules", "file": "commands/criar-rules.md", "title": "/criar-rules", "description": "Cria rules incondicionais e por path em .claude/rules/.", "recommended": false },
+        { "id": "configurar-comentarios", "file": "commands/configurar-comentarios.md", "title": "/configurar-comentarios", "description": "Instala o padrão de comentários (rule com orçamento, bloco no CLAUDE.md e hook bloqueante com catraca sobre o legado), inclusive Delphi/Pascal.", "recommended": true },
+        { "id": "criar-code-reviewer", "file": "commands/criar-code-reviewer.md", "title": "/criar-code-reviewer", "description": "Cria o agent code-reviewer (somente leitura) em .claude/agents/.", "recommended": true }
+      ]
+    },
+    {
+      "id": "dia-a-dia",
+      "title": "Slash commands & dia a dia",
+      "commands": [
+        { "id": "resolver-bug", "file": "commands/resolver-bug.md", "title": "/resolver-bug", "description": "Investiga, planeja em docs/bugs e corrige um bug passo a passo.", "recommended": true },
+        { "id": "nova-tarefa", "file": "commands/nova-tarefa.md", "title": "/nova-tarefa", "description": "Gera spec+plano em docs/ (start inicial ou nova tarefa) e, se confirmado, dispara o orquestrador.", "recommended": true }
+      ]
+    },
+    {
+      "id": "qualidade",
+      "title": "Qualidade & manutenção de código",
+      "commands": [
+        { "id": "gerar-testes", "file": "commands/gerar-testes.md", "title": "/gerar-testes", "description": "Detecta cobertura faltante e escreve testes seguindo TDD (RED→GREEN).", "recommended": false },
+        { "id": "refatorar", "file": "commands/refatorar.md", "title": "/refatorar", "description": "Refatora um alvo usando os testes como rede de segurança, sem mudar comportamento.", "recommended": false },
+        { "id": "codigo-morto", "file": "commands/codigo-morto.md", "title": "/codigo-morto", "description": "Varre o projeto em busca de código morto e propõe remoção segura.", "recommended": false },
+        { "id": "atualizar-deps", "file": "commands/atualizar-deps.md", "title": "/atualizar-deps", "description": "Atualiza dependências em lotes, testando a cada passo e isolando o que quebra.", "recommended": false }
+      ]
+    },
+    {
+      "id": "documentacao",
+      "title": "Documentação & onboarding",
+      "commands": [
+        { "id": "sincronizar-claude-md", "file": "commands/sincronizar-claude-md.md", "title": "/sincronizar-claude-md", "description": "Aponta onde o CLAUDE.md/SPEC.md divergiu do código, sem reescrever sozinho.", "recommended": false },
+        { "id": "diagrama", "file": "commands/diagrama.md", "title": "/diagrama", "description": "Gera diagramas Mermaid de arquitetura/fluxo a partir do código.", "recommended": false },
+        { "id": "onboarding", "file": "commands/onboarding.md", "title": "/onboarding", "description": "Gera um guia de onboarding (rodar, entender e contribuir) em docs/.", "recommended": false },
+        { "id": "gerar-env", "file": "commands/gerar-env.md", "title": "/gerar-env", "description": "Monta o .env.example a partir das variáveis de ambiente lidas no código.", "recommended": false }
+      ]
+    },
+    {
+      "id": "avancado",
+      "title": "Avançado (RAG, UX, Design, Auditorias)",
+      "commands": [
+        { "id": "criar-rag", "file": "commands/criar-rag.md", "title": "/criar-rag", "description": "Cria um sistema de RAG (SQLite + sqlite-vec) para capturar aprendizados.", "recommended": false },
+        { "id": "auditar-ui", "file": "commands/auditar-ui.md", "title": "/auditar-ui", "description": "Navega a app via Playwright MCP e audita UX/UI e/ou acessibilidade (a11y), por tela e severidade.", "recommended": false },
+        { "id": "design-system", "file": "commands/design-system.md", "title": "/design-system", "description": "Cria o agent de design system com skills e rules de identidade visual.", "recommended": false },
+        { "id": "auditar-performance", "file": "commands/auditar-performance.md", "title": "/auditar-performance", "description": "Audita gargalos de performance (queries, bundle, renders, algoritmos).", "recommended": false },
+        { "id": "auditar-seguranca", "file": "commands/auditar-seguranca.md", "title": "/auditar-seguranca", "description": "Auditoria defensiva: segredos, deps vulneráveis, inputs sem validação, configs e conformidade LGPD.", "recommended": false, "requiresSkills": ["lgpd-checker"] }
+      ]
+    },
+    {
+      "id": "manutencao",
+      "title": "Manutenção & validação",
+      "commands": [
+        { "id": "validar-commands", "file": "commands/validar-commands.md", "title": "/validar-commands", "description": "Audita .claude: valida modelos dos agents, aponta commands redundantes e sugere novos.", "recommended": false }
+      ]
+    },
+    {
+      "id": "utilitario",
+      "title": "Utilitário",
+      "commands": [
+        { "id": "git-commit-push", "file": "commands/git-commit-push.md", "title": "/git-commit-push", "description": "Gera mensagem e executa git add/commit/push em PT-BR.", "recommended": true },
+        { "id": "versao", "file": "commands/versao.md", "title": "/versao", "description": "Detecta o versionamento do projeto (qualquer stack) e aplica o bump de versão + changelog (autossuficiente), com gate de aprovação e sem push.", "recommended": true },
+        { "id": "configurar-auto-tag", "file": "commands/configurar-auto-tag.md", "title": "/configurar-auto-tag", "description": "Detecta o padrão de versionamento (qualquer stack, inclusive Delphi) e gera a GitHub Action que cria a tag automaticamente quando a versão chega na main.", "recommended": true },
+        { "id": "revisar-pr", "file": "commands/revisar-pr.md", "title": "/revisar-pr", "description": "Revisa um PR ou o diff atual, classificando em BLOQUEANTE/IMPORTANTE/SUGESTÃO.", "recommended": false }
+      ]
+    }
+  ]
+}

package/templates/commands/atualizar-deps.md

@@ -0,0 +1,15 @@
+---
+description: Atualiza dependências em lotes, rodando testes a cada passo e isolando o que quebra.
+---
+
+# Atualização segura de dependências
+
+Alvo (opcional — pacote específico ou "tudo"): $ARGUMENTS
+
+Passos:
+
+1. Detecte o gerenciador de pacotes do projeto (npm/pnpm/yarn, pip/poetry, go, cargo, maven, etc.) e liste as dependências **desatualizadas**, separando **patch**, **minor** e **major**.
+2. Garanta um baseline verde: rode build e testes **antes** de qualquer mudança. Se já estiver vermelho, **pare e me avise**.
+3. Atualize em lotes, do mais seguro ao mais arriscado: primeiro **patch**, depois **minor**, por último **major** (um de cada vez). Após cada lote, rode build + testes.
+4. Se um lote quebrar, **isole o pacote culpado**, reverta-o e siga com o resto. Para cada **major**, consulte o changelog/breaking changes antes (use o Context7 quando útil).
+5. **Não faça commit nem push** sem minha confirmação. Ao final, reporte: o que foi atualizado, o que foi segurado e por quê, e o estado da suíte.

package/templates/commands/auditar-performance.md

@@ -0,0 +1,27 @@
+---
+description: Audita o projeto em busca de gargalos de performance (queries, bundle, renders, algoritmos).
+---
+
+# Auditoria de performance
+
+Foco (opcional — ex.: "backend", "frontend", "tela X", "endpoint Y"): $ARGUMENTS
+
+Se eu não especifiquei, analise o projeto como um todo e priorize os pontos de maior impacto.
+
+Passos:
+
+1. Identifique a stack e analise os pontos quentes mais comuns:
+   - **Banco/dados**: queries N+1, falta de índices, `SELECT *`, paginação ausente, chamadas em loop.
+   - **Backend**: trabalho síncrono bloqueante, ausência de cache, serialização cara, I/O repetido.
+   - **Frontend**: tamanho do bundle, imports pesados, re-renders desnecessários, imagens não otimizadas, ausência de lazy-load.
+   - **Algoritmos**: complexidade desnecessária (O(n²) evitável), estruturas de dados inadequadas.
+2. Para cada achado, estime **impacto** (alto/médio/baixo) e **esforço** de correção, com o trecho de evidência (`arquivo:linha`).
+3. Onde possível, **meça** em vez de adivinhar (profiler, `EXPLAIN`, análise de bundle, logs de tempo). Não instale ferramentas novas sem me perguntar.
+4. Apresente um relatório priorizado por **impacto/esforço** com a correção recomendada de cada item. Não altere código sem minha confirmação.
+
+## Onde gravar o relatório
+
+Grave o relatório em `docs/investigacoes/<yyyy-mm-dd>-<slug>.md` — `<yyyy-mm-dd>` é a data atual e
+`<slug>` resume o tema auditado. **Não** grave em `docs/bugs/`: aquela pasta é só para defeito com
+sintoma reproduzível, causa-raiz e correção. Se a auditoria virar trabalho de correção, o plano
+vai para `docs/plans/`.

package/templates/commands/auditar-seguranca.md

@@ -0,0 +1,64 @@
+---
+description: Auditoria de segurança e LGPD — segredos, deps vulneráveis, inputs sem validação, configs inseguras e conformidade com a Lei nº 13.709/2018.
+---
+
+# Auditoria de segurança e LGPD
+
+Foco (opcional): $ARGUMENTS
+
+Esta é uma auditoria **defensiva** do próprio projeto, em duas frentes: **segurança técnica** e
+**conformidade com a LGPD**. Se `$ARGUMENTS` restringir o escopo (ex.: `só segurança`, `só lgpd`,
+`autenticação`), respeite-o; sem argumento, rode as duas frentes.
+
+## Parte 1 — Segurança técnica
+
+1. **Segredos**: procure chaves de API, senhas, tokens e credenciais hardcoded no código e no histórico recente. Verifique se `.env` está no `.gitignore`.
+2. **Dependências**: rode o auditor da stack (`npm audit`, `pip-audit`, `osv-scanner`, etc., se disponível) e liste vulnerabilidades conhecidas por severidade.
+3. **Validação de entrada**: identifique inputs sem validação/sanitização — risco de injeção (SQL, comando, XSS), path traversal e desserialização insegura.
+4. **AuthZ/AuthN**: rotas sem proteção, checagem de permissão ausente, segredos de sessão fracos, CORS permissivo demais.
+5. **Configuração**: modo debug em produção, headers de segurança ausentes, TLS, exposição de stack traces.
+6. Classifique cada achado em **CRÍTICO / ALTO / MÉDIO / BAIXO** (estilo CVSS), com evidência (`arquivo:linha`) e correção recomendada. Não exponha valores de segredos reais no relatório — referencie só a localização. Não altere código sem minha confirmação.
+
+## Parte 2 — Conformidade com a LGPD
+
+Use a skill **`lgpd-checker`**, instalada em `.claude/skills/lgpd-checker/`. Leia
+`.claude/skills/lgpd-checker/SKILL.md` e siga as fases dela; consulte
+`references/checklist.md` para a lista completa de verificações e `references/lgpd-artigos.md`
+para citar o artigo correto. Em resumo:
+
+- **Fase 1 — Reconhecimento**: tipo de aplicação, stack e se o sistema trata dados pessoais de
+  pessoa física. Se não tratar, registre isso com justificativa e pule a Parte 2.
+- **Fase 2 — Análise por categoria** (CAT-1 a CAT-11): bases legais e consentimento, minimização,
+  dados sensíveis, segurança técnica, logs e auditoria, direitos dos titulares, retenção e
+  eliminação, privacy by design, transferência internacional, documentação e governança,
+  notificação de incidentes. Faça **busca ativa** no código — não presuma conformidade.
+- **Fase 3 — Severidade e veredito**: classifique cada achado em
+  **CRÍTICO / ALTO / MÉDIO / BAIXO / INFO**, sempre citando o artigo da LGPD e uma recomendação
+  técnica concreta. Conclua o veredito de conformidade: ✅ CONFORME (nenhum CRÍTICO/ALTO),
+  ⚠️ PARCIALMENTE CONFORME (só MÉDIO/BAIXO) ou ❌ NÃO CONFORME (algum CRÍTICO/ALTO).
+
+CAT-4 (segurança técnica) se sobrepõe à Parte 1: **não duplique achados** — registre o achado uma
+vez na Parte 1 e referencie-o na CAT-4 com o artigo da LGPD correspondente.
+
+## Relatório
+
+Entregue um relatório único com:
+
+1. **Sumário executivo** — contagem de achados por severidade em cada frente e o veredito de
+   conformidade LGPD.
+2. **Achados críticos primeiro**, para eu saber o que atacar antes.
+3. **Segurança técnica** — achados da Parte 1 (severidade, `arquivo:linha`, correção).
+4. **Conformidade LGPD** — achados por categoria, no formato de
+   `.claude/skills/lgpd-checker/references/report-template.md`, com artigo citado.
+5. **Pontos positivos** — o que já está correto e conforme.
+6. **Plano de ação** em ordem de prioridade.
+
+Se faltar código para avaliar alguma categoria, diga explicitamente
+("Não foi possível avaliar [CAT-X] — arquivos de [tipo] não encontrados") em vez de presumir.
+
+## Onde gravar o relatório
+
+Grave o relatório em `docs/investigacoes/<yyyy-mm-dd>-<slug>.md` — `<yyyy-mm-dd>` é a data atual e
+`<slug>` resume o tema auditado. **Não** grave em `docs/bugs/`: aquela pasta é só para defeito com
+sintoma reproduzível, causa-raiz e correção. Se a auditoria virar trabalho de correção, o plano
+vai para `docs/plans/`.

package/templates/commands/auditar-ui.md

@@ -0,0 +1,38 @@
+---
+description: Navega a aplicação via Playwright MCP e audita UX/UI e/ou acessibilidade (a11y), gerando um relatório por tela e severidade.
+---
+
+# Auditoria de interface via navegador
+
+Usando o **MCP do Playwright**, abra o navegador **na minha tela** (para que eu acompanhe a navegação) e audite a aplicação.
+
+## Parâmetros
+
+Podem vir em `$ARGUMENTS`:
+
+$ARGUMENTS
+
+Preciso de quatro coisas. Para o que **não** veio em `$ARGUMENTS`, **pare e me pergunte antes de abrir o navegador**, oferecendo o exemplo como valor padrão que eu posso aceitar ou substituir:
+
+- **Lente da auditoria:** `ux` (UX/UI), `a11y` (acessibilidade) ou `tudo` (as duas) — padrão: `tudo`.
+- **URL** da aplicação (ex.: `http://localhost:3000`)
+- **Usuário** para login (ex.: `admin@admin.com.br`)
+- **Senha** para login (ex.: `admin`)
+
+Só prossiga depois que eu confirmar. Se `$ARGUMENTS` já trouxer os dados, use-os diretamente sem perguntar.
+
+## Passos
+
+1. Faça login e navegue por **todas** as telas, clicando em todos os menus e botões.
+2. Para cada tela, audite conforme a lente escolhida:
+   - **UX/UI** — clareza e consistência visual, hierarquia, feedback das ações, estados de vazio/erro/carregamento, fluxos confusos, responsividade.
+   - **a11y (WCAG AA)** — contraste de cores, uso correto de ARIA e roles, navegação por teclado (tab order, foco visível, atalhos), textos alternativos em imagens, labels em formulários, hierarquia de headings e foco em modais.
+3. Classifique cada achado por severidade — **CRÍTICO** (bloqueia o uso), **SÉRIO**, **MODERADO**, **MENOR** — citando o critério **WCAG** quando for um achado de a11y.
+4. Compile um **relatório único**, agrupado por **tela** e **severidade**, com a correção recomendada de cada item. Não altere código — apenas reporte o que precisa ser criado ou melhorado.
+
+## Onde gravar o relatório
+
+Grave o relatório em `docs/investigacoes/<yyyy-mm-dd>-<slug>.md` — `<yyyy-mm-dd>` é a data atual e
+`<slug>` resume o tema auditado. **Não** grave em `docs/bugs/`: aquela pasta é só para defeito com
+sintoma reproduzível, causa-raiz e correção. Se a auditoria virar trabalho de correção, o plano
+vai para `docs/plans/`.

package/templates/commands/codigo-morto.md

@@ -0,0 +1,22 @@
+---
+description: Varre o projeto em busca de código morto (imports, exports, funções e arquivos não usados) e propõe remoção.
+---
+
+# Caça ao código morto
+
+Escopo (opcional — pasta ou módulo): $ARGUMENTS
+
+Passos:
+
+1. Varra o projeto procurando: imports não utilizados, exports sem consumidores, funções/variáveis/classes nunca referenciadas, arquivos órfãos e dependências declaradas mas não usadas.
+2. Prefira ferramentas já disponíveis na stack (ex.: linter, `knip`, `ts-prune`, `depcheck`, `vulture`, analisadores nativos). **Não instale nada novo** sem me perguntar.
+3. Para cada achado, classifique a confiança: **ALTA** (claramente morto), **MÉDIA** (pode ser usado via reflexão/dinâmica/rota/teste), **BAIXA** (suspeito). Cuidado com APIs públicas, entrypoints, plugins e código acessado por string.
+4. Apresente a lista agrupada por confiança e **pergunte o que devo remover**. Não apague nada de **MÉDIA/BAIXA** sem confirmação.
+5. Após remover, rode build e testes para garantir que nada quebrou.
+
+## Onde gravar o relatório
+
+Grave o relatório em `docs/investigacoes/<yyyy-mm-dd>-<slug>.md` — `<yyyy-mm-dd>` é a data atual e
+`<slug>` resume o tema auditado. **Não** grave em `docs/bugs/`: aquela pasta é só para defeito com
+sintoma reproduzível, causa-raiz e correção. Se a auditoria virar trabalho de correção, o plano
+vai para `docs/plans/`.

package/templates/commands/configurar-auto-tag.md

@@ -0,0 +1,185 @@
+---
+description: Detecta o padrão de versionamento do projeto (qualquer stack, inclusive Delphi) e gera a GitHub Action que cria a tag automaticamente quando a versão chega na main. Separa versionar (humano) de taguear/deployar (automático).
+argument-hint: "[branch-de-producao]"
+---
+
+# /configurar-auto-tag — Auto-tag no merge para a branch de produção
+
+Você vai **configurar a automação de tag** deste repositório: descobrir **como o versionamento já funciona
+aqui** (Node/JS-TS, .NET, Delphi, Flutter, Python, arquivo `VERSION`, etc.) e gerar uma **GitHub Action** que
+**cria a tag automaticamente** quando um novo número de versão chega na branch de produção (`main` por padrão).
+
+O objetivo é separar dois papéis:
+
+- **Versionar** — ação humana (o comando `/versao`), com aprovação de versão e changelog. **Sem tag, sem push.**
+- **Taguear/deployar** — ação automática (esta Action), disparada quando o arquivo de versão muda na `main`.
+
+A **tag é a fonte única do release** e a criação é **idempotente** por versão (nunca recria uma tag existente).
+
+> **🚦 Há um GATE de aprovação obrigatório** antes de escrever qualquer arquivo. Este comando **não faz push**
+> e **não cria tags manualmente** — ele só instala a automação e a documentação.
+
+## Uso
+
+- `/configurar-auto-tag` — usa `main` como branch de produção.
+- `/configurar-auto-tag <branch>` — usa a branch informada (ex.: `master`, `release`) como alvo da tag.
+
+## Passo 0 — Pré-checagem (somente leitura)
+
+1. Confirme que é um repositório git com remoto no **GitHub** (`git remote -v`). Se não for GitHub, avise que
+   a Action de GitHub Actions não se aplica e **pergunte** como o usuário quer prosseguir (GitLab CI, etc.).
+2. Descubra a **branch de produção** real: use o argumento, senão a branch padrão do remoto
+   (`git symbolic-ref --short refs/remotes/origin/HEAD` ou olhe `main`/`master`). **Confirme com o usuário.**
+3. Verifique se já existe `.github/workflows/auto-tag.yml`. Se existir, leia e trate como **ajuste**, não
+   sobrescrita cega.
+
+## Passo 1 — Detectar a(s) fonte(s) de verdade da versão
+
+Investigue o projeto e **identifique TODAS as fontes da versão** (não assuma; confirme lendo). Para cada uma,
+registre: o **arquivo**, o **campo/chave**, o **formato** (`X.Y.Z` ou `X.Y.Z.W`) e **como extrair a versão via
+shell** (você vai embutir isso na Action). Por stack:
+
+- **Node / React (Vite/Next) / qualquer JS-TS:** `package.json` → campo `.version`.
+  - Extração: `jq -r '.version' package.json`
+  - Mobile Expo: `app.json` → `.expo.version` (`jq -r '.expo.version' app.json`).
+- **.NET / C#:** `*.csproj` (`<Version>`, senão `<FileVersion>`), `Directory.Build.props`.
+  - Extração: `grep -oPm1 '(?<=<Version>)[^<]+' App.csproj` (ajuste a tag lida).
+- **Delphi:** o número costuma viver no `*.dproj` (chaves `VerInfo_Keys` com `FileVersion`/`ProductVersion` e/ou
+  os campos `MajorVersion`/`MinorVersion`/`Release`/`Build`) **e/ou** em constante `.pas` (ex.: `cVersao`, `About`).
+  Escolha **uma** fonte estável como canônica e leia o **arquivo:linha** exato.
+  - Extração de `FileVersion` no `.dproj`: `grep -oPm1 'FileVersion=\K[0-9.]+' Projeto.dproj`
+  - Ou montando de partes: leia `MajorVersion`/`MinorVersion`/`Release`/`Build` com `grep`/`sed` e concatene.
+  - Ou de constante `.pas`: `grep -oPm1 "cVersao\s*=\s*'\K[0-9.]+" Sobre.pas`
+- **Flutter / Dart:** `pubspec.yaml` → `version:` (`grep -oPm1 '(?<=^version: )[0-9.+]+' pubspec.yaml`).
+- **Python:** `pyproject.toml` (`[project] version`/`[tool.poetry] version`) ou `__version__`.
+  - Extração: `grep -oPm1 '(?<=^version = ")[^"]+' pyproject.toml`.
+- **Genérico:** arquivo `VERSION` na raiz (`cat VERSION`), constante `VERSION`/`APP_VERSION`.
+
+> Se não encontrar nenhuma fonte de versão, **pergunte ao usuário** onde a versão é registrada antes de gerar a
+> Action — sem isso a Action não tem o que ler.
+
+Determine ainda:
+
+- **Repo único ou monorepo/multi-app.** Isso define o **formato da tag**:
+  - App único → tag `v<versão>` (ex.: `v1.4.0`).
+  - Monorepo → tag `<app>-v<versão>` (ex.: `web-v1.4.0`), com um arquivo de versão por app.
+- **Comando `/versao` já instalado?** Se sim, é ele quem faz o bump. Se não, sugira instalá-lo/rodá-lo para
+  produzir o commit de release que dispara esta Action.
+- **Como o deploy de produção é disparado** por cada tag (`deploy-*.yml` no GitHub Actions? webhook de app
+  externo tipo Expo/EAS?). Isso decide se o `RELEASE_PAT` é necessário (veja Passo 4).
+
+## Passo 2 — Montar a Action (rascunho, sem gravar ainda)
+
+Gere `.github/workflows/auto-tag.yml` seguindo este molde, **adaptando a extração da versão** à fonte detectada:
+
+```yaml
+name: Auto-tag na <BRANCH_PRODUCAO>
+
+on:
+  push:
+    branches: [<BRANCH_PRODUCAO>]
+    paths:
+      - <ARQUIVO(S)_DE_VERSAO>   # ex.: 'package.json' ou 'apps/**/package.json' ou 'src/Projeto.dproj'
+
+permissions:
+  contents: write
+
+jobs:
+  auto-tag:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.RELEASE_PAT || github.token }}
+
+      - name: Criar tag se a versão for nova
+        run: |
+          set -euo pipefail
+          # >>> AJUSTE a linha abaixo para extrair a versão da fonte de verdade detectada <<<
+          VERSION="$(jq -r '.version' package.json)"
+          if [ -z "$VERSION" ] || [ "$VERSION" = "null" ]; then
+            echo "Não consegui ler a versão"; exit 1
+          fi
+          TAG="v$VERSION"            # monorepo: TAG="<app>-v$VERSION"
+          if git rev-parse -q --verify "refs/tags/$TAG" >/dev/null; then
+            echo "Tag $TAG já existe — nada a fazer (idempotente)."
+            exit 0
+          fi
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "$TAG" -m "Release $TAG"
+          git push origin "$TAG"
+```
+
+Regras ao adaptar o molde:
+
+- **Substitua `<BRANCH_PRODUCAO>`** pela branch confirmada no Passo 0.
+- **`paths:`** deve listar **exatamente** o(s) arquivo(s) de versão detectados — assim a Action só roda quando a
+  versão muda de fato, não a cada push.
+- **Troque a linha de `VERSION=`** pela extração correta da stack (jq/grep/sed/cat conforme o Passo 1). Para
+  Delphi/.NET, use o `grep -oP`/`sed` adequado ao XML/`.pas`; **não** use `jq` fora de JSON.
+- **Monorepo:** faça um loop pelos apps (uma tag por app), lendo a versão de cada arquivo e montando
+  `<app>-v<versão>`, com a checagem de idempotência por tag dentro do loop.
+- **Idempotência:** a verificação `git rev-parse --verify refs/tags/$TAG` é obrigatória — nunca recrie tag.
+- Se a Action já existia, **preserve** ajustes locais e só reconcilie o necessário.
+
+## Passo 3 — 🚦 GATE de aprovação (obrigatório)
+
+Antes de escrever qualquer arquivo, apresente ao usuário:
+
+- a **branch de produção** e o **formato de tag** escolhidos (`v<versão>` ou `<app>-v<versão>`);
+- a(s) **fonte(s) de versão** e a **linha de extração** que vai para a Action;
+- o **conteúdo completo** do `auto-tag.yml` proposto;
+- se **`RELEASE_PAT`** será necessário (Passo 4) e por quê.
+
+**Peça aprovação explícita.** Não grave nada sem o "ok".
+
+## Passo 4 — Documentar o `RELEASE_PAT` (não crie segredo no código)
+
+Explique ao usuário, e registre na doc do Passo 5, a **pegadinha do token**:
+
+- O **`GITHUB_TOKEN` padrão NÃO dispara outras Actions.** Se o deploy de produção é uma **GitHub Action**
+  (`deploy-*.yml`) disparada pela criação da tag, a Action de auto-tag **precisa** empurrar a tag usando um
+  **`RELEASE_PAT`** (por isso o `token: ${{ secrets.RELEASE_PAT || github.token }}` no checkout).
+- Se o deploy é disparado por **webhook de app externo** (ex.: Expo/EAS), o PAT é **desnecessário**.
+- Como criar: **fine-grained PAT** com _Contents: Read and write_ no repositório (ou classic com escopo `repo`),
+  salvo em **Settings → Secrets and variables → Actions** como **`RELEASE_PAT`**.
+- **Nunca** coloque o token em arquivo versionado — só como secret do repositório.
+
+## Passo 5 — Gravar artefatos (somente após aprovação)
+
+1. Escreva `.github/workflows/auto-tag.yml`.
+2. Crie/atualize `docs/versionamento-tags.md` explicando:
+   - que **a tag aponta um commit, não uma branch** — o commit do release (com os workflows de deploy) precisa
+     estar na branch de produção **antes/junto** da criação da tag;
+   - o **fluxo completo** de release (abaixo);
+   - o funcionamento da Action e a **pegadinha `GITHUB_TOKEN` × `RELEASE_PAT`**;
+   - uma **tabela**: app → arquivo de versão → formato da tag → workflow de deploy disparado.
+3. Se houver comandos/docs antigos que mandavam **criar tag** ou **dar push de tag** manualmente, ajuste-os para
+   o novo fluxo (a tag agora é responsabilidade exclusiva da Action).
+
+### Fluxo de release resultante (documente assim)
+
+```
+/versao  →  push do commit de release  →  merge/entrega na branch de produção
+        →  Action auto-tag cria a tag  →  workflow de deploy dispara pela tag  →  produção
+```
+
+## Passo 6 — Verificar e finalizar (sem push)
+
+- Valide a sintaxe YAML do workflow (indentação, `on.push.paths`, `permissions`).
+- **Não** rode `git push` e **não** crie tags manualmente. Deixe as alterações prontas (working tree) e informe
+  o fluxo manual de commit/push ao usuário — ou, se o `/git-commit-push` estiver instalado, sugira usá-lo.
+- Sugira um commit semântico como `chore: Configura auto-tag na <branch> via GitHub Actions`.
+
+## Guardrails
+
+- **NUNCA** `git push`; **NUNCA** crie tag local — a tag é responsabilidade exclusiva da Action.
+- **Sempre** confirmar branch, fonte de versão e o YAML no GATE antes de gravar.
+- **Replicar o padrão do projeto** (formato de versão e de tag) — nunca impor um novo.
+- **Idempotência**: a Action nunca recria uma tag existente; para refazer deploy, use o gatilho manual do
+  workflow de deploy, não recrie a tag.
+- **`main`/branch de produção = deploy de produção** — trate-a como produção.
+- Sem `RELEASE_PAT`, tags criadas pelo `GITHUB_TOKEN` **não** disparam outras Actions de deploy; documente isso.
+- Documentação em **pt-BR**.