@justmpm/memory 0.1.0 → 0.1.2

package/AGENTS.md

@@ -0,0 +1,694 @@
+# @justmpm/memory - Guia para Subagents (AGENTS.md)
+
+## Visão Geral
+
+Este documento orienta os diferentes subagents (nexus, sentinel, qa-tester, etc.) sobre como usar o sistema de memória persistente do projeto.
+
+**Objetivo:** Permitir que cada subagent mantenha sua própria memória de aprendizados específicos entre sessões de trabalho.
+
+---
+
+## Quem Deve Usar Memória
+
+TODOS os subagents que participam de tarefas complexas e recorrentes devem usar memória. Isso inclui:
+
+- **nexus** - Orquestrador principal
+- **sentinel** - Estrategista de validação
+- **qa-tester** - Tester com automação no Chrome
+- **fix-worker** - Implementações e correções
+- **ui-designer** - Design e refatoração visual
+- **discover-opportunities** - Descoberta de features não exploradas
+- **audit-* (todos os audit agents)** - Auditorias especializadas
+
+---
+
+## Como Identificar Seu Nome de Agent
+
+Seu nome de agent é passado automaticamente pelo sistema. Para saber qual é:
+
+1. **Verifique seu contexto de inicialização** - O nome geralmente é explicitado
+2. **Use o comando `list`** - Para ver todos os agents com memória no projeto
+3. **Pergunte ao nexus/orquestrador** - Se estiver incerto
+
+**Nomes comuns:**
+- `nexus` - Orquestrador principal
+- `sentinel` - Estrategista de validação
+- `qa-tester` - QA com automação no Chrome
+- `fix-worker` - Executor de implementações
+- `ui-designer` - Designer visual
+
+**Normalização automática:**
+- "Sentinel" → `sentinel`
+- "QA-Tester" → `qa-tester`
+- "My Agent" → `my-agent`
+
+---
+
+## Quando Usar Memória
+
+### Sempre Use Quando:
+
+✅ **Ao iniciar uma sessão de trabalho**
+- Use `read` para carregar aprendizados anteriores
+- Analise o contexto salvo antes de começar
+- Use as informações para informar suas decisões
+
+✅ **Ao aprender algo sobre o projeto**
+- Descobrir padrões de código
+- Identificar estruturas recorrentes
+- Entender arquitetura específica
+
+✅ **Ao encontrar problemas recorrentes**
+- Bugs que aparecem em múltiplas tarefas
+- Erros de configuração
+- Limitações de ferramentas
+
+✅ **Ao tomar decisões**
+- Escolhas técnicas
+- Trade-offs considerados
+- Razões para não usar X
+
+✅ **Ao entender preferências**
+- Estilo de código preferido
+- Nível de detalhe esperado
+- Comunicação preferida
+
+### NÃO Use Quando:
+
+❌ **Para tarefas triviais de uma linha**
+- "Como escrever um loop for" não precisa ser salvo
+- "Como criar um array" é óbvio demais
+
+❌ **Para coisas específicas da sessão atual**
+- Conversação em andamento
+- Variáveis temporárias
+- Experimentos isolados
+
+❌ **Para duplicar informações**
+- Se algo já está salvo, não salve novamente
+- Use `search` para verificar antes
+
+---
+
+## Por Tipo de Agent
+
+### Nexus (Orquestrador)
+
+**Seu foco:** Coordenação, decisões de orquestração, preferências do usuário
+
+**O que salvar:**
+- Padrões de orquestração (ex: "Para tarefas > 5 arquivos, use /relay")
+- Decisões sobre qual agent usar (ex: "Escolhi fix-worker porque...")
+- Preferências do Matheus (ex: "Prefere resposta direta sem enrolação")
+- Sequências de comandos que funcionaram bem
+- Trade-offs que você fez e por quê
+
+**O que NÃO salvar:**
+- Cada mensagem da conversa
+- Coisas óbvias sobre sua função
+- Detalhes técnicos específicos de implementação (deixe isso para fix-worker)
+
+**Exemplo de entrada:**
+```json
+{
+  "command": "append",
+  "agent": "nexus",
+  "entry": "Decisão: Para tarefas longas com > 5 arquivos, use /relay. Para 3-5 arquivos, fix-worker direto funciona melhor. Motivo: /relay mantém contexto entre sessões, fix-worker é mais rápido para tarefas menores"
+}
+```
+
+---
+
+### Sentinel (Estrategista de Validação)
+
+**Seu foco:** Validação de planos, identificação de riscos, estratégias de implementação
+
+**O que salvar:**
+- Padrões de risco identificados no projeto
+- Tipos de erros que ocorrem frequentemente
+- Estratégias de validação que funcionaram
+- Limitações de arquitetura descobertas
+- Padrões de boas práticas específicos
+
+**O que NÃO salvar:**
+- Detalhes de validação triviais
+- Erros de uma única ocorrência
+- Coisas que são padrão geral (deixe isso para a documentação oficial)
+
+**Exemplo de entrada:**
+```json
+{
+  "command": "append",
+  "agent": "sentinel",
+  "entry": "Padrão de risco: Este projeto tem dependência circular entre /services/auth.ts e /services/user.ts. Quando validar planos que tocam esses arquivos, sempre verifique impacto em ambos."
+}
+```
+
+---
+
+### QA-Tester (Tester com Automação Chrome)
+
+**Seu foco:** Testes automatizados no navegador, bugs encontrados, workflows de teste
+
+**O que salvar:**
+- Bugs recorrentes que encontrou
+- Workflows de teste que funcionam
+- Padrões de comportamento da aplicação
+- Configurações de ambiente necessárias
+- Casos de borda importantes
+
+**O que NÃO salvar:**
+- Cada bug individual de teste
+- Detalhes triviais de navegação
+- Coisas que mudam entre testes
+
+**Exemplo de entrada:**
+```json
+{
+  "command": "append",
+  "agent": "qa-tester",
+  "entry": "Bug recorrente: O botão de submit no formulário de login não funciona quando usuário pressiona Enter rapidamente. Reproduzível em Chrome 120. Workaround: Use click() em vez de submit()"
+}
+```
+
+---
+
+### Fix-Worker (Executor de Implementações)
+
+**Seu foco:** Implementações, correções, código escrito
+
+**O que salvar:**
+- Padrões de código descobertos no projeto
+- Convenções específicas de formatação
+- Workarounds para problemas do stack
+- Integrações complexas que funcionaram
+- Limitações técnicas encontradas
+
+**O que NÃO salvar:**
+- Cada implementação individual
+- Coisas que são padrão de linguagem/framework
+- Detalhes que são óbvios do stack
+
+**Exemplo de entrada:**
+```json
+{
+  "command": "append",
+  "agent": "fix-worker",
+  "entry": "Padrão: Este projeto usa Zod v4.3.5 com strict mode. Quando criar schemas, sempre use .strict() e .parse() ao invés de .safeParse() para lançar erros automaticamente"
+}
+```
+
+---
+
+### UI-Designer (Designer Visual)
+
+**Seu foco:** Design, estética visual, refatoração UI, MUI v7
+
+**O que salvar:**
+- Tokens de design usados no projeto
+- Padrões visuais recorrentes
+- Preferências estéticas do usuário
+- Componentes MUI customizados
+- Limitações visuais descobertas
+
+**O que NÃO salvar:**
+- Cada ajuste visual individual
+- Coisas que são padrão MUI
+- Detalhes triviais de CSS
+
+**Exemplo de entrada:**
+```json
+{
+  "command": "append",
+  "agent": "ui-designer",
+  "entry": "Padrão visual: Este projeto usa MUI v7 com tema customizado. Cores primárias são indigo (#6366f1) e secundárias são emerald (#10b981). Use sempre variantes outlined para inputs e contained para botões de ação"
+}
+```
+
+---
+
+### Audit Agents (todos os audit-*)
+
+**Seu foco:** Auditorias especializadas, bugs encontrados, boas práticas
+
+**O que salvar:**
+- Padrões de bugs encontrados no projeto
+- Boas práticas que foram violadas frequentemente
+- Configurações específicas que causam problemas
+- Workflows de auditoria que funcionaram
+- Integrações problemáticas
+
+**O que NÃO salvar:**
+- Cada bug de auditoria individual
+- Coisas que são padrão de qualidade geral
+- Erros de uma única ocorrência
+
+**Exemplo de entrada (audit-technical):**
+```json
+{
+  "command": "append",
+  "agent": "audit-technical",
+  "entry": "Padrão de bug: Este projeto frequentemente esquece de tratar erros async/await. Use try/catch em todas as funções async ou .catch() em Promises"
+}
+```
+
+---
+
+### Discover-Opportunities (Descoberta de Features)
+
+**Seu foco:** Features não exploradas, diferenciais competitivos, verticais ausentes
+
+**O que salvar:**
+- Padrões de features que fazem sentido para o projeto
+- Verticais identificadas como ausentes
+- Diferenciais competitivos sugeridos
+- Restrições de negócio entendidas
+- Padrões de domínio do projeto
+
+**O que NÃO salvar:**
+- Cada sugestão individual
+- Coisas que não fazem sentido para o domínio
+- Ideias vagas sem contexto
+
+**Exemplo de entrada:**
+```json
+{
+  "command": "append",
+  "agent": "discover-opportunities",
+  "entry": "Padrão: Este projeto é um CRM de pets. Vertical ausente: não há funcionalidade de telemedicina veterinária, que seria um diferencial competitivo forte"
+}
+```
+
+---
+
+## Comandos Essenciais por Agent
+
+### Para TODOS os agents
+
+**Ao iniciar trabalho:**
+```json
+{
+  "command": "read",
+  "agent": "seu-nome-aqui"
+}
+```
+
+**Para salvar algo importante:**
+```json
+{
+  "command": "append",
+  "agent": "seu-nome-aqui",
+  "entry": "O que você aprendeu"
+}
+```
+
+**Para verificar algo antes de salvar:**
+```json
+{
+  "command": "search",
+  "agent": "seu-nome-aqui",
+  "query": "termo-busca"
+}
+```
+
+**Para limpar memória grande:**
+```json
+{
+  "command": "write",
+  "agent": "seu-nome-aqui",
+  "content": "# Memória do Seu-Nome\n\n## Seções\n..."
+}
+```
+
+### Específicos por tipo de agent
+
+**Orquestradores (nexus):**
+```json
+// Salvar decisão de orquestração
+{
+  "command": "append",
+  "agent": "nexus",
+  "entry": "Decisão: Escolhi /relay para esta tarefa porque envolve > 10 arquivos e precisa manter contexto entre sessões"
+}
+```
+
+**Executores (fix-worker, ui-designer):**
+```json
+// Salvar padrão de código
+{
+  "command": "append",
+  "agent": "fix-worker",
+  "entry": "Padrão: Sempre use try/catch em funções async que acessam Firestore"
+}
+```
+
+**Auditores (audit-*, sentinel, qa-tester):**
+```json
+// Salvar bug recorrente
+{
+  "command": "append",
+  "agent": "audit-technical",
+  "entry": "Bug recorrente: Formulários sem validação de Zod causam erros runtime em produção. Sempre adicione .strict() aos schemas"
+}
+```
+
+**Analisadores (discover-opportunities):**
+```json
+// Salvar padrão de domínio
+{
+  "command": "append",
+  "agent": "discover-opportunities",
+  "entry": "Padrão de domínio: Este projeto é focado em B2B, então features B2C (como reviews públicos) não são prioridade"
+}
+```
+
+---
+
+## Formato de Memória por Tipo de Agent
+
+### Nexus (Orquestrador)
+
+```markdown
+# Memória do Nexus
+
+## Padrões de Orquestração
+- Para tarefas > 5 arquivos, use /relay
+- Para 3-5 arquivos, fix-worker direto funciona melhor
+- Use analyze antes de delegar para agents
+
+## Decisões
+- Escolhi /relay para tarefas longas
+- Prefiro fix-worker para implementações diretas
+
+## Preferências do Matheus
+- Prefere resposta direta sem enrolação
+- Gosta de explicações simples
+- Valida decisões com contexto
+
+## Anti-padrões
+- Não chame agents sem investigar antes
+- Não assuma, pergunte se não tiver certeza
+```
+
+### Fix-Worker (Executor)
+
+```markdown
+# Memória do Fix-Worker
+
+## Padrões de Código
+- Use Zod com .strict() para validação
+- Trate erros async com try/catch
+- Use TypeScript strict mode
+
+## Integrações
+- Firestore: sempre verifique se array tem length > 0
+- Firebase Auth: use onAuthStateChanged para estado
+
+## Bugs Conhecidos
+- Bug XYZ: ocorre quando array vazio
+- Workaround: verificar antes de update
+
+## Limitações
+- Não consegue acessar recursos externos sem permissão
+```
+
+### QA-Tester (Tester)
+
+```markdown
+# Memória do QA-Tester
+
+## Padrões de Teste
+- Use Chrome 120+ para testes
+- Sempre limpe localStorage antes de testar
+- Use wait() para carregamento assíncrono
+
+## Bugs Recorrentes
+- Login falha quando Enter é pressionado
+- Workaround: usar click() em vez de submit
+
+## Configurações de Ambiente
+- URL base: http://localhost:3000
+- Timeout padrão: 10 segundos
+
+## Workflows de Teste
+- Teste de login: 1) Navegue para /login 2) ...
+```
+
+### UI-Designer (Designer)
+
+```markdown
+# Memória do UI-Designer
+
+## Tokens de Design
+- Primária: indigo (#6366f1)
+- Secundária: emerald (#10b981)
+- Fonte: Inter, 400/500/600
+
+## Padrões Visuais
+- Botões: variant outlined para inputs, contained para ações
+- Cards: elevation={2}, padding={3}
+- Spacing: múltiplos de 8px
+
+## Componentes MUI Customizados
+- CustomButton: com icon support
+- CustomCard: com hover effect
+
+## Preferências do Matheus
+- Prefere design minimalista
+- Gosta de consistência visual
+- Evita animações excessivas
+```
+
+---
+
+## Compartilhamento de Informações Entre Agents
+
+### Como Nexus pode ajudar outros agents
+
+**Ao delegar para fix-worker:**
+```json
+{
+  "command": "read",
+  "agent": "nexus"
+}
+
+// Nexus analisa se há informações relevantes para fix-worker
+// Se houver, passa no contexto da delegação
+```
+
+**Ao delegar para ui-designer:**
+```json
+{
+  "command": "read",
+  "agent": "nexus"
+}
+
+// Nexus busca preferências visuais do Matheus
+// Passa essas informações para ui-designer
+```
+
+### Como outros agents podem compartilhar com Nexus
+
+**Ao completar tarefa:**
+- Fix-worker: reporta padrões de código descobertos
+- QA-Tester: reporta bugs recorrentes encontrados
+- UI-Designer: reporta limitações visuais descobertas
+
+Nexus pode então usar `append` para salvar essas informações se forem importantes.
+
+### Quando usar `list` para descobrir outros agents
+
+```json
+{
+  "command": "list"
+}
+```
+
+**Útil para:**
+- Saber quais agents já trabalharam no projeto
+- Verificar se há memória relevante em outros agents
+- Entender a história do projeto
+
+---
+
+## Boas Práticas Específicas por Agent
+
+### Para Orquestradores (Nexus)
+
+✅ **DO:**
+- Salve decisões de por que escolheu X ao invés de Y
+- Salve padrões de orquestração que funcionaram
+- Salve preferências do usuário para passar a outros agents
+- Use `list` para descobrir agents existentes antes de delegar
+- Leia memória de outros agents se for relevante
+
+❌ **DON'T:**
+- Salve cada decisão trivial
+- Salve detalhes técnicos de implementação
+- Assuma que sabe tudo o que outros agents descobriram
+
+### Para Executores (Fix-Worker, UI-Designer)
+
+✅ **DO:**
+- Salve padrões de código/design específicos do projeto
+- Salve workarounds para problemas recorrentes
+- Salve limitações técnicas encontradas
+- Salve integrações que funcionaram bem
+- Use `search` para verificar se algo já foi salvo
+
+❌ **DON'T:**
+- Salve cada implementação individual
+- Salve coisas que são padrão de linguagem/framework
+- Salve detalhes triviais que não se repetem
+
+### Para Auditores (Audit-*, Sentinel, QA-Tester)
+
+✅ **DO:**
+- Salve padrões de bugs encontrados no projeto
+- Salve workflows de auditoria/teste que funcionaram
+- Salve configurações que causam problemas
+- Salve boas práticas violadas frequentemente
+- Salve restrições de ambiente/teste
+
+❌ **DON'T:**
+- Salve cada bug individual de uma única ocorrência
+- Salve coisas que são padrão geral de qualidade
+- Salve detalhes triviais de navegação/teste
+
+### Para Analisadores (Discover-Opportunities)
+
+✅ **DO:**
+- Salve padrões de domínio do projeto
+- Salve verticais identificadas como ausentes
+- Salve restrições de negócio entendidas
+- Salver diferenciais competitivos que fazem sentido
+- Salvar estratégias de análise que funcionaram
+
+❌ **DON'T:**
+- Salvar cada sugestão individual sem contexto
+- Salvar ideias vagas sem relação com o domínio
+- Salvar coisas que não fazem sentido para o projeto
+
+---
+
+## Exemplos Completos de Uso
+
+### Exemplo 1: Nexus iniciando sessão e delegando
+
+```
+// Nexus: Lê sua própria memória
+IA: { "command": "read", "agent": "nexus" }
+
+Resultado: 📝 Memória de "nexus" (30 linhas):
+─────────────────────────────────────────────────────────────────
+
+# Memória do Nexus
+
+## Padrões de Orquestração
+- Para tarefas > 5 arquivos, use /relay
+- Use analyze antes de delegar
+
+## Preferências do Matheus
+- Prefere resposta direta sem enrolação
+...
+
+// Nexus: Lista todos os agents com memória
+IA: { "command": "list" }
+
+Resultado: 📝 Agents com memória neste projeto (3):
+
+  • nexus (30 linhas)
+  • fix-worker (45 linhas)
+  • ui-designer (20 linhas)
+
+// Nexus: Lê memória do fix-worker para entender contexto
+IA: { "command": "read", "agent": "fix-worker" }
+
+Resultado: 📝 Memória de "fix-worker" (45 linhas):
+─────────────────────────────────────────────────────────────────
+
+# Memória do Fix-Worker
+
+## Padrões de Código
+- Use Zod com .strict() para validação
+...
+
+// Nexus: Delega para fix-worker com contexto completo
+IA: [Usa task para chamar fix-worker com contexto sobre o projeto]
+```
+
+### Exemplo 2: Fix-worker descobrindo padrão e salvando
+
+```
+// Fix-worker: Implementa um formulário
+IA: [Escreve código do formulário]
+
+// Fix-worker: Nota que todos os formulários usam Zod
+IA: { "command": "search", "agent": "fix-worker", "query": "Zod" }
+
+Resultado: 📝 Nenhuma ocorrência de "Zod" encontrada
+
+// Fix-worker: Salva o padrão descoberto
+IA: { "command": "append", "agent": "fix-worker",
+     "entry": "Padrão descoberto: Este projeto usa Zod v4.3.5 com strict mode para validação de formulários. Sempre use .strict() e .parse() ao criar schemas de formulário" }
+```
+
+### Exemplo 3: QA-tester encontrando bug recorrente
+
+```
+// QA-tester: Testa formulário de login
+IA: [Executa teste automatizado no Chrome]
+
+// QA-tester: Encontra bug ao pressionar Enter
+IA: { "command": "search", "agent": "qa-tester", "query": "Enter" }
+
+Resultado: 📝 Nenhuma ocorrência de "Enter" encontrada
+
+// QA-tester: Verifica se ocorre em outros formulários
+IA: [Testa mais formulários]
+
+// QA-tester: Confirma que é um padrão recorrente
+IA: { "command": "append", "agent": "qa-tester",
+     "entry": "Bug recorrente: Botões de submit em formulários não funcionam quando usuário pressiona Enter. Ocorre em formulários de login, cadastro e contato. Workaround: usar event de click() em vez de submit()" }
+```
+
+---
+
+## Checklist por Sessão
+
+### Ao INICIAR sessão de trabalho
+
+- [ ] Use `read` para carregar sua memória
+- [ ] Analise o conteúdo retornado
+- [ ] Use `list` para descobrir outros agents (se relevante)
+- [ ] Leia memórias de outros agents se for relevante para sua tarefa
+
+### DURANTE a sessão
+
+- [ ] Use `search` antes de salvar algo novo
+- [ ] Salve apenas coisas que são específicas e importantes
+- [ ] Seja específico e contextual em suas entradas
+- [ ] Explique o PORQUÊ quando relevante
+
+### Ao FINAL da sessão
+
+- [ ] Revise as entradas adicionadas
+- [ ] Se memória estiver grande (~150+ linhas), considere `WRITE`
+- [ ] Organize as entradas em seções (se usar WRITE)
+- [ ] Compartilhe informações relevantes com nexus/outros agents
+
+---
+
+## Resumo Rápido
+
+| Comando | Nexus | Fix-Worker | QA-Tester | UI-Designer |
+|---------|-------|------------|-----------|--------------|
+| `read` | ✅ Sempre | ✅ Sempre | ✅ Sempre | ✅ Sempre |
+| `append` | Decisões, preferências | Padrões de código | Bugs recorrentes | Padrões visuais |
+| `write` | Reorganizar | Reorganizar | Reorganizar | Reorganizar |
+| `search` | Verificar antes | Verificar antes | Verificar antes | Verificar antes |
+| `list` | Descobrir agents | Raramente | Raramente | Raramente |
+
+---
+
+**Lembre-se:** Cada agent tem sua própria especialização e foco. Salve o que é relevante para SUA função, não tudo o que você faz!