@onion-architect-ai/cli 4.1.0-beta.1 → 4.1.0-beta.3

package/templates/.cursor/docs/templates/solution-template.md

@@ -0,0 +1,390 @@
+# 🔧 Solução: [Nome da Solução] - [Sistema/Componente Afetado]
+
+**Tipo de Solução:** [Build | Runtime | Configuration | Integration | Performance]  
+**Severidade:** [🔴 CRÍTICA | 🟡 ALTA | 🟢 MÉDIA | 🔵 BAIXA]  
+**Complexidade:** [🚀 Simples | ⚡ Moderada | 🏗️ Complexa]  
+**Escopo:** [Projeto Específico | Múltiplos Projetos | Sistema Completo]  
+**Data:** [DD/MM/YYYY]  
+**Status:** [✅ Validado | 🧪 Em Teste | 📋 Documentado | 🚀 Produção]  
+**Responsável:** [Nome/Equipe]
+
+---
+
+## 🎯 **QUICK MATCH - AI DIAGNOSTIC**
+
+### **❓ Use esta solução SE você tem:**
+- [ ] **Erro específico**: `[Mensagem de erro exata ou padrão regex]`
+- [ ] **Sintoma**: [Comportamento observado específico]
+- [ ] **Contexto**: [Tecnologia/versão/ambiente específico]
+- [ ] **Comando falhando**: `[comando específico que falha]`
+
+### **❌ NÃO use esta solução SE:**
+- [ ] **Contexto diferente**: [Situações onde não se aplica]
+- [ ] **Versões incompatíveis**: [Limitações de versão]
+- [ ] **Ambiente específico**: [Limitações de ambiente]
+
+### **🏷️ Tags de Busca**
+```yaml
+Tecnologias: [tech1, tech2, tech3]
+Sintomas: [sintoma1, sintoma2, sintoma3]
+Comandos: [cmd1, cmd2, cmd3]
+Erros: [error-pattern-1, error-pattern-2]
+Arquitetura: [ESM, CommonJS, Workers, etc.]
+```
+
+---
+
+## 🚨 **PROBLEMA IDENTIFICADO**
+
+### **Contexto do Problema**
+[Descrição detalhada do contexto onde o problema ocorre]
+
+### **Sintomas Observados**
+```bash
+# Exemplo de erro/comportamento observado
+[Mensagem de erro completa ou comportamento]
+```
+
+**Manifestações:**
+- ✅ **Cenário que funciona**: [Descrição]
+- ❌ **Cenário que falha**: [Descrição] 
+- ⚠️ **Comportamento inconsistente**: [Descrição]
+
+### **Impacto do Problema**
+- **Bloqueio**: [O que fica bloqueado]
+- **Workarounds**: [Soluções temporárias conhecidas]
+- **Criticidade**: [Por que precisa ser resolvido]
+
+### **Diagnóstico - Comandos de Verificação**
+```bash
+# Verificar se você tem este problema
+[comando para diagnosticar]
+
+# Verificar versões/contexto
+[comando para verificar ambiente]
+
+# Logs específicos para análise
+[comando para ver logs relevantes]
+```
+
+---
+
+## 🔍 **ANÁLISE DA CAUSA RAIZ**
+
+### **Causa Principal**
+[Explicação técnica da causa fundamental do problema]
+
+### **Por que Acontece**
+1. **[Fator 1]**: [Explicação detalhada]
+2. **[Fator 2]**: [Explicação detalhada]
+3. **[Fator 3]**: [Explicação detalhada]
+
+### **Arquitetura/Fluxo Afetado**
+```mermaid
+graph TD
+    A[Componente A] -->|❌ Falha aqui| B[Componente B]
+    B --> C[Resultado Esperado]
+    
+    %% Problema
+    A -->|🔧 Solução proposta| D[Fix Aplicado]
+    D --> E[✅ Resultado Correto]
+    
+    classDef problemNode fill:#ffcccc,stroke:#ff0000
+    classDef solutionNode fill:#ccffcc,stroke:#00ff00
+    
+    class B problemNode
+    class D,E solutionNode
+```
+
+### **Diferenças de Problemas Similares**
+| **Este Problema** | **Problema Similar X** | **Diferença Chave** |
+|-------------------|------------------------|---------------------|
+| [Característica] | [Característica] | [Como distinguir] |
+
+---
+
+## ✅ **SOLUÇÃO IMPLEMENTADA**
+
+### **Estratégia da Solução**
+[Descrição de alto nível da abordagem escolhida e por quê]
+
+### **Implementação Passo a Passo**
+
+#### **Passo 1: [Nome do Passo]**
+**Objetivo:** [O que este passo resolve]
+
+```[linguagem]
+# [Descrição do código/comando]
+[código ou configuração específica]
+```
+
+**Validação:**
+```bash
+# Como verificar se este passo funcionou
+[comando de verificação]
+```
+
+#### **Passo 2: [Nome do Passo]**
+[Repetir estrutura similar para cada passo]
+
+### **Configurações Finais**
+```[formato]
+# [Descrição da configuração final]
+[configuração completa]
+```
+
+### **Por que Esta Solução Funciona**
+1. **[Razão técnica 1]**: [Explicação]
+2. **[Razão técnica 2]**: [Explicação]
+3. **[Razão técnica 3]**: [Explicação]
+
+---
+
+## 📊 **VALIDAÇÃO E RESULTADOS**
+
+### **Antes vs Depois**
+| **Teste/Cenário** | **❌ Antes** | **✅ Depois** |
+|-------------------|-------------|--------------|
+| [Cenário 1] | [Comportamento antigo] | [Comportamento novo] |
+| [Cenário 2] | [Comportamento antigo] | [Comportamento novo] |
+| [Cenário 3] | [Comportamento antigo] | [Comportamento novo] |
+
+### **Comandos de Validação Completa**
+```bash
+# Validação automática completa
+[comando que testa tudo]
+
+# Testes específicos
+[comando 1]                    # [O que testa]
+[comando 2]                    # [O que testa]
+[comando 3]                    # [O que testa]
+
+# Verificação de regressão
+[comando para garantir que não quebrou nada]
+```
+
+### **Métricas de Sucesso**
+```yaml
+Performance:
+  antes: [métrica anterior]
+  depois: [métrica nova]
+  melhoria: [X% ou Xms]
+
+Estabilidade:
+  taxa_sucesso_antes: [X%]
+  taxa_sucesso_depois: [Y%]
+  
+Manutenibilidade:
+  complexidade_antes: [Alta/Média/Baixa]
+  complexidade_depois: [Alta/Média/Baixa]
+```
+
+---
+
+## 🔄 **APLICAÇÃO A NOVOS CASOS**
+
+### **Para Novos Projetos do Mesmo Tipo**
+```bash
+# Setup automático para novo projeto
+[sequência de comandos ou script]
+```
+
+### **Para Projetos Similares**
+1. **Identificar similaridades**: [Como saber se aplica]
+2. **Adaptações necessárias**: [O que modificar]
+3. **Validação**: [Como confirmar que funcionou]
+
+### **Padrão Reutilizável**
+```[linguagem]
+// Template/função reutilizável baseada na solução
+[código genérico que pode ser aplicado]
+```
+
+### **Automação Preventiva**
+```bash
+# Script para aplicar automaticamente
+[script que detecta e aplica a solução]
+
+# Integração no CI/CD
+[como integrar para detectar o problema automaticamente]
+```
+
+---
+
+## 🚨 **TROUBLESHOOTING**
+
+### **Se a Solução NÃO Funcionar**
+
+#### **Problema A: [Cenário específico]**
+**Sintoma:**
+```
+[Mensagem de erro ou comportamento]
+```
+
+**Possível Causa:** [Explicação]
+
+**Solução:**
+```bash
+[comandos para resolver este caso específico]
+```
+
+#### **Problema B: [Cenário específico]**
+[Estrutura similar para outros casos]
+
+### **Quick Fixes (Soluções Rápidas)**
+```bash
+# Reset/limpeza completa (último recurso)
+[sequência de comandos para reset]
+
+# Diagnóstico em uma linha
+[comando que mostra status geral]
+
+# Fix comum #1
+[solução rápida para problema frequente]
+
+# Fix comum #2  
+[solução rápida para outro problema frequente]
+```
+
+### **Checklist de Diagnóstico**
+- [ ] **[Verificação 1]**: `[comando]` deve retornar `[resultado esperado]`
+- [ ] **[Verificação 2]**: `[comando]` deve retornar `[resultado esperado]`
+- [ ] **[Verificação 3]**: `[comando]` deve retornar `[resultado esperado]`
+- [ ] **[Verificação 4]**: `[comando]` deve retornar `[resultado esperado]`
+
+### **Rollback (Se Necessário)**
+```bash
+# Como desfazer esta solução completamente
+[sequência de comandos para reverter]
+```
+
+---
+
+## 🎯 **CASOS DE USO E LIMITAÇÕES**
+
+### **✅ Casos de Uso Validados**
+1. **[Caso 1]**: [Descrição] - ✅ Funcionando
+2. **[Caso 2]**: [Descrição] - ✅ Funcionando  
+3. **[Caso 3]**: [Descrição] - ✅ Funcionando
+
+### **❌ Limitações Conhecidas**
+1. **[Limitação 1]**: [Descrição e contexto]
+2. **[Limitação 2]**: [Descrição e contexto]
+
+### **🔄 Compatibilidade**
+```yaml
+Tecnologias_Suportadas:
+  - [tech1]: [versões]
+  - [tech2]: [versões]
+  
+Ambientes_Testados:
+  - [ambiente1]: ✅ Validado
+  - [ambiente2]: ⚠️ Parcial
+  - [ambiente3]: ❌ Não testado
+
+Sistemas_Operacionais:
+  - Linux: ✅ Validado
+  - macOS: ✅ Validado  
+  - Windows: ⚠️ Não testado
+```
+
+---
+
+## 📚 **REFERÊNCIAS E CONTEXTO**
+
+### **Problemas Relacionados**
+- 📄 **[Solução relacionada 1]**: [link] - [relação]
+- 📄 **[Solução relacionada 2]**: [link] - [relação]
+- 📄 **[Problema upstream]**: [link] - [como se relaciona]
+
+### **Issues/Discussões Externas**
+- 🔗 **[Issue relevante]**: [URL] - [resumo]
+- 🔗 **[Documentação oficial]**: [URL] - [seção específica]
+- 🔗 **[StackOverflow]**: [URL] - [problema similar]
+
+### **Tecnologias e Versões**
+```yaml
+Stack_Principal:
+  - [Tecnologia]: [versão mínima] - [versão testada]
+  - [Framework]: [versão mínima] - [versão testada]
+  
+Dependências_Críticas:
+  - [lib1]: [versão] - [por que esta versão]
+  - [lib2]: [versão] - [por que esta versão]
+```
+
+### **Histórico de Mudanças**
+| **Versão** | **Data** | **Mudanças** | **Compatibilidade** |
+|------------|----------|--------------|---------------------|
+| [X.Y.Z] | [DD/MM/YYYY] | [Mudanças específicas] | [Impacto na compatibilidade] |
+
+---
+
+## 🎉 **STATUS FINAL E BENEFÍCIOS**
+
+### **✅ Status de Produção**
+- **Ambiente Desenvolvimento**: ✅ Validado
+- **Ambiente Staging**: ✅ Validado  
+- **Ambiente Produção**: ✅ Deploy Ready
+- **Testes Automatizados**: ✅ Integrados
+
+### **🚀 Benefícios Alcançados**
+1. **[Benefício 1]**: [Métrica específica de melhoria]
+2. **[Benefício 2]**: [Métrica específica de melhoria]
+3. **[Benefício 3]**: [Métrica específica de melhoria]
+
+### **💡 Lições Aprendidas**
+- **✅ O que funcionou bem**: [Insights positivos]
+- **⚠️ O que poderia ser melhor**: [Pontos de melhoria]
+- **🔮 Próximas iterações**: [Evoluções planejadas]
+
+### **🎯 Próximos Passos**
+1. **[Ação 1]**: [Descrição e timeline]
+2. **[Ação 2]**: [Descrição e timeline]
+3. **[Ação 3]**: [Descrição e timeline]
+
+---
+
+## 📋 **QUICK REFERENCE PARA AI**
+
+### **Comandos de Diagnóstico Rápido**
+```bash
+# Um comando que determina se esta solução se aplica
+[comando único de diagnóstico]
+
+# Status geral do sistema após aplicar solução
+[comando de status]
+```
+
+### **Padrões de Erro que Esta Solução Resolve**
+```regex
+# Regex patterns para identificação automática
+^[padrão de erro 1].*$
+^[padrão de erro 2].*$
+```
+
+### **Tags de Classificação para Busca**
+```yaml
+problemas: [tag1, tag2, tag3]
+tecnologias: [tech1, tech2, tech3]  
+ambientes: [env1, env2, env3]
+severidade: [crítica|alta|média|baixa]
+complexidade: [simples|moderada|complexa]
+```
+
+---
+
+**💡 Dicas de Uso deste Template:**
+
+1. **🎯 Seja específico** nas mensagens de erro e sintomas
+2. **🔍 Inclua comandos** de diagnóstico funcionais  
+3. **📊 Documente resultados** antes/depois com métricas
+4. **🔄 Teste a aplicação** em cenários similares
+5. **🤖 Otimize para AI** com tags e padrões claros
+6. **📚 Referencie problemas** relacionados quando relevante
+
+---
+
+**📅 Última Atualização do Template:** [DD/MM/YYYY]  
+**📚 Versão do Template:** 1.0.0  
+**🔗 Baseado em:** Análise de [build-solution.md, CORS_SOLUTION.md, worker-thread-solution.md] 

