@fontdata/ai-harness 2.0.0

package/templates/commands/criar-rag.md

@@ -0,0 +1,25 @@
+---
+description: Cria um sistema de RAG (SQLite + sqlite-vec) para capturar e reusar aprendizados.
+---
+
+# Criação do sistema de RAG
+
+Leia o `SPEC.md`, o `CLAUDE.md` na raiz e o plano mais recente em `docs/plans/`.
+
+Crie um sistema de RAG para este projeto que captura aprendizados em três momentos: ao encerrar um agent, ao encerrar a sessão e ao iniciar um novo prompt.
+
+O sistema deve ter:
+
+1. **SCHEMA DO BANCO** — SQLite com `sqlite-vec`. Tabela `knowledge` com: `id`, `path`, `content`, `embedding`, `category`, `agent`, `created_at`.
+
+2. **SCRIPT DE RESUMO** (`.claude/scripts/summarize.ts`) — Recebe como input o contexto a resumir (transcript de agent ou da sessão inteira). Extrai aprendizados em 4 categorias: bugs resolvidos com causa raiz; decisões de arquitetura e o porquê; padrões adotados pelo time; o que não funcionou e por quê. Salva em `.claude/knowledge/YYYY-MM-DD-agent-slug.md`.
+
+3. **SCRIPT DE EMBEDDING** (`.claude/scripts/embed.ts`) — Lê o `.md` gerado, quebra em chunks de 200-300 tokens, gera embeddings com `all-MiniLM-L6-v2` e faz INSERT no `rag.db` com `agent` e `category`.
+
+4. **SCRIPT DE BUSCA** (`.claude/scripts/search.ts`) — Recebe a pergunta atual e o agent atual, gera o embedding da pergunta, busca os top-3 chunks mais similares, prioriza chunks da mesma categoria do agent ativo e retorna o conteúdo para injetar no contexto.
+
+5. **SUBAGENT STOP HOOK** (async, por agent) — Captura o aprendizado específico do agent que acabou de terminar uma task.
+
+6. **STOP HOOK** (async, por sessão) — Captura o aprendizado da sessão inteira como síntese.
+
+7. **USERPROMPTSUBMIT HOOK** — Busca conhecimento relevante para o prompt atual, prioriza a categoria do agent ativo e injeta os chunks encontrados no contexto.

package/templates/commands/criar-rules.md

@@ -0,0 +1,31 @@
+---
+description: Cria rules incondicionais e escopadas por path em .claude/rules/.
+---
+
+# Geração de rules baseadas nos agents
+
+Leia os agents em `.claude/agents/`, o `CLAUDE.md` e o `SPEC.md` do projeto.
+
+Para cada domínio coberto pelos agents, crie rules específicas que complementem o system prompt de cada agent.
+
+Crie em `.claude/rules/`:
+
+1. **Rules incondicionais** com restrições que valem para qualquer agent:
+   - `seguranca.md` (o que nunca fazer)
+   - `convencoes-gerais.md` (padrões universais)
+
+2. **Rules escopadas por path** para cada domínio:
+   - `backend/` com paths: `backend/**/*.py`
+   - `frontend/` com paths: `frontend/src/**`
+   - `tests/` com paths: `tests/**`
+
+**Não crie rule de comentários.** `.claude/rules/comentarios.md` é instalado por `/configurar-comentarios`
+(junto com o hook de enforcement e a catraca do legado). Se ele já existir, deixe-o como está; se não
+existir, sugira rodar `/configurar-comentarios` em vez de escrever uma versão paralela. Também não repita
+regra de comentário dentro de `convencoes-gerais.md` — duas fontes divergentes é pior que uma.
+
+Cada rule deve:
+- Ser concisa — máximo 30 linhas
+- Conter apenas o que o agent não descobriria sozinho lendo o código
+- Complementar o system prompt do agent, não repetir o que já está lá
+- Focar em restrições e padrões específicos do domínio — não em comportamento geral

package/templates/commands/criar-skill.md

@@ -0,0 +1,22 @@
+---
+description: Sugere e cria skills do projeto em .claude/skills/ para problemas recorrentes.
+---
+
+# Criação de Skill
+
+Leia o `CLAUDE.md` e o `SPEC.md` na raiz do projeto.
+
+Crie uma skill para este projeto que resolva um problema **recorrente** que os agents vão ter durante a implementação.
+
+Sugira opções de skills úteis para este projeto específico, com:
+- O que cada skill faria
+- Quando dispararia automaticamente
+- Que tipo de tarefa resolveria sem precisar repetir instruções no prompt
+
+Após minha escolha, crie a skill completa em `.claude/skills/nome-escolhido/SKILL.md`.
+
+A skill deve ter:
+1. Frontmatter com `name` e `description` bem escritos
+2. Instruções claras baseadas nas convenções do `CLAUDE.md`
+3. Exemplos de input e output esperados
+4. Critério de quando **NÃO** usar a skill

