synapos 2.5.0

package/.synapos/core/commands/setup/discover.md

@@ -0,0 +1,543 @@
+# Project Discovery & Context Mapping
+
+Este comando analisa automaticamente o projeto e gera um briefing técnico completo em formato modular.
+
+É **OPCIONAL** e pode ser executado:
+- Uma vez no início do projeto
+- Quando ADRs mudarem significativamente
+- Quando novo frontend Lovable for adicionado
+- Quando arquitetura backend mudar
+
+---
+
+# REGRAS ABSOLUTAS
+
+## Regra 1: JANELAS INTERATIVAS são OBRIGATÓRIAS
+
+Após cada fase de detecção, você DEVE usar `AskUserQuestion` para validar os resultados.
+
+## Regra 2: NUNCA INVENTE
+
+Você PODE detectar do código:
+- Tecnologias, estrutura de pastas, endpoints, ADRs existentes, configurações
+
+Você NÃO PODE inventar:
+- Convenções não documentadas
+- Decisões que não estão em ADRs
+- Regras "sempre" ou "nunca" que não estão escritas
+- Problemas ou dívida técnica
+
+## Regra 3: SE NÃO ENCONTRAR, MARQUE COMO "NÃO DETECTADO"
+
+Nunca assuma que existe convenção ou regra só porque "geralmente tem".
+
+---
+
+## Comportamento Incremental
+
+Este comando é **não-destrutivo**:
+- Se arquivos do briefing já existem: atualiza incrementalmente
+- Se não existem: cria do zero
+- Sempre preserva informações existentes
+
+## Estrutura Gerada
+
+```
+docs/tech-context/
+├── project-briefing.md              # Índice mestre + resumo
+└── briefing/
+    ├── critical-rules.md            # Regras não-negociáveis
+    ├── adrs-summary.md              # ADRs consolidadas
+    ├── backend-conventions.md       # Convenções de código
+    ├── frontend-lovable.md          # Mapeamento Lovable (se existe)
+    └── tech-stack.md                # Stack tecnológico
+```
+
+---
+
+## Fase 1: Análise de ADRs (Condicional)
+
+### 1.1 Detectar ADRs
+
+```bash
+paths_to_check = [
+  "docs/tech-context/adr/",
+  "docs/adr/",
+  "docs/tech/adr/",
+  "adr/"
+]
+```
+
+- Se **NENHUMA** pasta existe: pular esta fase completamente
+- Se existe: prosseguir com análise
+
+### 1.2 Processar ADRs (Silencioso)
+
+Para cada arquivo `.md` encontrado na pasta de ADRs:
+
+1. Ler o arquivo
+2. Extrair: número, título, status, contexto, decisão, consequências
+
+### 1.3 VALIDAR ADRs Detectadas
+
+```
+AskUserQuestion({
+  question: "Encontrei as seguintes ADRs. Todas estão ativas e corretas?",
+  options: [
+    { label: "Sim, corretas", description: "Prosseguir" },
+    { label: "ADRs incorretas", description: "Vou informar quais estão erradas" },
+    { label: "Faltam ADRs", description: "Vou informar as que faltam" }
+  ]
+})
+```
+
+Se "ADRs incorretas" ou "Faltam ADRs":
+```
+AskUserQuestion({
+  question: "Quais ADRs devem ser incluidas ou corrigidas?",
+  options: [
+    { label: "Vou listar", description: "Informar ADRs manualmente" },
+    { label: "Pular ADRs", description: "Gerar sem esta ADR" }
+  ]
+})
+```
+
+---
+
+## Fase 2: Mapeamento de Frontend Lovable (Condicional)
+
+### 2.1 Detectar Frontend
+
+Procurar por pastas:
+```bash
+frontend_paths = [
+  "apps/frontend/", "frontend/", "client/", "web/",
+  "packages/frontend/", "src/frontend/", "src/"
+]
+```
+
+Para cada pasta encontrada:
+- Verificar `package.json`
+- Verificar se é React/TypeScript
+
+### 2.2 Verificar se é Lovable
+
+Padrões que indicam Lovable:
+- Comentários com "lovable.dev" ou "Generated by Lovable"
+- Estrutura: `src/components/`, `src/pages/`, `src/lib/`
+- shadcn/ui (`components/ui/`)
+- Vite config
+
+### 2.3 VALIDAR Frontend Detectado
+
+```
+AskUserQuestion({
+  question: "Encontrei um frontend. É Lovable?",
+  options: [
+    { label: "É Lovable", description: "Prosseguir com mapeamento" },
+    { label: "É customizado", description: "Frontend manual, não Lovable" },
+    { label: "Não é frontend", description: "Não existe frontend" }
+  ]
+})
+```
+
+Se "É Lovable", perguntar sobre mocks:
+```
+AskUserQuestion({
+  question: "O frontend Lovable tem mocks de dados? (hardcoded no código)",
+  options: [
+    { label: "Sim, tem mocks", description: "Vou identificar os mocks" },
+    { label: "Não tem mocks", description: "Frontend já integrado" },
+    { label: "Não sei", description: "Preciso verificar" }
+  ]
+})
+```
+
+Se "Sim, tem mocks":
+- Escaneie componentes .tsx/.jsx em `src/`
+- Identifique: useState com arrays/objetos hardcoded, arquivos mock*.ts, fake*.ts
+- NÃO invente — liste apenas o que encontrar
+
+### 2.4 VALIDAR Mocks Encontrados
+
+```
+AskUserQuestion({
+  question: "Encontrei os seguintes mocks pendentes de integração. Confirmar?",
+  options: [
+    { label: "Corretos", description: "Prosseguir" },
+    { label: "Corrigir lista", description: "Vou informar quais estão errados" }
+  ]
+})
+```
+
+---
+
+## Fase 3: Análise de Arquitetura Backend (Sempre executa)
+
+### 3.1 Detectar Backend
+
+Procurar por pastas:
+```bash
+backend_paths = [
+  "apps/backend/", "backend/", "server/", "api/",
+  "packages/backend/", "src/backend/", "src/"
+]
+```
+
+### 3.2 Mapear Estrutura de Pastas (Silencioso)
+
+Escanear e detectar:
+- `src/controllers/` ou `src/routes/` → HTTP handlers
+- `src/services/` → Business logic
+- `src/repositories/` ou `src/dal/` → Data access
+- `src/models/` ou `src/entities/` → Domain models
+- `src/shared/` → Código compartilhado (enums/, types/, schemas/, utils/)
+- `src/tests/` ou `tests/` → Testes
+
+### 3.3 Identificar Convenções (SÓ as detectáveis)
+
+**Localização de ENUMs:**
+- Procurar por arquivos `*.enum.ts`
+- Marcar como "detectado em [caminho]" se > 80% estão na mesma pasta
+
+**Padrões de arquitetura:**
+- Repository Pattern? (existem pastas repositories/ E services/)
+- Service Layer? (existe pasta services/)
+- MVC? (existe controllers/, models/)
+
+### 3.4 VALIDAR Backend Detectado
+
+```
+AskUserQuestion({
+  question: "Detectei backend em [caminho]. Estrutura está correta?",
+  options: [
+    { label: "Correto", description: "Prosseguir" },
+    { label: "Corrigir estrutura", description: "Vou informar a estrutura correta" }
+  ]
+})
+```
+
+```
+AskUserQuestion({
+  question: "Detected as seguintes pastas. Confirmar convenções?",
+  options: [
+    { label: "Corretas", description: "Prosseguir" },
+    { label: "Corrigir", description: "Vou informar as correções" }
+  ]
+})
+```
+
+### 3.5 NÃO Assuma, Pergunte
+
+Se não conseguir detectar padrão claramente:
+
+```
+AskUserQuestion({
+  question: "Não consegui detectar o padrão arquitetural claramente. Qual é?",
+  options: [
+    { label: "MVC", description: "Model-View-Controller" },
+    { label: "Service Layer", description: "Services + Repositories" },
+    { label: "Clean Architecture", description: "Camadas separadas" },
+    { label: "Domain-Driven", description: "DDD com aggregates" },
+    { label: "Outro", description: "Vou especificar" }
+  ]
+})
+```
+
+---
+
+## Fase 4: Detectar Stack Tecnológico (Silencioso)
+
+Ler `package.json` do backend:
+
+**Extrair:**
+- Framework web: express, fastify, nest, koa, hapi
+- Database/ORM: prisma, typeorm, drizzle, sequelize, mongoose
+- Validação: zod, joi, yup, class-validator
+- Testes: jest, vitest, mocha
+- Runtime: engines.node
+
+### 4.1 VALIDAR Stack
+
+```
+AskUserQuestion({
+  question: "Detectei a seguinte stack. Confirmar?",
+  options: [
+    { label: "Stack Correta", description: "Prosseguir" },
+    { label: "Corrigir stack", description: "Vou informar a stack correta" }
+  ]
+})
+```
+
+Se "Corrigir", perguntar cada item separadamente.
+
+---
+
+## Fase 5: VALIDAR TUDO ANTES DE GERAR
+
+```
+AskUserQuestion({
+  question: "Análise completa. Resumo do que foi detectado:",
+  options: [
+    { label: "Está tudo correto", description: "Gerar briefing completo" },
+    { label: "Preciso corrigir", description: "Vou informar o que está errado" }
+  ]
+})
+```
+
+Se "Preciso corrigir":
+```
+AskUserQuestion({
+  question: "O que está errado?",
+  options: [
+    { label: "ADRs", description: "Corrigir ADRs" },
+    { label: "Frontend", description: "Corrigir frontend" },
+    { label: "Backend", description: "Corrigir backend" },
+    { label: "Stack", description: "Corrigir stack" },
+    { label: "Tudo", description: "Vou corrigir tudo" }
+  ]
+})
+```
+
+---
+
+## Fase 6: Geração dos Arquivos do Briefing
+
+**SÓ execute após validação completa.**
+
+### 6.1 Criar pasta
+
+```bash
+mkdir -p docs/tech-context/briefing/
+```
+
+### 6.2 Gerar `project-briefing.md`
+
+Template:
+```markdown
+# Project Briefing — {nome-do-projeto}
+
+> Gerado por /setup:discover em {YYYY-MM-DD}
+
+---
+
+## Projeto
+
+| Campo | Valor |
+|---|---|
+| **Nome** | {nome.detectado} |
+| **Stack** | {stack.validada} |
+| **Backend** | {caminho.detectado} |
+| **Frontend** | {tipo.validado} |
+
+## Status
+
+- ADRs: {N detectadas e validadas}
+- Frontend: {tipo.validado}
+- Convenções: {N detectadas}
+
+---
+
+## Índice
+
+{links para arquivos do briefing}
+```
+
+### 6.3 Gerar `briefing/critical-rules.md`
+
+**Regras SOMENTE de ADRs com status "Aceito" ou "Ativo"**
+
+Se não há ADRs ou nenhuma com status Aceito/Ativo:
+```markdown
+# Regras Críticas
+
+⚠️ Nenhuma ADR com status "Aceito" encontrada.
+
+Para definir regras críticas:
+1. Crie ADRs em `docs/tech/adr/`
+2. Defina o status como "Aceito" quando decidir
+3. Rode /discover novamente
+```
+
+### 6.4 Gerar `briefing/adrs-summary.md`
+
+Se ADRs existem e foram validadas:
+- Índice por categoria
+- Cada ADR com: título, status, decisão resumida
+
+Se NÃO existem ADRs:
+```markdown
+# Sumário de ADRs
+
+⚠️ Nenhuma ADR encontrada em `docs/tech/adr/`
+
+Para criar ADRs, execute /setup:build-tech.
+```
+
+### 6.5 Gerar `briefing/backend-conventions.md`
+
+**SÓ incluir convenções que foram validadas**
+
+```markdown
+# Convenções Backend
+
+**Estrutura de pastas:** {estrutura.validada}
+**Padrão arquitetural:** {padrão.validado}
+
+⚠️ Convenções marcadas como "não detectadas" precisam ser validadas pelo time.
+```
+
+### 6.6 Gerar `briefing/frontend-lovable.md`
+
+**SOMENTE se frontend Lovable foi confirmado**
+
+```markdown
+# Frontend Lovable
+
+**Status:** X mocks pendentes de integração
+
+{mockdetalhes.validado}
+```
+
+Se NÃO há frontend Lovable: NÃO criar este arquivo.
+
+### 6.7 Gerar `briefing/tech-stack.md`
+
+```markdown
+# Tech Stack
+
+**Runtime:** {detectado}
+**Framework:** {detectado}
+**Database:** {detectado}
+**ORM:** {detectado}
+**Validação:** {detectado}
+**Testes:** {detectado}
+
+⚠️ Itens marcados como "não detectado" precisam ser preenchidos.
+```
+
+### 6.8 Gerar `CLAUDE.md` (raiz)
+
+**Sempre execute.** Criar ou sobrescrever.
+
+```markdown
+# {nome-do-projeto}
+
+> Gerado por /setup:discover em {data}
+
+---
+
+## Projeto
+
+| Campo | Valor |
+|---|---|
+| **Nome** | {nome} |
+| **Stack** | {stack} |
+| **Backend** | {caminho} |
+| **Frontend** | {tipo} |
+| **Testes** | {framework} |
+
+---
+
+## Regras Críticas
+
+> Extraídas de ADRs ativas
+
+{listar APENAS se houver ADRs com status Aceito}
+
+---
+
+## Estrutura do Framework
+
+| Diretório | Conteúdo |
+|---|---|
+| `.synapos/core/` | Protocolos core do Framework Synapos |
+| `.synapos/squads/` | Squads instanciados e seus agents |
+| `docs/tech/` | Documentação técnica do projeto |
+| `docs/business/` | Contexto de negócio |
+| `docs/.squads/sessions/` | Estado das features em desenvolvimento |
+```
+
+**Regras de preenchimento:**
+- `{nome-do-projeto}`: de package.json ou pasta raiz
+- Stack: máximo 60 caracteres
+- ADRs: listar apenas de impacto alto
+- Se campo não detectado: usar `"Não detectado"`
+
+---
+
+## Fase 7: Validar Arquivos Gerados
+
+```
+AskUserQuestion({
+  question: "Briefing gerado. Deseja revisar algum arquivo?",
+  options: [
+    { label: "Revisar depois", description: "Encerrar aqui" },
+    { label: "Revisar agora", description: "Vou abrir para revisão" }
+  ]
+})
+```
+
+---
+
+## Resumo Final
+
+```
+✅ Project Discovery concluído!
+
+📁 Arquivos gerados:
+- CLAUDE.md (raiz)
+- docs/tech-context/project-briefing.md
+- docs/tech-context/briefing/critical-rules.md
+- docs/tech-context/briefing/adrs-summary.md
+- docs/tech-context/briefing/backend-conventions.md
+- docs/tech-context/briefing/frontend-lovable.md [se aplicável]
+- docs/tech-context/briefing/tech-stack.md
+
+📊 Análise:
+- ADRs: {N} (ativas: {N})
+- Frontend: {tipo.validado}
+- Backend: {caminho.validado}
+- Stack: {stack.validada}
+
+⚠️ Itens pendentes de validação:
+{listar items marcados como "não detectado" ou "A VALIDAR"}
+
+💡 Próximos Passos:
+1. Revise critical-rules.md
+2. Execute /setup:build-tech para completar docs técnicos
+3. Execute /setup:build-business para docs de negócio
+```
+
+⛔ **IMPORTANTE: Após informar, AGUARDE feedback. NÃO prossiga automaticamente.**
+
+---
+
+## Tratamento de Erros
+
+### Se ADRs malformadas:
+- Avisar: "ADR X está malformada, pulando"
+- NÃO criar ADR para ela
+- Continuar com outras
+
+### Se frontend sem padrão claro:
+- Documentar como "Frontend Não-classificado"
+- NÃO inventar mapeamento de mocks
+
+### Se estrutura backend não reconhecida:
+- Perguntar ao usuário com AskUserQuestion
+- NÃO assumir convenções
+
+### Se package.json não encontrado:
+- Avisar: "Backend sem package.json"
+- Documentar o que foi possível inferir
+
+---
+
+## Regras de Ouro
+
+1. **Nunca assumir:** Se não encontrar, pergunte
+2. **Ser incremental:** Não sobrescrever sem razão
+3. **Ser conservador:** Na dúvida, marque "não detectado"
+4. **Validar sempre:** AskUserQuestion após cada fase
+5. **Parar no fim:** Aguardar feedback do usuário