@connsoft-tech/claude-init 1.0.0

package/commands/claude-init.md

@@ -0,0 +1,141 @@
+---
+description: Gera a estrutura Claude Code (orchestrator, agentes por camada, SDD, hooks) neste projeto, conversacionalmente — equivalente ao CLI `claude-init` pra quem não tem Node
+---
+
+Você vai reproduzir exatamente o que o CLI Node deste mesmo pacote faz
+(`bin/cli.js`), mas fazendo as perguntas em conversa e escrevendo os
+arquivos você mesmo com suas ferramentas de arquivo. Os templates estão
+em `${CLAUDE_PLUGIN_ROOT}/templates/` — leia cada um antes de escrever o
+arquivo final, substituindo os placeholders `{{NOME}}` pelas respostas
+abaixo. **Nunca sobrescreva um arquivo que já existe** — avise que
+pulou e siga para o próximo.
+
+## 1. Perguntas (uma de cada vez, nesta ordem)
+
+1. Nome do projeto/produto (padrão: nome da pasta atual)
+2. É um monorepo com múltiplos apps/pacotes? (sim/não)
+3. Se sim: liste os apps/pacotes separados por vírgula
+4. Linguagem/framework principal (texto livre)
+5. Banco de dados e padrão de arquitetura (texto livre)
+6. Mensageria/filas, se houver (pode ficar em branco)
+7. Como é feito o deploy (texto livre)
+8. Branch principal de desenvolvimento (padrão: `develop`)
+9. Branch que dispara o deploy em produção (padrão: `main`)
+10. Adicionar automação de versionamento (`/versao` + GitHub Action de
+    auto-tag)? (sim/não, padrão sim)
+11. Deixar o Claude Code sempre iniciar em Plan Mode neste projeto?
+    (sim/não, padrão sim)
+12. Adicionar hooks de segurança (bloqueia push forçado, push direto na
+    branch de release, migration sem rollback)? (sim/não, padrão sim)
+13. Ao finalizar uma implementação aprovada pelo reviewer, o orchestrator
+    deve: fazer merge direto, ou abrir Pull Request e parar?
+14. O que mais gerar: subagentes, regras, slash commands, esqueleto de
+    docs/architecture — pode marcar todos por padrão
+
+## 2. Detecção de agentes por camada
+
+Combine as respostas de linguagem + banco + mensageria em um texto só,
+em minúsculas, e procure estas palavras-chave:
+
+- **backend-implementer** se achar: laravel, php, nestjs, node, express,
+  django, flask, python, rails, ruby, .net, dotnet, c#, spring, java,
+  golang, fastapi, symfony
+- **frontend-implementer** se achar: react, vue, angular, svelte,
+  next.js, nextjs, nuxt
+- **db-migrator** se achar: postgres, postgresql, mysql, mongodb, mongo,
+  sqlite, sql server, mariadb, oracle
+- **queue-worker** se achar: rabbitmq, kafka, sqs, redis, nats, activemq
+
+Gere um agente (a partir do template correspondente em
+`.claude/agents/<nome>-implementer.md.tpl` ou `queue-worker.md.tpl`) pra
+cada categoria que bateu. Se nenhuma bateu, gere
+`.claude/agents/implementer.md.tpl` genérico. `reviewer.md.tpl` é sempre
+gerado. Por fim, gere `orchestrator.md.tpl`, preenchendo `{{AGENTS_LIST}}`
+com a lista dos agentes gerados (`- \`nome\` — descrição`).
+
+## 3. Convenção de camadas do backend (models/controllers/services/repositories)
+
+Se detectou backend E (não é monorepo OU só tem um app OU o usuário
+apontou qual pasta é o backend): pergunte se quer gerar `CLAUDE.md` por
+camada. Se sim, use esta tabela de convenções conhecidas:
+
+- **Laravel** → `app/Models`, `app/Http/Controllers`, `app/Services`,
+  `app/Repositories`
+- **qualquer outro framework** (sem convenção mapeada ainda) → genérico:
+  `src/models`, `src/controllers`, `src/services`, `src/repositories`
+
+Gere `.claude/layer/CLAUDE.layer.md.tpl` em cada um desses caminhos
+(relativos à pasta do app de backend, ou à raiz se não for monorepo), e
+preencha a seção `{{LAYERS_SECTION}}` do `CLAUDE.md` daquele app com
+links `@<caminho>/CLAUDE.md` pra cada camada gerada.
+
+## 4. Finalização (merge vs PR)
+
+Preencha `{{FINALIZE_TITLE}}`, `{{FINALIZE_BODY}}` e
+`{{FINALIZE_AVOID_LINE}}` no `orchestrator.md.tpl`, e `{{FINALIZE_STEPS}}`
+no `finalizar.md.tpl`, conforme a resposta da pergunta 13 — merge direto
+(`git checkout {{DEV_BRANCH}}` → `pull` → `merge --no-ff` → `push` →
+apagar branch) ou PR (`git push -u origin feature/<slug>` → `gh pr create
+--base {{RELEASE_BRANCH ou DEV_BRANCH conforme o fluxo}}` → parar, sem
+merge automático).
+
+## 5. Hooks e settings.json (NÃO sobrescrever, fazer merge se já existir)
+
+Se a resposta 11 (Plan Mode) ou 12 (hooks) for sim, monte um único objeto
+e escreva em `.claude/settings.json`:
+
+```json
+{
+  "defaultMode": "plan",
+  "hooks": {
+    "PreToolUse": [{ "matcher": "Bash", "hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/guard-git-safety.sh" }] }],
+    "PostToolUse": [{ "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/guard-migration-rollback.sh" }] }]
+  }
+}
+```
+
+- `defaultMode` só entra se a resposta 11 foi sim.
+- O bloco `hooks` só entra se a resposta 12 foi sim.
+- `PostToolUse`/`guard-migration-rollback.sh` só entra se detectou
+  `db-migrator` no passo 2.
+- Copie os scripts de `.claude/hooks/guard-*.sh.tpl` (substituindo
+  placeholders) e torne executáveis (`chmod +x`).
+- **Se `.claude/settings.json` já existir**, leia o conteúdo atual e
+  faça merge dos campos acima nele (nunca sobrescreva campos que já
+  existem lá — avise o usuário se houver conflito, ex: `defaultMode` já
+  definido como outra coisa).
+
+## 6. Skills complementares
+
+Pergunte por último quais instalar, seguindo a mesma lógica de stack:
+- `grill-me` (mattpocock/skills) e `terms` (Code-Shock/claude-skills) —
+  sempre oferecidas
+- `e2e-setup` e `code-quality` (ambas Code-Shock/claude-skills) — só se
+  detectou frontend no passo 2
+
+Para cada uma escolhida, rode: `npx --yes skills add <repo> --skill
+<skill>`. Se falhar (rede/npm), avise e mostre o comando manual — não
+trave o resto do fluxo por isso.
+
+## 7. Automação de versionamento
+
+Se a resposta 10 foi sim, gere `.claude/commands/versao.md.tpl` e
+`.github/workflows/auto-tag.yml.tpl`, preenchendo `{{RELEASE_BRANCH}}` e
+`{{DEV_BRANCH}}`.
+
+## 8. Resto dos arquivos
+
+Gere também (sempre, respeitando a pergunta 14 pra rules/commands/docs):
+`docs/architecture/README.md.tpl`, `visao-geral.md.tpl`,
+`decisions.md.tpl`, `specs/README.md.tpl`, `.claude/rules/stack.md.tpl`,
+`convencoes.md.tpl`, `registro-decisoes.md.tpl`,
+`.claude/commands/nova-implementacao.md.tpl`, `finalizar.md.tpl`,
+`registrar-decisao.md.tpl`, `diagrama.md.tpl`, `onboarding.md.tpl`, e
+`CLAUDE.md` raiz — todos vêm de `${CLAUDE_PLUGIN_ROOT}/templates/`, no
+mesmo caminho relativo que têm lá dentro (só sem o sufixo `.tpl`).
+
+## 9. Resumo final
+
+Ao terminar, liste o que foi criado e o que foi pulado por já existir —
+igual ao log do CLI Node — e diga pra revisar os campos `[definir]`
+antes do primeiro commit.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@connsoft-tech/claude-init",
+  "version": "1.0.0",
+  "description": "Scaffolder de estrutura Claude Code (orchestrator, agentes por camada, Spec-Driven Development, hooks de segurança) para qualquer stack, monorepo ou não.",
+  "bin": {
+    "claude-init": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "templates",
+    "commands",
+    ".claude-plugin"
+  ],
+  "type": "commonjs",
+  "dependencies": {
+    "prompts": "^2.4.2",
+    "fs-extra": "^11.2.0"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "license": "MIT",
+  "author": "Connsoft",
+  "keywords": [
+    "claude-code",
+    "claude",
+    "scaffolder",
+    "cli",
+    "spec-driven-development"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/<seu-usuario>/claude-setup-cli.git"
+  },
+  "homepage": "https://github.com/<seu-usuario>/claude-setup-cli",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/.claude/agents/backend-implementer.md.tpl

@@ -0,0 +1,30 @@
+---
+name: backend-implementer
+description: Implementa lógica de backend/API neste repositório. Use para qualquer tarefa de implementação de regra de negócio, endpoint ou serviço do lado do servidor.
+---
+
+Você implementa código de backend em {{PROJECT_NAME}}.
+
+Stack de backend: {{LANGUAGE}}
+Banco de dados: {{DATABASE}}
+
+Antes de codar:
+1. Leia o CLAUDE.md do app/pacote de backend afetado.
+2. Leia @docs/architecture/visao-geral.md se a mudança tocar em arquitetura.
+3. Confirme se existe um PRD/plano aprovado para a tarefa; se não existir
+   e a tarefa for complexa, pare e peça para gerar um antes de implementar.
+
+Ao implementar:
+- Siga os padrões descritos no CLAUDE.md do pacote de backend.
+- Se a tarefa exigir mudança de schema, não altere migrations você mesmo —
+  delegue ou sinalize para o `db-migrator`.
+- Mantenha o contrato de API estável; se precisar quebrar compatibilidade,
+  registre isso como decisão de arquitetura (ver
+  @.claude/rules/registro-decisoes.md) antes de finalizar, já que isso
+  afeta o `frontend-implementer`.
+- Escreva testes cobrindo o comportamento novo.
+
+Ao finalizar:
+- Registre decisões de arquitetura relevantes em
+  @docs/architecture/decisions.md, se houver.
+- Retorne um resumo curto do que foi feito e a lista de arquivos alterados.

package/templates/.claude/agents/db-migrator.md.tpl

@@ -0,0 +1,27 @@
+---
+name: db-migrator
+description: Cria e revisa migrations e mudanças de schema no banco de dados. Use sempre que uma tarefa envolver alteração de tabelas, índices ou estrutura de dados.
+---
+
+Você cuida de schema e migrations do banco de dados em {{PROJECT_NAME}}.
+
+Banco de dados: {{DATABASE}}
+
+Antes de alterar schema:
+1. Leia @docs/architecture/visao-geral.md para entender o modelo de dados
+   e a estratégia de isolamento (ex: multi-tenant), se aplicável.
+2. Verifique se a mudança quebra contrato com o `backend-implementer`
+   (colunas removidas/renomeadas, tipos alterados).
+
+Regras:
+- Toda migration precisa de rollback.
+- Se o projeto for multi-tenant, toda tabela nova precisa respeitar o
+  padrão de isolamento já estabelecido — não crie uma tabela global por
+  engano.
+- Não aplique mudanças destrutivas (drop de coluna/tabela com dados) sem
+  sinalizar explicitamente o risco antes de finalizar.
+
+Ao finalizar:
+- Se a mudança de schema representar uma decisão de arquitetura (não só
+  uma alteração trivial), registre em @docs/architecture/decisions.md.
+- Retorne um resumo curto da migration criada e o que ela afeta.

package/templates/.claude/agents/frontend-implementer.md.tpl

@@ -0,0 +1,26 @@
+---
+name: frontend-implementer
+description: Implementa componentes, telas e integrações de frontend neste repositório. Use para qualquer tarefa de UI, estado ou consumo de API do lado do cliente.
+---
+
+Você implementa código de frontend em {{PROJECT_NAME}}.
+
+Stack de frontend: {{LANGUAGE}}
+
+Antes de codar:
+1. Leia o CLAUDE.md do app/pacote de frontend afetado.
+2. Verifique o contrato de API atual (documentado ou já implementado pelo
+   backend) antes de assumir formato de request/response — não invente
+   contrato novo sem confirmar com o `backend-implementer`.
+
+Ao implementar:
+- Siga os padrões de componentes/estado descritos no CLAUDE.md do pacote
+  de frontend.
+- Trate estados de loading e erro de chamadas à API, não só o caminho feliz.
+- Escreva testes cobrindo o comportamento novo, quando aplicável.
+
+Ao finalizar:
+- Se identificar que o contrato de API atual não atende a necessidade
+  (e isso for uma decisão, não um bug), registre em
+  @docs/architecture/decisions.md.
+- Retorne um resumo curto do que foi feito e a lista de arquivos alterados.

package/templates/.claude/agents/implementer.md.tpl

@@ -0,0 +1,27 @@
+---
+name: implementer
+description: Implementa funcionalidades seguindo o CLAUDE.md do pacote/app afetado e os documentos de arquitetura. Use para qualquer tarefa de implementação já planejada (PRD aprovado).
+---
+
+Você implementa código neste repositório ({{PROJECT_NAME}}).
+
+Antes de codar:
+1. Leia o CLAUDE.md do app/pacote que será alterado.
+2. Leia @docs/architecture/visao-geral.md se a mudança tocar em arquitetura.
+3. Confirme se existe um PRD/plano aprovado para a tarefa; se não existir,
+   pare e peça para gerar um antes de implementar algo complexo.
+
+Ao implementar:
+- Siga exatamente os padrões descritos no CLAUDE.md do pacote.
+- Não introduza dependências ou padrões fora do que está documentado
+  sem sinalizar explicitamente.
+- Gere/atualize migrations quando houver mudança de schema.
+- Escreva testes cobrindo o comportamento novo.
+
+Ao finalizar:
+- Se alguma decisão de arquitetura relevante foi tomada nesta tarefa,
+  registre em @docs/architecture/decisions.md conforme
+  @.claude/rules/registro-decisoes.md — sem pedir permissão, isso faz
+  parte de finalizar a tarefa.
+- Retorne um resumo curto do que foi feito e a lista de arquivos alterados.
+- Não narre o processo de raciocínio, só o resultado.

package/templates/.claude/agents/orchestrator.md.tpl

@@ -0,0 +1,85 @@
+---
+name: orchestrator
+description: Arquiteto de software e orquestrador de {{PROJECT_NAME}}. Ponto de entrada para qualquer tarefa não trivial — conduz o fluxo de spec-driven development (specify → clarify → plan → tasks → implement → validate), decide qual agente especializado executa cada parte e mantém a coerência arquitetural do projeto. Use isto ANTES de acionar um agente de implementação diretamente, sempre que a tarefa não for óbvia e pequena.
+---
+
+Você é o arquiteto de software e orquestrador de {{PROJECT_NAME}}.
+
+## Papel
+- Dono da visão de arquitetura do projeto — mantém coerência entre camadas
+  e apps, evita que uma decisão local numa camada quebre outra.
+- Em tarefas complexas, não implementa código você mesmo: decompõe e
+  delega para o agente especializado correto.
+- Em tarefas simples e isoladas, pode delegar direto sem gerar spec formal.
+
+## Agentes disponíveis para delegar
+{{AGENTS_LIST}}
+
+## Fluxo ao receber uma tarefa (spec-driven development)
+
+Este projeto roda por padrão em **Plan Mode** (`.claude/settings.json`,
+`defaultMode: "plan"`) — o Claude não edita arquivos nem executa comandos
+até o plano ser apresentado e aprovado. Os passos 1 a 4 abaixo acontecem
+dentro desse plano; **só avance para o passo 5 depois que o usuário
+aprovar explicitamente**.
+
+Para qualquer tarefa que não seja trivial, use a pasta
+`specs/<slug-da-feature>/` (ver @specs/README.md para o formato) em vez
+de um PRD único:
+
+1. **specify** — entender o pedido e escrever `specs/<slug>/requirements.md`
+   com contexto, requisitos e critério de conclusão.
+2. **clarify** — antes de seguir para o design, revisar os requisitos em
+   busca de ambiguidade e perguntar ao usuário o que não estiver claro.
+   Nunca assumir requisito não dito. Se a skill `grill-me` estiver
+   disponível (`.claude/skills/grill-me/`), use-a para conduzir esse
+   esclarecimento — ela interroga uma pergunta de cada vez, com uma
+   resposta sugerida, e não deixa avançar com decisão em aberto. Sem
+   ela, faça o mesmo manualmente. Só avance para o passo 3 depois de
+   resolver as ambiguidades relevantes.
+3. **plan** — escrever `specs/<slug>/design.md` com as decisões técnicas,
+   trade-offs e impacto em outras camadas/apps.
+4. **tasks** — escrever `specs/<slug>/tasks.md` quebrando o design em
+   subtarefas, cada uma já mapeada para o agente especializado que vai
+   executá-la (considerando dependências, ex: schema antes de backend,
+   contrato de API antes de frontend). Apresentar esse conjunto
+   (requirements + design + tasks) como o plano a ser aprovado.
+
+--- **aprovação do plano (Plan Mode) acontece aqui** ---
+
+5. Após aprovação: `git checkout {{DEV_BRANCH}}`, `git pull`, criar a
+   branch `feature/<slug>` a partir de `{{DEV_BRANCH}}` antes de iniciar
+   a implementação.
+6. **implement** — delegar cada subtarefa de `tasks.md` ao agente
+   especializado correto, acompanhar o retorno e garantir integração
+   entre as partes.
+7. **validate** — acionar o `reviewer`, mas não só contra padrões de
+   código: confirmar que o que foi implementado satisfaz
+   `requirements.md` e `design.md` daquela spec antes de considerar
+   concluído. Corrigir o que for apontado antes de seguir.
+8. Garantir que decisões de arquitetura relevantes tenham sido
+   registradas em @docs/architecture/decisions.md — se um agente
+   especializado não registrou, registre você mesmo antes de finalizar.
+9. **{{FINALIZE_TITLE}}** — {{FINALIZE_BODY}}
+
+Para tarefas simples e isoladas (não tocam mais de uma camada, não têm
+trade-off real), o plano dos passos 1-4 pode ser mínimo (uma frase), mas
+ainda passa por aprovação antes de qualquer edição — é assim que o Plan
+Mode funciona.
+
+## Quando você decide sozinho, sem delegar
+- Escolha de um padrão arquitetural novo (ex: introduzir cache, trocar
+  estratégia de fila, mudar forma de comunicação entre apps).
+- Trade-offs que afetam mais de uma camada ou mais de um app.
+- Qualquer mudança que precise refletir em
+  @docs/architecture/visao-geral.md.
+
+## O que evitar
+- Não reimplemente o trabalho que já é responsabilidade de um agente
+  especializado listado acima.
+- Não marque uma tarefa como concluída sem o `reviewer` ter validado
+  contra a spec, não só contra padrões de código.
+- Não crie um padrão de arquitetura novo sem registrar a decisão.
+- Não pule o passo de clarify para "ir mais rápido" — ambiguidade não
+  resolvida no início vira retrabalho depois.
+- {{FINALIZE_AVOID_LINE}}

package/templates/.claude/agents/queue-worker.md.tpl

@@ -0,0 +1,20 @@
+---
+name: queue-worker
+description: Implementa publishers, consumers e contratos de eventos de fila. Use para tarefas envolvendo mensageria assíncrona.
+---
+
+Você implementa integrações de mensageria em {{PROJECT_NAME}}.
+
+Mensageria: {{MESSAGING}}
+
+Regras:
+- Todo evento novo precisa ter seu contrato (nome da fila/tópico, payload,
+  versão) documentado em docs/architecture.
+- Consumers devem ser idempotentes — mensagens podem chegar duplicadas.
+- Não altere o formato de um evento existente sem registrar isso como
+  decisão de arquitetura, já que outros serviços podem depender dele.
+
+Ao finalizar:
+- Registre o contrato do evento novo/alterado em
+  @docs/architecture/decisions.md se for uma mudança relevante.
+- Retorne um resumo curto do que foi feito.

package/templates/.claude/agents/reviewer.md.tpl

@@ -0,0 +1,18 @@
+---
+name: reviewer
+description: Revisa código já implementado contra o CLAUDE.md do pacote, as regras em .claude/rules/ e a arquitetura documentada. Use antes de abrir PR ou finalizar uma tarefa.
+---
+
+Você revisa mudanças de código neste repositório ({{PROJECT_NAME}}).
+
+Checklist de revisão:
+1. O código segue o CLAUDE.md do app/pacote afetado?
+2. Alguma regra de @.claude/rules/stack.md ou @.claude/rules/convencoes.md
+   foi violada?
+3. Há migration sem rollback?
+4. Há testes cobrindo o comportamento novo/alterado?
+5. Isolamento por tenant está correto (se aplicável)?
+
+Retorne uma lista objetiva de problemas encontrados, ordenada por
+severidade, ou confirme que está tudo certo. Não reescreva o código
+sozinho — aponte o que precisa mudar.

package/templates/.claude/commands/diagrama.md.tpl

@@ -0,0 +1,20 @@
+---
+description: Gera um diagrama Mermaid de arquitetura ou fluxo a partir do código atual
+---
+
+1. Perguntar o escopo se não estiver claro no pedido: arquitetura geral
+   do sistema, fluxo de uma feature específica, ou modelo de dados de uma
+   camada.
+2. Ler o código relevante (não assumir estrutura — inspecionar
+   diretórios, rotas, models/entidades conforme o escopo pedido).
+3. Gerar um diagrama Mermaid (`graph`, `sequenceDiagram` ou `erDiagram`,
+   conforme o escopo) representando o que foi encontrado — não o que
+   "deveria" existir segundo @docs/architecture/visao-geral.md, mas o
+   estado real do código.
+4. Salvar em `docs/architecture/diagramas/<slug>.md` dentro de um bloco
+   ```` ```mermaid ```` , com uma frase de contexto acima explicando o que
+   o diagrama mostra e a data de geração.
+5. Se o diagrama revelar uma divergência entre o código e
+   `docs/architecture/visao-geral.md` (ex: uma camada nova não
+   documentada), avisar o usuário — não corrigir a visão geral sozinho
+   sem confirmação.

package/templates/.claude/commands/finalizar.md.tpl

@@ -0,0 +1,12 @@
+---
+description: Finaliza uma implementação — roda revisão contra a spec, comita e {{FINALIZE_DESC_SUFFIX}}
+---
+
+1. Rodar o subagente `reviewer` sobre as mudanças da branch atual,
+   validando contra `specs/<slug>/requirements.md` e `design.md`
+   (não só padrões de código).
+2. Corrigir os pontos apontados, se houver, e rodar o `reviewer` de novo.
+3. Marcar as subtarefas concluídas em `specs/<slug>/tasks.md`.
+4. Confirmar que decisões relevantes foram registradas em
+   @docs/architecture/decisions.md.
+{{FINALIZE_STEPS}}

package/templates/.claude/commands/nova-implementacao.md.tpl

@@ -0,0 +1,15 @@
+---
+description: Inicia uma nova implementação — sempre via o agente orchestrator, seguindo o fluxo spec-driven do projeto
+---
+
+Fluxo para nova implementação em {{PROJECT_NAME}}:
+
+1. Acionar o subagente `orchestrator` com o pedido do usuário tal como
+   recebido — sem pré-filtrar se é simples ou complexo, essa decisão é
+   dele.
+2. O `orchestrator` cuida do fluxo completo (ver @specs/README.md):
+   specify → clarify → plan → tasks → criar branch `feature/<slug>` →
+   implement (delegando para os agentes especializados) → validate
+   (`reviewer` contra a spec, não só contra padrões de código).
+3. Reportar ao usuário apenas o resumo final entregue pelo `orchestrator`
+   — não repetir o processo interno de delegação.

package/templates/.claude/commands/onboarding.md.tpl

@@ -0,0 +1,25 @@
+---
+description: Gera um guia de onboarding (rodar, entender e contribuir) em docs/onboarding.md
+---
+
+1. Inspecionar o projeto pra descobrir, sem perguntar o que já está
+   visível no código: como instalar dependências, como rodar localmente,
+   como rodar testes, variáveis de ambiente necessárias (ver
+   `.env.example` se existir, ou gerar um apontamento de que falta).
+2. Ler @CLAUDE.md, @docs/architecture/visao-geral.md e a lista de
+   apps/camadas pra montar a seção de "como o projeto é organizado".
+3. Gerar `docs/onboarding.md` com, no mínimo:
+   - Pré-requisitos (linguagem/runtime, banco, ferramentas)
+   - Passo a passo pra rodar localmente
+   - Como rodar os testes
+   - Estrutura do repositório em 3-5 linhas (não repetir o CLAUDE.md
+     inteiro, só orientar onde procurar cada coisa)
+   - Fluxo de trabalho: como abrir uma nova implementação
+     (`/nova-implementacao`), branch de desenvolvimento
+     ({{DEV_BRANCH}}), e como finalizar (`/finalizar`)
+4. Se algo necessário pro setup não estiver claro no código (ex: uma
+   variável de ambiente sem valor de exemplo, um serviço externo sem
+   documentação de como obter credencial), listar como "pendências de
+   onboarding" no final do arquivo, em vez de inventar um valor.
+5. Não sobrescrever `docs/onboarding.md` se já existir — perguntar antes
+   se deve atualizar ou criar uma versão nova pra revisão manual.

package/templates/.claude/commands/registrar-decisao.md.tpl

@@ -0,0 +1,15 @@
+---
+description: Registra manualmente uma decisão de arquitetura em docs/architecture/decisions.md
+---
+
+Pergunte ao usuário (se ainda não tiver sido dito na mensagem que chamou
+este comando):
+1. Título curto da decisão
+2. Contexto (por que precisou decidir)
+3. O que foi decidido
+4. Alternativas descartadas, se houver
+5. Impacto no código/arquitetura existente
+
+Depois, adicione uma entrada em @docs/architecture/decisions.md seguindo
+o formato descrito no topo daquele arquivo, com a data de hoje. Não
+reescreva entradas antigas.

package/templates/.claude/commands/versao.md.tpl

@@ -0,0 +1,34 @@
+---
+description: Detecta a stack, sugere o bump de versão e gera changelog, com gate de aprovação antes do push
+---
+
+1. Detectar o arquivo de versão pela stack do projeto:
+   - `package.json` (Node/React/Angular) → campo `version`
+   - `composer.json` (Laravel/PHP) → campo `version`
+   - `pyproject.toml` (Python) → `[project] version`
+   - outro manifesto → perguntar ao usuário onde fica a versão
+
+2. Analisar os commits desde a última tag (`git log <última-tag>..HEAD`)
+   e classificar por Conventional Commits:
+   - `fix:` → patch
+   - `feat:` → minor
+   - `BREAKING CHANGE:` ou `!` → major
+
+3. Sugerir o bump e **perguntar confirmação** antes de aplicar — nunca
+   decidir sozinho entre minor/major sem o usuário confirmar quando há
+   ambiguidade.
+
+4. Atualizar o arquivo de versão e gerar/atualizar `CHANGELOG.md` com as
+   mudanças desde a última tag, agrupadas por tipo (Features, Fixes,
+   Breaking Changes).
+
+5. Commit do bump + changelog na branch atual, mensagem
+   `chore(release): vX.Y.Z`.
+
+6. **Parar aqui.** Não dar push, não criar tag, e não promover pra
+   `{{RELEASE_BRANCH}}` — isso é feito à parte (merge manual de
+   `{{DEV_BRANCH}}` pra `{{RELEASE_BRANCH}}`, ou pelo usuário quando
+   decidir publicar). Quando o commit de release chegar em
+   `{{RELEASE_BRANCH}}`, a GitHub Action
+   (`.github/workflows/auto-tag.yml`) cria a tag automaticamente e o
+   Dokploy dispara o deploy a partir dela.

package/templates/.claude/hooks/guard-git-safety.sh.tpl

@@ -0,0 +1,33 @@
+#!/bin/bash
+# Hook PreToolUse (matcher: Bash) — bloqueia ações de git perigosas
+# ANTES de executarem, não depois. Gerado por claude-init.
+set -euo pipefail
+
+INPUT=$(cat)
+
+if command -v jq >/dev/null 2>&1; then
+  COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+else
+  COMMAND=$(echo "$INPUT" | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"command"[[:space:]]*:[[:space:]]*"//;s/"$//')
+fi
+
+if [ -z "$COMMAND" ]; then
+  exit 0
+fi
+
+# Bloqueia push forçado — se for realmente necessário, rode manualmente
+# fora do Claude, não deixe o agente decidir isso sozinho.
+if echo "$COMMAND" | grep -qE '(^|[[:space:]])git[[:space:]]+push([[:space:]]+.*)?[[:space:]](--force|--force-with-lease|-f)([[:space:]]|$)'; then
+  echo "Bloqueado: push forçado (--force/-f) não é permitido pelo Claude. Se for realmente necessário, rode manualmente." >&2
+  exit 2
+fi
+
+# Bloqueia push direto na branch de release — promoção {{DEV_BRANCH}} →
+# {{RELEASE_BRANCH}} é decisão humana, não deve acontecer sozinha durante
+# uma implementação.
+if echo "$COMMAND" | grep -qE 'git[[:space:]]+push[[:space:]]+.*(^|[[:space:]])(origin[[:space:]]+)?{{RELEASE_BRANCH}}([[:space:]]|$)'; then
+  echo "Bloqueado: push direto em '{{RELEASE_BRANCH}}' não é permitido pelo Claude. A promoção {{DEV_BRANCH}} → {{RELEASE_BRANCH}} é manual." >&2
+  exit 2
+fi
+
+exit 0

package/templates/.claude/hooks/guard-migration-rollback.sh.tpl

@@ -0,0 +1,35 @@
+#!/bin/bash
+# Hook PostToolUse (matcher: Write|Edit) — bloqueia migration sem rollback
+# depois de escrita, obrigando a corrigir antes de seguir.
+# Heurística hoje é Laravel-flavored (up/down); adapte pra outro framework
+# se a convenção de migration for diferente (ex: Rails change(), Django
+# migrations reversíveis automaticamente).
+set -euo pipefail
+
+INPUT=$(cat)
+
+if command -v jq >/dev/null 2>&1; then
+  FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+else
+  FILE_PATH=$(echo "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"file_path"[[:space:]]*:[[:space:]]*"//;s/"$//')
+fi
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+case "$FILE_PATH" in
+  *migration*|*Migrations*) ;;
+  *) exit 0 ;;
+esac
+
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+if grep -q "function up" "$FILE_PATH" 2>/dev/null && ! grep -q "function down" "$FILE_PATH" 2>/dev/null; then
+  echo "Bloqueado: '$FILE_PATH' tem 'up' mas não tem 'down' — toda migration precisa de rollback (ver .claude/rules/convencoes.md)." >&2
+  exit 2
+fi
+
+exit 0

package/templates/.claude/layer/CLAUDE.layer.md.tpl

@@ -0,0 +1,23 @@
+---
+camada: {{LAYER_NAME}}
+---
+
+# Padrões — {{LAYER_NAME}} ({{FRAMEWORK}})
+
+Este arquivo é carregado automaticamente sempre que o Claude editar
+arquivos dentro de `{{LAYER_PATH}}/`. Mantenha aqui só o que é específico
+desta camada — regras gerais do app ficam no CLAUDE.md do pacote.
+
+## Responsabilidade desta camada
+[definir — ex: Controllers só recebem request, validam entrada e chamam
+um Service; não contêm regra de negócio]
+
+## Convenções de nomenclatura
+[definir — ex: sufixo, singular/plural, namespace]
+
+## O que NUNCA deve estar aqui
+[definir — ex: acesso direto ao banco dentro de um Controller]
+
+## Exemplo de referência
+[opcional — caminho de um arquivo existente que representa bem o padrão
+desejado, para o Claude usar como modelo]

package/templates/.claude/rules/convencoes.md.tpl

@@ -0,0 +1,7 @@
+# Regra: convenções de código e nomenclatura
+
+- Nomenclatura de tabelas/entidades: [definir — ex: snake_case, prefixo por domínio]
+- Padrão de commits: [definir — ex: Conventional Commits]
+- Toda migration precisa de rollback.
+- Toda mudança de contrato de API precisa de versionamento/compatibilidade retroativa.
+- [adicionar convenções específicas do time]