package/templates/commands/design-system.md

@@ -0,0 +1,27 @@
+---
+description: Cria o agent de design system com skills e rules de conformidade da identidade visual.
+---
+
+# Criação do agente de design system
+
+Crie um **agente responsável pelo design system** do projeto. Esse agente deve trabalhar em conjunto, principalmente, com o agente de frontend. Ele deve ter **skills** e **rules** referentes à guarda e à garantia da conformidade da identidade visual do projeto.
+
+Crie o agent em `.claude/agents/`, as skills em `.claude/skills/` e as rules em `.claude/rules/`.
+
+## Origem da identidade visual
+
+A fonte do design system depende de eu ter passado, ou não, uma **URL** em `$ARGUMENTS`:
+
+$ARGUMENTS
+
+- **Se eu informei uma URL** em `$ARGUMENTS`: trate-a como referência externa e rode a instrução da seção **"Extrair identidade visual de uma referência externa"** abaixo, extraindo dela cores, fontes e padrões visuais para replicar no nosso projeto.
+
+- **Se eu NÃO informei nenhuma URL** (`$ARGUMENTS` vazio): **não acesse a internet**. Extraia o design system **já existente no próprio projeto, via código** — varra o código-fonte (CSS/SCSS, tokens de tema, Tailwind/`tailwind.config`, variáveis CSS, bibliotecas de UI, componentes) e consolide cores, tipografia, espaçamentos e demais padrões visuais reais do projeto. Use isso como base do agent, skills e rules.
+
+---
+
+### Extrair identidade visual de uma referência externa
+
+**Rode esta seção somente quando eu tiver informado uma URL em `$ARGUMENTS`.**
+
+Acesse o site informado e extraia dele todas as informações de cores, fontes e padrões visuais — principalmente de CSS — para replicar isso no nosso projeto.

package/templates/commands/diagrama.md

@@ -0,0 +1,17 @@
+---
+description: Gera diagramas Mermaid de arquitetura/fluxo a partir do código do projeto.
+---
+
+# Geração de diagrama (Mermaid)
+
+O que diagramar (opcional — ex.: "arquitetura geral", "fluxo de login", "modelo de dados"): $ARGUMENTS
+
+Se eu não especifiquei, me pergunte qual visão eu quero antes de gerar.
+
+Passos:
+
+1. Explore o código para entender a estrutura relevante (módulos, camadas, serviços, entidades, rotas, eventos) ao tema pedido.
+2. Gere um diagrama em **Mermaid**, escolhendo o tipo adequado: `flowchart` (arquitetura/fluxo), `sequenceDiagram` (interações), `erDiagram` (dados), `classDiagram` (modelo OO), `stateDiagram` (estados).
+3. Mantenha o diagrama **fiel ao código real**, não a uma versão idealizada. Use nomes reais de módulos/arquivos.
+4. Salve em `docs/diagramas/<slug>.md` (crie a pasta se necessário) com um título e um parágrafo curto explicando o que o diagrama mostra.
+5. Mostre o bloco Mermaid no chat e o caminho do arquivo salvo.

package/templates/commands/executar-plan.md

@@ -0,0 +1,36 @@
+---
+description: Orquestra a execução do plano com sub-agents em paralelo, fase a fase, com gates e TDD.
+---
+
+# Execução do plano com sub-agents
+
+Leia o `SPEC.md` e o `CLAUDE.md` na raiz e o **plano mais recente em `docs/plans/`** (a spec correspondente está em `docs/specs/`). O scaffold está completo e os testes de smoke passam.
+
+Sua função é de **ORQUESTRADOR**. Você não implementa nada diretamente — você lê o plano e delega cada task para sub-agents independentes, respeitando as dependências entre fases. **Sempre relate no chat qual agent está ativo**, principalmente nos gates.
+
+## Regras de orquestração
+
+1. **LEIA O PLANO COMPLETO** — Antes de qualquer delegação, leia todas as fases, tasks, inputs, outputs e testes críticos. Monte internamente o grafo de dependências.
+
+2. **EXECUTE FASE POR FASE** — Nunca inicie uma fase antes que todas as tasks da fase anterior estejam concluídas e os testes passando.
+
+3. **DENTRO DE CADA FASE — PARALELO** — Para cada fase, dispare sub-agents simultâneos para todas as tasks marcadas como paralelas. Cada sub-agent recebe: o contexto da task (Input, Output, Testes críticos), a instrução de escrever os testes ANTES de implementar, a instrução de seguir as convenções do `CLAUDE.md` e a instrução de marcar o checkbox da task no plano ao concluir.
+
+4. **INSTRUÇÃO PARA CADA SUB-AGENT** — Ao delegar, passe exatamente este contexto:
+
+   > "Você é responsável pela [NOME DA TASK] do plano em `docs/plans/...`.
+   > Input: [INPUT DA TASK]
+   > Output esperado: [OUTPUT DA TASK]
+   > Testes críticos:
+   > - [TESTE 1]
+   > - [TESTE 2]
+   > Siga as convenções do `CLAUDE.md`. Escreva os testes primeiro (RED), confirme que falham, implemente o mínimo para passar (GREEN), e marque o checkbox no plano ao concluir.
+   > Comentários: o padrão é não comentar (bloco <= 3 linhas, docstring pública <= 5, cabeçalho de arquivo proibido). **Não** escreva no código o número da task, a fase, o plano, a data nem o que você investigou — isso vai na mensagem de commit. Ver `.claude/rules/comentarios.md`."
+
+5. **GATE ENTRE FASES** — Após todos os sub-agents de uma fase reportarem conclusão, execute o critério de gate da fase. Só avance se o gate passar. Se falhar, sinalize o erro e aguarde instrução — não tente corrigir automaticamente.
+
+6. **RELATÓRIO DE PROGRESSO** — Após cada fase, exiba: tasks concluídas e testes passando, tasks que bloquearam e o motivo, gate da fase (passou/falhou) e a próxima fase.
+
+7. **RESTRIÇÕES** — Não modifique `SPEC.md`, `CLAUDE.md` ou os planos. Não implemente nada fora do escopo do plano. Não avance se um gate falhar. Se uma task bloquear por mais de 2 tentativas, sinalize e aguarde — não invente solução alternativa.
+
+Inicie lendo o plano e apresentando o plano de execução completo antes de disparar qualquer sub-agent. Aguarde minha confirmação para começar.

