From 83a69e681cedba3b0fd357e48fd2a999ce61a7d9 Mon Sep 17 00:00:00 2001 From: Emanuel Almeida Date: Wed, 28 Oct 2026 16:08:27 +0000 Subject: [PATCH] feat(core-tools): adiciona plugin core-tools (agents, skills, knowledge e metadados do projeto) --- core-tools/.claude-plugin/plugin.json | 12 + core-tools/README.md | 41 +++ core-tools/plugin.json | 23 ++ core-tools/skills/AGENTS.md | 17 ++ core-tools/skills/CHANGELOG.md | 5 + core-tools/skills/MEMORY.md | 4 + core-tools/skills/README.md | 3 + core-tools/skills/STATUS.md | 8 + core-tools/skills/_core/SKILL.md | 136 +++++++++ core-tools/skills/_core/datasets-mapping.json | 283 ++++++++++++++++++ .../skills/_core/dify-integration-protocol.md | 128 ++++++++ .../skills/_core/instrumentation-protocol.md | 157 ++++++++++ .../skills/_core/notebooklm-mapping.json | 69 +++++ .../skills/agent-context-injector/SKILL.md | 66 ++++ .../skills/component-generator/SKILL.md | 269 +++++++++++++++++ .../skills/db-maintenance-manager/SKILL.md | 173 +++++++++++ core-tools/skills/desk.project | 6 + core-tools/skills/index.md | 8 + .../skills/infrastructure-manager/SKILL.md | 165 ++++++++++ core-tools/skills/log.md | 1 + core-tools/skills/metrics/SKILL.md | 184 ++++++++++++ .../references/dashboards-templates.md | 126 ++++++++ .../skills/metrics/references/sql-queries.md | 77 +++++ core-tools/skills/plugin-curator/SKILL.md | 113 +++++++ core-tools/skills/plugin-manager/SKILL.md | 156 ++++++++++ .../skills/plugin-manager/profiles.json | 143 +++++++++ core-tools/skills/quality-validator/SKILL.md | 144 +++++++++ .../skills/relationship-manager/SKILL.md | 191 ++++++++++++ 28 files changed, 2708 insertions(+) create mode 100644 core-tools/.claude-plugin/plugin.json create mode 100644 core-tools/README.md create mode 100644 core-tools/plugin.json create mode 100644 core-tools/skills/AGENTS.md create mode 100644 core-tools/skills/CHANGELOG.md create mode 100644 core-tools/skills/MEMORY.md create mode 100644 core-tools/skills/README.md create mode 100644 core-tools/skills/STATUS.md create mode 100644 core-tools/skills/_core/SKILL.md create mode 100644 core-tools/skills/_core/datasets-mapping.json create mode 100644 core-tools/skills/_core/dify-integration-protocol.md create mode 100644 core-tools/skills/_core/instrumentation-protocol.md create mode 100644 core-tools/skills/_core/notebooklm-mapping.json create mode 100644 core-tools/skills/agent-context-injector/SKILL.md create mode 100644 core-tools/skills/component-generator/SKILL.md create mode 100644 core-tools/skills/db-maintenance-manager/SKILL.md create mode 100644 core-tools/skills/desk.project create mode 100644 core-tools/skills/index.md create mode 100644 core-tools/skills/infrastructure-manager/SKILL.md create mode 100644 core-tools/skills/log.md create mode 100644 core-tools/skills/metrics/SKILL.md create mode 100644 core-tools/skills/metrics/references/dashboards-templates.md create mode 100644 core-tools/skills/metrics/references/sql-queries.md create mode 100644 core-tools/skills/plugin-curator/SKILL.md create mode 100644 core-tools/skills/plugin-manager/SKILL.md create mode 100644 core-tools/skills/plugin-manager/profiles.json create mode 100644 core-tools/skills/quality-validator/SKILL.md create mode 100644 core-tools/skills/relationship-manager/SKILL.md diff --git a/core-tools/.claude-plugin/plugin.json b/core-tools/.claude-plugin/plugin.json new file mode 100644 index 0000000..7ffe2b8 --- /dev/null +++ b/core-tools/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "core-tools", + "description": "Core system tools for plugin management, metrics, and infrastructure meta-operations", + "version": "2.0.0", + "author": { + "name": "Descomplicar", + "url": "https://descomplicar.pt" + }, + "homepage": "https://descomplicar.pt", + "license": "MIT", + "keywords": ["core", "plugins", "management", "profiles", "infrastructure", "meta"] +} diff --git a/core-tools/README.md b/core-tools/README.md new file mode 100644 index 0000000..b95434b --- /dev/null +++ b/core-tools/README.md @@ -0,0 +1,41 @@ +# Core Tools Plugin + +**Versão:** 1.0.0 +**Autor:** Descomplicar® +**Desk Project:** #65 Stack Workflow + +## Descrição + +Core system tools for Claude Code infrastructure and meta-management. + +Este plugin contém skills fundamentais para gestão e manutenção do ecossistema Claude Code. + +## Skills Incluídas + +### Infraestrutura +- **infrastructure-manager** - Gestão automatizada da infraestrutura Claude Code +- **db-maintenance-manager** - Manutenção das tabelas cr_* do sistema +- **relationship-manager** - Gestão de relacionamentos entre componentes + +### Plugins & Componentes +- **plugin-manager** - Gestão dinâmica de plugins (activar/desactivar por perfil) +- **plugin-curator** - Curadoria inteligente de plugins +- **component-generator** - Gera skills/agents/commands automaticamente +- **quality-validator** - Valida componentes contra standards + +### Agentes +- **agent-context-injector** - Injeta contexto específico quando um agente é iniciado + +### Métricas +- **metrics** - Dashboard de performance com ROI e telemetria + +### Core +- **_core** - Padrões fundamentais Descomplicar® (Sacred Rules, Excellence Standards, MCP Protocol) + +## Utilização + +Skills activadas automaticamente pelo sistema quando necessário. + +## Tags + +infrastructure, meta, system, core diff --git a/core-tools/plugin.json b/core-tools/plugin.json new file mode 100644 index 0000000..c04810d --- /dev/null +++ b/core-tools/plugin.json @@ -0,0 +1,23 @@ +{ + "name": "core-tools", + "version": "1.0.0", + "description": "Core system tools for Claude Code infrastructure and meta-management", + "author": "Descomplicar®", + "skills": [ + "agent-context-injector", + "component-generator", + "metrics", + "plugin-curator", + "plugin-manager", + "quality-validator", + "relationship-manager", + "infrastructure-manager", + "db-maintenance-manager", + "_core" + ], + "agents": [], + "hooks": [], + "commands": [], + "tags": ["infrastructure", "meta", "system", "core"], + "desk_project": 65 +} diff --git a/core-tools/skills/AGENTS.md b/core-tools/skills/AGENTS.md new file mode 100644 index 0000000..37d90a2 --- /dev/null +++ b/core-tools/skills/AGENTS.md @@ -0,0 +1,17 @@ +# AGENTS.md — skills + +Directrizes específicas deste projecto para agentes IA. + +## Referências obrigatórias + +- `ECOSYSTEM.md` — Hub/06-Operacoes/Documentacao/ECOSYSTEM.md +- `PROC-DEV-STANDARD` — D7-SIS-006 +- `PROC-AUDIT-STANDARD` — D7-SIS-007 + +## Protocolo de sessão + +Início: ler MEMORY.md + STATUS.md. Fim: actualizar ambos. + +## Convenções específicas + +- (a definir) diff --git a/core-tools/skills/CHANGELOG.md b/core-tools/skills/CHANGELOG.md new file mode 100644 index 0000000..5e14603 --- /dev/null +++ b/core-tools/skills/CHANGELOG.md @@ -0,0 +1,5 @@ +# CHANGELOG — skills + +## 0.1.0 — 2026-06-30 +### Adicionado +- Estrutura padrão (PROC-DEV-STANDARD) diff --git a/core-tools/skills/MEMORY.md b/core-tools/skills/MEMORY.md new file mode 100644 index 0000000..4971060 --- /dev/null +++ b/core-tools/skills/MEMORY.md @@ -0,0 +1,4 @@ +# MEMORY.md — skills + +## 2026-06-30 +- Estrutura padrão aplicada via propagate-structure.sh diff --git a/core-tools/skills/README.md b/core-tools/skills/README.md new file mode 100644 index 0000000..2ad232f --- /dev/null +++ b/core-tools/skills/README.md @@ -0,0 +1,3 @@ +# skills + +Subprojecto skills do ecossistema Descomplicar. diff --git a/core-tools/skills/STATUS.md b/core-tools/skills/STATUS.md new file mode 100644 index 0000000..07c1590 --- /dev/null +++ b/core-tools/skills/STATUS.md @@ -0,0 +1,8 @@ +# STATUS.md — skills + +**Versão:** 0.1 | **Data:** 2026-06-30 | **Agente:** — + +## Estado actual +- Em curso: — +- Bloqueios: — +- Próximos passos: — diff --git a/core-tools/skills/_core/SKILL.md b/core-tools/skills/_core/SKILL.md new file mode 100644 index 0000000..8f47b27 --- /dev/null +++ b/core-tools/skills/_core/SKILL.md @@ -0,0 +1,136 @@ +--- +name: core-descomplicar +description: Padrões fundamentais Descomplicar® — regras sagradas, standards de excelência e protocolo MCP. Skill base para todos os agentes. +user-invocable: false +layer: wiki +--- + +# Core Standards Descomplicar® + +Padrões obrigatórios para todos os agentes do sistema. + +--- + +## 🔟 REGRAS SAGRADAS + +### 1. É permitido falhar +Reportar erros com transparência. Falhar rápido, aprender mais rápido. + +### 2. Transparência e honestidade +Comunicar claramente. Não omitir informações. + +### 3. Más notícias primeiro +Escalar problemas imediatamente. + +### 4. Foco na resolução +Todo problema deve incluir soluções propostas. + +### 5. Nunca prejudicar +Princípio "do no harm". Proteger dados e sistemas. + +### 6. Passar a bola certa +Delegar para o especialista quando necessário. + +### 7. 3x antes de escalar +Três tentativas documentadas antes de escalação. + +### 8. Feedback protocol +Crítica privada, elogio público. + +### 9. Perguntar sempre +Pedir esclarecimento quando incerto. + +### 10. Crescimento contínuo +Mentalidade de aprendizagem constante. + +### 11. CWP: Zero Invenção (CLAUDE.md #38) +Sempre pesquisar wiki CWP e skills `/cwp-*` antes de qualquer operação CWP. Apenas scripts oficiais (`/scripts/*`). Nunca inventar comandos ou paths CWP sem verificação prévia. + +--- + +## 🎯 PADRÕES DE EXCELÊNCIA + +### Qualidade Mínima: 100/100 + +- **Precisão**: 100% informação verificada +- **Completude**: Especificações cumpridas +- **Consistência**: Alinhamento com padrões +- **Usabilidade**: Solução funcional +- **Manutenibilidade**: Sustentável longo prazo + +### Dados Reais Obrigatórios + +**NUNCA simular quando dados reais existem.** + +Hierarquia: +1. MCPs especializados (desk-crm, dify-kb, wikijs) +2. Sistemas internos (Gitea, Drive) +3. Documentação oficial (Context7) +4. Simulação APENAS se dados não existem + +--- + +## ⚡ PROTOCOLO MCP (3 PASSOS) + +### PASSO 1: Recuperação de Contexto + +``` +SEMPRE EXECUTAR PRIMEIRO: +1. mcp__mem_search_memories → Experiência histórica +2. mcp__wikijs__search_pages → Documentação interna +3. mcp__dify-kb__dify_kb_retrieve_segments → Knowledge base temática +``` + +### PASSO 2: Hierarquia de Fontes + +``` +🥇 1ª: MCPs especializados (mem0, dify-kb, desk-crm-v3) +🥈 2ª: MCPs de sistema (wikijs, filesystem, google-workspace) +🥉 3ª: MCPs complementares (context7, puppeteer) +🔧 ÚLTIMO: Ferramentas nativas Claude +``` + +### PASSO 3: Captura de Aprendizagem + +``` +SEMPRE GUARDAR ao final: +mcp__mem_save_memory { + "text": "[área/projecto/tipo] [Resumo do trabalho e decisões]" +} +``` + +--- + +## ✅ CHECKLIST PRE-ENTREGA + +- [ ] Dados verificados com fontes reais +- [ ] Qualidade técnica validada (100/100) +- [ ] Padrões Descomplicar® seguidos +- [ ] Documentação clara +- [ ] Testes executados (quando aplicável) +- [ ] Aprendizagens capturadas + +--- + +## 📝 OUTPUT + +- **Assinatura**: `/** @author Descomplicar® | @link descomplicar.pt | @copyright 2026 */` +- **Markdown**: Obsidian-ready (frontmatter, wikilinks, callouts) +- **Língua**: Português Europeu (PT-PT) +- **Monetário**: 95€ (não 95,00€) + +--- + +*Core Standards v1.1 | 2026-03-12* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/core-tools/skills/_core/datasets-mapping.json b/core-tools/skills/_core/datasets-mapping.json new file mode 100644 index 0000000..17ae070 --- /dev/null +++ b/core-tools/skills/_core/datasets-mapping.json @@ -0,0 +1,283 @@ +{ + "mapping": { + "analytics-insights-agent": { + "model": "haiku", + "tools": ["Read", "Glob", "Grep"], + "datasets": ["Marketing Digital", "Gestão de Marketing", "SEO (Search Engine Optimization)", "Gestão de Tráfego"], + "notebooks": [ + {"id": "76647e0f-3ae2-4c00-a0a8-f457aebf5655", "title": "Marketing Digital Avancado"}, + {"id": "4c595973-ba10-420a-a3bf-e4389e424ad3", "title": "Marketing Digital PT"} + ] + }, + "automation-lead": { + "model": "sonnet", + "tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"], + "datasets": ["n8n", "Ferramentas de Automação e IA", "Dify", "Flowise"], + "notebooks": [ + {"id": "f2c809b8-1cb5-4dd0-aa7e-be2cfb6704d1", "title": "n8n"}, + {"id": "ab876d0d-12a8-43d9-bc62-59c1c8e9d0f8", "title": "Transformacao Digital e IA"}, + {"id": "929ef67b-c131-4f01-abd0-8b078491a6b7", "title": "AI Automation Stack"} + ] + }, + "backup-specialist": { + "model": "sonnet", + "tools": ["Read", "Write", "Bash", "Glob", "Grep"], + "datasets": ["TI (Tecnologia da Informação)", "Linux", "CWP Centos Web Panel", "AWS (Amazon Web Services)"], + "notebooks": [ + {"id": "f9a79b5a-649f-4443-afaf-7ff562b6c2e7", "title": "Cloud e Infraestrutura TI"}, + {"id": "0ded7bd6-69b3-4c76-b327-452396bf7ea7", "title": "CWP"} + ] + }, + "content-manager": { + "model": "sonnet", + "tools": ["Read", "Write", "Edit", "Glob", "Grep"], + "datasets": ["Marketing de Conteúdo", "Copywriting", "Blogging", "Marketing Digital"], + "notebooks": [ + {"id": "76647e0f-3ae2-4c00-a0a8-f457aebf5655", "title": "Marketing Digital Avancado"}, + {"id": "7b8fec17-d34f-4e3f-a8c6-8231e51f6323", "title": "Copywriting e Persuasao"} + ] + }, + "copywriter": { + "model": "sonnet", + "tools": ["Read", "Write", "Glob", "Grep"], + "datasets": ["Copywriting", "Marketing de Conteúdo", "Escrever PT-PT", "Branding"], + "notebooks": [ + {"id": "7b8fec17-d34f-4e3f-a8c6-8231e51f6323", "title": "Copywriting e Persuasao"}, + {"id": "9053d0e8-dd39-460b-b5ea-e67af3e9a675", "title": "Social Media e Branding"} + ] + }, + "crm-admin-specialist": { + "model": "sonnet", + "tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"], + "datasets": ["PerfexCRM", "Gestão", "Gestão de Processos"], + "notebooks": [ + {"id": "df4688bb-c2c0-4aba-98c1-38c3b50a353c", "title": "Perfex CRM: Gestao de Clientes e Projetos"}, + {"id": "0c9c079c-a426-486c-99eb-1564d42d37ad", "title": "Gestao de Projectos e Agile"}, + {"id": "f9dc59c2-718b-4b12-bd06-095d4bfa3e34", "title": "Gestao de Operacoes"} + ] + }, + "cwp-server-manager": { + "model": "sonnet", + "tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"], + "datasets": ["CWP Centos Web Panel", "Linux", "TI (Tecnologia da Informação)"], + "notebooks": [ + {"id": "0ded7bd6-69b3-4c76-b327-452396bf7ea7", "title": "CWP"}, + {"id": "f9a79b5a-649f-4443-afaf-7ff562b6c2e7", "title": "Cloud e Infraestrutura TI"} + ] + }, + "database-design-specialist": { + "model": "sonnet", + "tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"], + "datasets": ["TI (Tecnologia da Informação)", "Desenvolvimento de Software", "AWS (Amazon Web Services)"], + "notebooks": [ + {"id": "f9a79b5a-649f-4443-afaf-7ff562b6c2e7", "title": "Cloud e Infraestrutura TI"}, + {"id": "24947ffa-0019-448a-a340-2f4a275d2eb1", "title": "Programacao"} + ] + }, + "dev-helper": { + "model": "sonnet", + "tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"], + "datasets": ["Desenvolvimento de Software", "TI (Tecnologia da Informação)", "Claude Code"], + "notebooks": [ + {"id": "24947ffa-0019-448a-a340-2f4a275d2eb1", "title": "Programacao"}, + {"id": "f9a79b5a-649f-4443-afaf-7ff562b6c2e7", "title": "Cloud e Infraestrutura TI"}, + {"id": "2876d1fe-5cea-4d98-8140-b0e1a81c6bc4", "title": "Claude Code"} + ] + }, + "development-lead": { + "model": "sonnet", + "tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"], + "datasets": ["Desenvolvimento de Software", "Gestão de Projetos", "Estratégia"], + "notebooks": [ + {"id": "24947ffa-0019-448a-a340-2f4a275d2eb1", "title": "Programacao"}, + {"id": "0c9c079c-a426-486c-99eb-1564d42d37ad", "title": "Gestao de Projectos e Agile"}, + {"id": "79d43410-0e29-4be1-881d-84db6bdc239a", "title": "Estrategia e Empreendedorismo"} + ] + }, + "easypanel-specialist": { + "model": "sonnet", + "tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"], + "datasets": ["TI (Tecnologia da Informação)", "Linux", "AWS (Amazon Web Services)"], + "notebooks": [ + {"id": "f9a79b5a-649f-4443-afaf-7ff562b6c2e7", "title": "Cloud e Infraestrutura TI"} + ] + }, + "finance-manager": { + "model": "sonnet", + "tools": ["Read", "Write", "Edit", "Glob", "Grep"], + "datasets": ["Gestão", "Estratégia", "Estratégia Descomplicar"], + "notebooks": [ + {"id": "0c9c079c-a426-486c-99eb-1564d42d37ad", "title": "Gestao de Projectos e Agile"}, + {"id": "79d43410-0e29-4be1-881d-84db6bdc239a", "title": "Estrategia e Empreendedorismo"}, + {"id": "f29c8457-f16d-4fb3-979d-6e5901de1b20", "title": "Descomplicar: Marketing Digital"} + ] + }, + "javascript-fullstack-specialist": { + "model": "sonnet", + "tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"], + "datasets": ["Desenvolvimento de Software", "TI (Tecnologia da Informação)"], + "notebooks": [ + {"id": "24947ffa-0019-448a-a340-2f4a275d2eb1", "title": "Programacao"}, + {"id": "f9a79b5a-649f-4443-afaf-7ff562b6c2e7", "title": "Cloud e Infraestrutura TI"} + ] + }, + "lead-qualifier": { + "model": "haiku", + "tools": ["Read", "Glob", "Grep"], + "datasets": ["Vendas", "Marketing Digital", "PerfexCRM"], + "notebooks": [ + {"id": "76647e0f-3ae2-4c00-a0a8-f457aebf5655", "title": "Marketing Digital Avancado"}, + {"id": "df4688bb-c2c0-4aba-98c1-38c3b50a353c", "title": "Perfex CRM: Gestao de Clientes e Projetos"} + ] + }, + "marketing-planning-expert": { + "model": "sonnet", + "tools": ["Read", "Write", "Edit", "Glob", "Grep"], + "datasets": ["Marketing Digital", "Gestão de Marketing", "Estratégia", "Marketing Redes Sociais"], + "notebooks": [ + {"id": "76647e0f-3ae2-4c00-a0a8-f457aebf5655", "title": "Marketing Digital Avancado"}, + {"id": "79d43410-0e29-4be1-881d-84db6bdc239a", "title": "Estrategia e Empreendedorismo"}, + {"id": "9053d0e8-dd39-460b-b5ea-e67af3e9a675", "title": "Social Media e Branding"} + ] + }, + "master-orchestrator": { + "model": "opus", + "tools": ["Task", "Read", "Write", "Edit", "Bash", "Glob", "Grep"], + "datasets": ["Gestão de Projetos", "Gestão", "Estratégia", "Estratégia Descomplicar"], + "notebooks": [ + {"id": "0c9c079c-a426-486c-99eb-1564d42d37ad", "title": "Gestao de Projectos e Agile"}, + {"id": "79d43410-0e29-4be1-881d-84db6bdc239a", "title": "Estrategia e Empreendedorismo"}, + {"id": "f29c8457-f16d-4fb3-979d-6e5901de1b20", "title": "Descomplicar: Marketing Digital"} + ] + }, + "mcp-protocol-developer": { + "model": "sonnet", + "tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"], + "datasets": ["MCP Servers", "Claude Code", "Desenvolvimento de Software"], + "notebooks": [ + {"id": "73102308-70ef-403e-9be9-eae0cfc62d55", "title": "Desenvolvimento de MCPs"}, + {"id": "2876d1fe-5cea-4d98-8140-b0e1a81c6bc4", "title": "Claude Code"}, + {"id": "24947ffa-0019-448a-a340-2f4a275d2eb1", "title": "Programacao"} + ] + }, + "n8n-automation-expert": { + "model": "sonnet", + "tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"], + "datasets": ["n8n", "Ferramentas de Automação e IA", "Dify"], + "notebooks": [ + {"id": "f2c809b8-1cb5-4dd0-aa7e-be2cfb6704d1", "title": "n8n"}, + {"id": "ab876d0d-12a8-43d9-bc62-59c1c8e9d0f8", "title": "Transformacao Digital e IA"}, + {"id": "929ef67b-c131-4f01-abd0-8b078491a6b7", "title": "AI Automation Stack"} + ] + }, + "perfex-crm-module-developer": { + "model": "sonnet", + "tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"], + "datasets": ["PerfexCRM", "Desenvolvimento de Software"], + "notebooks": [ + {"id": "df4688bb-c2c0-4aba-98c1-38c3b50a353c", "title": "Perfex CRM: Gestao de Clientes e Projetos"}, + {"id": "24947ffa-0019-448a-a340-2f4a275d2eb1", "title": "Programacao"} + ] + }, + "performance-optimization-engineer": { + "model": "sonnet", + "tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"], + "datasets": ["TI (Tecnologia da Informação)", "Desenvolvimento de Software", "AWS (Amazon Web Services)"], + "notebooks": [ + {"id": "f9a79b5a-649f-4443-afaf-7ff562b6c2e7", "title": "Cloud e Infraestrutura TI"}, + {"id": "24947ffa-0019-448a-a340-2f4a275d2eb1", "title": "Programacao"} + ] + }, + "php-fullstack-engineer": { + "model": "sonnet", + "tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"], + "datasets": ["Desenvolvimento de Software", "WordPress", "TI (Tecnologia da Informação)"], + "notebooks": [ + {"id": "24947ffa-0019-448a-a340-2f4a275d2eb1", "title": "Programacao"}, + {"id": "5be0d1a6-00f2-4cd9-b835-978cb7721601", "title": "WordPress e Elementor"}, + {"id": "f9a79b5a-649f-4443-afaf-7ff562b6c2e7", "title": "Cloud e Infraestrutura TI"} + ] + }, + "project-manager": { + "model": "sonnet", + "tools": ["Read", "Write", "Edit", "Glob", "Grep"], + "datasets": ["Gestão de Projetos", "Gestão", "Estratégia"], + "notebooks": [ + {"id": "0c9c079c-a426-486c-99eb-1564d42d37ad", "title": "Gestao de Projectos e Agile"}, + {"id": "79d43410-0e29-4be1-881d-84db6bdc239a", "title": "Estrategia e Empreendedorismo"} + ] + }, + "sales-manager": { + "model": "sonnet", + "tools": ["Read", "Write", "Edit", "Glob", "Grep"], + "datasets": ["Vendas", "Marketing Digital", "PerfexCRM"], + "notebooks": [ + {"id": "76647e0f-3ae2-4c00-a0a8-f457aebf5655", "title": "Marketing Digital Avancado"}, + {"id": "df4688bb-c2c0-4aba-98c1-38c3b50a353c", "title": "Perfex CRM: Gestao de Clientes e Projetos"} + ] + }, + "security-compliance-specialist": { + "model": "opus", + "tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"], + "datasets": ["TI (Tecnologia da Informação)", "Linux", "AWS (Amazon Web Services)"], + "notebooks": [ + {"id": "f9a79b5a-649f-4443-afaf-7ff562b6c2e7", "title": "Cloud e Infraestrutura TI"} + ] + }, + "seo-specialist": { + "model": "haiku", + "tools": ["Read", "Glob", "Grep"], + "datasets": ["SEO (Search Engine Optimization)", "Marketing Digital", "Marketing de Conteúdo"], + "notebooks": [ + {"id": "76647e0f-3ae2-4c00-a0a8-f457aebf5655", "title": "Marketing Digital Avancado"} + ] + }, + "software-project-planner": { + "model": "sonnet", + "tools": ["Read", "Write", "Edit", "Glob", "Grep"], + "datasets": ["Gestão de Projetos", "Desenvolvimento de Software", "Estratégia"], + "notebooks": [ + {"id": "0c9c079c-a426-486c-99eb-1564d42d37ad", "title": "Gestao de Projectos e Agile"}, + {"id": "24947ffa-0019-448a-a340-2f4a275d2eb1", "title": "Programacao"}, + {"id": "79d43410-0e29-4be1-881d-84db6bdc239a", "title": "Estrategia e Empreendedorismo"} + ] + }, + "ui-designer": { + "model": "sonnet", + "tools": ["Read", "Write", "Edit", "Glob", "Grep"], + "datasets": ["UX e Usabilidade", "Desenvolvimento de WebSites", "Canva"], + "notebooks": [ + {"id": "081ca512-8279-4850-b2b9-dff090267482", "title": "UI/UX Design"}, + {"id": "5be0d1a6-00f2-4cd9-b835-978cb7721601", "title": "WordPress e Elementor"}, + {"id": "9053d0e8-dd39-460b-b5ea-e67af3e9a675", "title": "Social Media e Branding"} + ] + }, + "web-designer": { + "model": "sonnet", + "tools": ["Read", "Write", "Edit", "Glob", "Grep"], + "datasets": ["Desenvolvimento de WebSites", "WordPress", "Elementor", "UX e Usabilidade"], + "notebooks": [ + {"id": "5be0d1a6-00f2-4cd9-b835-978cb7721601", "title": "WordPress e Elementor"}, + {"id": "081ca512-8279-4850-b2b9-dff090267482", "title": "UI/UX Design"} + ] + }, + "wordpress-performance-specialist": { + "model": "sonnet", + "tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"], + "datasets": ["WordPress", "Elementor", "Crocoblock", "TI (Tecnologia da Informação)"], + "notebooks": [ + {"id": "5be0d1a6-00f2-4cd9-b835-978cb7721601", "title": "WordPress e Elementor"}, + {"id": "f9a79b5a-649f-4443-afaf-7ff562b6c2e7", "title": "Cloud e Infraestrutura TI"} + ] + }, + "wordpress-plugin-developer": { + "model": "sonnet", + "tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"], + "datasets": ["WordPress", "Crocoblock", "Elementor", "Desenvolvimento de Software"], + "notebooks": [ + {"id": "5be0d1a6-00f2-4cd9-b835-978cb7721601", "title": "WordPress e Elementor"}, + {"id": "24947ffa-0019-448a-a340-2f4a275d2eb1", "title": "Programacao"} + ] + } + } +} diff --git a/core-tools/skills/_core/dify-integration-protocol.md b/core-tools/skills/_core/dify-integration-protocol.md new file mode 100644 index 0000000..09337da --- /dev/null +++ b/core-tools/skills/_core/dify-integration-protocol.md @@ -0,0 +1,128 @@ +# Protocolo de Knowledge Sources v2.0 + +**Data:** 2026-02-12 +**Propósito:** Consulta inteligente de conhecimento com dual-source (NotebookLM + Dify KB) + +--- + +## Visão Geral + +Skills e agents consultam conhecimento via dual-source: +1. **NotebookLM** (primario) - Gemini 2.5 RAG com conhecimento curado +2. **Dify KB** (fallback) - Datasets tematicos quando NotebookLM insuficiente + +## Fluxo de Consulta + +``` +1. Skill/Agent precisa conhecimento +2. Consultar NotebookLM (primario) + → mcp__notebooklm__notebook_query notebook_id:"" query:"" +3. Se resultado suficiente → usar +4. Se insuficiente → consultar Dify KB (fallback) + → mcp__dify-kb__dify_kb_retrieve_segments dataset:"" query:"" +5. Agregar resultados +``` + +## Como Consultar NotebookLM (Primario) + +### 1. Identificar Notebook (via notebooklm-mapping.json) + +```javascript +// Ler mapeamento +const mapping = require('./notebooklm-mapping.json').mapping; +const notebook = mapping['WordPress']; +// → {notebook_id: "5be0d1a6-...", notebook_title: "WordPress e Elementor"} +``` + +### 2. Consultar Notebook + +``` +mcp__notebooklm__notebook_query notebook_id:"5be0d1a6-00f2-4cd9-b835-978cb7721601" query:"elementor custom widgets" +``` + +### 3. Múltiplos Notebooks + +Quando o tema cobre vários notebooks, consultar em paralelo: + +``` +# Paralelo: WordPress + Dev +mcp__notebooklm__notebook_query notebook_id:"5be0d1a6-..." query:"tema" +mcp__notebooklm__notebook_query notebook_id:"24947ffa-..." query:"tema" +``` + +## Como Consultar Dify KB (Fallback) + +### 1. Identificar Dataset + +```javascript +mcp__dify-kb__dify_kb_retrieve_segments({ + dataset: "WordPress", + query: "elementor custom widgets", + top_k: 5 +}); +``` + +### 2. Consulta Paralela (Múltiplos Datasets) + +```javascript +// Lançar consultas em paralelo para datasets prioritarios +const results = await Promise.all([ + dify_kb_retrieve(dataset1, query), + dify_kb_retrieve(dataset2, query) +]); +``` + +## Mapeamento Notebooks + +Ficheiro central: `notebooklm-mapping.json` (mesmo directorio) + +51 notebooks disponiveis cobrindo: +- Marketing (5 notebooks) +- Desenvolvimento (8 notebooks) +- Infraestrutura (3 notebooks) +- Gestao (3 notebooks) +- Negocio (4 notebooks) +- Automacao (3 notebooks) +- Design (2 notebooks) + +## Template para Agents + +Secção standard nos agents: + +```markdown +## Knowledge Sources (Consultar SEMPRE) + +### NotebookLM (Primario - usar PRIMEIRO) + +``` +mcp__notebooklm__notebook_query notebook_id:"" query:"" +``` + +### Dify KB (Secundario - se NotebookLM insuficiente) + +``` +mcp__dify-kb__dify_kb_retrieve_segments dataset:"" query:"" +``` +``` + +## Template para Skills + +Adicionar no SKILL.md: + +```markdown +# PRIMARIO: NotebookLM (Gemini 2.5 RAG) +# mcp__notebooklm__notebook_query notebook_id:"" +# FALLBACK: Dify KB +mcp__dify-kb__dify_kb_retrieve_segments dataset:"" query:"" +``` + +## Metricas + +Rastrear na instrumentacao: +- `kb_source`: "notebooklm" ou "dify" +- `kb_consulted`: 1 se consultou KB +- `kb_fallback`: 1 se precisou de Dify apos NotebookLM + +--- + +**Protocolo v2.0** | 2026-02-12 | Dual-source (NotebookLM + Dify KB) diff --git a/core-tools/skills/_core/instrumentation-protocol.md b/core-tools/skills/_core/instrumentation-protocol.md new file mode 100644 index 0000000..4e4ffa5 --- /dev/null +++ b/core-tools/skills/_core/instrumentation-protocol.md @@ -0,0 +1,157 @@ +# Protocolo de Instrumentação Automática v1.0 + +**Data:** 2026-02-03 +**Propósito:** Auto-registar métricas de execução de skills para análise PDCA + +--- + +## Visão Geral + +Toda skill instrumentada deve gravar automaticamente métricas de execução na tabela `tblskill_agent_metrics` do Desk CRM. + +## Quando Instrumentar + +Skills que: +- Têm baseline definido em `_knowledge-map.json` +- São frequentemente usadas (>5x/semana) +- Estão em processo de optimização + +## Estrutura de Instrumentação + +### 1. Início de Execução + +Ao iniciar a skill, registar: + +```javascript +const SKILL_START = Date.now(); +const SESSION_ID = crypto.randomUUID(); // ou usar session_id existente +``` + +### 2. Rastreio de Consultas KB + +Se a skill consultar Dify KB: + +```javascript +let KB_CONSULTED = false; +let KB_HITS = 0; +let KB_MISS = 0; + +// Após cada consulta Dify bem sucedida +KB_CONSULTED = true; +KB_HITS++; + +// Se consulta falhou ou sem resultados +KB_MISS++; +``` + +### 3. Contagem de Tool Calls + +```javascript +let TOOL_CALLS = 0; + +// Incrementar a cada tool call +TOOL_CALLS++; +``` + +### 4. Fim de Execução - Gravar Métrica + +**Via SQL directo (fallback robusto):** + +```sql +INSERT INTO tblskill_agent_metrics ( + type, name, duration_ms, status, + session_id, task_id, project_id, staff_id, + kb_consulted, kb_hits, kb_miss, tool_calls, + error_type, error_message, context_tokens, output_tokens, + model_used, created_at +) VALUES ( + 'skill', '/nome-skill', {DURATION_MS}, '{STATUS}', + '{SESSION_ID}', {TASK_ID}, {PROJECT_ID}, 25, + {KB_CONSULTED}, {KB_HITS}, {KB_MISS}, {TOOL_CALLS}, + NULL, NULL, NULL, NULL, + 'opus-4.5', NOW() +); +``` + +**Via MCP tool (quando disponível):** + +```javascript +mcp__desk-crm-v3__log_skill_metric({ + type: 'skill', + name: '/nome-skill', + duration_ms: Date.now() - SKILL_START, + status: 'success', // ou 'error', 'partial' + session_id: SESSION_ID, + task_id: CURRENT_TASK_ID, + project_id: CURRENT_PROJECT_ID, + staff_id: 25, // AikTop + kb_consulted: KB_CONSULTED, + kb_hits: KB_HITS, + kb_miss: KB_MISS, + tool_calls: TOOL_CALLS +}); +``` + +## Status Possíveis + +| Status | Quando Usar | +|--------|-------------| +| `success` | Skill completou com sucesso | +| `error` | Skill falhou com erro | +| `partial` | Skill completou parcialmente | +| `cancelled` | Utilizador cancelou | + +## Campos Opcionais + +| Campo | Quando Preencher | +|-------|------------------| +| `task_id` | Se executando dentro de tarefa Desk | +| `project_id` | Se contexto de projecto conhecido | +| `error_type` | Se status = 'error' | +| `error_message` | Se status = 'error' | +| `context_tokens` | Se disponível via API | +| `output_tokens` | Se disponível via API | + +## Template para Skills + +Adicionar esta secção no final de cada SKILL.md instrumentada: + +```markdown +--- + +## Instrumentação Automática + +Esta skill grava métricas automaticamente para análise PDCA. + +### Ao Executar Esta Skill + +1. **Início:** Registar timestamp inicial +2. **Consultas KB:** Rastrear hits/miss do Dify +3. **Fim:** Gravar métrica via SQL ou MCP + +### Query para Gravar (executar no final) + +\`\`\`sql +INSERT INTO tblskill_agent_metrics (type, name, duration_ms, status, staff_id, kb_consulted, created_at) +VALUES ('skill', '/nome-skill', {DURACAO_MS}, '{STATUS}', 25, {KB_CONSULTADO}, NOW()); +\`\`\` + +### Ver Métricas + +\`\`\`bash +/metrics /nome-skill +\`\`\` +``` + +## Integração com /reflect + +Se degradação detectada (performance >15% pior que baseline): + +1. `/metrics` mostra alerta +2. Sugerir `/reflect` para investigação +3. `/reflect` analisa padrões e propõe melhorias +4. Registar ciclo PDCA em `tblskill_agent_pdca_cycles` + +--- + +**Protocolo v1.0** | 2026-02-03 diff --git a/core-tools/skills/_core/notebooklm-mapping.json b/core-tools/skills/_core/notebooklm-mapping.json new file mode 100644 index 0000000..992373d --- /dev/null +++ b/core-tools/skills/_core/notebooklm-mapping.json @@ -0,0 +1,69 @@ +{ + "description": "Mapeamento Dify KB datasets -> NotebookLM notebooks. NotebookLM e fonte primaria (Gemini 2.5 RAG). Dify KB e fallback.", + "updated": "2026-02-12", + "query_tool": "mcp__notebooklm__notebook_query", + "fallback_tool": "mcp__dify-kb__dify_kb_retrieve_segments", + "mapping": { + "Marketing Digital": {"notebook_id": "76647e0f-3ae2-4c00-a0a8-f457aebf5655", "notebook_title": "Marketing Digital Avancado"}, + "Marketing": {"notebook_id": "76647e0f-3ae2-4c00-a0a8-f457aebf5655", "notebook_title": "Marketing Digital Avancado"}, + "Gestao de Marketing": {"notebook_id": "76647e0f-3ae2-4c00-a0a8-f457aebf5655", "notebook_title": "Marketing Digital Avancado"}, + "Gestao de Trafego": {"notebook_id": "76647e0f-3ae2-4c00-a0a8-f457aebf5655", "notebook_title": "Marketing Digital Avancado"}, + "Marketing de Conteudo": {"notebook_id": "76647e0f-3ae2-4c00-a0a8-f457aebf5655", "notebook_title": "Marketing Digital Avancado"}, + "Growth Hacking": {"notebook_id": "76647e0f-3ae2-4c00-a0a8-f457aebf5655", "notebook_title": "Marketing Digital Avancado"}, + "Marketing Redes Sociais": {"notebook_id": "9053d0e8-dd39-460b-b5ea-e67af3e9a675", "notebook_title": "Social Media e Branding"}, + "Branding": {"notebook_id": "9053d0e8-dd39-460b-b5ea-e67af3e9a675", "notebook_title": "Social Media e Branding"}, + "Canva": {"notebook_id": "9053d0e8-dd39-460b-b5ea-e67af3e9a675", "notebook_title": "Social Media e Branding"}, + "SEO (Search Engine Optimization)": {"notebook_id": "76647e0f-3ae2-4c00-a0a8-f457aebf5655", "notebook_title": "Marketing Digital Avancado", "note": "SEO coberto genericamente no Marketing Avancado"}, + "SEO": {"notebook_id": "76647e0f-3ae2-4c00-a0a8-f457aebf5655", "notebook_title": "Marketing Digital Avancado"}, + "Copywriting": {"notebook_id": "7b8fec17-d34f-4e3f-a8c6-8231e51f6323", "notebook_title": "Copywriting e Persuasao"}, + "Youtube Marketing": {"notebook_id": "058a896e-6c9a-4e51-ae7d-9adb2738bc5f", "notebook_title": "Producao de Video e Youtube"}, + "Vendas": {"notebook_id": "76647e0f-3ae2-4c00-a0a8-f457aebf5655", "notebook_title": "Marketing Digital Avancado", "note": "Sem notebook dedicado, coberto parcialmente"}, + "Email Marketing": {"notebook_id": "76647e0f-3ae2-4c00-a0a8-f457aebf5655", "notebook_title": "Marketing Digital Avancado", "note": "Sem notebook dedicado"}, + "Blogging": {"notebook_id": "76647e0f-3ae2-4c00-a0a8-f457aebf5655", "notebook_title": "Marketing Digital Avancado", "note": "Sem notebook dedicado"}, + "Mentor: Seth Godin": {"notebook_id": "79d43410-0e29-4be1-881d-84db6bdc239a", "notebook_title": "Estrategia e Empreendedorismo"}, + "Mentor: Russel Brunson": {"notebook_id": "79d43410-0e29-4be1-881d-84db6bdc239a", "notebook_title": "Estrategia e Empreendedorismo"}, + "Mentor: Gary Vee": {"notebook_id": "7b8fec17-d34f-4e3f-a8c6-8231e51f6323", "notebook_title": "Copywriting e Persuasao"}, + "Mentor: Alex Vargas": {"notebook_id": "4c595973-ba10-420a-a3bf-e4389e424ad3", "notebook_title": "Marketing Digital PT"}, + "Mentor: Natanael Oliveira": {"notebook_id": "4c595973-ba10-420a-a3bf-e4389e424ad3", "notebook_title": "Marketing Digital PT"}, + "Mentor: Ricardo Piovan": {"notebook_id": "0c9c079c-a426-486c-99eb-1564d42d37ad", "notebook_title": "Gestao de Projectos e Agile"}, + "Claude Code": {"notebook_id": "2876d1fe-5cea-4d98-8140-b0e1a81c6bc4", "notebook_title": "Claude Code"}, + "MCP Servers": {"notebook_id": "73102308-70ef-403e-9be9-eae0cfc62d55", "notebook_title": "Desenvolvimento de MCPs"}, + "VS Code": {"notebook_id": "57d9c6c9-48ba-4d83-8f71-cc890f348a53", "notebook_title": "AI Code Editors"}, + "Windsurf": {"notebook_id": "57d9c6c9-48ba-4d83-8f71-cc890f348a53", "notebook_title": "AI Code Editors"}, + "Claude Computer Use": {"notebook_id": "57d9c6c9-48ba-4d83-8f71-cc890f348a53", "notebook_title": "AI Code Editors"}, + "Desenvolvimento de Software": {"notebook_id": "24947ffa-0019-448a-a340-2f4a275d2eb1", "notebook_title": "Programacao"}, + "Obsidian + Claude Code": {"notebook_id": "ebee9fe1-78fd-4f85-8938-f19f3ea32131", "notebook_title": "Obsidian + Claude"}, + "WordPress": {"notebook_id": "5be0d1a6-00f2-4cd9-b835-978cb7721601", "notebook_title": "WordPress e Elementor"}, + "Elementor": {"notebook_id": "5be0d1a6-00f2-4cd9-b835-978cb7721601", "notebook_title": "WordPress e Elementor"}, + "Crocoblock": {"notebook_id": "5be0d1a6-00f2-4cd9-b835-978cb7721601", "notebook_title": "WordPress e Elementor"}, + "Desenvolvimento de WebSites": {"notebook_id": "5be0d1a6-00f2-4cd9-b835-978cb7721601", "notebook_title": "WordPress e Elementor"}, + "CWP Centos Web Panel": {"notebook_id": "0ded7bd6-69b3-4c76-b327-452396bf7ea7", "notebook_title": "CWP"}, + "TI (Tecnologia da Informação)": {"notebook_id": "f9a79b5a-649f-4443-afaf-7ff562b6c2e7", "notebook_title": "Cloud e Infraestrutura TI"}, + "TI": {"notebook_id": "f9a79b5a-649f-4443-afaf-7ff562b6c2e7", "notebook_title": "Cloud e Infraestrutura TI"}, + "Linux": {"notebook_id": "f9a79b5a-649f-4443-afaf-7ff562b6c2e7", "notebook_title": "Cloud e Infraestrutura TI"}, + "AWS (Amazon Web Services)": {"notebook_id": "f9a79b5a-649f-4443-afaf-7ff562b6c2e7", "notebook_title": "Cloud e Infraestrutura TI"}, + "AWS": {"notebook_id": "f9a79b5a-649f-4443-afaf-7ff562b6c2e7", "notebook_title": "Cloud e Infraestrutura TI"}, + "Gestao": {"notebook_id": "0c9c079c-a426-486c-99eb-1564d42d37ad", "notebook_title": "Gestao de Projectos e Agile"}, + "Gestao de Projetos": {"notebook_id": "0c9c079c-a426-486c-99eb-1564d42d37ad", "notebook_title": "Gestao de Projectos e Agile"}, + "Gestao de Processos": {"notebook_id": "f9dc59c2-718b-4b12-bd06-095d4bfa3e34", "notebook_title": "Gestao de Operacoes"}, + "Estrategia": {"notebook_id": "79d43410-0e29-4be1-881d-84db6bdc239a", "notebook_title": "Estrategia e Empreendedorismo"}, + "Estratégia": {"notebook_id": "79d43410-0e29-4be1-881d-84db6bdc239a", "notebook_title": "Estrategia e Empreendedorismo"}, + "Produtividade": {"notebook_id": "ebee9fe1-78fd-4f85-8938-f19f3ea32131", "notebook_title": "Obsidian + Claude"}, + "Escrever PT-PT": {"notebook_id": null, "notebook_title": null, "note": "Sem equivalente NotebookLM - usar apenas Dify"}, + "n8n": {"notebook_id": "f2c809b8-1cb5-4dd0-aa7e-be2cfb6704d1", "notebook_title": "n8n"}, + "Dify": {"notebook_id": "929ef67b-c131-4f01-abd0-8b078491a6b7", "notebook_title": "AI Automation Stack"}, + "Flowise": {"notebook_id": "929ef67b-c131-4f01-abd0-8b078491a6b7", "notebook_title": "AI Automation Stack", "note": "Coberto parcialmente"}, + "Open WebUI": {"notebook_id": "be6f72ac-f8ba-4337-912d-abd5dd448519", "notebook_title": "Open WebUI"}, + "Ferramentas de Automação e IA": {"notebook_id": "ab876d0d-12a8-43d9-bc62-59c1c8e9d0f8", "notebook_title": "Transformacao Digital e IA"}, + "Ferramentas Automacao e IA": {"notebook_id": "ab876d0d-12a8-43d9-bc62-59c1c8e9d0f8", "notebook_title": "Transformacao Digital e IA"}, + "PerfexCRM": {"notebook_id": "df4688bb-c2c0-4aba-98c1-38c3b50a353c", "notebook_title": "Perfex CRM: Gestao de Clientes e Projetos"}, + "Servicos Descomplicar": {"notebook_id": "f29c8457-f16d-4fb3-979d-6e5901de1b20", "notebook_title": "Descomplicar: Marketing Digital"}, + "e-commerce": {"notebook_id": "226e384e-d4bc-48f4-bb82-7927360436cc", "notebook_title": "E-commerce Pratico"}, + "Empreendedorismo": {"notebook_id": "79d43410-0e29-4be1-881d-84db6bdc239a", "notebook_title": "Estrategia e Empreendedorismo"}, + "Agencia Digital": {"notebook_id": "f9dc59c2-718b-4b12-bd06-095d4bfa3e34", "notebook_title": "Gestao de Operacoes"}, + "Estrategia Descomplicar": {"notebook_id": "f29c8457-f16d-4fb3-979d-6e5901de1b20", "notebook_title": "Descomplicar: Marketing Digital"}, + "Aceleracao Digital": {"notebook_id": "ab876d0d-12a8-43d9-bc62-59c1c8e9d0f8", "notebook_title": "Transformacao Digital e IA"}, + "UX e Usabilidade": {"notebook_id": "081ca512-8279-4850-b2b9-dff090267482", "notebook_title": "UI/UX Design"}, + "Criatividade": {"notebook_id": "081ca512-8279-4850-b2b9-dff090267482", "notebook_title": "UI/UX Design", "note": "Sem notebook dedicado"} + } +} diff --git a/core-tools/skills/agent-context-injector/SKILL.md b/core-tools/skills/agent-context-injector/SKILL.md new file mode 100644 index 0000000..70e2a20 --- /dev/null +++ b/core-tools/skills/agent-context-injector/SKILL.md @@ -0,0 +1,66 @@ +--- +name: agent-context-injector +description: Injeccao dinamica de contexto (MCPs e Skills) nos agentes via script Python + hook SessionStart com deteccao de staleness. +user-invocable: false +allowed-tools: Read, Glob, Grep, ToolSearch +layer: wiki +--- + +# Agent Context Injector + +Regeneracao automatica das seccoes "Your Available MCPs" e "Your Available Skills" em todos os agentes. + +## Como funciona + +1. **Hook SessionStart** (`~/.claude/hooks/agent-context-refresh.sh`) calcula hash dos inputs +2. Se hash mudou → executa `~/.claude/scripts/regenerate-agent-context.py` +3. Script le frontmatter de cada agente, inventario MCPs, mapeamento domain e skills dos plugins +4. Gera seccoes entre marcadores `` / `` +5. Guarda novo hash em `~/.claude/.agent-context-hash` + +## Ficheiros + +| Ficheiro | Funcao | +|----------|--------| +| `~/.claude/scripts/regenerate-agent-context.py` | Script principal de regeneracao | +| `~/.claude/hooks/agent-context-refresh.sh` | Hook SessionStart com staleness | +| `~/.claude/_resources/domain-mcp-map.json` | Mapeamento domain -> MCPs recomendados | +| `~/.claude/_resources/mcps.json` | Inventario de 34+ MCPs | +| `~/.claude/.agent-context-hash` | Hash MD5 dos inputs (staleness) | + +## Dados de entrada + +- **Agentes:** `~/.claude/agents/*.md` — frontmatter com `domain`, `skills` +- **MCPs:** `~/.claude/_resources/mcps.json` — lista com `id`, `name`, `category` +- **Domain map:** `~/.claude/_resources/domain-mcp-map.json` — primary/recommended por domain +- **Skills:** `descomplicar-plugins/*/skills/*/SKILL.md` — frontmatter com `name`, `description` + +## Performance + +| Cenario | Tempo | +|---------|-------| +| Sem mudancas (hash match) | ~66ms | +| Com regeneracao (61 agentes) | ~2-3s | + +## Manutencao + +- **Adicionar MCP:** actualizar `mcps.json` e `domain-mcp-map.json` → proximo SessionStart regenera +- **Adicionar skill:** criar SKILL.md no plugin → proximo SessionStart regenera +- **Adicionar agente:** criar .md com frontmatter `domain:` → proximo SessionStart gera contexto +- **Mudar domain map:** editar `domain-mcp-map.json` → proximo SessionStart regenera + +## Tarefa Desk + +#1996 — Sistema injeccao Skills e MCPs nos agentes + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/core-tools/skills/component-generator/SKILL.md b/core-tools/skills/component-generator/SKILL.md new file mode 100644 index 0000000..e3660cb --- /dev/null +++ b/core-tools/skills/component-generator/SKILL.md @@ -0,0 +1,269 @@ +--- +name: component-generator +description: Gera componentes Claude Code (skills, agents, commands) seguindo templates Descomplicar® com ciclo criar, validar e registar. +disable-model-invocation: true +allowed-tools: Read, Write, Edit, Glob, ToolSearch +layer: wiki +--- + +# Component Generator + +Skill para criar componentes de alta qualidade automaticamente, fechando o ciclo CRIAR → VALIDAR → REGISTAR. + +## Triggers + +Esta skill deve ser activada quando: +- Utilizador pede para criar nova skill +- Utilizador pede para criar novo agent +- Utilizador pede para criar novo command +- Necessidade de scaffold de componente identificada +- Comando `/descomplicar:create` é invocado + +## Capabilities + +### 1. Scaffold Skill + +Cria estrutura completa de skill com frontmatter obrigatório. + +**Comando:** +``` +/descomplicar:create skill +``` + +**Template Gerado:** +```markdown +--- +name: +description: > + [Capability]. Use when "[trigger1]", "[trigger2]", + "[keyword1]", "[keyword2]", "[keyword3]". +author: Descomplicar® +version: 1.0.0 +desk_task: XXXX +allowed-tools: Read, Glob, Grep +--- + +# + +[Descrição da skill] + +## Triggers + +Esta skill deve ser activada quando: +- [Trigger 1] +- [Trigger 2] + +## Capabilities + +### 1. [Capability 1] +[Descrição] + +### 2. [Capability 2] +[Descrição] + +## Workflow + +``` +[PASSO1] → [PASSO2] → [PASSO3] → [PASSO4] +``` + +## Exemplo de Uso + +``` +User: [Exemplo de input] +Assistant: [Exemplo de output] +``` + +## Limites + +- [Quando NÃO usar] +- [Escopo máximo] +``` + +**Acções Automáticas:** +1. Criar directório `skills//` +2. Gerar `SKILL.md` com template +3. Registar em `cr_skills` (MySQL) +4. Criar tarefa Desk CRM (se desk_task fornecido) + +### 2. Scaffold Agent + +Cria ficheiro de agente com mapeamento de MCPs por categoria. + +**Comando:** +``` +/descomplicar:create agent [--category dev|business|marketing|infra] +``` + +**Template Gerado:** +```markdown +--- +name: +description: > + [Descrição]. Use for [uso1], [uso2], [uso3]. +model: sonnet +tools: Read, Glob, Grep, ToolSearch +allowed-mcps: [MCPs baseados na categoria] +category: +author: Descomplicar® +version: 1.0.0 +desk_task: XXXX +--- + +# + +[Descrição do agente] + +## Quando Usar + +USAR PROATIVAMENTE para: +- [Caso de uso 1] +- [Caso de uso 2] + +## Capabilities + +### [Capability 1] +- [Detalhe] + +## Tools Disponíveis + +| Tool | Uso | +|------|-----| +| [tool] | [descrição] | + +## Workflow Típico + +``` +1. [Passo 1] +2. [Passo 2] +3. [Passo 3] +4. [Passo 4] +``` + +## Colaborações + +- [Agente relacionado 1] +- [Agente relacionado 2] + +## Limites + +- [Limite 1] +- [Limite 2] +``` + +**MCPs por Categoria:** +| Categoria | MCPs Primary | MCPs Recommended | +|-----------|--------------|------------------| +| dev | gitea, filesystem | ssh-unified, desk-crm-v3 | +| business | desk-crm-v3, moloni | google-workspace | +| marketing | google-workspace, tavily | desk-crm-v3 | +| infra | ssh-unified, cwp | filesystem, gitea | + +**Acções Automáticas:** +1. Criar `agents/.md` +2. Registar em `cr_agents` (MySQL) +3. Criar mapeamentos em `cr_agent_mcps` +4. Sugerir colaborações em `cr_agent_collaborations` +5. Criar tarefa Desk CRM + +### 3. Scaffold Command + +Cria ficheiro de comando com namespace e arguments. + +**Comando:** +``` +/descomplicar:create command +``` + +**Template Gerado:** +```markdown +--- +name: +description: > + [Descrição do comando]. [O que faz]. +argument-hint: "[argumentos opcionais]" +--- + +# /descomplicar: + +[Descrição detalhada] + +## Objectivo + +[O que este comando faz] + +## Sintaxe + +``` +/descomplicar: [action] [args] +``` + +## Acções Disponíveis + +### 1. [Acção 1] + +``` +/descomplicar: [action1] +``` + +[Descrição] + +## Output Esperado + +``` +╔═══════════════════════════════════════════╗ +║ [OUTPUT VISUAL] ║ +╚═══════════════════════════════════════════╝ +``` +``` + +**Acções Automáticas:** +1. Criar `commands/.md` +2. Actualizar `plugin.json` com novo command + +### 4. Registar em MySQL + +```sql +-- Para Skills +INSERT INTO cr_skills (slug, name, category, status, desk_task, created_at) +VALUES (?, ?, ?, 'active', ?, NOW()); + +-- Para Agents +INSERT INTO cr_agents (slug, name, category, status, desk_task, created_at) +VALUES (?, ?, ?, 'active', ?, NOW()); +``` + +### 5. Criar Tarefa Desk CRM + +```sql +INSERT INTO tbltasks (name, description, rel_type, rel_id, milestone, status, dateadded, startdate, addedfrom) +VALUES ( + ': ', + '

