@onion-ai/cli 1.0.0-beta.1

package/framework/docs/tools/README.md

@@ -0,0 +1,356 @@
+# 🛠️ 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 .claude/](./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 .claude/](./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>

package/framework/docs/tools/agents.md

@@ -0,0 +1,365 @@
+# 🤖 Agentes Especializados
+
+## 📑 Índice
+
+- [Gestão de Produto](#gestão-de-produto)
+- [Desenvolvimento](#desenvolvimento)
+- [Qualidade e Review](#qualidade-e-review)
+- [Compliance e Meta](#compliance-e-meta)
+- [Pesquisa e Dados](#pesquisa-e-dados)
+- [Deployment](#deployment)
+
+---
+
+## Gestão de Produto
+
+### `@product-agent`
+
+```typescript
+agent: 'product-agent';
+// Propósito: Gestor estratégico de produto - planejamento, roadmap, integração ClickUp
+// Especialidades: Product strategy, backlog management, stakeholder communication
+// Quando usar: Planejamento de features, priorização, gestão de tasks no ClickUp
+```
+
+**Capacidades:**
+
+- 📋 Criação e gestão de tasks no ClickUp
+- 🎯 Definição de roadmap e prioridades
+- 📊 Análise de métricas de produto
+- 🔄 Sincronização entre desenvolvimento e negócio
+- 📝 Documentação de requisitos
+
+**Workflows:**
+
+- `/product/plan-feature` - Planeja nova feature
+- `/product/review-backlog` - Revisa backlog
+- `/product/update-roadmap` - Atualiza roadmap
+
+---
+
+## Desenvolvimento
+
+### `@react-developer`
+
+```typescript
+agent: 'react-developer';
+// Propósito: Especialista em desenvolvimento React/Next.js
+// Especialidades: React, TypeScript, Next.js, TailwindCSS, hooks, performance
+// Quando usar: Desenvolvimento de componentes, features React, otimizações frontend
+```
+
+**Capacidades:**
+
+- ⚛️ Componentes React modernos (hooks, context)
+- 🎨 Estilização com TailwindCSS
+- 🚀 Otimização de performance
+- 📱 Responsive design
+- ♿ Acessibilidade (a11y)
+
+### `@python-developer`
+
+```typescript
+agent: 'python-developer';
+// Propósito: Especialista em desenvolvimento Python
+// Especialidades: Python 3.x, FastAPI, Django, async/await, data processing
+// Quando usar: Backend Python, APIs, scripts, processamento de dados
+```
+
+**Capacidades:**
+
+- 🐍 Python moderno (3.10+)
+- 🚀 APIs com FastAPI/Django
+- 📊 Processamento de dados
+- 🔄 Programação assíncrona
+- 🧪 Testes com pytest
+
+---
+
+## Qualidade e Review
+
+### `@code-reviewer`
+
+```typescript
+agent: 'code-reviewer';
+// Propósito: Revisor de código - qualidade, padrões, best practices
+// Especialidades: Code review, refactoring, performance analysis
+// Quando usar: Review de PRs, análise de qualidade, sugestões de melhorias
+```
+
+**Capacidades:**
+
+- 🔍 Análise de qualidade de código
+- 📐 Verificação de padrões
+- 🎯 Sugestões de refactoring
+- 🐛 Identificação de bugs potenciais
+- 📊 Análise de complexidade
+
+### `@branch-code-reviewer`
+
+```typescript
+agent: 'branch-code-reviewer';
+// Propósito: Revisor especializado em mudanças de branch
+// Especialidades: Git diff analysis, branch comparison, merge conflicts
+// Quando usar: Review de branches antes de merge, análise de conflitos
+```
+
+**Capacidades:**
+
+- 🌿 Análise de diff entre branches
+- 🔀 Detecção de conflitos
+- 📝 Sugestões de merge
+- 🎯 Foco em mudanças específicas
+
+### `@test-engineer`
+
+```typescript
+agent: 'test-engineer';
+// Propósito: Engenheiro de testes - strategy, implementation, coverage
+// Especialidades: Unit tests, integration tests, E2E, TDD
+// Quando usar: Criação de testes, estratégia de testing, análise de cobertura
+```
+
+**Capacidades:**
+
+- 🧪 Testes unitários e integração
+- 🎭 Testes E2E (Playwright, Cypress)
+- 📊 Análise de cobertura
+- 🔄 TDD e BDD
+- 🐛 Testes de regressão
+
+### `@test-planner`
+
+```typescript
+agent: 'test-planner';
+// Propósito: Planejador de estratégia de testes
+// Especialidades: Test planning, test cases, QA strategy
+// Quando usar: Planejamento de testes para features, definição de casos de teste
+```
+
+**Capacidades:**
+
+- 📋 Planos de teste
+- 🎯 Casos de teste
+- 📊 Estratégia de QA
+- 📝 Documentação de testes
+
+### `@branch-test-planner`
+
+```typescript
+agent: 'branch-test-planner';
+// Propósito: Planejador de testes específicos para branch
+// Especialidades: Branch-specific testing, regression testing
+// Quando usar: Planejamento de testes para mudanças específicas de branch
+```
+
+---
+
+## Compliance e Meta
+
+### `@metaspec-gate-keeper`
+
+```typescript
+agent: 'metaspec-gate-keeper';
+// Propósito: Guardian da arquitetura - valida mudanças contra metaspec
+// Especialidades: Architecture validation, metaspec compliance, design patterns
+// Quando usar: Validação de mudanças arquiteturais, review de design decisions
+```
+
+**Capacidades:**
+
+- 🏛️ Validação arquitetural
+- 📐 Conformidade com metaspec
+- 🎯 Design patterns
+- 🔒 Enforcement de regras
+- 📊 Análise de impacto
+
+### `@branch-metaspec-checker`
+
+```typescript
+agent: 'branch-metaspec-checker';
+// Propósito: Verificador de metaspec para branches
+// Especialidades: Branch-level architecture validation
+// Quando usar: Verificação de conformidade arquitetural em branches
+```
+
+---
+
+## Pesquisa e Dados
+
+### `@research-agent`
+
+```typescript
+agent: 'research-agent';
+// Propósito: Pesquisador - busca informações, analisa documentação, web search
+// Especialidades: Information retrieval, documentation analysis, web research
+// Quando usar: Pesquisa de tecnologias, análise de docs, busca de soluções
+```
+
+**Capacidades:**
+
+- 🔍 Web search
+- 📚 Análise de documentação
+- 🎯 Pesquisa de best practices
+- 📊 Comparação de tecnologias
+- 💡 Recomendações baseadas em pesquisa
+
+### `@data-analyst`
+
+```typescript
+agent: 'data-analyst';
+// Propósito: Analista de dados - análise, visualização, insights
+// Especialidades: Data analysis, visualization, metrics, reporting
+// Quando usar: Análise de métricas, geração de relatórios, insights de dados
+```
+
+**Capacidades:**
+
+- 📊 Análise de dados
+- 📈 Visualizações
+- 🎯 KPIs e métricas
+- 📝 Relatórios
+- 💡 Insights e recomendações
+
+---
+
+## Deployment
+
+### `@deployment-specialist`
+
+```typescript
+agent: 'deployment-specialist';
+// Propósito: Especialista em deployment - CI/CD, infrastructure, releases
+// Especialidades: Docker, Kubernetes, CI/CD pipelines, cloud platforms
+// Quando usar: Setup de CI/CD, deployment configurations, release management
+```
+
+**Capacidades:**
+
+- 🚀 Configuração de CI/CD
+- 🐳 Containerização (Docker)
+- ☸️ Orquestração (Kubernetes)
+- ☁️ Cloud platforms (AWS, GCP, Azure)
+- 📦 Release management
+
+---
+
+## Especialistas Técnicos
+
+### `@clickup-specialist`
+
+```typescript
+agent: 'clickup-specialist';
+// Propósito: Especialista técnico em ClickUp MCP - otimizações, troubleshooting
+// Especialidades: ClickUp API, MCP integration, automation, optimization
+// Quando usar: Problemas técnicos com ClickUp, otimizações, automações complexas
+```
+
+**Capacidades:**
+
+- 🔌 Integração ClickUp MCP
+- ⚡ Otimizações de API
+- 🐛 Troubleshooting
+- 🤖 Automações avançadas
+- 📊 Custom fields e workflows
+
+### `@cursor-specialist`
+
+```typescript
+agent: 'cursor-specialist';
+// Propósito: Especialista em Cursor IDE - configuração, troubleshooting, otimização
+// Especialidades: Cursor configuration, rules, commands, agents setup
+// Quando usar: Problemas com Cursor IDE, configuração de agentes/comandos
+```
+
+**Capacidades:**
+
+- ⚙️ Configuração do Cursor
+- 📋 Criação de comandos
+- 🤖 Setup de agentes
+- 🔧 Troubleshooting IDE
+- ⚡ Otimizações de performance
+
+---
+
+## Documentação
+
+### `@branch-documentation-writer`
+
+```typescript
+agent: 'branch-documentation-writer';
+// Propósito: Escritor de documentação para branches
+// Especialidades: Branch documentation, changelog, migration guides
+// Quando usar: Documentação de mudanças em branches, changelogs
+```
+
+**Capacidades:**
+
+- 📝 Documentação de branches
+- 📋 Changelogs
+- 🔄 Guias de migração
+- 📊 Documentação técnica
+
+---
+
+## 🎯 Como Escolher o Agente Certo
+
+### Por Tipo de Tarefa
+
+| Tarefa                  | Agente Recomendado       |
+| ----------------------- | ------------------------ |
+| Planejamento de feature | `@product-agent`         |
+| Desenvolvimento React   | `@react-developer`       |
+| Backend Python          | `@python-developer`      |
+| Review de código        | `@code-reviewer`         |
+| Criação de testes       | `@test-engineer`         |
+| Validação arquitetural  | `@metaspec-gate-keeper`  |
+| Problemas ClickUp       | `@clickup-specialist`    |
+| Problemas Cursor        | `@cursor-specialist`     |
+| Pesquisa técnica        | `@research-agent`        |
+| Deployment              | `@deployment-specialist` |
+
+### Por Fase do Desenvolvimento
+
+```mermaid
+graph LR
+    A[Planning] -->|@product-agent| B[Development]
+    B -->|@react-developer/@python-developer| C[Testing]
+    C -->|@test-engineer| D[Review]
+    D -->|@code-reviewer| E[Validation]
+    E -->|@metaspec-gate-keeper| F[Deploy]
+    F -->|@deployment-specialist| G[Production]
+```
+
+---
+
+## 💡 Dicas de Uso
+
+### Invocação
+
+```markdown
+@product-agent preciso planejar uma nova feature de autenticação
+```
+
+### Combinação de Agentes
+
+```markdown
+@product-agent crie a task no ClickUp
+@react-developer implemente o componente
+@test-engineer crie os testes
+@code-reviewer revise o código
+```
+
+### Contexto Específico
+
+```markdown
+@clickup-specialist estou tendo erro ao criar task com custom fields
+```
+
+---
+
+## 📚 Recursos Relacionados
+
+- [Ferramentas MCP](./mcps.md)
+- [Comandos .claude/](./commands.md)
+- [Workflows](./workflows.md)