package/templates/commands/gerar-claude-md.md

@@ -0,0 +1,66 @@
+---
+description: Gera o CLAUDE.md (context file) na raiz a partir do SPEC.md.
+---
+
+# Geração do CLAUDE.md
+
+Leia o `SPEC.md` na raiz do projeto e gere o **Context File** do projeto, salvando como `CLAUDE.md` **na raiz**.
+
+Gere o arquivo exatamente nesta estrutura, sem adicionar nem remover seções:
+
+```markdown
+# [NOME DO PROJETO]
+> [1 frase: o que o sistema faz e qual problema resolve]
+
+## Stack
+| Camada | Tecnologia |
+|--------|------------|
+[preencha com a stack do SPEC]
+
+## Estrutura de pastas
+[árvore de pastas do projeto com comentário em cada pasta]
+
+## Como rodar localmente
+[comandos exatos de instalação e execução, separados por backend e frontend]
+
+## Padrões de código
+- Nomenclatura de arquivos: [regra]
+- Nomenclatura de variáveis e funções: [regra]
+- Estrutura de endpoints: [regra]
+- Estrutura de componentes: [regra]
+- Tipagem: [regra]
+
+## Comentários em código
+[Se o projeto já tiver o bloco "Comentários em código" no CLAUDE.md atual, copie-o INTEGRALMENTE aqui,
+incluindo a linha `@.claude/rules/comentarios.md`. Se não tiver, escreva apenas:
+"Rode `/configurar-comentarios` para instalar o padrão de comentários deste projeto."]
+
+## TDD
+- Framework backend: [nome]
+- Framework frontend: [nome]
+- Onde ficam os testes: [caminho]
+- Regra: [cobertura mínima exigida]
+- Testes críticos deste projeto:
+  - [ ] [teste 1 extraído do SPEC]
+  - [ ] [teste 2 extraído do SPEC]
+  - [ ] [teste 3 extraído do SPEC]
+
+## Nunca fazer
+- Nunca [proibição específica deste projeto]
+- Nunca [proibição específica deste projeto]
+- Nunca [proibição específica deste projeto]
+- Nunca [proibição específica deste projeto]
+- Nunca [proibição específica deste projeto]
+
+## Decisões em aberto
+- [ ] [decisão 1 não resolvida no SPEC]
+- [ ] [decisão 2 não resolvida no SPEC]
+```
+
+Preencha apenas os campos entre colchetes. Não invente nada que não esteja no SPEC. Se uma informação não existir no SPEC, escreva "a definir".
+
+> Preserve, se possível, a seção de filosofia/fluxo do harness já presente no `CLAUDE.md` atual (orquestração, TDD, gates, modelo de arquivos `docs/specs` e `docs/plans`).
+
+> **Nunca descarte** o bloco "Comentários em código" nem a linha `@.claude/rules/comentarios.md` que já
+> existirem no `CLAUDE.md` atual — eles são instalados por `/configurar-comentarios` e regenerar o arquivo
+> sem eles desliga o padrão de comentários do projeto inteiro.

package/templates/commands/gerar-env.md