Propósito

...

Estado

Em desenvolvimento

', + 'project', 65, -- Stack Workflow + ?, -- Milestone apropriado + 1, NOW(), CURDATE(), 1 +); +``` + +## Workflow Completo + +``` +CREATE → VALIDATE → REGISTER → DESK TASK → READY + ↓ ↓ ↓ ↓ +Template Score≥70 MySQL Tracking +``` + +## Validação Automática + +Após criação, invoca `quality-validator` para garantir score >= 70: +- Se score < 70: ALERTA + sugestões de melhoria +- Se score >= 70: componente activado + +## Exemplo de Uso + +``` +User: Cria uma nova skill para gestão de backups + +Component Generator: +1. [Cria directório skills/backup-mana \ No newline at end of file diff --git a/core-tools/skills/db-maintenance-manager/SKILL.md b/core-tools/skills/db-maintenance-manager/SKILL.md new file mode 100644 index 0000000..8d7aca9 --- /dev/null +++ b/core-tools/skills/db-maintenance-manager/SKILL.md @@ -0,0 +1,173 @@ +--- +name: db-maintenance-manager +description: Manutenção automatizada das tabelas cr_* da infraestrutura Claude Code — limpeza de órfãos, migração de schema, backups e optimização. +disable-model-invocation: true +allowed-tools: Read, Glob, Grep, ToolSearch +layer: wiki +--- + +# DB Maintenance Manager + +Gestão e manutenção automatizada das tabelas cr_* (Claude Resources) na base de dados Desk CRM. + +## Triggers + +Esta skill deve ser activada quando: +- Utilizador menciona "manutenção BD", "database maintenance" +- Detectados órfãos nas tabelas de relacionamento +- Telemetria antiga (>90 dias) a ocupar espaço +- Necessidade de migração de schema +- Backup/restore de componentes + +## Schema das Tabelas cr_* + +### Core Tables (Entidades) + +| Tabela | Descrição | Manutenção | +|--------|-----------|------------| +| `cr_agents` | Agentes especializados | Sync, Backup | +| `cr_skills` | Skills invocáveis | Sync, Backup | +| `cr_mcps` | Servidores MCP | Sync, Backup | +| `cr_lsps` | Language Server Protocols | Sync, Backup | +| `cr_plugins` | Software Development Kits | Sync, Backup | +| `cr_mcp_tools` | Ferramentas por MCP | Sync | +| `cr_plugins` | Plugins instalados | Sync, Backup | +| `cr_hooks` | Hooks configurados | Sync, Backup | + +### Relationship Tables (Limpeza de Órfãos) + +| Tabela | FK Agent | FK Resource | Cleanup Priority | +|--------|----------|-------------|------------------| +| `cr_agent_mcps` | agent_id → cr_agents | mcp_id → cr_mcps | Alta | +| `cr_agent_lsps` | agent_id → cr_agents | lsp_id → cr_lsps | Alta | +| `cr_plugin_agents` | sdk_id → cr_plugins | agent_id → cr_agents | Média | +| `cr_plugin_skills` | sdk_id → cr_plugins | skill_id → cr_skills | Média | +| `cr_plugin_mcps` | sdk_id → cr_plugins | mcp_id → cr_mcps | Média | +| `cr_agent_skills` | agent_id → cr_agents | skill_id → cr_skills | Alta | +| `cr_skill_mcps` | skill_id → cr_skills | mcp_id → cr_mcps | Alta | +| `cr_agent_collaborations` | agent_id → cr_agents | collaborator_id → cr_agents | Média | + +### Telemetry Tables (Archiving) + +| Tabela | Retenção Activa | Archive After | +|--------|-----------------|---------------| +| `cr_agent_usage` | 90 dias | cr_agent_usage_archive | +| `cr_skill_usage` | 90 dias | cr_skill_usage_archive | +| `cr_mcp_tool_usage` | 90 dias | cr_mcp_tool_usage_archive | +| `cr_lsp_usage` | 90 dias | cr_lsp_usage_archive | + +## Capabilities + +### 1. Cleanup de Órfãos + +Detecta e remove referências inválidas nas tabelas de relacionamento. + +**Detecção:** +```sql +-- Órfãos em cr_agent_mcps +SELECT am.id, am.agent_id, am.mcp_id +FROM cr_agent_mcps am +LEFT JOIN cr_agents a ON am.agent_id = a.id +LEFT JOIN cr_mcps m ON am.mcp_id = m.id +WHERE a.id IS NULL OR m.id IS NULL; +``` + +**Limpeza (com confirmação):** +```sql +-- Backup antes de limpar +CREATE TABLE cr_agent_mcps_orphans_backup_YYYYMMDD AS +SELECT * FROM cr_agent_mcps am +WHERE agent_id NOT IN (SELECT id FROM cr_agents) + OR mcp_id NOT IN (SELECT id FROM cr_mcps); + +-- Limpar órfãos +DELETE FROM cr_agent_mcps +WHERE agent_id NOT IN (SELECT id FROM cr_agents) + OR mcp_id NOT IN (SELECT id FROM cr_mcps); +``` + +### 2. Migração de Schema + +Gestão de alterações estruturais nas tabelas cr_*. + +**Estrutura de Migrations:** +``` +migrations/ +├── 001_initial_schema.sql +├── 002_add_lsp_tables.sql +├── 003_add_telemetry.sql +├── 004_add_archive_tables.sql +└── migrations_log.sql +``` + +**Tabela de Controlo:** +```sql +CREATE TABLE IF NOT EXISTS cr_migrations ( + id INT AUTO_INCREMENT PRIMARY KEY, + migration_name VARCHAR(100) NOT NULL, + applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + checksum VARCHAR(64), + status ENUM('applied', 'rolled_back', 'failed') DEFAULT 'applied' +); +``` + +### 3. Backup Selectivo + +Backup apenas das tabelas cr_* (não toda a BD Desk). + +**Tabelas a incluir:** +```sql +-- Lista de tabelas para backup +SELECT table_name +FROM information_schema.tables +WHERE table_schema = DATABASE() + AND table_name LIKE 'cr_%'; +``` + +**Formato de Backup:** +``` +backups/ +└── cr_backup_YYYYMMDD_HHMMSS/ + ├── manifest.json + ├── cr_agents.sql + ├── cr_skills.sql + ├── cr_mcps.sql + └── ... (todas as tabelas cr_*) +``` + +### 4. Archiving de Telemetria + +Move dados antigos para tabelas de arquivo. + +**Processo:** +```sql +-- 1. Criar tabela archive se não existir +CREATE TABLE IF NOT EXISTS cr_agent_usage_archive LIKE cr_agent_usage; + +-- 2. Mover dados > 90 dias +INSERT INTO cr_agent_usage_archive +SELECT * FROM cr_agent_usage +WHERE created_at < DATE_SUB(NOW(), INTERVAL 90 DAY); + +-- 3. Limpar tabela principal +DELETE FROM cr_agent_usage +WHERE created_at < DATE_SUB(NOW(), INTERVAL 90 DAY); + +-- 4. Registar operação +INSERT INTO cr_maintenance_log (operation, table_name, rows_affected, executed_at) +VALUES ('archive', 'cr_agent_usage', ROW_COUNT(), NOW()); +``` + +### 5. Optimização + +Manutenção de performance das tabelas. + +```sql +-- Optimizar tabelas fragmentadas +OPTIMIZE TABLE cr_agent_usage, cr_skill_usage, cr_mcp_tool_usage; + +-- Analisar estatísticas +ANALYZE TABLE cr_agents, cr_skills, cr_mcps, cr_agent_mcps; + +-- Verificar índices em falta +SE \ No newline at end of file diff --git a/core-tools/skills/desk.project b/core-tools/skills/desk.project new file mode 100644 index 0000000..5678920 --- /dev/null +++ b/core-tools/skills/desk.project @@ -0,0 +1,6 @@ +{ + "task_id": null, + "project_id": null, + "customer_id": null, + "gitea_repo": null +} diff --git a/core-tools/skills/index.md b/core-tools/skills/index.md new file mode 100644 index 0000000..1d7c6b4 --- /dev/null +++ b/core-tools/skills/index.md @@ -0,0 +1,8 @@ +# skills + +## Documentação + +- [README](README.md) +- [AGENTS](AGENTS.md) +- [STATUS](STATUS.md) +- [MEMORY](MEMORY.md) diff --git a/core-tools/skills/infrastructure-manager/SKILL.md b/core-tools/skills/infrastructure-manager/SKILL.md new file mode 100644 index 0000000..dab170c --- /dev/null +++ b/core-tools/skills/infrastructure-manager/SKILL.md @@ -0,0 +1,165 @@ +--- +name: infrastructure-manager +description: Gestão automatizada da infraestrutura Claude Code Descomplicar — componentes, health, sincronização e relacionamentos entre MCPs, skills e agentes. +allowed-tools: Read, Glob, Grep, ToolSearch +layer: wiki +--- + +# Infrastructure Manager + +Gestão automatizada da infraestrutura Claude Code Descomplicar com suporte completo a relacionamentos. + +## Triggers + +Esta skill deve ser activada quando: +- Utilizador menciona "infraestrutura", "sistema", "componentes" +- Há problemas de sincronização detectados +- Health score cai abaixo de 90 +- Novo componente é adicionado ao sistema +- Relacionamentos inconsistentes detectados + +## Schema da Base de Dados + +### Core Tables (Entidades) + +| Tabela | Registos | Descrição | +|--------|----------|-----------| +| `cr_agents` | 46 | Agentes especializados | +| `cr_skills` | 54 | Skills invocáveis | +| `cr_mcps` | 33 | Servidores MCP | +| `cr_lsps` | 11+ | Language Server Protocols | +| `cr_plugins` | 29 | Software Development Kits | +| `cr_mcp_tools` | 822 | Ferramentas por MCP | +| `cr_plugins` | 5+ | Plugins instalados | +| `cr_hooks` | 6+ | Hooks configurados | + +### Relationship Tables (800+ relacionamentos) + +| Tabela | Registos | Relacionamento | +|--------|----------|----------------| +| `cr_agent_mcps` | 483 | Agente ↔ MCP (primary/recommended/available) | +| `cr_agent_lsps` | ~40 | Agente ↔ LSP (primary/recommended/available) | +| `cr_plugin_agents` | 131 | TaskForce ↔ Agente | +| `cr_plugin_skills` | 75 | TaskForce ↔ Skill | +| `cr_plugin_mcps` | 56 | TaskForce ↔ MCP | +| `cr_agent_skills` | ~50 | Agente ↔ Skill | +| `cr_skill_mcps` | ~45 | Skill ↔ MCP | +| `cr_agent_collaborations` | ~30 | Agente ↔ Agente | + +### Telemetry Tables + +| Tabela | Descrição | +|--------|-----------| +| `cr_agent_usage` | Tracking uso de agentes | +| `cr_skill_usage` | Tracking uso de skills | +| `cr_mcp_tool_usage` | Tracking uso de ferramentas MCP | +| `cr_lsp_usage` | Tracking uso de LSPs | + +### Intelligence Tables + +| Tabela | Registos | Descrição | +|--------|----------|-----------| +| `cr_decision_trees` | 5 | Árvores de decisão para selecção de agentes | +| `cr_recommendations` | 3 | Sugestões de melhorias | +| `cr_component_issues` | 2 | Issues abertos | +| `cr_reflections` | 1 | Reflexões do sistema | + +## Capabilities + +### 1. Monitorização Completa + +**Entidades:** +```sql +SELECT + 'agents' as type, COUNT(*) as total, + SUM(CASE WHEN status='active' THEN 1 ELSE 0 END) as active +FROM cr_agents +UNION ALL +SELECT 'skills', COUNT(*), SUM(CASE WHEN status='active' THEN 1 ELSE 0 END) FROM cr_skills +UNION ALL +SELECT 'mcps', COUNT(*), SUM(CASE WHEN status='active' THEN 1 ELSE 0 END) FROM cr_mcps +UNION ALL +SELECT 'sdks', COUNT(*), SUM(CASE WHEN status='active' THEN 1 ELSE 0 END) FROM cr_plugins; +``` + +**Relacionamentos:** +```sql +SELECT 'agent_mcps' as table_name, COUNT(*) as count FROM cr_agent_mcps +UNION ALL SELECT 'agent_lsps', COUNT(*) FROM cr_agent_lsps +UNION ALL SELECT 'sdk_agents', COUNT(*) FROM cr_plugin_agents +UNION ALL SELECT 'sdk_skills', COUNT(*) FROM cr_plugin_skills +UNION ALL SELECT 'sdk_mcps', COUNT(*) FROM cr_plugin_mcps +UNION ALL SELECT 'agent_skills', COUNT(*) FROM cr_agent_skills +UNION ALL SELECT 'skill_mcps', COUNT(*) FROM cr_skill_mcps +UNION ALL SELECT 'agent_collaborations', COUNT(*) FROM cr_agent_collaborations; +``` + +**Órfãos (inconsistências):** +```sql +-- Agent_mcps com agentes inexistentes +SELECT COUNT(*) FROM cr_agent_mcps am +LEFT JOIN cr_agents a ON am.agent_id = a.id +WHERE a.id IS NULL; + +-- Repetir para todas as tabelas de relacionamento +``` + +### 2. Auto-Repair de Relacionamentos + +Quando detectados órfãos: +```sql +-- Limpar referências inválidas +DELETE FROM cr_agent_mcps WHERE agent_id NOT IN (SELECT id FROM cr_agents); +DELETE FROM cr_agent_mcps WHERE mcp_id NOT IN (SELECT id FROM cr_mcps); +DELETE FROM cr_plugin_agents WHERE sdk_id NOT IN (SELECT id FROM cr_plugins); +DELETE FROM cr_plugin_agents WHERE agent_id NOT IN (SELECT id FROM cr_agents); +-- ... repetir para outras tabelas +``` + +### 3. Health Score Calculation + +``` +Health Score = ( + entities_sync * 20 + + relationships_consistent * 20 + + mcps_responsive * 15 + + hooks_healthy * 15 + + decision_trees_valid * 10 + + telemetry_active * 10 + + plugins_functional * 10 +) / 100 +``` + +**Thresholds:** +- >= 90: Excelente (verde) +- 70-89: Bom (amarelo) +- < 70: Crítico (vermelho) + +### 4. Reporting Detalhado + +Dashboard completo incluindo: +- Contagem de entidades +- Contagem de relacionamentos +- Órfãos detectados +- Telemetria (30 dias) +- Decision trees status +- Recommendations pendentes + +## Workflow + +``` +DETECTAR → DIAGNOSTICAR → REPARAR → VALIDAR → REPORTAR +``` + +1. **DETECTAR**: Query todas as tabelas +2. **DIAGNOSTICAR**: Identificar inconsistências +3. **REPARAR**: Limpar órfãos, actualizar telemetria +4. **VALIDAR**: Re-verificar consistência +5. **REPORTAR**: Gerar dashboard com métricas + +## Integrações + +- **MCPs**: desk-crm-v3, filesystem, mcp-time +- **Commands**: + - `/descomplicar:status` - Dashboard completo + - `/descomplicar:sy \ No newline at end of file diff --git a/core-tools/skills/log.md b/core-tools/skills/log.md new file mode 100644 index 0000000..66e9c4d --- /dev/null +++ b/core-tools/skills/log.md @@ -0,0 +1 @@ +## 2026-06-30 init | Estrutura padrão diff --git a/core-tools/skills/metrics/SKILL.md b/core-tools/skills/metrics/SKILL.md new file mode 100644 index 0000000..f0542f2 --- /dev/null +++ b/core-tools/skills/metrics/SKILL.md @@ -0,0 +1,184 @@ +--- +name: metrics +description: Dashboard de metricas de performance de skills e agentes com telemetria quantitativa, trending temporal, alertas de degradacao e calculo de ROI. +layer: wiki +--- + +# SKILL: Performance Metrics Dashboard + +## Proposito + +Dashboard interactivo de performance de skills e agents com metricas quantitativas automaticas gravadas em Desk DB. + +Complementa `/reflect` (qualitativo) com dados quantitativos, `/worklog` com metricas objectivas, e PDCA com decisoes data-driven. + +--- + +## Quando Usar + +- Ver performance de skills/agents +- Identificar degradacoes de performance +- Validar melhorias PDCA +- Analise ROI de optimizacoes +- Dashboard executivo de automacao + +--- + +## Comandos + +| Comando | Funcao | +|---------|--------| +| `/metrics` | Overview geral (30 dias) | +| `/metrics ` | Detalhes de skill especifica | +| `/metrics --project ` | Metricas por projecto | +| `/metrics --trend` | Trending temporal | +| `/metrics --compare` | Comparacao vs baseline | +| `/metrics --kb` | Metricas Dify KB | +| `/metrics --roi` | ROI por cliente/projecto | +| `/metrics --export` | Exportar JSON/CSV | +| `/metrics --alerts` | Listar alertas activos | +| `/metrics --tools` | **Telemetria local de tool calls (ver secção Local Tool Telemetry)** | + +--- + +## Local Tool Telemetry (G3.1-B) + +Desde 08-04-2026 há captura universal de **todas** as tool calls do Claude Code via hook PostToolUse (`~/.claude/hooks/telemetry-posttool-hook.sh`). Complementa a telemetria Desk CRM com dados locais imediatos. + +**Ficheiro:** `~/.claude-work/tool-invocations.jsonl` (1 linha por tool call: ts, session, tool_use_id, tool_name, success, error) + +**Agregador:** `/media/ealmeida/Dados/Dev/ClaudeDev/tool-metrics.py` + +```bash +# Overview últimas 24h +python3 /media/ealmeida/Dados/Dev/ClaudeDev/tool-metrics.py + +# Só hoje +python3 /media/ealmeida/Dados/Dev/ClaudeDev/tool-metrics.py --today + +# Últimos 7 dias +python3 /media/ealmeida/Dados/Dev/ClaudeDev/tool-metrics.py --last 7d + +# Filtrar por sessão +python3 /media/ealmeida/Dados/Dev/ClaudeDev/tool-metrics.py --session + +# Output JSON (para pipeline/grafos) +python3 /media/ealmeida/Dados/Dev/ClaudeDev/tool-metrics.py --json +``` + +**Output:** total de invocations, sessões únicas, top 20 tools (contagem + %), falhas por tool com amostras de erro, top 5 sessões por volume. + +**Limitações conhecidas:** +- Duration não é capturada (harness não entrega duration no hook payload). Apenas contagem e success/failure. +- Tokens não capturáveis via hooks (não estão no payload). +- Só captura tool calls que chegam ao PostToolUse — tool calls bloqueados por hooks PreToolUse não aparecem. + +Ver `04-Stack/CHANGELOG.md` bloco 08-04-2026 sessão 2 para contexto do gap e decisão de scope. + +### Agregacoes Disponiveis + +1. **avg** - Medias de performance (padrao) +2. **count** - Contagens por status +3. **trend** - Evolucao temporal (semanal) +4. **compare** - Comparacao com baseline +5. **detailed** - Listagem detalhada + +--- + +## Execucao + +### 1. Verificar Tools MCP + +```javascript +// Tools necessarios (MCP desk-crm-v3) +const REQUIRED_TOOLS = [ + 'mcp__desk-crm-v3__log_skill_metric', + 'mcp__desk-crm-v3__get_skill_metrics' +]; +// Se tools nao disponiveis -> query SQL directa como fallback +``` + +### 2. Query Metricas + +**Via MCP (preferencial):** + +```javascript +const metrics = await mcp__desk_crm_v3__get_skill_metrics({ + days: 30, + aggregate: 'avg', + limit: 10 +}); +``` + +**Fallback SQL:** Ver [references/sql-queries.md](references/sql-queries.md) + +### 3. Formatar Output + +``` +Performance Overview (ultimos {days} dias) + +Top Skills/Agents: +| Nome | Usos | Avg Time | Trend | Status | +|----------------|------|----------|-------|--------| +| /orcamento | 45 | 18min | -12% | OK | +| /lead-approach | 38 | 22min | +5% | Alerta | +| wp-plugin-dev | 32 | 47min | -8% | OK | +``` + +### 4. Analise Especifica + +```javascript +const details = await get_skill_metrics({ + name: skill_name, + days: 30, + aggregate: 'detailed' +}); + +const baseline = await query( + "SELECT baseline_duration_ms FROM tblskill_agent_baselines WHERE name = ?", + [skill_name] +); +const improvement = ((baseline - current_avg) / baseline * 100); +``` + +--- + +## Alertas Automaticos + +```javascript +const degraded = await get_skill_metrics({ + aggregate: 'compare', + days: 7 +}); + +const alerts = degraded.results.filter(r => + r.performance_status === 'DEGRADED' +); + +if (alerts.length > 0) { + // Output alertas e sugerir /reflect para investigar +} +``` + +### Trigger Reflect se Degradacao + +```javascript +if (degradation_pct > 15) { + // AUTO: Invocar reflect-agent em background + Task({ + subagent_type: 'reflect-agent', + background: true, + model: 'sonnet', + prompt: `PERFORMANCE DEGRADATION: ${name} +${degradation_pct}%` + }); +} +``` + +--- + +## Integracao com Outros Sistemas + +| Comando | Foco | Quando Usar | +|---------|------|-------------| +| `/taskforce kb-health` | Saude sistema KB | Visao arquitectural | +| `/metrics --kb` | Performance queries \ No newline at end of file diff --git a/core-tools/skills/metrics/references/dashboards-templates.md b/core-tools/skills/metrics/references/dashboards-templates.md new file mode 100644 index 0000000..9989f55 --- /dev/null +++ b/core-tools/skills/metrics/references/dashboards-templates.md @@ -0,0 +1,126 @@ +# Metrics - Templates de Dashboards + +## Dashboard KB Performance + +``` +DIFY KB PERFORMANCE DASHBOARD + +CACHE PERFORMANCE +Hit Rate: [barra progresso] X% (target: 40%+) + +Cache Breakdown: +| Skill | Queries | Hits | Hit % | +|----------------|---------|------|-------| +| /orcamento | 5 | 1 | 20% | +| /lead-approach | 3 | 0 | 0% | +| /wp-dev | 4 | 0 | 0% | + +QUERY RELEVANCE (avg score) +SEO: 0.85 +Perfex: 0.79 +Elementor: 0.70 +Marketing: 0.66 +Vendas: 0.46 (alerta) + +IMPACT ON PERFORMANCE +Com Dify KB: 18 min avg +Sem Dify KB: 30 min avg (baseline) +Improvement: -40% +``` + +## Dashboard ROI por Cliente/Projecto + +``` +ROI POR CLIENTE/PROJECTO (ultimos 30 dias) + +TOP CLIENTES POR VALOR GERADO +| Cliente | Horas | Skills | Valor (EUR) | +|--------------|-------|--------|-------------| +| SFV-360 | 24h | 45 | 1.200,00 | +| Descomplicar | 18h | 32 | 900,00 | +| INTERNAL | 12h | 28 | 600,00 | + +TOTAL PERIODO: 54 horas poupadas = 2.700,00 EUR +Custo hora interno: 50,00 EUR + +BREAKDOWN POR SKILL +/orcamento: 12h poupadas (baseline 30min->18min) +/wp-dev: 8h poupadas (baseline 4h->2h) +/lead-approach: 6h poupadas (baseline 25min->12min) +``` + +## Dashboard Alertas + +``` +ALERTAS ACTIVOS + +DEGRADACAO (>15% vs baseline) +/lead-approach: +22% (baseline 12min -> actual 15min) +Ultima ocorrencia: 2026-02-02 +Afecta: 3 projectos +Accao: Executar /reflect para investigar + +LOW CACHE HIT (<30%) +Cache hit rate: 6.3% +Target: 40% +Causa: Sistema recente, acumular com uso + +MELHORIAS DETECTADAS +/orcamento: -40% (era 30min, agora 18min) +/wp-dev: -50% (era 4h, agora 2h) + +Configurar alertas: +- Degradacao threshold: 15% (padrao) +- Cache hit minimum: 30% (padrao) +- Error rate maximum: 10% (padrao) +``` + +## Dashboard Export + +``` +Formatos disponiveis: +1. JSON - ~/.claude/skills/_metrics-export-YYYYMMDD.json +2. CSV - ~/.claude/skills/_metrics-export-YYYYMMDD.csv +3. Markdown - Para colar em documentos + +Campos exportados: +- name, type, executions, avg_ms, baseline_ms +- improvement_pct, error_rate, kb_consulted +- cache_hit_rate, project_id, client_name +``` + +## ASCII Charts Library + +### Progress Bar + +```javascript +function progressBar(value, max, width=20) { + const filled = Math.round((value / max) * width); + const empty = width - filled; + return '#'.repeat(filled) + '-'.repeat(empty); +} +``` + +### Trending Arrow + +```javascript +function trendIcon(pct) { + if (pct < -10) return 'melhoria significativa'; + if (pct < 0) return 'melhoria'; + if (pct === 0) return 'estavel'; + if (pct < 10) return 'degradacao ligeira'; + return 'degradacao significativa'; +} +``` + +### Mini Sparkline + +```javascript +function sparkline(values) { + const chars = '________'; + const min = Math.min(...values); + const max = Math.max(...values); + const range = max - min || 1; + return values.map(v => chars[Math.floor((v - min) / range * 7)]).join(''); +} +``` diff --git a/core-tools/skills/metrics/references/sql-queries.md b/core-tools/skills/metrics/references/sql-queries.md new file mode 100644 index 0000000..1def1d8 --- /dev/null +++ b/core-tools/skills/metrics/references/sql-queries.md @@ -0,0 +1,77 @@ +# Metrics - Queries SQL (Fallback) + +Queries para usar quando tools MCP nao estao disponiveis. + +## Top 10 Skills + +```sql +SELECT + name, + COUNT(*) as uses, + AVG(duration_ms)/60000 as avg_min, + (SUM(CASE WHEN status='error' THEN 1 ELSE 0 END) / COUNT(*) * 100) as error_rate +FROM tblskill_agent_metrics +WHERE created_at > DATE_SUB(NOW(), INTERVAL 30 DAY) + AND type = 'skill' +GROUP BY name +ORDER BY uses DESC +LIMIT 10; +``` + +## ROI por Projecto + +```sql +WITH skill_savings AS ( + SELECT + m.project_id, + m.name, + COUNT(*) as uses, + (b.baseline_duration_ms - AVG(m.duration_ms))/60000 as saved_per_use_min + FROM tblskill_agent_metrics m + JOIN tblskill_agent_baselines b ON b.name = m.name + WHERE m.status = 'success' + GROUP BY m.project_id, m.name +) +SELECT + p.name as project, + c.company as client, + s.name as skill, + s.uses, + ROUND(s.uses * s.saved_per_use_min/60, 1) as hours_saved, + ROUND((s.uses * s.saved_per_use_min/60) * 50, 2) as value_eur +FROM skill_savings s +JOIN tblprojects p ON p.id = s.project_id +JOIN tblclients c ON c.userid = p.clientid +WHERE s.saved_per_use_min > 0 +ORDER BY hours_saved DESC; +``` + +## Trending Semanal + +```sql +SELECT + name, + DATE_FORMAT(created_at, '%Y-W%u') as week, + COUNT(*) as executions, + AVG(duration_ms) as avg_ms +FROM tblskill_agent_metrics +WHERE created_at > DATE_SUB(NOW(), INTERVAL 30 DAY) +GROUP BY name, week +ORDER BY name, week DESC; +``` + +## Query Basica via MCP + +```sql +SELECT + name, + type, + COUNT(*) as executions, + AVG(duration_ms) as avg_ms, + (SUM(CASE WHEN status='error' THEN 1 ELSE 0 END) / COUNT(*) * 100) as error_rate +FROM tblskill_agent_metrics +WHERE created_at > DATE_SUB(NOW(), INTERVAL 30 DAY) +GROUP BY name, type +ORDER BY executions DESC +LIMIT 10; +``` diff --git a/core-tools/skills/plugin-curator/SKILL.md b/core-tools/skills/plugin-curator/SKILL.md new file mode 100644 index 0000000..c63a8dd --- /dev/null +++ b/core-tools/skills/plugin-curator/SKILL.md @@ -0,0 +1,113 @@ +--- +name: plugin-curator +description: Curadoria inteligente de plugins para o ecossistema Claude Code — descoberta, recomendações, actualizações e identificação de gaps funcionais. +allowed-tools: Read, Glob, Grep, WebFetch, WebSearch +layer: wiki +--- + +# Plugin Curator + +Curadoria inteligente de plugins para o ecossistema Claude Code. + +## Triggers + +Esta skill deve ser activada quando: +- Utilizador pede recomendações de plugins +- Novo tipo de tarefa sem skill/plugin adequado +- Actualização disponível para plugins instalados +- Gap identificado na cobertura funcional + +## Capabilities + +### 1. Gap Analysis +- Mapear funcionalidades existentes +- Identificar áreas sem cobertura +- Sugerir plugins ou skills a desenvolver +- Priorizar baseado em uso real + +### 2. Discovery +- Pesquisar marketplaces oficiais e comunitários +- Avaliar relevância baseada no contexto actual +- Identificar plugins com funcionalidades sobrepostas +- Detectar plugins desactualizados ou abandonados + +### 3. Evaluation +- Analisar qualidade do código (se open source) +- Verificar compatibilidade com sistema actual +- Avaliar segurança (hooks, permissões) +- Medir popularidade e manutenção activa + +### 4. Installation Management +- Instalar plugins recomendados +- Configurar hooks e MCPs do plugin +- Resolver conflitos com plugins existentes +- Gerir actualizações e rollbacks + +## Marketplaces Conhecidos + +| Marketplace | URL | Tipo | +|-------------|-----|------| +| anthropics/claude-plugins-official | github.com | Oficial | +| coreyhaines31/marketingskills | github.com | Marketing | +| alirezarezvani/claude-skills | github.com | Geral | +| Chat2AnyLLM/awesome-claude-plugins | github.com | Curadoria | +| obra/superpowers | github.com | Metodologia | + +## Scoring Algorithm + +``` +score = 0 +score += keyword_match * 3 # Max 3 (bool: 0|1) +score += category_align * 2 # Max 2 (bool: 0|1) +score += popularity # Max 2 (tiered: 0=<100 stars, 1=100-1k, 2=>1k) +score += recent_update # Max 1 (bool: 1 se último commit <30 dias) +score += no_conflicts * 2 # Max 2 (bool: 0|1) +# Total max: 3 + 2 + 2 + 1 + 2 = 10 +``` + +## Workflow + +``` +ANALYSE GAPS → SEARCH MARKETPLACES → EVALUATE → RECOMMEND → INSTALL +``` + +## Exemplo de Uso + +``` +User: Preciso de ajuda com testes automatizados +Assistant: [Activa plugin-curator] +- Verifica skills de testing existentes: Nenhuma +- Pesquisa marketplaces por "testing", "QA", "automation" +- Encontra: pr-review-toolkit (6 agents QA), superpowers (TDD) +- Recomenda: "Encontrei 2 plugins relevantes para testing: + 1. pr-review-toolkit - 6 agents especializados em QA + 2. superpowers - Metodologia TDD integrada + Qual preferes instalar?" +``` + +## Limites + +- Não instala plugins automaticamente (requer confirmação) +- Não avalia plugins de fontes privadas/não acessíveis +- Score máximo 10 - pode não reflectir 100% da qualidade real +- Depende de metadados disponíveis nos marketplaces + +## Anti-Patterns + +- NUNCA instalar plugins sem confirmação do utilizador +- NUNCA instalar plugins de fontes não verificadas +- Verificar SEMPRE conflitos antes de instalar +- Manter registo de todos os plugins avaliados + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"2026-04-06","issue":"Capabilities ordenadas por ordem diferente do Workflow (Discovery 1º, Gap Analysis 4º) — incoerência com fluxo ANALYSE GAPS → SEARCH → EVALUATE → RECOMMEND → INSTALL","fix":"Reordenadas Capabilities para seguir ordem do Workflow: 1.Gap Analysis 2.Discovery 3.Evaluation 4.Installation Management","source":"auto"} +{"date":"2026-04-06","issue":"Scoring algorithm: score += popularity sem multiplicador e sem documentar escala — ambíguo se max é 1 (bool) ou 2 (tiered)","fix":"Adicionados comentários inline a todos os campos: tipo (bool/tiered), escala e critério. Confirmada soma: 3+2+2+1+2=10.","source":"auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/core-tools/skills/plugin-manager/SKILL.md b/core-tools/skills/plugin-manager/SKILL.md new file mode 100644 index 0000000..263a4b5 --- /dev/null +++ b/core-tools/skills/plugin-manager/SKILL.md @@ -0,0 +1,156 @@ +--- +name: plugin-config +description: Gestão inteligente de plugins por contexto. Avalia regras aditivas e activa cada plugin relevante para o contexto actual (directório, ficheiros, conversa). +user-invocable: false +allowed-tools: Read, Bash, Glob +layer: wiki +--- + +# /plugin-config v3.0 - Gestao Inteligente de Plugins + +Cada plugin tem regras de activacao. O sistema avalia todas e activa o que fizer sentido. +Sem profiles — aditivo, contextual, automatico. + +--- + +## Comandos + +| Comando | Funcao | +|---------|--------| +| `/plugin-config status` | Plugins activos/inactivos e porquê | +| `/plugin-config apply` | Avalia regras e aplica alteracoes ao settings.json | +| `/plugin-config enable ` | Forca activacao de um plugin | +| `/plugin-config disable ` | Forca desactivacao de um plugin | +| `/plugin-config reset` | Activa todos os plugins | + +--- + +## Como funciona + +### Registry (profiles.json v3.0) + +Cada plugin tem regras `activate_when`: +- **directories** — $PWD comeca com este path +- **files** — ficheiro existe no projecto (ate 2 niveis acima) +- **keywords** — palavra aparece no contexto da conversa +- **ssh_context** — quando trabalho via SSH envolve estes termos +- **content_match** — conteudo especifico dentro de um ficheiro + +Regras sao **aditivas**: se qualquer regra de um plugin faz match, esse plugin activa. +Multiplos plugins podem activar simultaneamente. + +### Always-on (4 plugins) + +Nunca desactivados, independentemente do contexto: +- gestao, crm-ops, core-tools, superpowers + +### Contextuais (19 plugins) + +| Plugin | Activa quando | +|--------|---------------| +| **project-manager** | SPEC.md, SPRINT.md, .desk-project, Dev/ ou Hub/ directory | +| **wordpress** | wp-config.php, wordpress, elementor, woocommerce | +| **dev-tools** | package.json, composer.json, react, typescript, refactor | +| **infraestrutura** | docker-compose.yml, servidor, cwp, easypanel, ssl, deploy | +| **marketing** | seo, campanha, google ads, social media, copywriting | +| **design-media** | design, ui, ux, apresentacao, video, figma | +| **metabase** | metabase, dashboard bi, kpi, query sql | +| **automacao** | n8n, workflow, moloni, webhook, mcp server | +| **perfex-dev** | init.php + register_module, perfex | +| **negocio** | estrategia negocio, saas, e-commerce, pricing, swot | +| **plugin-dev** | .claude-plugin, SKILL.md, criar skill/agent/hook | +| **feature-dev** | package.json, implementar feature, nova feature | +| **frontend-design** | tailwind.config, css, frontend design, layout | +| **frontend-excellence** | next.config.*, react avancado, nextjs, state management | +| **cache-components** | next.config.*, cache component, ppr | +| **pr-review-toolkit** | .git, review, pull request, code review | +| **context7** | package.json, docs, documentacao biblioteca | +| **ralph-loop** | ralph, loop autonomo | +| **playground** | playground, html interactivo | + +--- + +## Protocolo: /plugin-config apply + +``` +1. Ler profiles.json (registry) +2. Para CADA plugin contextual: + a. Avaliar activate_when.directories vs $PWD + b. Avaliar activate_when.files vs ficheiros no projecto + c. Avaliar activate_when.keywords vs contexto da conversa + d. Se qualquer regra match → marcar para activar + e. Se nenhuma regra match → marcar para desactivar +3. Construir mapa enabledPlugins: + - always_on → sempre true + - matched → true + - nao matched → false +4. Aplicar via jq em ~/.claude/settings.json +5. Output: lista de alteracoes +6. Informar: "Alteracoes aplicadas. Restart sessao para efeito." +``` + +## Protocolo: /plugin-config status + +``` +1. Ler ~/.claude/settings.json → enabledPlugins +2. Ler profiles.json → registry +3. Para cada plugin: + - Estado actual (activo/inactivo) + - Tipo (always_on / contextual) + - Regras que fazem match no contexto actual +4. Mostrar tabela organizada +``` + +## Protocolo: /plugin-config enable + +``` +1. Activar plugin via jq em settings.json +2. Informar: "Plugin activado. Restart sessao para efeito." +``` + +## Protocolo: /plugin-config disable + +``` +1. Verificar que nao esta em always_on +2. Desactivar via jq em settings.json +3. Informar: "Plugin desactivado. Restart sessao para efeito." +``` + +## Protocolo: /plugin-config reset + +``` +1. Activar TODOS os plugins (contextual + always_on) em settings.json +2. Informar: "Todos os plugins activados." +``` + +--- + +## Hook automatico + +`~/.claude/hooks/plugin-context-detector.sh` corre no inicio de cada sessao (UserPromptSubmit). +Avalia todas as regras e sugere `/plugin-config apply` se detectar alteracoes necessarias. + +--- + +## Anti-Patterns + +- NUNCA desactivar plugins always_on +- NUNCA editar settings.json sem jq (Regra #40) +- NUNCA prometer efeito imediato — restart e necessario +- NUNCA ignorar sugestao do hook — executar /plugin-config apply + +--- + +*Skill v3.0.0 | 04-03-2026 | Descomplicar* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha ap \ No newline at end of file diff --git a/core-tools/skills/plugin-manager/profiles.json b/core-tools/skills/plugin-manager/profiles.json new file mode 100644 index 0000000..01a1c41 --- /dev/null +++ b/core-tools/skills/plugin-manager/profiles.json @@ -0,0 +1,143 @@ +{ + "version": "3.1", + "type": "plugin-registry", + "always_on": [ + "gestao@descomplicar-plugins", + "crm-ops@descomplicar-plugins", + "core-tools@descomplicar-plugins", + "superpowers@claude-plugins-official" + ], + "plugins": { + "wordpress@descomplicar-plugins": { + "description": "WordPress, Elementor, WooCommerce, themes, plugins WP", + "activate_when": { + "files": ["wp-config.php", "wp-content", "functions.php", "style.css"], + "keywords": ["wordpress", "elementor", "woocommerce", "wp-cli", "theme wordpress", "plugin wp", "rank math", "branda", "wp-admin", "wp update"], + "ssh_context": ["cwp", "public_html", "wp-admin"] + } + }, + "dev-tools@descomplicar-plugins": { + "description": "Desenvolvimento JS/PHP/DB, React, arquitectura, code review", + "activate_when": { + "files": ["package.json", "composer.json", "tsconfig.json", "artisan", ".eslintrc", "Makefile", "pom.xml"], + "keywords": ["react", "typescript", "javascript", "php", "laravel", "api rest", "database design", "schema", "refactor", "debug codigo", "componente react", "fullstack", "backend", "endpoint"] + } + }, + "infraestrutura@descomplicar-plugins": { + "description": "Servidores, CWP, EasyPanel, Proxmox, SSL, DNS, Docker, backups servidor", + "activate_when": { + "files": ["docker-compose.yml", "Dockerfile", ".env.production"], + "directories": ["/root/Dev"], + "keywords": ["servidor", "server", "cwp", "easypanel", "proxmox", "ssl certificado", "dns", "docker", "deploy", "backup servidor", "nginx", "apache", "firewall", "ssh servidor", "email servidor", "postfix", "pbs", "migration vm"] + } + }, + "marketing@descomplicar-plugins": { + "description": "SEO, campanhas, ads, social media, conteudo, copywriting", + "activate_when": { + "keywords": ["seo", "marketing", "campanha", "google ads", "meta ads", "social media", "copywriting", "newsletter", "email marketing", "landing page", "conversao", "lead approach", "conteudo marketing", "instagram", "linkedin", "tiktok", "youtube marketing", "ppc"] + } + }, + "design-media@descomplicar-plugins": { + "description": "Design UI/UX, apresentacoes, infograficos, video, identidade visual", + "activate_when": { + "keywords": ["design", "ui design", "ux design", "apresentacao", "infografico", "logo", "identidade visual", "pptx", "slides", "remotion", "video producao", "thumbnail", "figma", "penpot", "mockup", "wireframe", "brand"] + } + }, + "metabase@descomplicar-plugins": { + "description": "BI, dashboards Metabase, queries SQL analytics", + "activate_when": { + "keywords": ["metabase", "dashboard bi", "analytics dados", "kpi dashboard", "query sql metabase", "relatorio dados"] + } + }, + "automacao@descomplicar-plugins": { + "description": "N8N, workflows, integracoes, Moloni, MCPs dev, webhooks", + "activate_when": { + "keywords": ["n8n", "workflow automacao", "moloni", "webhook", "integracao sistemas", "mcp server", "mcp desenvolvimento", "automacao processo"] + } + }, + "perfex-dev@descomplicar-plugins": { + "description": "Modulos Perfex CRM, controllers, hooks, views, migrations Perfex", + "activate_when": { + "files": ["init.php"], + "content_match": "register_module", + "keywords": ["perfex", "modulo perfex", "perfex crm"] + } + }, + "negocio@descomplicar-plugins": { + "description": "Estrategia, pesquisa mercado, SaaS, e-commerce, produto", + "activate_when": { + "keywords": ["estrategia negocio", "pesquisa mercado", "saas", "e-commerce", "produto digital", "pricing", "business model", "swot", "porter", "concorrencia", "proposta valor"] + } + }, + "project-manager@descomplicar-plugins": { + "description": "Specs, sprints, brainstorm, status projecto, scope", + "activate_when": { + "files": ["SPEC.md", "SPRINT.md", ".desk-project"], + "directories": ["/media/ealmeida/Dados/Dev", "/media/ealmeida/Dados/Hub"], + "keywords": ["spec", "sprint", "brainstorm", "status projecto", "scope", "planeamento dev", "fase projecto", "milestone"] + } + }, + "plugin-dev@claude-plugins-official": { + "description": "Criar/editar plugins Claude Code, skills, agents, hooks", + "activate_when": { + "directories": ["/home/ealmeida/.claude/plugins"], + "files": [".claude-plugin", "SKILL.md", "plugin.json"], + "keywords": ["criar plugin", "criar skill", "criar agent", "criar hook", "plugin-dev", "editar skill", "novo agent"] + } + }, + "feature-dev@claude-plugins-official": { + "description": "Desenvolvimento guiado de features com exploracao de codebase", + "activate_when": { + "files": ["package.json", "composer.json", "tsconfig.json"], + "keywords": ["feature dev", "implementar feature", "desenvolver funcionalidade", "nova feature", "feature branch"] + } + }, + "frontend-design@claude-plugins-official": { + "description": "Design frontend, componentes visuais, CSS, Tailwind", + "activate_when": { + "files": ["tailwind.config.js", "tailwind.config.ts", "postcss.config.js", "globals.css"], + "keywords": ["frontend design", "css", "tailwind", "componente visual", "responsive design", "layout pagina", "estilo css", "styled components"] + } + }, + "frontend-excellence@dotclaude-plugins": { + "description": "React avancado, state management, performance frontend", + "activate_when": { + "files": ["next.config.js", "next.config.mjs", "next.config.ts", "vite.config.ts"], + "keywords": ["react avancado", "next.js", "nextjs", "state management", "zustand", "redux", "performance frontend", "core web vitals", "server components"] + } + }, + "cache-components@nextjs": { + "description": "Next.js Cache Components e Partial Prerendering", + "activate_when": { + "files": ["next.config.js", "next.config.mjs", "next.config.ts"], + "keywords": ["cache component", "ppr", "partial prerendering", "next.js cache", "isr"] + } + }, + "pr-review-toolkit@claude-plugins-official": { + "description": "Code review, PR review, analise de codigo, silent failures", + "activate_when": { + "files": [".git"], + "keywords": ["review", "code review", "pull request", "pr review", "review codigo", "merge", "git diff", "commit review"] + } + }, + "ralph-loop@claude-plugins-official": { + "description": "Loop autonomo iterativo para tarefas complexas", + "activate_when": { + "keywords": ["ralph", "loop autonomo", "iteracao autonoma", "ralph loop"] + } + }, + "playground@claude-plugins-official": { + "description": "Playgrounds HTML interactivos para exploracao visual", + "activate_when": { + "keywords": ["playground", "html interactivo", "explorador visual", "configurador visual"] + } + }, + "context7@claude-plugins-official": { + "description": "Documentacao actualizada de bibliotecas e frameworks", + "activate_when": { + "files": ["package.json", "composer.json", "requirements.txt", "Gemfile"], + "keywords": ["docs", "documentacao biblioteca", "context7", "como usar", "api reference", "exemplo codigo"] + } + } + } +} diff --git a/core-tools/skills/quality-validator/SKILL.md b/core-tools/skills/quality-validator/SKILL.md new file mode 100644 index 0000000..f6d31ac --- /dev/null +++ b/core-tools/skills/quality-validator/SKILL.md @@ -0,0 +1,144 @@ +--- +name: quality-validator +description: Validação de componentes contra os standards Descomplicar® — frontmatter, checklists e quality gates antes de activação ou release. +allowed-tools: Read, Glob, Grep +layer: wiki +--- + +# Quality Validator + +Skill para validar componentes e garantir qualidade mínima antes de activação. + +## Triggers + +Esta skill deve ser activada quando: +- Novo componente é criado +- Comando `/descomplicar:validate` é invocado +- Antes de release (`/descomplicar:release`) +- Após edição de componente existente +- Durante sync para bloquear componentes inválidos + +## Capabilities + +### 1. Validar Skill + +**Checklist Obrigatório:** + +| Campo | Obrigatório | Peso | +|-------|-------------|------| +| `name:` | Sim | 15 | +| `description:` | Sim | 20 | +| `author:` | Sim | 5 | +| `version:` | Sim | 5 | +| `desk_task:` | Não | 5 | +| `allowed-tools:` | Sim | 10 | +| Triggers section | Sim | 10 | +| Capabilities section | Sim | 10 | +| Workflow | Não | 5 | +| Exemplo de Uso | Não | 10 | +| Limites section | Não | 5 | + +**Validações de Qualidade:** +- `description:` contém triggers (keywords) → +5 pontos +- `description:` tem 5+ keywords → +5 pontos +- Tamanho < 500 linhas → +5 pontos +- Sem erros de sintaxe YAML → obrigatório + +### 2. Validar Agent + +**Checklist Obrigatório:** + +| Campo | Obrigatório | Peso | +|-------|-------------|------| +| `name:` | Sim | 15 | +| `description:` | Sim | 20 | +| `model:` | Sim | 10 | +| `tools:` | Sim | 10 | +| `allowed-mcps:` | Sim | 15 | +| `category:` | Sim | 10 | +| `author:` | Sim | 5 | +| `version:` | Sim | 5 | +| Quando Usar section | Não | 5 | +| Workflow section | Não | 5 | + +**Validações de Qualidade:** +- MCPs mapeados existem em `cr_mcps` → +5 pontos +- Categoria válida (dev|business|marketing|infra) → obrigatório +- Model válido (sonnet|opus|haiku) → obrigatório + +### 3. Validar Command + +**Checklist Obrigatório:** + +| Campo | Obrigatório | Peso | +|-------|-------------|------| +| `name:` | Sim | 20 | +| `description:` | Sim | 30 | +| `argument-hint:` | Não | 10 | +| Objectivo section | Sim | 15 | +| Sintaxe section | Sim | 15 | +| Output section | Não | 10 | + +### 4. Calcular Score + +**Fórmula:** +``` +score = (campos_obrigatorios * peso_obrigatorio) + (campos_opcionais * peso_opcional) + bonus_qualidade +``` + +**Interpretação:** +| Score | Status | Acção | +|-------|--------|-------| +| >= 90 | Production | Pronto para uso | +| 70-89 | Beta | Pode activar com aviso | +| 50-69 | Draft | Requer melhorias | +| < 50 | Invalid | **BLOQUEAR** activação | + +### 5. Gerar Relatório + +**Output:** +``` +╔══════════════════════════════════════════════════════════════════════╗ +║ QUALITY VALIDATION: ║ +║ Type: Skill | Path: skills//SKILL.md ║ +╠══════════════════════════════════════════════════════════════════════╣ +║ FRONTMATTER ║ +║ ├── name: ✓ Present ║ +║ ├── description: ✓ Present (5 keywords detected) ║ +║ ├── author: ✓ Present ║ +║ ├── version: ✓ Present (1.0.0) ║ +║ ├── desk_task: ✗ Missing (optional) ║ +║ └── allowed-tools: ✓ Present (Read, Glob, Grep) ║ +╠══════════════════════════════════════════════════════════════════════╣ +║ CONTENT SECTIONS ║ +║ ├── Triggers: ✓ Present ║ +║ ├── Capabilities: ✓ Present (3 capabilities) ║ +║ ├── Workflow: ✓ Present ║ +║ ├── Exemplo: ✗ Missing (recommended) ║ +║ └── Limites: ✗ Missing (recommended) ║ +╠══════════════════════════════════════════════════════════════════════╣ +║ QUALITY CHECKS ║ +║ ├── Lines: 234 (< 500 ✓) ║ +║ ├── YAML syntax: Valid ✓ ║ +║ └── Keywords: 5 detected ✓ ║ +╠══════════════════════════════════════════════════════════════════════╣ +║ SCORE: 78/100 ████████████████░░░░ BETA ║ +╠══════════════════════════════════════════════════════════════════════╣ +║ SUGGESTIONS ║ +║ 1. Adicionar secção "Exemplo de Uso" (+10 pontos) ║ +║ 2. Adicionar secção "Limites" (+5 pontos) ║ +║ 3. Adicionar desk_task no frontmatter (+5 pontos) ║ +╚══════════════════════════════════════════════════════════════════════╝ +``` + +## Quality Gates + +### Gate 1: Criação +- Score >= 50 para criar componente +- Se < 50: BLOQUEAR e mostrar erros + +### Gate 2: Activação +- Score >= 70 para activar componente +- Se < 70: AVISO + sugestões + +### Gate 3: Re \ No newline at end of file diff --git a/core-tools/skills/relationship-manager/SKILL.md b/core-tools/skills/relationship-manager/SKILL.md new file mode 100644 index 0000000..0eeac07 --- /dev/null +++ b/core-tools/skills/relationship-manager/SKILL.md @@ -0,0 +1,191 @@ +--- +name: relationship-manager +description: Gestão inteligente de relacionamentos entre componentes do sistema — mapeamento de dependências, colaborações agent-MCP/skill e análise de impacto. +allowed-tools: Read, Glob, Grep, ToolSearch +layer: wiki +--- + +# Relationship Manager + +Gestão inteligente de relacionamentos entre componentes do sistema. + +## Triggers + +Esta skill deve ser activada quando: +- Utilizador pede para configurar relacionamentos +- Novo componente é adicionado e precisa de mapeamentos +- Inconsistências detectadas em relacionamentos +- Análise de impacto de mudanças + +## Schema de Relacionamentos + +### Hierarquia + +``` +TaskForce (Plugin) +├── cr_plugin_agents → Agentes do Plugin +├── cr_plugin_skills → Skills do Plugin +└── cr_plugin_mcps → MCPs do Plugin + +Agent +├── cr_agent_mcps → MCPs do Agente (primary/recommended/available) +├── cr_agent_skills → Skills do Agente +└── cr_agent_collaborations → Colaborações com outros Agentes + +Skill +└── cr_skill_mcps → MCPs necessários para a Skill + +Decision Tree +└── Referencia um Agent para selecção automática +``` + +### Tipos de Relacionamento + +**cr_agent_mcps.relationship_type:** +- `primary` - MCPs essenciais, sempre disponíveis +- `recommended` - MCPs recomendados, usar quando relevante +- `available` - MCPs opcionais, disponíveis se necessário + +**cr_agent_collaborations.collaboration_type:** +- `technical` - Colaboração técnica (mesmo domínio) +- `cross-domain` - Colaboração entre domínios diferentes +- `sequential` - Um passa trabalho para outro +- `parallel` - Trabalham em paralelo + +## Capabilities + +### 1. Análise de Relacionamentos + +**Ver todos os relacionamentos de um componente:** +```sql +-- Para um Agente +SELECT 'MCP' as type, m.slug, am.relationship_type +FROM cr_agent_mcps am +JOIN cr_mcps m ON am.mcp_id = m.id +WHERE am.agent_id = (SELECT id FROM cr_agents WHERE slug = ?) + +UNION ALL + +SELECT 'Skill', s.slug, 'uses' +FROM cr_agent_skills ags +JOIN cr_skills s ON ags.skill_id = s.id +WHERE ags.agent_id = (SELECT id FROM cr_agents WHERE slug = ?) + +UNION ALL + +SELECT 'TaskForce', p.slug, 'member' +FROM cr_plugin_agents pa +JOIN cr_plugins p ON pa.plugin_id = p.id +WHERE pa.agent_id = (SELECT id FROM cr_agents WHERE slug = ?) + +UNION ALL + +SELECT 'Collaborator', a2.slug, ac.collaboration_type +FROM cr_agent_collaborations ac +JOIN cr_agents a2 ON ac.collaborator_id = a2.id +WHERE ac.agent_id = (SELECT id FROM cr_agents WHERE slug = ?); +``` + +### 2. Sugestão de Relacionamentos + +Baseado em padrões existentes: +```sql +-- MCPs usados por agentes similares (mesma categoria) +SELECT + m.slug, + COUNT(*) as usage_count, + GROUP_CONCAT(DISTINCT a.slug) as used_by +FROM cr_agent_mcps am +JOIN cr_mcps m ON am.mcp_id = m.id +JOIN cr_agents a ON am.agent_id = a.id +WHERE a.category = (SELECT category FROM cr_agents WHERE slug = ?) +AND am.agent_id != (SELECT id FROM cr_agents WHERE slug = ?) +AND m.id NOT IN ( + SELECT mcp_id FROM cr_agent_mcps + WHERE agent_id = (SELECT id FROM cr_agents WHERE slug = ?) +) +GROUP BY m.id +ORDER BY usage_count DESC +LIMIT 5; +``` + +### 3. Validação de Consistência + +```sql +-- Verificar órfãos em todas as tabelas +SELECT 'cr_agent_mcps (agent)' as issue, + COUNT(*) as orphans +FROM cr_agent_mcps am +LEFT JOIN cr_agents a ON am.agent_id = a.id +WHERE a.id IS NULL + +UNION ALL + +SELECT 'cr_agent_mcps (mcp)', + COUNT(*) +FROM cr_agent_mcps am +LEFT JOIN cr_mcps m ON am.mcp_id = m.id +WHERE m.id IS NULL + +-- ... continuar para todas as tabelas +``` + +### 4. Propagação de Mudanças + +Quando um componente é removido/desactivado: +```sql +-- Marcar relacionamentos como inactivos (não deletar) +UPDATE cr_agent_mcps +SET status = 'inactive', updated_at = NOW() +WHERE agent_id = (SELECT id FROM cr_agents WHERE slug = ?); + +-- Ou limpar (se preferido) +DELETE FROM cr_agent_mcps +WHERE agent_id = (SELECT id FROM cr_agents WHERE slug = ?); +``` + +### 5. Análise de Impacto + +Antes de remover um componente, verificar dependências: +```sql +-- Impacto de remover um MCP +SELECT + 'Agents afectados' as impact, + COUNT(DISTINCT am.agent_id) as count, + GROUP_CONCAT(DISTINCT a.slug) as list +FROM cr_agent_mcps am +JOIN cr_agents a ON am.agent_id = a.id +WHERE am.mcp_id = (SELECT id FROM cr_mcps WHERE slug = ?) +AND am.relationship_type = 'primary' + +UNION ALL + +SELECT + 'Skills afectadas', + COUNT(DISTINCT sm.skill_id), + GROUP_CONCAT(DISTINCT s.slug) +FROM cr_skill_mcps sm +JOIN cr_skills s ON sm.skill_id = s.id +WHERE sm.mcp_id = (SELECT id FROM cr_mcps WHERE slug = ?); +``` + +## Workflows + +### Adicionar Novo Agente + +1. Inserir em `cr_agents` +2. Mapear MCPs em `cr_agent_mcps`: + - Identificar MCPs primários (essenciais) + - Identificar MCPs recomendados (úteis) + - Listar MCPs disponíveis (opcionais) +3. Mapear Skills em `cr_agent_skills` +4. Associar a TaskForces em `cr_plugin_agents` +5. Definir colaborações em `cr_agent_collaborations` +6. Criar decision tree se necessário + +### Remover Componente + +1. Verificar impacto com análise de dependências +2. Confirmar com utilizador +3. Remover relacionamentos (ou marcar inactive) +4. Actualizar decision tre \ No newline at end of file