package/templates/.cursor/docs/tools/README.md

@@ -0,0 +1,325 @@
+# 🛠️ Documentação de Ferramentas - Sistema Onion
+
+> Documentação completa de todas as ferramentas disponíveis no contexto do Cursor IDE organizadas por categoria.
+
+## 📑 Índice Geral
+
+### 🔌 [Ferramentas MCP](./mcps.md)
+Integrações com Model Context Protocol - ClickUp, Postman, Nx
+- **50+ funções** para gestão de projeto e workflow
+- Integração completa com ClickUp (tasks, time tracking, docs)
+- Postman API management (collections, mocks, monitors)
+- Nx monorepo tools (generators, CI/CD)
+
+### 🤖 [Agentes Especializados](./agents.md)
+14+ agentes de IA especializados para tarefas específicas
+- Gestão de Produto (@product-agent, @clickup-specialist)
+- Desenvolvimento (@react-developer, @python-developer)
+- Qualidade (@code-reviewer, @test-engineer)
+- Arquitetura (@metaspec-gate-keeper)
+
+### 📋 [Comandos .cursor/](./commands.md)
+46 comandos organizados em workflows automatizados
+- **Product Workflow** (10 comandos) - Feature planning, specs
+- **Engineer Workflow** (11 comandos) - Development, PR, versioning
+- **Git Workflow** (11 comandos) - Feature/Release/Hotfix flows
+- **Documentation** (9 comandos) - Docs generation & validation
+
+### ⚙️ [Regras e Configurações](./rules.md)
+Regras do workspace, padrões e convenções
+- Convenções de linguagem (EN code, PT-BR docs)
+- Estrutura de projeto
+- Formatação ClickUp (Markdown vs Unicode)
+- Padrões de código e testes
+
+### 🛠️ [Ferramentas Core do Cursor](./cursor.md)
+Ferramentas fundamentais do Cursor IDE
+- Operações de codebase (search, read, edit)
+- File operations (create, update, delete)
+- Terminal commands
+- Grep/search avançado
+- Linting & validation
+
+---
+
+## 🎯 Guia Rápido de Uso
+
+### Por Tipo de Tarefa
+
+| Preciso... | Use... |
+|-----------|--------|
+| 🎯 Planejar feature | `@product-agent` + `/product/feature` |
+| ✅ Criar task ClickUp | `mcp_ClickUp_clickup_create_task` |
+| 💻 Desenvolver código | `@react-developer` ou `@python-developer` |
+| 🔍 Buscar no código | `codebase_search` (semântico) ou `grep` (exato) |
+| 📝 Editar arquivo | `search_replace` |
+| 🧪 Criar testes | `@test-engineer` |
+| 👀 Review código | `@code-reviewer` + `/git/code-review` |
+| 🚀 Fazer deploy | `@deployment-specialist` |
+| 📚 Gerar docs | `/docs/build-tech-docs` |
+| 🔧 Problema técnico ClickUp | `@clickup-specialist` |
+| ⚙️ Problema Cursor IDE | `@cursor-specialist` |
+
+### Por Fase do Projeto
+
+#### 1️⃣ Discovery & Planning
+```bash
+@product-agent                 # Consultar especialista
+/product/feature              # Iniciar planejamento
+mcp_ClickUp_clickup_create_task  # Criar task
+```
+
+#### 2️⃣ Development
+```bash
+/engineer/start               # Setup sessão
+@react-developer              # Consultar especialista
+codebase_search()             # Explorar código
+search_replace()              # Editar código
+```
+
+#### 3️⃣ Testing & Review
+```bash
+@test-engineer                # Criar testes
+/engineer/pre-pr              # Validar
+@code-reviewer                # Review
+```
+
+#### 4️⃣ Integration & Deploy
+```bash
+/engineer/pr                  # Criar PR
+/git/feature/finish           # Merge
+@deployment-specialist        # Deploy
+```
+
+---
+
+## 📊 Estatísticas
+
+### Por Categoria
+
+| Categoria | Quantidade | Uso Principal |
+|-----------|------------|---------------|
+| **MCP - ClickUp** | 50+ funções | Gestão de tasks, time tracking |
+| **MCP - Postman** | 30+ funções | API management, testing |
+| **MCP - Nx** | 10+ funções | Monorepo, generators, CI/CD |
+| **Agentes** | 14+ agentes | Especialização em tarefas |
+| **Comandos** | 46 comandos | Workflows automatizados |
+| **Core Tools** | 15+ ferramentas | Operações fundamentais IDE |
+
+### Mais Utilizados
+
+#### Ferramentas MCP
+1. `mcp_ClickUp_clickup_create_task`
+2. `mcp_ClickUp_clickup_search`
+3. `mcp_ClickUp_clickup_update_task`
+4. `mcp_ClickUp_clickup_create_task_comment`
+5. `mcp_ClickUp_clickup_get_task`
+
+#### Agentes
+1. `@product-agent`
+2. `@react-developer`
+3. `@code-reviewer`
+4. `@clickup-specialist`
+5. `@test-engineer`
+
+#### Comandos
+1. `/engineer/work`
+2. `/product/feature`
+3. `/git/feature/start`
+4. `/engineer/pr`
+5. `/docs/build-tech-docs`
+
+#### Core Tools
+1. `codebase_search`
+2. `read_file`
+3. `search_replace`
+4. `grep`
+5. `run_terminal_cmd`
+
+---
+
+## 🎓 Melhores Práticas
+
+### ✅ Fazer
+
+1. **Use agentes especializados** para tarefas específicas
+   ```markdown
+   @product-agent planeje feature de autenticação
+   @react-developer implemente componente
+   @test-engineer crie os testes
+   ```
+
+2. **Combine ferramentas** para workflows completos
+   ```typescript
+   // 1. Buscar contexto
+   codebase_search({query: "Como funciona autenticação?"})
+   
+   // 2. Criar task
+   mcp_ClickUp_clickup_create_task({name: "Implementar JWT"})
+   
+   // 3. Desenvolver
+   search_replace({file_path: "auth/service.ts", ...})
+   
+   // 4. Documentar
+   mcp_ClickUp_clickup_create_task_comment({...})
+   ```
+
+3. **Siga workflows estabelecidos** para consistência
+   ```bash
+   /product/feature → /engineer/start → /engineer/work → /engineer/pr
+   ```
+
+4. **Paralelizar operações** independentes
+   ```typescript
+   Promise.all([
+     read_file({target_file: "file1.ts"}),
+     read_file({target_file: "file2.ts"}),
+     read_file({target_file: "file3.ts"})
+   ])
+   ```
+
+### ❌ Evitar
+
+1. ❌ Usar ferramentas genéricas quando há especializadas
+   - Prefira `@clickup-specialist` a perguntas gerais sobre ClickUp
+   - Use `codebase_search` em vez de grep para busca semântica
+
+2. ❌ Pular etapas de validação
+   - Sempre use `/engineer/pre-pr` antes de PR
+   - Valide com `@metaspec-gate-keeper` mudanças arquiteturais
+
+3. ❌ Criar arquivos temporários sem cleanup
+   - Delete scripts helper após uso
+   - Mantenha workspace limpo
+
+4. ❌ Misturar idiomas
+   - Código sempre em inglês
+   - Comentários e commits em português
+
+---
+
+## 🔗 Links Rápidos
+
+### Documentação Detalhada
+- [🔌 MCP Tools (ClickUp, Postman, Nx)](./mcps.md)
+- [🤖 Agentes Especializados](./agents.md)
+- [📋 Comandos .cursor/](./commands.md)
+- [⚙️ Regras e Configurações](./rules.md)
+- [🛠️ Ferramentas Core](./cursor.md)
+
+### Recursos Externos
+- [ClickUp API Docs](https://clickup.com/api)
+- [Postman API Docs](https://www.postman.com/postman/workspace/postman-public-workspace/documentation/12959542-c8142d51-e97c-46b6-bd77-52bb66712c9a)
+- [Nx Documentation](https://nx.dev)
+- [Cursor IDE Documentation](https://cursor.sh/docs)
+
+---
+
+## 🆘 Precisa de Ajuda?
+
+### Por Tipo de Problema
+
+| Problema | Solução |
+|----------|---------|
+| 🔌 Erro ClickUp MCP | `@clickup-specialist` |
+| 🖥️ Problema Cursor IDE | `@cursor-specialist` |
+| 💻 Dúvida técnica React | `@react-developer` |
+| 🐍 Dúvida técnica Python | `@python-developer` |
+| 🏗️ Validação arquitetura | `@metaspec-gate-keeper` |
+| 📝 Ajuda com documentação | `/docs/help` |
+| 🔀 Ajuda com Git | `/git/help` |
+| 🔍 Pesquisa geral | `@research-agent` |
+
+### Comandos de Ajuda
+```bash
+/docs/help        # Comandos de documentação
+/git/help         # Comandos Git
+/product/README   # Workflow de produto
+/engineer/README  # Workflow de engenharia
+```
+
+---
+
+## 🚀 Começando
+
+### Setup Inicial
+1. ✅ Verifique regras do workspace em [rules.md](./rules.md)
+2. ✅ Explore comandos disponíveis em [commands.md](./commands.md)
+3. ✅ Conheça os agentes em [agents.md](./agents.md)
+4. ✅ Configure integrações MCP em [mcps.md](./mcps.md)
+
+### Primeira Feature
+```bash
+# 1. Planeje
+/product/feature
+
+# 2. Configure ambiente
+/engineer/start
+
+# 3. Desenvolva
+/engineer/work
+
+# 4. Finalize
+/engineer/pr
+/git/feature/finish
+```
+
+### Warm-up Rápido
+```bash
+/warm-up                    # Contexto geral
+/product/warm-up            # Contexto de produto
+/engineer/warm-up           # Contexto técnico
+```
+
+---
+
+## 📈 Roadmap
+
+### Próximas Adições
+- [ ] Workflows de deployment
+- [ ] Mais templates de documentação
+- [ ] Automações de CI/CD
+- [ ] Integrações adicionais MCP
+
+### Melhorias Planejadas
+- [ ] Otimização de performance
+- [ ] Mais exemplos práticos
+- [ ] Troubleshooting guides
+- [ ] Video tutorials
+
+---
+
+## 🎉 Contribuindo
+
+Esta documentação é viva e evolui com o projeto. Para sugestões:
+1. Use `@product-agent` para planejar melhorias
+2. Documente mudanças em `/docs/`
+3. Mantenha sincronizado com código
+
+---
+
+## 📝 Notas da Versão
+
+### v1.0.1 - Atualização (2025-01-27)
+- ✅ Adicionadas ferramentas MCP gerais (list_mcp_resources, fetch_mcp_resource)
+- ✅ Validação completa de todas as ferramentas disponíveis
+- ✅ Documentação sincronizada com contexto atual
+
+### v1.0.0 - Setup Inicial (2025-01-27)
+- ✅ 50+ ferramentas MCP documentadas
+- ✅ 14+ agentes especializados catalogados
+- ✅ 46 comandos organizados por categoria
+- ✅ Guias de uso e melhores práticas
+- ✅ Índice central de recursos
+
+---
+
+<div align="center">
+
+**Sistema Onion** 🧅  
+*Eficiência • Qualidade • Automação Inteligente*
+
+[Início](#-documentação-de-ferramentas---sistema-onion) • [MCP](./mcps.md) • [Agentes](./agents.md) • [Comandos](./commands.md) • [Regras](./rules.md) • [Core](./cursor.md)
+
+</div>
+