@@ -0,0 +1,16 @@
+---
+description: Monta o .env.example a partir das variáveis de ambiente realmente lidas no código.
+---
+
+# Geração de .env.example
+
+Escopo (opcional): $ARGUMENTS
+
+Passos:
+
+1. Varra o código procurando todo acesso a variáveis de ambiente (`process.env.X`, `os.environ`, `os.getenv`, `Deno.env`, `System.getenv`, libs de config, etc.).
+2. Consolide a lista única de variáveis usadas, inferindo para cada uma: finalidade, se é obrigatória ou opcional e um valor de exemplo **seguro** (placeholder).
+3. **Nunca** copie segredos reais para o `.env.example` — use placeholders como `troque-me`, `sua-chave-aqui`. Se encontrar segredos hardcoded no código, **avise** como achado de segurança.
+4. Gere/atualize `.env.example` agrupando por contexto (banco, auth, integrações, etc.) com um comentário curto por variável.
+5. Compare com o `.env` atual (se existir e não estiver no git) e aponte variáveis usadas no código mas ausentes da config, e vice-versa.
+6. Garanta que `.env` está no `.gitignore`. Mostre o resultado e as divergências encontradas.

package/templates/commands/gerar-ignore.md

@@ -0,0 +1,37 @@
+---
+description: Gera .claudeignore e .gitignore conforme a stack do projeto.
+---
+
+# Geração de arquivos de exclusão de contexto
+
+Analise a estrutura do projeto e gere os arquivos de exclusão de contexto adequados para o Claude Code.
+
+Se a stack não estiver clara, leia o `CLAUDE.md`/`SPEC.md` ou me pergunte antes.
+
+Stack do projeto: $ARGUMENTS
+
+Gere o arquivo `.claudeignore` com estas seções obrigatórias, nesta ordem:
+
+```
+# Dependências
+[liste os diretórios de dependências da stack]
+
+# Build e arquivos gerados
+[liste os diretórios de build e arquivos gerados]
+
+# Segredos e variáveis de ambiente
+[liste todos os padrões de arquivos com credenciais]
+
+# Banco de dados local
+[liste arquivos de banco de dados de desenvolvimento]
+
+# Uploads e mídia
+[liste diretórios de arquivos enviados pelo usuário]
+
+# Cache e logs
+[liste diretórios de cache e arquivos de log]
+```
+
+Gere também um `.gitignore` reforçado cobrindo as mesmas categorias acima.
+
+Regra: seja conservador. Em caso de dúvida, exclua. Nunca exclua arquivos de código fonte, testes ou documentação.

package/templates/commands/gerar-spec.md

@@ -0,0 +1,33 @@
+---
+description: Conduz uma entrevista de requisitos e gera o SPEC.md principal na raiz.
+---
+
+# Geração do SPEC.md principal
+
+Você vai me ajudar a criar o **SPEC.md principal** do projeto — a definição completa e única, gravada na **raiz** do projeto (`SPEC.md`). Vale tanto para projeto novo quanto existente. Não quero escrever o spec manualmente — conduza uma entrevista de requisitos comigo.
+
+## Fase 1 — Entrevista
+
+Faça perguntas para entender o projeto a fundo. **Uma pergunta por vez.** Cubra obrigatoriamente: problema real que resolve, quem são os usuários, funcionalidades essenciais vs. nice-to-have, módulos e suas responsabilidades, stack técnica, constraints e o que está fora do escopo. Quando tiver informação suficiente, avise que está pronto para gerar o SPEC.
+
+## Fase 2 — Geração do SPEC.md
+
+Quando eu confirmar, gere o arquivo `SPEC.md` **na raiz do projeto** com esta estrutura, sem adicionar nem remover seções:
+
+```markdown
+# SPEC.md
+
+## Problema
+## Usuários
+## Funcionalidades
+### Essenciais
+### Fora do escopo
+## Módulos
+## Stack
+## Constraints técnicas
+## Critérios de aceitação
+```
+
+Não invente informações que não surgiram na entrevista. Se algo ficou ambíguo, registre como decisão em aberto.
+
+> Observação: este SPEC é a definição **principal** do projeto. O "start" inicial e cada nova tarefa geram specs **complementares** em `docs/specs/` (via `/nova-tarefa`).

package/templates/commands/gerar-testes.md

@@ -0,0 +1,17 @@
+---
+description: Detecta cobertura de testes faltante e escreve os testes seguindo TDD (RED→GREEN).
+---
+
+# Geração de testes
+
+Alvo (arquivo, módulo ou pasta): $ARGUMENTS
+
+Se eu não informei um alvo, primeiro liste os módulos com **menor cobertura ou sem testes** e me pergunte por onde começar.
+
+Passos:
+
+1. Leia o `CLAUDE.md` e o framework de testes já usado no projeto. **Não introduza um framework novo** sem me perguntar.
+2. Para o alvo, mapeie os comportamentos críticos, casos de borda e caminhos de erro que **não** estão cobertos hoje.
+3. Escreva os testes seguindo **TDD**: primeiro confirme que eles falham (**RED**) contra o estado atual quando fizer sentido; depois garanta que passam (**GREEN**). Mínimo de **2 testes críticos** por comportamento.
+4. **Não altere o código de produção** para fazer um teste passar, a menos que exista um bug evidente — nesse caso, **pare e me avise** antes.
+5. Ao final, rode a suíte e reporte: quantos testes foram criados, o que passou/falhou e qual a cobertura aproximada antes/depois.

package/templates/commands/git-commit-push.md

@@ -0,0 +1,38 @@
+---
+description: Gera a mensagem (PT-BR, Conventional Commits) e executa git add/commit/push sem confirmação.
+---
+
+# /git-commit-push
+
+No repositório atual, execute commit e push conforme o uso abaixo.
+
+## Uso
+
+- **Sem texto após o comando** (`/git-commit-push` sozinho): sugira a mensagem a partir das mudanças e execute `git add`, commit e `git push` **sem pedir confirmação**.
+- **Com texto após o comando** (`/git-commit-push …`): use **exatamente** o que o usuário informou como mensagem de commit completa (título e, se houver, corpo) e execute `git add`, commit e `git push` **sem pedir confirmação**.
+
+## Etapas
+
+1. Inspecione as mudanças com:
+   - `git status`
+   - `git diff`
+   - `git log -5 --oneline`
+2. **Mensagem de commit**
+   - Se o usuário **não** passou texto após o comando: sugira em português do Brasil com:
+     - título no formato `tipo: Descrição`
+     - título em uma linha
+     - primeira letra maiúscula após `: `
+     - tipos aceitos: `feat`, `fix`, `refactor`, `docs`, `chore`, `style`, `test`
+     - corpo detalhado com descrição completa do que foi feito no commit (itens objetivos)
+   - Se o usuário **passou** texto após o comando: use esse texto como mensagem do commit (multilinha permitida).
+3. Execute **imediatamente** (sem etapa de confirmação):
+   - `git add -A`
+   - `git commit` com a mensagem definida no passo 2 (título + corpo quando aplicável)
+   - `git push`
+4. Retorne um resumo final com branch, hash e status do push.
+
+## Guardrails
+
+- Se não houver alterações, interrompa com aviso.
+- Não execute push forçado.
+- Em caso de erro, pare e explique o próximo passo recomendado.

package/templates/commands/harness.md

@@ -0,0 +1,34 @@
+---
+description: Comando-mestre — conduz a sequência de setup do harness em ordem, validando entre etapas.
+---
+
+# /harness — setup guiado do projeto
+
+Conduza a configuração completa do harness deste projeto executando as etapas **em ordem**, parando para validar comigo antes de avançar de uma para a outra. Em cada etapa, use o slash command correspondente como referência de instrução.
+
+Contexto inicial (opcional): $ARGUMENTS
+
+## Antes de começar: novo ou existente?
+
+Pergunte se este é um **projeto novo** ou um **projeto existente** (se eu não tiver dito).
+
+- **Projeto novo** → execute todas as 8 etapas.
+- **Projeto existente** → **pule as etapas 1, 5, 6 e 8** (validar ideia, gerar plano do start, scaffold e executar o plano). Execute apenas as etapas **2, 3, 4 e 7** — documentar o projeto (SPEC/CLAUDE/ignores) e montar o harness sobre o código que já existe. Nas etapas 2 e 3, leve em conta o código atual ao gerar o SPEC.md e o CLAUDE.md.
+
+## Sequência
+
+1. **Validar ideia** (`/validar-ideia`) — confirme que o escopo cabe em ~4h com multi-agents. Se o veredito for AJUSTAR ou REPROVAR, pare e ajuste comigo antes de seguir.
+2. **Gerar SPEC principal** (`/gerar-spec`) — entrevista de requisitos → `SPEC.md` na raiz. Valide comigo.
+3. **Gerar CLAUDE.md** (`/gerar-claude-md`) — context file na raiz a partir do SPEC.
+4. **Gerar ignores** (`/gerar-ignore`) — `.claudeignore` e `.gitignore`.
+5. **Gerar plano do start** (`/nova-tarefa`) — derive o start inicial do `SPEC.md`: spec complementar em `docs/specs/` + plano em `docs/plans/`. Valide comigo. Não dispare o orquestrador ainda — o scaffold vem antes.
+6. **Scaffold** (`/scaffold`) — estrutura inicial, rota `/health` e testes de smoke. Confirme que o servidor sobe.
+7. **Montar o harness** — nesta ordem: `/configurar-comentarios` (**primeiro**: instala o padrão de comentários, o hook e a catraca, para que os agents já nasçam com a regra no system prompt), `/criar-skill` (skills antes dos agents, que dependem delas), depois `/criar-agents`, `/criar-code-reviewer`, `/criar-rules`, `/criar-hooks` e, por fim, `/configurar-orquestrador` (configura o Claude Code como orquestrador dos agents) — sugira pular o que não fizer sentido.
+8. **Executar o plano** (`/executar-plan`) — só depois da minha confirmação, orquestre a implementação com sub-agents.
+
+## Regras
+
+- **Não avance de etapa sem minha confirmação explícita.**
+- Sempre relate qual etapa/agent está ativo.
+- Respeite TDD e os gates entre fases.
+- Se uma etapa não se aplicar a este projeto, proponha pulá-la e siga só com meu OK.

package/templates/commands/nova-tarefa.md

@@ -0,0 +1,60 @@
+---
+description: Gera a spec complementar + o plano de implementação em docs/specs e docs/plans (start inicial ou nova tarefa) e, se confirmado, dispara o orquestrador.
+---
+
+# Planejamento de tarefa (start inicial ou nova tarefa)
+
+Este comando transforma um recorte de trabalho em **spec complementar + plano de implementação** prontos para a orquestração com sub-agents. Serve tanto para o **start inicial** do projeto quanto para **cada nova tarefa** do dia a dia.
+
+Tarefa / recorte: $ARGUMENTS
+
+## 1. Defina o recorte
+
+Antes de tudo, leia o `SPEC.md` principal e o `CLAUDE.md` na raiz (e a spec/plano mais recentes em `docs/`, se já existirem).
+
+- **Start inicial** (não há nada em `docs/plans/` ainda, ou eu pedi "start" / "primeira fatia"): derive o recorte direto do `SPEC.md` — a primeira fatia vertical a construir. **Não precisa entrevista**, mas confirme comigo o recorte escolhido antes de gerar.
+- **Nova tarefa**: faça de **2 a 3 perguntas** (uma por vez, mais se necessário) para entender a fundo o que deve ser feito. Ao final, resuma o que foi **entendido e planejado** e aguarde minha aprovação.
+
+**Nunca grave `PLAN.md` na raiz.** Use sempre a convenção de pastas do projeto.
+
+## 2. Spec complementar
+
+Quando eu aprovar o recorte, grave a spec em `docs/specs/AAAA-MM-DD-breve-descricao.md` (data atual + descrição curta derivada do recorte). Descreva de forma enxuta o que será implementado e os critérios de aceite. Valide comigo.
+
+## 3. Plano de implementação
+
+Grave o plano em `docs/plans/AAAA-MM-DD-breve-descricao.md` (use o **mesmo nome** da spec complementar), com esta estrutura, sem adicionar nem remover seções:
+
+```markdown
+# Plano — [breve descrição]
+
+## Sprint [n] — [critério de conclusão em 1 frase verificável]
+
+### Fase [n] — [nome]
+> Dependências: [fases anteriores ou "nenhuma"]
+> Paralelismo: [quais tasks desta fase rodam em paralelo]
+
+#### Task [n.n] — [nome]
+- Agent: [papel do agent responsável]
+- Input: [o que precisa estar pronto para iniciar]
+- Output: [entregável específico com assinatura ou estrutura]
+- Testes críticos:
+  - [ ] [comportamento esperado — input válido]
+  - [ ] [caso de erro tratado]
+```
+
+Regras obrigatórias:
+
+1. Toda task tem pelo menos 2 testes críticos definidos antes de qualquer código — os testes são escritos primeiro.
+2. Nenhum output pode ser vago — descreva o arquivo, função ou estrutura exata que será entregue.
+3. Tasks na mesma fase são genuinamente independentes — não tocam os mesmos arquivos nem dependem uma da outra.
+4. A ordem das fases respeita dependências reais — nenhuma task de integração antes das tasks base existirem.
+5. Use os nomes de módulos definidos no `SPEC.md` — sem criar nomenclatura nova.
+6. Cada fase tem um critério de conclusão verificável por um comando de terminal.
+
+## 4. Validação e execução
+
+Ao terminar, informe o caminho dos dois arquivos gravados e liste quais tasks rodam em paralelo e quantos agents serão necessários no total. Valide comigo se é isto que desejo.
+
+- **Start inicial (fluxo `/harness`):** o próximo passo normalmente é `/scaffold` antes de implementar — **não dispare o orquestrador automaticamente**, aguarde minha instrução.
+- **Nova tarefa:** se eu confirmar, **chame o orquestrador** (`/executar-plan`) para realizar todo o plano aprovado, com sub-agents em paralelo e TDD obrigatório.

package/templates/commands/onboarding.md

@@ -0,0 +1,21 @@
+---
+description: Gera um guia de onboarding (como rodar, entender e contribuir) para um dev novo no projeto.
+---
+
+# Guia de onboarding
+
+Público-alvo (opcional — ex.: "dev backend júnior", "pessoa de QA"): $ARGUMENTS
+
+Passos:
+
+1. Leia o `CLAUDE.md`, o `SPEC.md` (se houver), os scripts do projeto e a estrutura de pastas.
+2. Monte um guia prático em `docs/ONBOARDING.md` cobrindo:
+   - **Visão geral** do que o projeto faz (1–2 parágrafos).
+   - **Pré-requisitos** e versões (linguagem, runtime, ferramentas).
+   - **Setup passo a passo** até rodar localmente (instalar, variáveis de ambiente, subir o app).
+   - **Como rodar testes** e o que o harness espera (TDD, gates).
+   - **Mapa do código**: principais pastas/módulos e o que cada um faz.
+   - **Fluxo de trabalho**: branches, commits semânticos, slash commands do dia a dia.
+   - **Onde pedir ajuda / armadilhas comuns**.
+3. Baseie tudo no estado **real** do projeto — confira que os comandos descritos realmente existem e funcionam. Não invente passos.
+4. Ao final, mostre o caminho do arquivo e um resumo do que foi documentado.

package/templates/commands/refatorar.md

@@ -0,0 +1,17 @@
+---
+description: Refatora um alvo usando os testes existentes como rede de segurança, sem mudar comportamento.
+---
+
+# Refatoração guiada por testes
+
+Alvo da refatoração: $ARGUMENTS
+
+Se eu não informei um alvo, me pergunte qual arquivo/módulo refatorar e qual o objetivo (legibilidade, duplicação, performance, acoplamento).
+
+Regras:
+
+1. **Refatoração não muda comportamento.** A interface pública e os resultados observáveis devem permanecer idênticos.
+2. Antes de tocar no código, verifique se há **testes cobrindo o alvo**. Se a cobertura for insuficiente, **pare e me avise** — ofereça rodar `/gerar-testes` primeiro para criar a rede de segurança.
+3. Rode os testes **antes** (baseline verde), faça a refatoração em passos pequenos e rode os testes **depois** de cada passo. Se algo ficar vermelho, reverta o passo.
+4. Não misture refatoração com novas funcionalidades nem com correção de bugs na mesma passada.
+5. Ao final, reporte: o que mudou, por quê, e a confirmação de que toda a suíte continua verde.

package/templates/commands/resolver-bug.md

@@ -0,0 +1,25 @@
+---
+description: Investiga, planeja em docs/bugs e corrige um bug passo a passo, com aprovação.
+---
+
+# Resolver bug
+
+Trate o bug descrito abaixo (se eu não tiver descrito, peça os detalhes antes de começar).
+
+Bug: $ARGUMENTS
+
+Faça o seguinte, **sem pular nenhuma etapa** e pedindo minha confirmação nos momentos críticos:
+
+1. **Investigue** onde está o bug e o que ele afeta.
+2. **Monte um plano de conserto** dividido em etapas e grave-o em `docs/bugs/<yyyy-mm-dd>-<slug>.md`, onde `<yyyy-mm-dd>` é a data atual e `<slug>` é uma descrição resumida do bug.
+3. **Peça minha aprovação** antes de mexer em qualquer coisa.
+4. **Execute o conserto passo a passo**, verificando se cada etapa funcionou.
+5. **Revise a qualidade** do que foi feito ao final de cada etapa.
+6. **Sugira uma regra nova** no projeto (`.claude/rules/`) para esse bug nunca voltar.
+
+## Bug ou investigação?
+
+Só use `docs/bugs/` se a apuração fechar os três: sintoma reproduzível, causa-raiz identificada e
+correção a aplicar. Se concluir que não há defeito — é auditoria, paridade com legado, medição ou
+levantamento — grave em `docs/investigacoes/<yyyy-mm-dd>-<slug>.md` e me avise, em vez de registrar
+como bug.

package/templates/commands/review-por-task.md

@@ -0,0 +1,16 @@
+---
+description: Enforça o fluxo implementação → review isolado → correção em cada task da fase.
+---
+
+# Orquestrador com review obrigatório por task
+
+Leia o **plano mais recente em `docs/plans/`** e execute a fase indicada (por padrão a próxima fase pendente) seguindo este fluxo **obrigatório** para cada task:
+
+1. Despache o agent de implementação correto (ex: `@backend-agent`) para implementar a task.
+2. Aguarde o retorno confirmando conclusão.
+3. Despache o `@code-reviewer` para revisar o que foi implementado — **em contexto isolado**.
+4. Aguarde o veredicto do reviewer.
+5. Se houver item **BLOQUEANTE**: corrija antes de avançar para a próxima task.
+6. Se não houver bloqueantes: avance.
+
+Não pule o step de review em nenhuma task. O orquestrador despacha cada agent separadamente — o reviewer nunca vê a conversa de implementação, só o output final. É o contexto mais limpo possível. **Relate no chat qual agent está ativo a cada passo.**

package/templates/commands/revisar-pr.md

@@ -0,0 +1,18 @@
+---
+description: Faz o review de um PR ou do diff atual, classificando achados em BLOQUEANTE, IMPORTANTE e SUGESTÃO.
+---
+
+# Review de PR / diff
+
+Alvo (opcional — número do PR, branch ou nada para o diff atual): $ARGUMENTS
+
+Passos:
+
+1. Determine o que revisar:
+   - Se eu informei um **número de PR**, use o `gh` para buscar o diff (`gh pr diff <n>`) e a descrição.
+   - Se informei uma **branch**, compare-a com a branch principal.
+   - Se **nada** foi informado, revise o diff local atual (`git diff` do que está em andamento vs. a base).
+2. Se existir o agent `@code-reviewer` em `.claude/agents/`, **delegue a ele** a análise, passando `SPEC.md`/plano como referência. Caso contrário, faça o review diretamente.
+3. Avalie: correção (bugs, casos de borda), segurança, performance, testes (existem? cobrem o crítico?), aderência ao `CLAUDE.md` e às convenções, legibilidade e simplicidade, e **comentários** (orçamento da rule `.claude/rules/comentarios.md`: bloco <= 3 linhas, docstring pública <= 5, sem cabeçalho de arquivo, sem banner/separador, sem task/plano/data/hash de commit no código) — comentário fora do padrão é **IMPORTANTE**, não SUGESTÃO.
+4. Classifique cada achado em **BLOQUEANTE** (não pode entrar assim), **IMPORTANTE** (deveria ser ajustado) e **SUGESTÃO** (melhoria opcional), com `arquivo:linha` e a correção proposta.
+5. Termine com um veredito: **aprovar**, **aprovar com ressalvas** ou **solicitar mudanças**. Não altere o código — apenas revise.

package/templates/commands/scaffold.md

@@ -0,0 +1,25 @@
+---
+description: Cria a estrutura inicial do projeto (pastas, configs, rota /health, testes de smoke).
+---
+
+# Geração de Scaffold
+
+Leia o `SPEC.md` e o `CLAUDE.md` na raiz do projeto, e o plano mais recente em `docs/plans/`.
+
+Gere o scaffold completo do projeto seguindo estas regras:
+
+1. **ESTRUTURA DE PASTAS** — Crie todos os diretórios e subdiretórios definidos na seção de estrutura do `CLAUDE.md`. Adicione um `README.md` de uma linha em cada pasta descrevendo sua responsabilidade.
+
+2. **ARQUIVOS DE CONFIGURAÇÃO** — Crie todos os arquivos de configuração da stack: `requirements.txt`, `package.json`, `tsconfig.json`, `tailwind.config.js`, `.env.example`, `.gitignore` e qualquer outro necessário. Instale as dependências após criar os arquivos.
+
+3. **PONTO DE ENTRADA MÍNIMO** — Crie um `main.py` (ou `index.ts`, `server.js` — conforme a stack) com apenas o servidor inicializado e uma rota `/health` que retorna status 200. Nenhuma lógica de negócio.
+
+4. **SETUP DE TESTES** — Configure o framework de testes definido no `CLAUDE.md`: crie a pasta de testes espelhando a estrutura do projeto e um teste de smoke que verifica se o servidor sobe.
+
+5. **O QUE NÃO FAZER**
+   - Não implemente nenhuma lógica de negócio
+   - Não crie modelos de dados
+   - Não crie endpoints funcionais além de `/health`
+   - Não crie componentes de UI além do layout base
+
+6. **CRITÉRIO DE CONCLUSÃO** — Ao terminar, execute os comandos de verificação definidos no `CLAUDE.md` e confirme que o servidor sobe sem erros antes de encerrar.

package/templates/commands/sincronizar-claude-md.md

@@ -0,0 +1,15 @@
+---
+description: Relê o código e aponta onde o CLAUDE.md/SPEC.md divergiu da realidade — sem reescrever sozinho.
+---
+
+# Sincronização do CLAUDE.md com o código
+
+Foco (opcional — seção ou tema): $ARGUMENTS
+
+Passos:
+
+1. Leia o `CLAUDE.md` (e o `SPEC.md`, se existir) e confronte com o estado **real** do código: stack, scripts, estrutura de pastas, comandos de build/test, convenções e fluxos descritos.
+2. Liste as **divergências** encontradas, cada uma com: o que o doc afirma, o que o código mostra e o trecho/arquivo de evidência (use links clicáveis `arquivo:linha`).
+3. Classifique cada divergência em **DESATUALIZADO** (doc ficou para trás), **FALTANDO** (existe no código, não no doc) ou **OBSOLETO** (no doc, não existe mais).
+4. **Não reescreva** `CLAUDE.md`/`SPEC.md` por conta própria — essa é uma regra do harness. Apresente as correções propostas e **pergunte quais devo aplicar**.
+5. Só depois da minha confirmação, aplique exatamente as mudanças aprovadas.