diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 638bdcd..2cf573f 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -20,7 +20,7 @@ "name": "crm-ops", "source": "./crm-ops", "description": "CRM operations, sales management, leads, customers, estimates, invoices, tickets and expense tracking with Desk CRM. Backed by NotebookLM notebooks.", - "version": "1.0.0", + "version": "1.3.1", "author": { "name": "Descomplicar - Crescimento Digital", "url": "https://descomplicar.pt" @@ -50,7 +50,7 @@ "name": "gestao", "source": "./gestao", "description": "Project management, time tracking, daily checkups, worklogs, reflections, knowledge management and archiving. Backed by NotebookLM notebooks.", - "version": "1.0.0", + "version": "1.7.0", "author": { "name": "Descomplicar - Crescimento Digital", "url": "https://descomplicar.pt" @@ -70,7 +70,7 @@ "name": "infraestrutura", "source": "./infraestrutura", "description": "Server management, Proxmox VE/PBS/Clustering, CWP administration, EasyPanel deployments, security audits, backups and MCP development. Backed by NotebookLM notebooks (Proxmox 150+ sources).", - "version": "1.1.0", + "version": "1.2.2", "author": { "name": "Descomplicar - Crescimento Digital", "url": "https://descomplicar.pt" @@ -80,7 +80,7 @@ "name": "marketing", "source": "./marketing", "description": "Digital marketing strategy, SEO, content marketing, social media, ads, copywriting, video and YouTube. Backed by NotebookLM notebooks.", - "version": "1.0.0", + "version": "2.1.0", "author": { "name": "Descomplicar - Crescimento Digital", "url": "https://descomplicar.pt" @@ -110,7 +110,7 @@ "name": "project-manager", "source": "./project-manager", "description": "Spec-driven project management with flexible sprints, scope validation, and NotebookLM-powered discovery.", - "version": "1.1.0", + "version": "1.2.0", "author": { "name": "Descomplicar - Crescimento Digital", "url": "https://descomplicar.pt" @@ -120,7 +120,7 @@ "name": "wordpress", "source": "./wordpress", "description": "WordPress development, maintenance and optimization - plugins, themes, WooCommerce, Elementor, Crocoblock. Backed by NotebookLM notebooks.", - "version": "1.0.0", + "version": "1.1.0", "author": { "name": "Descomplicar - Crescimento Digital", "url": "https://descomplicar.pt" diff --git a/.gitignore b/.gitignore index 7fd144d..de1fcdd 100644 --- a/.gitignore +++ b/.gitignore @@ -1,9 +1,7 @@ design-media/skills/*/references/__pycache__/ -# Symlinks absolutos para skills locais da máquina -design-media/skills/pptx-generator -design-media/skills/remotion-video -design-media/skills/ui-ux-pro-max -dev-tools/skills/frontend-design -marketing/skills/brand-voice-generator +# Estado de runtime IJFW (sessoes, metricas, cursores) — local, nunca versionado +.ijfw/ + +# Output do graphify (hook local de rebuild) graphify-out/ diff --git a/README.md b/README.md index fe28e71..149565a 100644 --- a/README.md +++ b/README.md @@ -8,4 +8,31 @@ layer: wiki --- # claude-plugins -Marketplace de plugins Claude Code da Descomplicar \ No newline at end of file +Marketplace de plugins Claude Code da Descomplicar + +## Versões — bumpar sempre nos DOIS sítios + +A versão de cada plugin vive em dois ficheiros e **não há automação a sincronizá-los**: + +| Ficheiro | Papel | Quem o lê | +|---|---|---| +| `/.claude-plugin/plugin.json` | **fonte de verdade** | `/plugin update` — é esta que decide se há versão nova | +| `.claude-plugin/marketplace.json` | agregado derivado | `/plugin marketplace update` — catálogo | + +Bumpar só o agregado **não tem efeito nenhum**: o catálogo mostra a versão nova, o +`/plugin update` responde `already at the latest version` e o cache continua na antiga. +Aconteceu a 30-07-2026 com marketing/gestao/project-manager/wordpress. + +Verificar coerência antes de commitar: + +```bash +for p in */; do p=${p%/}; f="$p/.claude-plugin/plugin.json"; [ -f "$f" ] || continue + a=$(jq -r .version "$f") + b=$(jq -r ".plugins[]|select(.name==\"$p\").version" .claude-plugin/marketplace.json) + [ "$a" = "$b" ] || echo "DIVERGE $p: plugin.json=$a marketplace.json=$b" +done +``` + +Depois de publicar: `/plugin marketplace update descomplicar-plugins` (catálogo) **e** +`/plugin update @descomplicar-plugins` (reinstala no cache). O primeiro sozinho +não actualiza o que corre. \ No newline at end of file diff --git a/VALIDACAO-FASE-F-2026-08-19.md b/VALIDACAO-FASE-F-2026-08-19.md new file mode 100644 index 0000000..6e7e390 --- /dev/null +++ b/VALIDACAO-FASE-F-2026-08-19.md @@ -0,0 +1,23 @@ +--- +type: Validation +version: 2.5 +padrao-versao: 2.5 +timestamp: 2026-08-19 09:16:34 UTC +mode: project +status: ❌ FAILED +--- + +# VALIDAÇÃO — 2026-08-19 + +## Resumo + +| Métrica | Valor | +|---------|-------| +| Modo | project | +| Total projecto | 23 | +| Ficheiros OKF | 0 | +| Entidades OKF | 0 | +| Relacionamentos OKF | 0 | +| Erros | 23 | +| Avisos | 6 | +| Veredicto | ❌ FAILED | diff --git a/acidaos/skills/devops/SKILL.md b/acidaos/skills/devops/SKILL.md index 762a887..a9bfdc2 100644 --- a/acidaos/skills/devops/SKILL.md +++ b/acidaos/skills/devops/SKILL.md @@ -1,8 +1,7 @@ --- name: devops description: CI/CD pipelines para o AcidaOS via Gitea Actions — build, test, deploy para acidaos-core (Rust) e acidaos-dashboard (Next.js). Usar quando "pipeline acidaos", "gitea actions acidaos", "ci cd acidaos", "deploy acidaos", "workflow acidaos". -allowed-tools: Read, Write, Edit, Bash, mcp__gitea__list_repo_action_workflows, mcp__gitea__get_repo_action_workflow, mcp__gitea__create_file, mcp__gitea__update_file, mcp__mem_search_memories -layer: wiki +allowed-tools: Read, Write, Edit, Bash, mcp__gitea__list_repo_action_workflows, mcp__gitea__get_repo_action_workflow, mcp__gitea__create_file, mcp__gitea__update_file, mcp__mem0__search_memories --- # AcidaOS DevOps — Gitea Actions @@ -31,7 +30,7 @@ Deploy target: ## Protocolo Inicial ``` -mcp__mem_search_memories "acidaos devops pipeline" +mcp__mem0__search_memories "acidaos devops pipeline" mcp__gitea__list_repo_action_workflows # ver workflows existentes ``` @@ -203,4 +202,127 @@ jobs: uses: actions/setup-node@v4 with: node-version: '20' - cache: 'pnpm \ No newline at end of file + cache: 'pnpm' + + - name: Instalar dependências + run: pnpm install --frozen-lockfile + + - name: TypeScript check + run: pnpm tsc --noEmit + + - name: ESLint + run: pnpm lint + + test: + name: Testes + needs: lint-typecheck + runs-on: [self-hosted, linux, node] + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'pnpm' + + - name: Instalar dependências + run: pnpm install --frozen-lockfile + + - name: Testes unitários + run: pnpm test + + - name: Build de verificação + run: pnpm build + env: + ACIDAOS_CORE_URL: http://localhost:3001 + + e2e: + name: Testes E2E + needs: test + runs-on: [self-hosted, linux, node] + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'pnpm' + + - name: Instalar dependências + run: pnpm install --frozen-lockfile + + - name: Instalar Playwright + run: pnpm exec playwright install --with-deps chromium + + - name: Testes E2E + run: pnpm test:e2e + env: + BASE_URL: http://localhost:3000 + ACIDAOS_CORE_URL: http://localhost:3001 + + - name: Upload relatório E2E + if: failure() + uses: actions/upload-artifact@v3 + with: + name: playwright-report + path: playwright-report/ +``` + +--- + +## Gestão via MCP Gitea + +```javascript +// Listar workflows de um repo +mcp__gitea__list_repo_action_workflows({ owner: "descomplicar", repo: "acidaos-core" }) + +// Ver runs recentes +mcp__gitea__list_repo_action_runs({ owner: "descomplicar", repo: "acidaos-core" }) + +// Desencadear workflow manualmente +mcp__gitea__dispatch_repo_action_workflow({ + owner: "descomplicar", + repo: "acidaos-core", + workflow_id: "deploy.yml", + ref: "main" +}) + +// Ver logs de uma job +mcp__gitea__get_repo_action_job_log_preview({ owner: "descomplicar", repo: "acidaos-core", job_id: }) +``` + +## Segredos necessários (Gitea Secrets) + +| Segredo | Usado em | Descrição | +|---------|----------|-----------| +| `TEST_DATABASE_URL` | Core CI | PostgreSQL de teste | +| `REGISTRY_TOKEN` | Core Deploy | Token registry Docker | +| `EASYPANEL_TOKEN` | Core/Dashboard Deploy | Token API EasyPanel | + +## Checklist Pipeline Nova + +- [ ] Workflow criado em `.gitea/workflows/` +- [ ] Runner labels correctas (`self-hosted, linux, rust` ou `node`) +- [ ] Cache Cargo/pnpm configurado +- [ ] Segredos referenciados (não hardcoded) +- [ ] Health check no deploy +- [ ] Tested com `mcp__gitea__dispatch_repo_action_workflow` + +--- +**Versão**: 1.0.0 | **Autor**: Descomplicar® | **Plugin**: acidaos + +--- + +## 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/acidaos/skills/docs/SKILL.md b/acidaos/skills/docs/SKILL.md index ff531b4..45048fe 100644 --- a/acidaos/skills/docs/SKILL.md +++ b/acidaos/skills/docs/SKILL.md @@ -1,8 +1,7 @@ --- name: docs description: Gerar documentação técnica do AcidaOS a partir do código — Rust (rustdoc), TypeScript (TypeDoc), e publicar no Outline. Usar quando "documentação acidaos", "gerar docs", "rustdoc", "typedoc", "acidaos-docs", documentar código do projecto. -allowed-tools: Read, Write, Bash, mcp__gitea__get_file_content, mcp__gitea__get_dir_content, mcp__outline-api__create_document, mcp__outline-api__update_document, mcp__outline-api__search_documents, mcp__mem_search_memories -layer: wiki +allowed-tools: Read, Write, Bash, mcp__gitea__get_file_content, mcp__gitea__get_dir_content, mcp__outline-api__create_document, mcp__outline-api__update_document, mcp__outline-api__search_documents, mcp__mem0__search_memories --- # AcidaOS Docs @@ -22,7 +21,7 @@ Skill para gerar e publicar documentação técnica do AcidaOS. ## Protocolo ``` -mcp__mem_search_memories "acidaos documentação" +mcp__mem0__search_memories "acidaos documentação" mcp__outline-api__search_documents "acidaos" # ver docs existentes ``` @@ -37,9 +36,9 @@ mcp__outline-api__search_documents "acidaos" # ver docs existentes mcp__gitea__get_dir_content acidaos-core/src/ ``` -**Gerar localmente (no container dev):** +**Gerar localmente (desktop):** ```bash -cd /root/Dev/acidaos-core +cd /media/ealmeida/Dados/Dev/acidaos-core cargo doc --all-features --no-deps --open ``` @@ -82,9 +81,9 @@ pub struct ComponenteX { ... } mcp__gitea__get_file_content acidaos-dashboard/typedoc.json ``` -**Gerar (no container dev):** +**Gerar (localmente no desktop):** ```bash -cd /root/Dev/acidaos-dashboard +cd /media/ealmeida/Dados/Dev/acidaos-dashboard pnpm typedoc --out docs/api src/ ``` diff --git a/acidaos/skills/rust-dev/SKILL.md b/acidaos/skills/rust-dev/SKILL.md index fbb1b5e..7facaf1 100644 --- a/acidaos/skills/rust-dev/SKILL.md +++ b/acidaos/skills/rust-dev/SKILL.md @@ -1,8 +1,7 @@ --- name: rust-dev description: Desenvolvimento do AcidaOS Core em Rust — criar crates, definir endpoints Axum, debugar erros do compilador. Usar quando "rust", "axum", "cargo", "crate", "core", "acidaos core", "rust error", "borrow checker", desenvolvimento do motor central do AcidaOS. -allowed-tools: Read, Write, Edit, Bash, mcp__mem_search_memories, mcp__gitea__get_file_content, mcp__gitea__create_file, mcp__gitea__update_file -layer: wiki +allowed-tools: Read, Write, Edit, Bash, mcp__mem0__search_memories, mcp__gitea__get_file_content, mcp__gitea__create_file, mcp__gitea__update_file --- # AcidaOS Rust Dev @@ -30,7 +29,7 @@ acidaos-core (Rust) ## Protocolo Inicial ``` -mcp__mem_search_memories "acidaos core [componente]" +mcp__mem0__search_memories "acidaos core [componente]" mcp__gitea__get_file_content acidaos-core/Cargo.toml # verificar dependências actuais ``` @@ -205,4 +204,41 @@ async fn handler(req: Arc) -> Response { ... } Antes de fazer commit: ```bash -ca \ No newline at end of file +cargo check # zero erros +cargo clippy # zero warnings +cargo test # todos os testes passam +cargo fmt --check # formatação correcta +``` + +**Standards:** +- Zero `unwrap()` em código de produção — usar `?` ou `expect("mensagem descritiva")` +- Funções async < 50 linhas +- `tracing::instrument` em todas as funções públicas async +- Documentação `///` em todos os tipos e funções públicas + +--- + +## Checklist Entrega + +- [ ] `cargo check` sem erros +- [ ] `cargo clippy -- -D warnings` limpo +- [ ] `cargo test` 100% pass +- [ ] Documentação `///` completa +- [ ] Observabilidade: `#[instrument]` nos handlers +- [ ] Sem `.unwrap()` em paths críticos +- [ ] CHANGELOG.md actualizado + +--- +**Versão**: 1.0.0 | **Autor**: Descomplicar® | **Plugin**: acidaos + +--- + +## 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/acidaos/skills/spoke-dev/SKILL.md b/acidaos/skills/spoke-dev/SKILL.md index 8ef90fc..a5ba96a 100644 --- a/acidaos/skills/spoke-dev/SKILL.md +++ b/acidaos/skills/spoke-dev/SKILL.md @@ -1,8 +1,7 @@ --- name: spoke-dev description: Desenvolvimento de Spokes do AcidaOS em Next.js/TypeScript — criar aplicações Spoke, componentes React com testes e Storybook. Usar quando "spoke", "dashboard acidaos", "next.js acidaos", "componente react acidaos", "ts-create-spoke", "acidaos ui", "acidaos frontend". -allowed-tools: Read, Write, Edit, Bash, mcp__mem_search_memories, mcp__gitea__get_file_content, mcp__gitea__create_file, mcp__gitea__update_file -layer: wiki +allowed-tools: Read, Write, Edit, Bash, mcp__mem0__search_memories, mcp__gitea__get_file_content, mcp__gitea__create_file, mcp__gitea__update_file --- # AcidaOS Spoke Dev @@ -33,7 +32,7 @@ acidaos-dashboard (Next.js 15 + App Router) ## Protocolo Inicial ``` -mcp__mem_search_memories "acidaos spoke dashboard [componente]" +mcp__mem0__search_memories "acidaos spoke dashboard [componente]" mcp__gitea__get_file_content acidaos-dashboard/package.json ``` @@ -47,8 +46,8 @@ mcp__gitea__get_file_content acidaos-dashboard/package.json **Estrutura a criar:** ```bash -# No container dev (Regra #48) -cd /root/Dev +# Localmente no desktop (Regra #48 — CT 102 extinto) +cd /media/ealmeida/Dados/Dev npx create-next-app@latest acidaos- \ --typescript \ --tailwind \ @@ -205,4 +204,48 @@ export type { Props } from './'; - Hooks custom em `src/lib/hooks/use.ts` - Server Components por defeito; `'use client'` apenas quando necessário -### Performance \ No newline at end of file +### Performance +- `next/image` para todas as imagens +- `loading="lazy"` em componentes pesados +- `Suspense` boundaries em torno de data-fetching +- Cache de API calls com `unstable_cache` ou React cache + +### Segurança +- Nunca expor `ACIDAOS_CORE_URL` no cliente (apenas server-side) +- Sanitizar input do utilizador antes de enviar ao Core +- Usar Next.js Server Actions para mutações + +--- + +## Quality Gate + +```bash +pnpm build # zero erros TypeScript +pnpm test # todos os testes passam +pnpm lint # zero erros ESLint +``` + +## Checklist Entrega + +- [ ] Tipos TypeScript sem `any` +- [ ] Testes criados (>80% cobertura) +- [ ] Story Storybook criada +- [ ] `displayName` definido no componente +- [ ] `pnpm build` sem erros +- [ ] Client/Server components correctamente marcados +- [ ] CHANGELOG.md actualizado + +--- +**Versão**: 1.0.0 | **Autor**: Descomplicar® | **Plugin**: acidaos + +--- + +## 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/automacao/agents/automation-lead.md b/automacao/agents/automation-lead.md index 9bc90e1..1033fbf 100644 --- a/automacao/agents/automation-lead.md +++ b/automacao/agents/automation-lead.md @@ -7,6 +7,8 @@ model: sonnet tools: Read, Write, Edit, Bash, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 - n8n @@ -46,7 +48,6 @@ escalates_to: created: "2025-01-13" updated: "2026-02-04" author: "Descomplicar®" -layer: wiki --- # Automation Lead Descomplicar @@ -168,9 +169,66 @@ mcp__notebooklm__notebook_query notebook_id:"929ef67b-c131-4f01-abd0-8b078491a6b - **ssh-unified** - SSH, SFTP, servidor management - **gitea** - Repositórios Git, issues, PRs - **puppeteer** - Browser automation -- **mem0** - Memória longo prazo +- **mem0** - Mem0 (Tier 2, `mcp__mem0__*`) + IJFW (Tier 1, automático via hooks) - **** - Knowledge base AI - **filesystem** - Ficheiros locais ### All Available (32 total) -moloni, context7, cwp, google-analytics, google-workspace, imap, outline-api, youtube-research, youtube-uploader, wikijs, gsc, lighthouse, mcp-time, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, p \ No newline at end of file +moloni, context7, cwp, google-analytics, google-workspace, imap, outline-api, youtube-research, youtube-uploader, gsc, lighthouse, mcp-time, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, magic, vimeo, design-systems, replicate + +**Discovery:** Use ToolSearch to find specific tools. +**Example:** `ToolSearch("ssh upload")` finds SSH upload tools. +## Your Available Skills + +### Primary Skills (Your Domain) +✓ **/delegate** - Delegar tarefas dev para outros chats Claude com workflow completo - timer, impl + - Invoke: `/delegate` + +✓ **/archive** - Arquivamento automatico de ficheiros concluidos - move ficheiros com status done + - Invoke: `/archive` + +### Recommended for automation +- **/doc-sync** - Sincronização automática de documentação Stack/Vault. Garant +- **/time** - Time tracking integrado com Desk CRM. Inicia e para timers e +- **/taskforce** - Gestão de TaskForces - pacotes de trabalho padronizados com skills + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /lead-approach, /orcamento, /saas, /content-marketing-pt, /remotion-video, /seo-content-optimization, /social-media, /video, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /crm-admin, /db-design, /elementor, /mcp-dev, /nextjs, /php-dev, /react-patterns, /woocommerce, /wp-dev, /backup-strategies, /security-audit, /server-health, /wp-performance, /wp-update, /second-brain-repo, /ads, /marketing-strategy, /product, /skill-creator, /sop-creator, /calendar-manager, /interview, /today, /research, /youtube, /seo-audit, /seo-report, /metrics + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. +## Colaboração + +- **Reports to**: CTO +- **Colabora com**: N8N Automation Expert, MCP Protocol Developer, Development Lead, All department heads +- **Escalar para**: CTO (decisões estratégicas), Security Compliance Specialist (segurança workflows) +## Your Team & Responsibilities + +You are part of **2 SDKs** (TaskForce teams): + +### TaskForce Claude Agents + +**Purpose:** NULL + +**Your responsibilities in this TaskForce:** +### TaskForce Claude Workflow + +**Purpose:** NULL + +**Your responsibilities in this TaskForce:** + +- **Sistema de automacao com hooks Claude Code, integracao N8N e gestao de sessoes com auto-triggers.**: NULL + +**Collaboration:** +- Work with other agents in your TaskForce teams +- Share knowledge and context across team members +- Leverage team-specific skills and MCPs +- Contribute to team goals and deliverables + diff --git a/automacao/agents/mcp-protocol-developer.md b/automacao/agents/mcp-protocol-developer.md index 8c120e9..7189c00 100644 --- a/automacao/agents/mcp-protocol-developer.md +++ b/automacao/agents/mcp-protocol-developer.md @@ -9,6 +9,8 @@ model: sonnet tools: Read, Write, Edit, Bash, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 - gitea @@ -38,7 +40,6 @@ compliance: created: '2025-01-13' updated: '2026-02-04' author: Descomplicar® -layer: wiki --- # MCP Protocol Developer Descomplicar @@ -142,15 +143,73 @@ Especialista em desenvolvimento, optimizacao e manutencao de servidores MCP e fe - **n8n** - Workflows automation - **filesystem** - Ficheiros locais - **magic** - AI-powered UI component generation (tipo v0.dev) -- **mem0** - Memória longo prazo +- **mem0** - Mem0 (Tier 2, `mcp__mem0__*`) + IJFW (Tier 1, automático via hooks) - **cwp** - CentOS Web Panel - **puppeteer** - Browser automation ### All Available (32 total) -moloni, google-analytics, google-workspace, imap, outline-api, youtube-research, youtube-uploader, wikijs, gsc, lighthouse, mcp-time, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, vimeo, design-systems, replicate +moloni, google-analytics, google-workspace, imap, outline-api, youtube-research, youtube-uploader, gsc, lighthouse, mcp-time, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, vimeo, design-systems, replicate **Discovery:** Use ToolSearch to find specific tools. **Example:** `ToolSearch("ssh upload")` finds SSH upload tools. ## Your Available Skills -### Primary Skills (Your \ No newline at end of file +### Primary Skills (Your Domain) +✓ **/wp-dev** - Desenvolvimento WordPress especializado - plugins, temas, WooCommerce. Usar para + - Invoke: `/wp-dev` + +✓ **/php-dev** - Desenvolvimento PHP fullstack - Laravel, Symfony, APIs RESTful, arquitectura bac + - Invoke: `/php-dev` + +✓ **/db-design** - Design de bases de dados - schema, optimização queries, MySQL/PostgreSQL, arquit + - Invoke: `/db-design` + +✓ **/mcp-dev** - Desenvolvimento de servidores MCP - criar, configurar, testar e documentar MCPs + - Invoke: `/mcp-dev` + +### Recommended for dev +- **/react-patterns** - Padrões React modernos - Hooks, Server Components, State Man +- **/nextjs** - Desenvolvimento Next.js moderno com App Router, Server Compo +- **/elementor** - Desenvolvimento avançado com Elementor Pro e Crocoblock - wi +- **/woocommerce** - Desenvolvimento e optimização de lojas WooCommerce - checkou +- **/crm-admin** - Administração e desenvolvimento Perfex CRM - gestão dados, m +- **/video** - Criar vídeos programáticos com Remotion e React. Gera intros +- **/doc-sync** - Sincronização automática de documentação Stack/Vault. Garant +- **/delegate** - Delegar tarefas dev para outros chats Claude com workflow co +- **/time** - Time tracking integrado com Desk CRM. Inicia e para timers e + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /lead-approach, /orcamento, /saas, /content-marketing-pt, /remotion-video, /seo-content-optimization, /social-media, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /backup-strategies, /security-audit, /server-health, /wp-performance, /wp-update, /second-brain-repo, /ads, /marketing-strategy, /product, /skill-creator, /sop-creator, /calendar-manager, /interview, /today, /research, /youtube, /seo-audit, /seo-report, /archive, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. +## Your Team & Responsibilities + +You are part of **2 SDKs** (TaskForce teams): + +### TaskForce Claude Agents + +**Purpose:** NULL + +**Your responsibilities in this TaskForce:** +### TaskForce MCP + +**Purpose:** NULL + +**Your responsibilities in this TaskForce:** + +- **Desenvolvimento de servidores MCP - criar, configurar, testar e publicar MCPs customizados com padrões Descomplicar.**: NULL + +**Collaboration:** +- Work with other agents in your TaskForce teams +- Share knowledge and context across team members +- Leverage team-specific skills and MCPs +- Contribute to team goals and deliverables + diff --git a/automacao/agents/n8n-automation-expert.md b/automacao/agents/n8n-automation-expert.md index e9c977e..e14d9bf 100644 --- a/automacao/agents/n8n-automation-expert.md +++ b/automacao/agents/n8n-automation-expert.md @@ -9,6 +9,8 @@ model: sonnet tools: Read, Write, Edit, Bash, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - n8n - desk-crm-v3 @@ -37,7 +39,6 @@ compliance: created: '2025-01-13' updated: '2026-02-04' author: Descomplicar® -layer: wiki --- # N8N Automation Expert Descomplicar @@ -134,7 +135,7 @@ Especialista em design, desenvolvimento e optimizacao de workflows automatizados ✓ **mem0** (system) - Memória longo prazo - - Usage: `mcp__mem_*` + - Usage: `mcp__mem0__*` ### Recommended for automation - **ssh-unified** - SSH, SFTP, servidor management @@ -143,7 +144,7 @@ Especialista em design, desenvolvimento e optimizacao de workflows automatizados - **filesystem** - Ficheiros locais ### All Available (32 total) -moloni, context7, cwp, google-analytics, google-workspace, imap, outline-api, youtube-research, youtube-uploader, wikijs, gsc, lighthouse, mcp-time, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, magic, vimeo, design-systems, replicate +moloni, context7, cwp, google-analytics, google-workspace, imap, outline-api, youtube-research, youtube-uploader, gsc, lighthouse, mcp-time, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, magic, vimeo, design-systems, replicate **Discovery:** Use ToolSearch to find specific tools. **Example:** `ToolSearch("ssh upload")` finds SSH upload tools. @@ -153,4 +154,46 @@ moloni, context7, cwp, google-analytics, google-workspace, imap, outline-api, yo ✓ **/delegate** - Delegar tarefas dev para outros chats Claude com workflow completo - timer, impl - Invoke: `/delegate` -✓ **/archive** - Arquivamento automat \ No newline at end of file +✓ **/archive** - Arquivamento automatico de ficheiros concluidos - move ficheiros com status done + - Invoke: `/archive` + +### Recommended for automation +- **/doc-sync** - Sincronização automática de documentação Stack/Vault. Garant +- **/time** - Time tracking integrado com Desk CRM. Inicia e para timers e +- **/taskforce** - Gestão de TaskForces - pacotes de trabalho padronizados com skills + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /lead-approach, /orcamento, /saas, /content-marketing-pt, /remotion-video, /seo-content-optimization, /social-media, /video, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /crm-admin, /db-design, /elementor, /mcp-dev, /nextjs, /php-dev, /react-patterns, /woocommerce, /wp-dev, /backup-strategies, /security-audit, /server-health, /wp-performance, /wp-update, /second-brain-repo, /ads, /marketing-strategy, /product, /skill-creator, /sop-creator, /calendar-manager, /interview, /today, /research, /youtube, /seo-audit, /seo-report, /metrics + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. +## Your Team & Responsibilities + +You are part of **2 SDKs** (TaskForce teams): + +### TaskForce Claude Agents + +**Purpose:** NULL + +**Your responsibilities in this TaskForce:** +### TaskForce Claude Workflow + +**Purpose:** NULL + +**Your responsibilities in this TaskForce:** + +- **Sistema de automacao com hooks Claude Code, integracao N8N e gestao de sessoes com auto-triggers.**: NULL + +**Collaboration:** +- Work with other agents in your TaskForce teams +- Share knowledge and context across team members +- Leverage team-specific skills and MCPs +- Contribute to team goals and deliverables + diff --git a/automacao/skills/moloni-api/SKILL.md b/automacao/skills/moloni-api/SKILL.md index b123fbc..72f54af 100644 --- a/automacao/skills/moloni-api/SKILL.md +++ b/automacao/skills/moloni-api/SKILL.md @@ -1,7 +1,6 @@ --- name: moloni-api description: Referência da API Moloni v2 para facturação portuguesa — autenticação, documentos, clientes e produtos. -layer: wiki --- # Moloni API v2 diff --git a/automacao/skills/n8n/SKILL.md b/automacao/skills/n8n/SKILL.md index 5e18f8f..a22cfe6 100644 --- a/automacao/skills/n8n/SKILL.md +++ b/automacao/skills/n8n/SKILL.md @@ -1,7 +1,6 @@ --- name: n8n description: Meta-skill n8n para criação e gestão de workflows na instância automator.descomplicar.pt. Cobre health check, webhooks, schedule (cron), sync de dados, notify (Slack/email/SMS) e chatbots/AI agents (LangChain/RAG). Triggers — n8n, workflow, automação, webhook, schedule, cron, sync, notify, alerta, slack, chatbot, ai agent, langchain, rag, automator, health check n8n. -layer: wiki --- # /n8n - Meta-skill n8n @@ -141,4 +140,131 @@ Upsert: { nodeType: "nodes-base.postgres", config: { operation: "upsert", table: "clientes", columns: "email,nome,empresa", conflictColumns: "email" } } ``` -Erros: retry (`{ options: { retry: { maxRetries: 3, retryInterval: 1000 } } }`), D \ No newline at end of file +Erros: retry (`{ options: { retry: { maxRetries: 3, retryInterval: 1000 } } }`), Dead Letter Queue (Error Trigger -> BD -> Slack). + +Exemplo CRM->Sheets: Schedule -> HTTP GET leads -> IF -> Set -> Google Sheets append -> Slack. + +Troubleshooting: duplicados (upsert), timeout (batches menores), rate limit (delays). + +--- + +## 5. Notify (alertas) + +``` +/n8n notify create +/n8n notify slack +/n8n notify email +``` + +Canais: Slack (`nodes-base.slack`), Email (`nodes-base.emailSend`), Telegram, Discord, SMS Twilio. + +Slack: +```js +mcp__n8n__validate_node({ + nodeType: "nodes-base.slack", + config: { resource: "message", operation: "post", channel: "#alertas", text: "..." }, + mode: "minimal" +}) +``` + +Mensagem formatada (Blocks): header + section com `mrkdwn` e `{{ $json.message }}`. + +Email: +```js +mcp__n8n__validate_node({ + nodeType: "nodes-base.emailSend", + config: { fromEmail: "alertas@descomplicar.pt", toEmail: "emanuel@descomplicar.pt", subject: "Alerta: {{ $json.title }}", text: "{{ $json.message }}" }, + mode: "minimal" +}) +``` + +Padrões: Webhook->Slack, Monitor->Multi-canal (Schedule -> HTTP -> IF -> Slack+Email), Error Handler (Error Trigger -> Slack). + +Níveis: Info (Slack), Warning (Slack+Email), Critical (Slack+Email+SMS) — implementar com IF aninhado por `severity`. + +Troubleshooting: Slack não envia (token/canal), email em spam (SPF/DKIM), rate limited (agrupar). + +--- + +## 6. Chatbot / AI Agents (LangChain) + +``` +/n8n chatbot create +/n8n chatbot agent +/n8n chatbot rag +``` + +### Nodes LangChain + +Core: `@n8n/n8n-nodes-langchain.agent`, `chainLlm`, `chainRetrievalQa`. +Modelos: `lmChatOpenAi`, `lmChatAnthropic`, `lmChatOllama`. +Memória: `memoryBufferWindow`, `memoryPostgresChat`, `memoryRedisChat`. +Tools: `toolCalculator`, `toolCode`, `toolHttpRequest`, `toolWorkflow`. +Vector Stores: `vectorStoreSupabase`, `vectorStorePinecone`, `vectorStorePgVector`. + +### Chatbot básico + +``` +Webhook -> LLM Chat -> Memory Buffer -> Agent -> Resposta +``` + +### RAG + +``` +Documentos -> Embeddings -> Vector Store -> Query -> Retriever -> LLM +``` + +```js +mcp__n8n__validate_node({ + nodeType: "@n8n/n8n-nodes-langchain.vectorStoreSupabase", + config: { mode: "insert", tableName: "documents", queryName: "match_documents" }, + mode: "minimal" +}) +``` + +### AI Agent com tools + +```js +mcp__n8n__validate_node({ + nodeType: "@n8n/n8n-nodes-langchain.agent", + config: { agentType: "conversationalAgent", systemMessage: "Tu és um assistente prestável...", options: { returnIntermediateSteps: true } }, + mode: "minimal" +}) +``` + +### Exemplos práticos + +- Suporte: Webhook -> Memory Postgres -> Vector Store -> Chain Retrieval QA -> Webhook Response. +- Agent CRM: Webhook -> Agent (tools: pesquisar/criar lead/actualizar tarefa) -> Slack. +- Resumo PDFs: Webhook -> PDF Extract -> Text Splitter -> LLM Chain -> Email. + +### Credenciais + +OpenAI/Anthropic (API Key), Supabase (URL+Key), Pinecone (API Key). + +### Boas práticas + +System prompt claro | temperatura 0.1-0.3 | memória limitada | retry on error | logs de conversas. + +### Troubleshooting + +Inconsistente (baixar temperatura), contexto perdido (memória), RAG vazio (embeddings), timeout (limite), token limit (resumir). + +--- + +## Templates + +```js +mcp__n8n__search_templates({ searchMode: "by_task", task: "ai_automation" }) +mcp__n8n__search_templates({ searchMode: "keyword", query: "chatbot langchain openai" }) +``` + +--- + +**Versão:** 2.0.0 (consolidação 6->1, 07-04-2026) | **Autor:** Descomplicar® + +## Healing Log + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` diff --git a/core-tools/skills/_core/SKILL.md b/core-tools/skills/_core/SKILL.md index 8f47b27..a5877dc 100644 --- a/core-tools/skills/_core/SKILL.md +++ b/core-tools/skills/_core/SKILL.md @@ -2,7 +2,6 @@ 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® @@ -63,7 +62,7 @@ Sempre pesquisar wiki CWP e skills `/cwp-*` antes de qualquer operação CWP. Ap **NUNCA simular quando dados reais existem.** Hierarquia: -1. MCPs especializados (desk-crm, dify-kb, wikijs) +1. MCPs especializados (desk-crm, dify-kb) 2. Sistemas internos (Gitea, Drive) 3. Documentação oficial (Context7) 4. Simulação APENAS se dados não existem @@ -76,16 +75,17 @@ Hierarquia: ``` 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 +1. IJFW (Tier 1) — automático via hooks (SessionStart/PostToolUse/Stop), nada a invocar +2. mcp__mem0__search_memories → Mem0 (Tier 2): experiência histórica cross-agent +3. /knowledge (router Hub QR/PROC) → Conhecimento curado do stack +4. 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) +🥇 1ª: Memória — IJFW Tier 1 (automático) + Mem0 Tier 2 (mcp__mem0__*) +🥈 2ª: MCPs especializados (dify-kb, desk-crm-v3) e de sistema (filesystem, google-workspace) 🥉 3ª: MCPs complementares (context7, puppeteer) 🔧 ÚLTIMO: Ferramentas nativas Claude ``` @@ -93,10 +93,16 @@ SEMPRE EXECUTAR PRIMEIRO: ### PASSO 3: Captura de Aprendizagem ``` -SEMPRE GUARDAR ao final: -mcp__mem_save_memory { - "text": "[área/projecto/tipo] [Resumo do trabalho e decisões]" -} +Factos duráveis (Tier 2, protocolo Wayland v2): +1. Dedup primeiro: mcp__mem0__search_memories +2. Guardar: mcp__mem0__save_memory + - P5 = identidade ("Emanuel | atributo | valor") + - P4 = procedimento ("COMO fazer X em Y: método Z") + - P3 = facto atómico (S|P|O, máx 80 chars) + - tier=global (cross-projecto) ou tier=project + - Tags: mínimo 2, kebab-case +Estado de sessão: NÃO guardar em Mem0 — é papel do IJFW (Tier 1, automático). +MEMORY.md pessoal de agente: deprecated. ``` --- diff --git a/core-tools/skills/agent-context-injector/SKILL.md b/core-tools/skills/agent-context-injector/SKILL.md index 70e2a20..9b70650 100644 --- a/core-tools/skills/agent-context-injector/SKILL.md +++ b/core-tools/skills/agent-context-injector/SKILL.md @@ -3,7 +3,6 @@ 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 diff --git a/core-tools/skills/component-generator/SKILL.md b/core-tools/skills/component-generator/SKILL.md index e3660cb..0d2bf90 100644 --- a/core-tools/skills/component-generator/SKILL.md +++ b/core-tools/skills/component-generator/SKILL.md @@ -3,7 +3,6 @@ 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 @@ -266,4 +265,32 @@ Após criação, invoca `quality-validator` para garantir score >= 70: 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 +1. [Cria directório skills/backup-manager/] +2. [Gera SKILL.md com template Descomplicar®] +3. [Valida: score 65/100 - Draft] +4. [Regista em cr_skills (id: 55)] +5. [Cria tarefa Desk #1503] +6. Resposta: "Skill backup-manager criada com sucesso! + - Path: skills/backup-manager/SKILL.md + - Score: 65/100 (Draft) + - Próximo passo: Editar e correr /descomplicar:validate" +``` + +## Limites + +- Apenas cria estrutura base - conteúdo deve ser desenvolvido +- Score inicial tipicamente 50-70 (Draft) +- Não cria componentes duplicados (verifica slug existente) +- Requer conexão MySQL para registo em cr_* +- Não modifica componentes existentes (usar Edit tool) +--- + +## 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/db-maintenance-manager/SKILL.md b/core-tools/skills/db-maintenance-manager/SKILL.md index 8d7aca9..933c416 100644 --- a/core-tools/skills/db-maintenance-manager/SKILL.md +++ b/core-tools/skills/db-maintenance-manager/SKILL.md @@ -3,7 +3,6 @@ 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 @@ -170,4 +169,106 @@ OPTIMIZE TABLE cr_agent_usage, cr_skill_usage, cr_mcp_tool_usage; ANALYZE TABLE cr_agents, cr_skills, cr_mcps, cr_agent_mcps; -- Verificar índices em falta -SE \ No newline at end of file +SELECT DISTINCT table_name, column_name +FROM information_schema.columns c +WHERE table_schema = DATABASE() + AND table_name LIKE 'cr_%' + AND column_name LIKE '%_id' + AND NOT EXISTS ( + SELECT 1 FROM information_schema.statistics s + WHERE s.table_schema = c.table_schema + AND s.table_name = c.table_name + AND s.column_name = c.column_name + ); +``` + +## Workflow + +``` +ANALISAR → BACKUP → EXECUTAR → VALIDAR → REPORTAR +``` + +1. **ANALISAR**: Identificar necessidades de manutenção +2. **BACKUP**: Criar backup antes de operações destrutivas +3. **EXECUTAR**: Correr operação com transação +4. **VALIDAR**: Verificar integridade pós-operação +5. **REPORTAR**: Registar em cr_maintenance_log + +## Integrações + +- **MCP**: desk-crm-v3 (operações MySQL) +- **Commands**: + - `/descomplicar:db-cleanup` - Limpeza de órfãos + - `/descomplicar:db-migrate` - Migração de schema + - `/descomplicar:db-backup` - Backup selectivo + - `/descomplicar:db-archive` - Archiving telemetria +- **Skills**: infrastructure-manager (detecção), quality-validator (validação) + +## Métricas de Sucesso + +| Métrica | Target | +|---------|--------| +| Órfãos | 0 | +| Telemetria activa | < 90 dias | +| Backup age | < 7 dias | +| Migrations pendentes | 0 | + +## Exemplo de Uso + +``` +User: A BD tem dados antigos e órfãos. Limpa tudo. + +DB Maintenance Manager: +1. [Analisa estado actual] + - Órfãos: 12 em cr_agent_mcps, 3 em cr_skill_mcps + - Telemetria: 45.000 registos > 90 dias + - Último backup: há 15 dias + +2. [Cria backup preventivo] + ✓ Backup criado: cr_backup_20260204_163000/ + +3. [Executa limpeza órfãos] + ✓ cr_agent_mcps: 12 órfãos removidos + ✓ cr_skill_mcps: 3 órfãos removidos + +4. [Executa archiving] + ✓ cr_agent_usage: 15.000 → archive + ✓ cr_skill_usage: 20.000 → archive + ✓ cr_mcp_tool_usage: 10.000 → archive + +5. [Valida resultado] + ✓ Integridade OK + ✓ 0 órfãos + ✓ Telemetria < 90 dias + +Resultado: +╔════════════════════════════════════════╗ +║ DB MAINTENANCE COMPLETE ║ +╠════════════════════════════════════════╣ +║ Órfãos removidos: 15 ║ +║ Registos arquivados: 45.000 ║ +║ Espaço libertado: ~12 MB ║ +║ Backup: ✓ Criado ║ +╚════════════════════════════════════════╝ +``` + +## Limites + +- Não executa operações destrutivas sem backup prévio +- Archiving mantém dados (move, não apaga) +- Migrations requerem aprovação manual +- Backup não inclui tabelas não-cr_* +- Optimização pode demorar em tabelas grandes (>1M registos) +- Não substitui backups gerais do Desk CRM + +--- + +## 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/infrastructure-manager/SKILL.md b/core-tools/skills/infrastructure-manager/SKILL.md index dab170c..8b7bdad 100644 --- a/core-tools/skills/infrastructure-manager/SKILL.md +++ b/core-tools/skills/infrastructure-manager/SKILL.md @@ -2,7 +2,6 @@ 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 @@ -162,4 +161,57 @@ DETECTAR → DIAGNOSTICAR → REPARAR → VALIDAR → REPORTAR - **MCPs**: desk-crm-v3, filesystem, mcp-time - **Commands**: - `/descomplicar:status` - Dashboard completo - - `/descomplicar:sy \ No newline at end of file + - `/descomplicar:sync` - Sincronização + - `/descomplicar:relationships` - Gestão relacionamentos + - `/descomplicar:telemetry` - Métricas de uso + - `/descomplicar:decision-trees` - Gestão decision trees + - `/descomplicar:lsps` - Gestão Language Server Protocols + +## Métricas de Sucesso + +| Métrica | Target | +|---------|--------| +| Health Score | >= 90 | +| Órfãos | 0 | +| Sync latency | < 5s | +| Telemetry coverage | 100% | + +## Exemplo de Uso + +``` +User: Qual o estado da infraestrutura? + +Infrastructure Manager: +1. [Verifica data/hora: 2026-02-04 16:00] +2. [Query entidades: 46 agents, 54 skills, 33 MCPs] +3. [Query relacionamentos: 800+ total, 0 órfãos] +4. [Calcula Health Score: 95/100] +5. Resposta: + "Health Score: 95/100 ████████████████████░ EXCELENTE + + Core: 46 agents ✓ | 54 skills ✓ | 33 MCPs ✓ + Relacionamentos: 800+ (0 órfãos) ✓ + Última sync: há 2h + + Alerta menor: MCP 'moloni' com latência 2.1s" +``` + +## Limites + +- Health Score é indicativo, não absoluto +- Sync pode demorar > 5s em bases de dados grandes +- Detecção de órfãos limitada a tabelas cr_* conhecidas +- Não corrige problemas automaticamente (apenas reporta) +- Telemetria depende de hooks activos e funcionais + +--- + +## 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/metrics/SKILL.md b/core-tools/skills/metrics/SKILL.md index f0542f2..29155e7 100644 --- a/core-tools/skills/metrics/SKILL.md +++ b/core-tools/skills/metrics/SKILL.md @@ -1,7 +1,6 @@ --- 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 @@ -181,4 +180,47 @@ if (degradation_pct > 15) { | Comando | Foco | Quando Usar | |---------|------|-------------| | `/taskforce kb-health` | Saude sistema KB | Visao arquitectural | -| `/metrics --kb` | Performance queries \ No newline at end of file +| `/metrics --kb` | Performance queries KB | Analise operacional | +| `/metrics --roi` | Valor economico gerado | Justificacao investimento | + +**Workflow recomendado:** +1. `/taskforce kb-health` - Verificar gaps e coverage +2. `/metrics --kb` - Analisar performance queries +3. `/metrics --roi` - Calcular ROI para stakeholders + +Link Desk CRM: `https://desk.descomplicar.pt/admin/projects/view/65` + +--- + +## Notas Tecnicas + +**Tabelas DB:** `tblskill_agent_metrics` (telemetria), `tblskill_agent_baselines` (baselines), `tblskill_agent_pdca_cycles` (PDCA historico) + +**Tools:** Implementados em `/opt/desk-crm-v3/src/tools/core/metrics.ts` + +**Fallback:** Se tools MCP nao disponiveis, usar queries SQL directas via `sql_direct`. + +--- + +## Conteudo Detalhado + +| Referencia | Conteudo | +|------------|----------| +| [references/sql-queries.md](references/sql-queries.md) | Queries SQL completas (top 10, ROI, trending) | +| [references/dashboards-templates.md](references/dashboards-templates.md) | Templates visuais KB, ROI, alertas, export, ASCII charts | + +--- + +**Desk CRM:** Projecto #65, Task #1637 + +--- + +## 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/plugin-curator/SKILL.md b/core-tools/skills/plugin-curator/SKILL.md index c63a8dd..f8d0ad7 100644 --- a/core-tools/skills/plugin-curator/SKILL.md +++ b/core-tools/skills/plugin-curator/SKILL.md @@ -2,7 +2,6 @@ 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 diff --git a/core-tools/skills/plugin-manager/SKILL.md b/core-tools/skills/plugin-manager/SKILL.md index 263a4b5..ef6b0ea 100644 --- a/core-tools/skills/plugin-manager/SKILL.md +++ b/core-tools/skills/plugin-manager/SKILL.md @@ -3,7 +3,6 @@ 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 @@ -153,4 +152,4 @@ Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de exe {"date":"","issue":"","fix":"","source":"user|auto"} ``` -*Adicionar nova linha ap \ No newline at end of file +*Adicionar nova linha após cada erro corrigido.* diff --git a/core-tools/skills/plugin-manager/profiles.json b/core-tools/skills/plugin-manager/profiles.json index 01a1c41..6d00754 100644 --- a/core-tools/skills/plugin-manager/profiles.json +++ b/core-tools/skills/plugin-manager/profiles.json @@ -27,7 +27,7 @@ "description": "Servidores, CWP, EasyPanel, Proxmox, SSL, DNS, Docker, backups servidor", "activate_when": { "files": ["docker-compose.yml", "Dockerfile", ".env.production"], - "directories": ["/root/Dev"], + "directories": ["/media/ealmeida/Dados/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"] } }, diff --git a/core-tools/skills/quality-validator/SKILL.md b/core-tools/skills/quality-validator/SKILL.md index f6d31ac..1f8e742 100644 --- a/core-tools/skills/quality-validator/SKILL.md +++ b/core-tools/skills/quality-validator/SKILL.md @@ -2,7 +2,6 @@ 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 @@ -141,4 +140,63 @@ score = (campos_obrigatorios * peso_obrigatorio) + (campos_opcionais * peso_opci - Score >= 70 para activar componente - Se < 70: AVISO + sugestões -### Gate 3: Re \ No newline at end of file +### Gate 3: Release +- Score >= 90 para todos os componentes +- Se algum < 90: BLOQUEAR release + +## Integração com Sync + +Durante `/descomplicar:sync`: +```sql +-- Verificar componentes com score baixo +SELECT c.slug, c.quality_score, c.status +FROM cr_skills c +WHERE c.quality_score < 70 AND c.status = 'active'; + +-- Marcar para revisão +UPDATE cr_skills +SET status = 'review_required' +WHERE quality_score < 70 AND status = 'active'; +``` + +## Workflow + +``` +READ COMPONENT → PARSE FRONTMATTER → CHECK SECTIONS → CALCULATE SCORE → REPORT + ↓ ↓ ↓ ↓ ↓ + File path YAML valid All present 0-100 Suggestions +``` + +## Exemplo de Uso + +``` +User: Valida a skill infrastructure-manager + +Quality Validator: +1. [Lê skills/infrastructure-manager/SKILL.md] +2. [Verifica frontmatter: 6/6 campos] +3. [Verifica secções: 4/5 presentes] +4. [Calcula score: 85/100] +5. Resultado: + "Score: 85/100 (BETA) + ✓ Pronto para uso + Sugestão: Adicionar secção 'Limites' para score 90+" +``` + +## Limites + +- Não modifica componentes (apenas lê e reporta) +- Não cria componentes (usar component-generator) +- Não executa correções automáticas (usar /descomplicar:upgrade) + +--- + +## 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/relationship-manager/SKILL.md b/core-tools/skills/relationship-manager/SKILL.md index 0eeac07..09cb5e7 100644 --- a/core-tools/skills/relationship-manager/SKILL.md +++ b/core-tools/skills/relationship-manager/SKILL.md @@ -2,7 +2,6 @@ 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 @@ -188,4 +187,51 @@ WHERE sm.mcp_id = (SELECT id FROM cr_mcps WHERE slug = ?); 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 +4. Actualizar decision trees +5. Log em telemetria + +## Métricas + +| Métrica | Descrição | +|---------|-----------| +| Densidade | Média de relacionamentos por componente | +| Cobertura | % de componentes com relacionamentos | +| Consistência | % de relacionamentos válidos | +| Conectividade | Componentes isolados vs conectados | + +## Exemplo de Uso + +``` +User: Configura o novo agente video-editor com os MCPs necessários + +Relationship Manager: +1. [Analisa agentes similares na categoria 'content'] +2. [Identifica MCPs comuns: filesystem, google-workspace, elevenlabs] +3. [Sugere relacionamentos:] + - PRIMARY: filesystem, elevenlabs + - RECOMMENDED: google-workspace, pexels, pixabay + - AVAILABLE: vimeo, youtube-uploader +4. [Cria mapeamentos em cr_agent_mcps] +5. [Sugere colaborações: content-manager, copywriter] +6. [Reporta: "Agente video-editor configurado com 7 MCPs e 2 colaborações"] +``` + +## Limites + +- Não cria componentes novos (apenas relacionamentos) +- Sugestões baseadas em padrões podem não ser 100% precisas +- Análise de impacto limitada a relacionamentos directos +- Não propaga alterações automaticamente (requer confirmação) +- Depende de consistência das tabelas cr_* na BD + +--- + +## 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/crm-ops/.claude-plugin/plugin.json b/crm-ops/.claude-plugin/plugin.json index fff727f..c1702ce 100644 --- a/crm-ops/.claude-plugin/plugin.json +++ b/crm-ops/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "crm-ops", "description": "CRM operations, sales management, leads, customers, estimates, invoices, tickets and expense tracking with Desk CRM. Backed by NotebookLM notebooks.", - "version": "1.2.0", + "version": "1.3.1", "author": { "name": "Descomplicar - Crescimento Digital", "url": "https://descomplicar.pt" diff --git a/crm-ops/CHANGELOG.md b/crm-ops/CHANGELOG.md index 309cad2..567c5d0 100644 --- a/crm-ops/CHANGELOG.md +++ b/crm-ops/CHANGELOG.md @@ -1,5 +1,16 @@ # CHANGELOG — crm-ops +## 1.3.1 — 2026-10-17 +### Corrigido +- `estrategia-marca/references/metodologia-acida.md`: ACIDA = Atrair, Construir confiança, Interesse, Decisão, Ação (decisão do Emanuel). A tabela "ACIDA 2.0 — Fases operacionais" (Análise, Criação, Implementação, Desenvolvimento, Acompanhamento) passa a "Ciclo de projeto (orientado pela ACIDA)". + +## 1.3.0 — 2026-10-17 +### Alterado +- `estrategia-marca`: alinhada com a SPEC de Estratégia de Marca v2.0 (níveis Essencial, Standard e Completo; estrutura completa de 36 capítulos com todos os elementos das estratégias já entregues; BRIEFING-LLM e validador obrigatórios na entrega). +- Fundida a antiga `marketing:brand-strategy` (rondas de briefing, níveis, erros a evitar, exemplo de persona com 20 dimensões). +### Adicionado +- `references/estrutura-completa.md`, `references/prompt-redacao-parte.md` (redação em paralelo por parte), `scripts/montar.py` (montagem + anexo de pontos a validar), `scripts/render_pdf.py` (PDF A4 com a identidade da marca), `assets/marca-descomplicar.json`. + ## 0.1.0 — 2026-06-30 ### Adicionado - Estrutura padrão (PROC-DEV-STANDARD) diff --git a/crm-ops/agents/budget-proposal-specialist.md b/crm-ops/agents/budget-proposal-specialist.md index 4590f1a..f4a88b2 100644 --- a/crm-ops/agents/budget-proposal-specialist.md +++ b/crm-ops/agents/budget-proposal-specialist.md @@ -7,6 +7,8 @@ model: sonnet tools: Read, Write, Edit, Glob, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 - google-workspace @@ -46,7 +48,6 @@ escalates_to: created: "2025-01-13" updated: "2026-02-04" author: "Descomplicar®" -layer: wiki --- # Budget Proposal Specialist Descomplicar @@ -172,4 +173,65 @@ Você é um especialista comercial responsável por: ## Knowledge Sources (Consultar SEMPRE) -### NotebookLM (Primario - usar PRIMEIR \ No newline at end of file +### NotebookLM (Primario - usar PRIMEIRO) + +``` +mcp__notebooklm__notebook_query notebook_id:"76647e0f-3ae2-4c00-a0a8-f457aebf5655" query:"orcamento proposta pricing" +mcp__notebooklm__notebook_query notebook_id:"0c9c079c-a426-486c-99eb-1564d42d37ad" query:"projectos estimativa custos" +mcp__notebooklm__notebook_query notebook_id:"5be0d1a6-00f2-4cd9-b835-978cb7721601" query:"desenvolvimento custos" +``` + +## Your Available MCPs + +### Recommended for business +- **desk-crm-v3** - Clientes, projectos, facturas, time tracking +- **moloni** - Facturação +- **google-workspace** - Email, calendário, docs, drive +- **imap** - Email IMAP +- **mem0** - Mem0 (Tier 2, `mcp__mem0__*`) + IJFW (Tier 1, automático via hooks) +- **** - Knowledge base AI +- **outline-api** - Outline documentation + +### All Available (32 total) +context7, gitea, n8n, cwp, filesystem, ssh-unified, google-analytics, youtube-research, youtube-uploader, gsc, lighthouse, mcp-time, puppeteer, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, magic, vimeo, design-systems, replicate + +**Discovery:** Use ToolSearch to find specific tools. +**Example:** `ToolSearch("ssh upload")` finds SSH upload tools. +## Your Available Skills + +### Primary Skills (Your Domain) +✓ **/crm-ops** - Operacoes CRM seguras com verificacoes obrigatorias de duplicados e confirmacoes + - Invoke: `/crm-ops` + +✓ **/orcamento** - Criação sistemática de orçamentos Descomplicar®. Usar quando o utilizador pedir + - Invoke: `/orcamento` + +✓ **/billing-check** - Comparação de horas trabalhadas (Desk CRM) vs horas facturadas (Moloni). Identif + - Invoke: `/billing-check` + +✓ **/lead-approach** - Abordagem estratégica de leads - análise, estratégia e primeiro contacto. Usar q + - Invoke: `/lead-approach` + +### Recommended for business +- **/ecommerce** - Estratégia e arquitectura e-commerce - funil conversão, plat +- **/saas** - Arquitectura e desenvolvimento SaaS - multi-tenant, billing, +- **/product** - Gestão de produto e planeamento features - discovery, RICE p +- **/time** - Time tracking integrado com Desk CRM. Inicia e para timers e + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/content-marketing-pt, /remotion-video, /seo-content-optimization, /social-media, /video, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /crm-admin, /db-design, /elementor, /mcp-dev, /nextjs, /php-dev, /react-patterns, /woocommerce, /wp-dev, /backup-strategies, /security-audit, /server-health, /wp-performance, /wp-update, /second-brain-repo, /ads, /doc-sync, /marketing-strategy, /skill-creator, /sop-creator, /calendar-manager, /delegate, /interview, /today, /research, /youtube, /seo-audit, /seo-report, /archive, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. +## Colaboração + +- **Reports to**: Sales Manager +- **Colabora com**: Project Manager, Development Lead, Marketing Planning Expert, Finance Manager +- **Escalar para**: Sales Manager (decisões pricing fora tabela), Project Manager (validar prazos) diff --git a/crm-ops/agents/lead-approach-strategist.md b/crm-ops/agents/lead-approach-strategist.md index 97c874b..6571586 100644 --- a/crm-ops/agents/lead-approach-strategist.md +++ b/crm-ops/agents/lead-approach-strategist.md @@ -9,6 +9,8 @@ model: sonnet tools: Read, Write, Edit, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 - google-workspace @@ -36,7 +38,6 @@ compliance: created: '2025-01-13' updated: '2026-02-04' author: Descomplicar® -layer: wiki --- # Lead Approach Strategist Descomplicar @@ -167,7 +168,7 @@ Estrategista comercial especializado em análise de leads e criação de abordag ✓ **mem0** (system) - Memória longo prazo - - Usage: `mcp__mem_*` + - Usage: `mcp__mem0__*` ### Recommended for marketing - **google-workspace** - Email, calendário, docs, drive @@ -176,4 +177,45 @@ Estrategista comercial especializado em análise de leads e criação de abordag - **youtube-uploader** - Upload vídeos YouTube - **pixabay** - Pesquisa imagens e vídeos stock gratuitos - **pexels** - Pesquisa imagens stock de alta qualidade -- **tavily** - AI-powered search API \ No newline at end of file +- **tavily** - AI-powered search API - web search optimizado para LLMs +- **elevenlabs** - Text-to-speech, voice cloning, audio transcription +- **vimeo** - Video management - upload, metadata, transcripts, analytics +- **replicate** - AI models - imagem, vídeo, áudio, LLMs + +### All Available (32 total) +moloni, context7, gitea, n8n, cwp, filesystem, ssh-unified, imap, outline-api, gsc, lighthouse, mcp-time, puppeteer, mcp-mermaid, mcp-echarts, powerpoint, penpot, magic, design-systems + +**Discovery:** Use ToolSearch to find specific tools. +**Example:** `ToolSearch("ssh upload")` finds SSH upload tools. +## Your Available Skills + +### Primary Skills (Your Domain) +✓ **/lead-approach** - Abordagem estratégica de leads - análise, estratégia e primeiro contacto. Usar q + - Invoke: `/lead-approach` + +✓ **/marketing-strategy** - Estratégia de marketing digital integrada - análise mercado, posicionamento, mix + - Invoke: `/marketing-strategy` + +✓ **/ads** - Gestão de campanhas de publicidade paga (PPC) - Google Ads, Meta Ads, LinkedIn A + - Invoke: `/ads` + +### Recommended for marketing +- **/social-media** - Gestão e estratégia de redes sociais - Instagram, LinkedIn, +- **/content-marketing-pt** - Criação de conteúdo marketing em Português Europeu. Tom de v +- **/seo-content-optimization** - Optimização SEO técnico e conteúdo - meta tags, structured d +- **/youtube** - Extrair transcrições e metadados do YouTube + Estratégia cre +- **/research** - Pesquisa profunda e análise competitiva - SWOT, Porter's Fiv + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /orcamento, /saas, /remotion-video, /video, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /crm-admin, /db-design, /elementor, /mcp-dev, /nextjs, /php-dev, /react-patterns, /woocommerce, /wp-dev, /backup-strategies, /security-audit, /server-health, /wp-performance, /wp-update, /second-brain-repo, /doc-sync, /product, /skill-creator, /sop-creator, /calendar-manager, /delegate, /interview, /time, /today, /seo-audit, /seo-report, /archive, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. + diff --git a/crm-ops/agents/lead-qualifier.md b/crm-ops/agents/lead-qualifier.md index 78315cc..406d4bf 100644 --- a/crm-ops/agents/lead-qualifier.md +++ b/crm-ops/agents/lead-qualifier.md @@ -9,6 +9,8 @@ model: sonnet tools: Read, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 recommended_mcps: @@ -35,7 +37,6 @@ compliance: created: '2025-01-13' updated: '2026-02-04' author: Descomplicar® -layer: wiki --- # Lead Qualifier Descomplicar @@ -131,7 +132,7 @@ Avalia e prioriza leads inbound, garantindo que a equipa de vendas se foca em pr ✓ **mem0** (system) - Memória longo prazo - - Usage: `mcp__mem_*` + - Usage: `mcp__mem0__*` ### Recommended for business - **moloni** - Facturação @@ -140,7 +141,7 @@ Avalia e prioriza leads inbound, garantindo que a equipa de vendas se foca em pr - **outline-api** - Outline documentation ### All Available (32 total) -context7, gitea, n8n, cwp, filesystem, ssh-unified, google-analytics, youtube-research, youtube-uploader, wikijs, gsc, lighthouse, mcp-time, puppeteer, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, magic, vimeo, design-systems, replicate +context7, gitea, n8n, cwp, filesystem, ssh-unified, google-analytics, youtube-research, youtube-uploader, gsc, lighthouse, mcp-time, puppeteer, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, magic, vimeo, design-systems, replicate **Discovery:** Use ToolSearch to find specific tools. **Example:** `ToolSearch("ssh upload")` finds SSH upload tools. @@ -151,4 +152,52 @@ context7, gitea, n8n, cwp, filesystem, ssh-unified, google-analytics, youtube-re - Invoke: `/crm-ops` ✓ **/orcamento** - Criação sistemática de orçamentos Descomplicar®. Usar quando o utilizador pedir - - Invoke: \ No newline at end of file + - Invoke: `/orcamento` + +✓ **/billing-check** - Comparação de horas trabalhadas (Desk CRM) vs horas facturadas (Moloni). Identif + - Invoke: `/billing-check` + +✓ **/lead-approach** - Abordagem estratégica de leads - análise, estratégia e primeiro contacto. Usar q + - Invoke: `/lead-approach` + +### Recommended for business +- **/ecommerce** - Estratégia e arquitectura e-commerce - funil conversão, plat +- **/saas** - Arquitectura e desenvolvimento SaaS - multi-tenant, billing, +- **/product** - Gestão de produto e planeamento features - discovery, RICE p +- **/time** - Time tracking integrado com Desk CRM. Inicia e para timers e + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/content-marketing-pt, /remotion-video, /seo-content-optimization, /social-media, /video, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /crm-admin, /db-design, /elementor, /mcp-dev, /nextjs, /php-dev, /react-patterns, /woocommerce, /wp-dev, /backup-strategies, /security-audit, /server-health, /wp-performance, /wp-update, /second-brain-repo, /ads, /doc-sync, /marketing-strategy, /skill-creator, /sop-creator, /calendar-manager, /delegate, /interview, /today, /research, /youtube, /seo-audit, /seo-report, /archive, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. +## Your Team & Responsibilities + +You are part of **3 SDKs** (TaskForce teams): + +### TaskForce Claude Agents + +**Purpose:** NULL + +**Your responsibilities in this TaskForce:** +### TaskForce Marketing Estratégico + +**Purpose:** NULL + +### TaskForce Vendas + +**Purpose:** NULL + +**Collaboration:** +- Work with other agents in your TaskForce teams +- Share knowledge and context across team members +- Leverage team-specific skills and MCPs +- Contribute to team goals and deliverables + diff --git a/crm-ops/agents/sales-manager.md b/crm-ops/agents/sales-manager.md index e24f6e4..02ed324 100644 --- a/crm-ops/agents/sales-manager.md +++ b/crm-ops/agents/sales-manager.md @@ -18,13 +18,15 @@ user_invocable: true tier: 1 # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 # Business operations - google-workspace # Docs, Sheets, proposals recommended_mcps: - moloni # Invoicing - imap # Email management - - mem0 # Long-term memory + - mem0 # Memória longo prazo (Tier 2) via Mem0 - outline-api # Documentation primary_skills: @@ -68,7 +70,6 @@ collaborations: created: 2026-02-04 last_updated: 2026-02-04 quality_score: 85 -layer: wiki --- # Sales Manager Descomplicar diff --git a/crm-ops/agents/support-specialist.md b/crm-ops/agents/support-specialist.md index 1749187..bdad392 100644 --- a/crm-ops/agents/support-specialist.md +++ b/crm-ops/agents/support-specialist.md @@ -10,6 +10,8 @@ domain: Support, CRM model: sonnet tools: Read, Glob, Grep, ToolSearch +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 recommended_mcps: @@ -51,7 +53,6 @@ escalates_to: created: "2026-04-07" updated: "2026-04-07" author: "Descomplicar®" -layer: wiki --- # Support Specialist Descomplicar @@ -156,4 +157,30 @@ Você é o especialista de suporte D2 da Descomplicar®. A sua missão é garant ### Referências PROCs (Consultar SEMPRE) ``` Read: /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D2-Suporte/PROC-D2-SUP-001-Atendimento-Cliente.md -Read: /media/ealmeida/Dados/Hub/06-Operacoes/Procedimento \ No newline at end of file +Read: /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D2-Suporte/PROC-D2-SUP-002-Ticketing-Workflow.md +Read: /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D2-Suporte/PROC-D2-SUP-003-SLA-Management.md +``` + +### Desk CRM (Dados Reais) +``` +mcp__desk-crm-v3__get_tickets({ status: [1,2,3] }) +mcp__desk-crm-v3__get_ticket({ ticket_id: id }) +mcp__desk-crm-v3__reply_ticket({ ticket_id: id, message: html, internal: false }) +mcp__desk-crm-v3__close_ticket({ ticket_id: id }) +``` + +## Métricas de Sucesso + +| Métrica | Meta | +|---------|------| +| SLA resposta cumprido | >95% | +| SLA resolução cumprido | >90% | +| Resolução 1º contacto | >60% | +| NPS médio | >8/10 | +| Tickets P1 violados | 0/semana | + +## Colaboração + +- **Reporta a**: Emanuel Almeida +- **Colabora com**: sales-manager (tickets pós-venda), lead-qualifier (clientes novos) +- **Escalar para**: Emanuel (P1 crítico, SLA violado), D7 Tecnologia (tech complexo) diff --git a/crm-ops/skills/auto-expense/SKILL.md b/crm-ops/skills/auto-expense/SKILL.md index 0836b9d..250b6ef 100644 --- a/crm-ops/skills/auto-expense/SKILL.md +++ b/crm-ops/skills/auto-expense/SKILL.md @@ -2,7 +2,6 @@ name: auto-expense description: Criação automática de despesas a partir de facturas detectadas no IMAP e tickets. Extrai dados, verifica duplicados por reference_no e cria despesas no Desk CRM com PDF anexo. disable-model-invocation: true -layer: wiki --- # /auto-expense v1.1 @@ -143,4 +142,96 @@ Formato linha: id_desk;data;categoria;fornecedor;descricao;valor;SIM;ficheiro;em Escrever em ~/.claude-work/today-expenses-{date}.json: { "despesas_criadas": [ - {"id": 1180, "fornecedor": "MEO", "valor": 76.26, "moeda": "EUR", "referencia": "FT A/8 \ No newline at end of file + {"id": 1180, "fornecedor": "MEO", "valor": 76.26, "moeda": "EUR", "referencia": "FT A/861215955"} + ], + "duplicados": [ + {"fornecedor": "MEO", "referencia": "FT A/861215955", "existente_id": 1175, "camada": 0} + ], + "flagged": [ + {"fornecedor": "Desconhecido", "nota": "TOConline - emitente desconhecido: XPTO LDA"} + ], + "erros": [], + "total_processadas": 1, + "total_duplicados": 0 +} +``` + +--- + +## Plataformas Multi-Fornecedor - Padroes de Extracao + +> Ver tabela completa em: Hub/06-Operacoes/Documentacao/fornecedores-recorrentes.md + +| Plataforma | Padrao no Subject/HTML | +|-----------|----------------------| +| TOConline | "Emitido por:", "Emitente:" no HTML | +| Stripe | "Receipt from [Empresa]" ou "Your receipt from [Empresa]" no subject | +| PayPal | "You paid [Empresa]" no subject | +| FastSpring | "Order from [Empresa]" no subject/corpo | +| PayPro Global | Nome produto/empresa no corpo | + +--- + +## Campos Criticos Desk CRM + +``` +currency = 3 (EUR) → Fornecedores EUR +currency = 2 (USD) → Fornecedores USD (manter valor original, NAO converter) +currency = 1 → NAO EXISTE - causa despesas invisiveis + +tax = 1 → Fornecedores PT (MEO, Moloni, PTisp, Staples) +tax = 0 → Fornecedores estrangeiros + +send_invoice_to_customer = 0 → OBRIGATORIO (sem default na BD) + +reference_no → coluna correcta (NAO "reference") — CHAVE DE DEDUPLICACAO +``` + +--- + +## Output Standalone + +```markdown +## Auto-Despesas - DD-MM-YYYY + +### Despesas Criadas (X) +| # Desk | Fornecedor | Valor | Moeda | Ref | PDF | +|--------|-----------|-------|-------|-----|-----| + +### Duplicados Detectados (Y) +| Fornecedor | Ref | ID Existente | Camada | +|-----------|-----|-------------|--------| + +### Pendentes Revisao (Z) +- [Plataforma] - emitente desconhecido: [nome] +``` + +--- + +## Anti-Patterns + +- NUNCA usar currency=1 (nao existe) +- NUNCA converter USD para EUR (manter original com currency=2) +- NUNCA criar despesa sem verificar duplicado primeiro (3 camadas obrigatorias) +- NUNCA omitir send_invoice_to_customer=0 +- NUNCA omitir reference_no ao criar despesa (chave primaria de dedup) +- NUNCA saltar a Camada 0 (referencia de factura) — e a mais fiavel +- SEMPRE ler o email/ticket HTML para extrair valor real (nunca assumir) +- SEMPRE incluir reference_no quando disponivel +- SEMPRE logar duplicados detectados no output JSON com camada e ID existente + +--- + +*Skill v1.1.0 | 30-03-2026 | Descomplicar | Fix: dedup por reference_no (DES-137)* + +--- + +## 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/crm-ops/skills/billing-check/SKILL.md b/crm-ops/skills/billing-check/SKILL.md index d2ce1ae..a51704e 100644 --- a/crm-ops/skills/billing-check/SKILL.md +++ b/crm-ops/skills/billing-check/SKILL.md @@ -1,7 +1,6 @@ --- name: billing-check description: Verificação de facturação e validação de facturas. Sincroniza facturas Moloni com horas Desk CRM para projectos 360, compara horas facturadas vs entregues e calcula saldos. -layer: wiki --- # Billing Check - Desk vs Moloni (v2.0) @@ -224,4 +223,85 @@ ToolSearch: "+desk timesheets" ### v1.0.0 (2026-01-27) - Versão inicial -- Documentação de mapeamento Desk ↔ \ No newline at end of file +- Documentação de mapeamento Desk ↔ Moloni + +--- + +**Dashboard:** https://plan-eal.descomplicar.pt +**Versão**: 2.0.0 | **Autor**: Descomplicar® + +--- + + +## Quando NÃO Usar + +- Para tarefas fora do domínio de especialização desta skill +- Quando outra skill mais específica está disponível +- Para operações que requerem aprovação manual obrigatória +- Quando os requisitos não estão claramente definidos + + +## Protocolo de Execução + +1. **Análise Inicial** + - Verificar requisitos e contexto + - Identificar ferramentas necessárias + +2. **Preparação** + - Validar acesso a recursos + - Preparar ambiente de trabalho + +3. **Execução** + - Executar operações de forma incremental + - Validar cada passo antes de prosseguir + +4. **Validação** + - Verificar resultados obtidos + - Confirmar sucesso da operação + +5. **Conclusão** + - Documentar alterações realizadas + - Reportar status final e próximos passos + + +## Exemplos de Uso + +### Exemplo 1: Caso Básico +``` +User: [requisição simples relacionada com billing-check] +Skill: [execução directa com validação] +Output: [resultado conciso e accionável] +``` + +### Exemplo 2: Caso Complexo +``` +User: [requisição multi-passo ou complexa] +Skill: + 1. Análise dos requisitos + 2. Planeamento da abordagem + 3. Execução faseada + 4. Validação contínua +Output: [resultado detalhado com próximos passos] +``` + +### Exemplo 3: Caso com Dependências +``` +User: [requisição que depende de outros sistemas] +Skill: + 1. Verificar dependências disponíveis + 2. Coordenar com skills/MCPs necessários + 3. Executar workflow integrado +Output: [resultado completo com referências] +``` + +--- + +## 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/crm-ops/skills/crm-admin/SKILL.md b/crm-ops/skills/crm-admin/SKILL.md index d8dc663..b7ca7c1 100644 --- a/crm-ops/skills/crm-admin/SKILL.md +++ b/crm-ops/skills/crm-admin/SKILL.md @@ -2,7 +2,6 @@ name: crm-admin description: Administração e manutenção do Desk CRM. Gestão de utilizadores, permissões, campos personalizados, configuração de sistema e módulos Perfex. disable-model-invocation: true -layer: wiki --- # CRM Admin Specialist @@ -23,8 +22,8 @@ Skill para gestão e desenvolvimento Perfex CRM seguindo padrões Descomplicar® Antes de qualquer operação, usar MCPs: ``` mcp__desk-crm-v3__get_customers - verificar dados existentes -mcp__mem_search_memories "[contexto crm]" -mcp__wikijs__search_pages "perfex crm [funcionalidade]" +mcp__mem0__search_memories "[contexto crm]" +/knowledge (router Hub QR/PROC) + mcp__mem0__search_memories "perfex crm [funcionalidade]" ``` ### 2. Dados Reais Obrigatórios @@ -155,4 +154,84 @@ mcp__dify-kb__dify_kb_retrieve_segments({ ### Quando Consultar - Desenvolver módulos Perfex CRM -- Configurar automações de \ No newline at end of file +- Configurar automações de vendas +- Optimizar processos de facturação +- Implementar workflows de gestão de clientes + +--- +**Versão**: 1.0.0 | **Autor**: Descomplicar® + +--- + +## Instrumentação Automática + +Esta skill grava métricas automaticamente para análise PDCA. + +### Query para Gravar (executar no final) + +```sql +INSERT INTO tblskill_agent_metrics ( + type, name, duration_ms, status, staff_id, + kb_consulted, kb_cache_hit, tool_calls, project_id +) VALUES ( + 'skill', '/$SKILL_NAME', {DURACAO_MS}, '{STATUS}', 25, + {KB_CONSULTADO}, {CACHE_HIT}, {TOOL_CALLS}, {PROJECT_ID} +); +``` + +--- + +**Instrumentação**: Activa | **Data**: 2026-02-03 + +--- + + +## Quando NÃO Usar + +- Para tarefas fora do domínio de especialização desta skill +- Quando outra skill mais específica está disponível +- Para operações que requerem aprovação manual obrigatória +- Quando os requisitos não estão claramente definidos + + +## Exemplos de Uso + +### Exemplo 1: Caso Básico +``` +User: [requisição simples relacionada com crm-admin] +Skill: [execução directa com validação] +Output: [resultado conciso e accionável] +``` + +### Exemplo 2: Caso Complexo +``` +User: [requisição multi-passo ou complexa] +Skill: + 1. Análise dos requisitos + 2. Planeamento da abordagem + 3. Execução faseada + 4. Validação contínua +Output: [resultado detalhado com próximos passos] +``` + +### Exemplo 3: Caso com Dependências +``` +User: [requisição que depende de outros sistemas] +Skill: + 1. Verificar dependências disponíveis + 2. Coordenar com skills/MCPs necessários + 3. Executar workflow integrado +Output: [resultado completo com referências] +``` + +--- + +## 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/crm-ops/skills/crm/SKILL.md b/crm-ops/skills/crm/SKILL.md index 3d21ba1..1d90544 100644 --- a/crm-ops/skills/crm/SKILL.md +++ b/crm-ops/skills/crm/SKILL.md @@ -1,7 +1,6 @@ --- name: crm description: Operações CRM unificadas. Leads, customers, proposals, estimates e visão 360 do cliente. Consolida crm-ops e crm-admin com verificação obrigatória de duplicados. -layer: wiki --- # /crm v2.0 - Operações CRM Unificadas @@ -221,4 +220,110 @@ Integrar insights do NotebookLM nas recomendações e decisões. ### 💰 Financeiro | Métrica | Valor | |---------|-------| -| Total facturado | € \ No newline at end of file +| Total facturado | €15.000 | +| Pagamentos | €12.000 | +| Em aberto | €3.000 | + +### 🎫 Suporte +- Tickets abertos: 1 +- Tickets total (12m): 8 +- Tempo resposta médio: 4h + +### 📝 Notas Recentes +- [2026-02-01] Reunião marcada para dia 10 +- [2026-01-15] Preferem comunicação por email +``` + +--- + +## Status Codes + +### Leads +| ID | Status | +|----|--------| +| 1 | Novo | +| 2 | Contactado | +| 3 | Qualificado | +| 4 | Proposta | +| 5 | Ganho (→ Customer) | +| 6 | Perdido | + +### Estimates +| ID | Status | +|----|--------| +| 1 | Rascunho | +| 2 | Enviado | +| 3 | Visto | +| 4 | Aceite | +| 5 | Recusado | + +### Proposals +| ID | Status | +|----|--------| +| 1 | Draft | +| 2 | Sent | +| 3 | Open | +| 6 | Accepted | + +--- + +## Staff IDs + +| ID | Nome | Usar | +|----|------|------| +| 25 | AikTop | **Default** - automático | +| 1 | Emanuel | Comunicação cliente | + +--- + +## Anti-Patterns (NUNCA) + +1. **NUNCA** criar lead sem verificar duplicados +2. **NUNCA** criar customer sem confirmação explícita +3. **NUNCA** criar customer automaticamente para estimate +4. **NUNCA** usar estimate para leads (usar proposal) +5. **NUNCA** converter estimate não-aceite para invoice + +--- + +## Migração + +Skills descontinuadas: +- `/crm-ops` → migrar para `/crm` +- `/crm-admin` → comandos admin em `/crm` + +--- + +## Changelog + +### v2.0.0 (2026-02-05) +- Consolidar crm-ops + crm-admin +- Novo comando /crm 360 para visão cliente +- Todos os subcomandos unificados +- Anti-duplicados reforçado + +### v1.2.0 (crm-ops) +- Distinção Lead vs Customer +- Proposal vs Estimate + + + +--- + +## Self-Healing + +Antes de executar, ler `~/.claude-work/healing/crm.jsonl` (se existir). Cada linha é um padrão de erro conhecido: + +```json +{"date":"YYYY-MM-DD","issue":"descrição do problema","fix":"como evitar","source":"user|auto"} +``` + +Se encontrares um padrão relevante ao contexto actual, aplica o fix preventivamente. Após cada erro ou correcção do utilizador nesta skill, **adicionar nova linha** ao healing log com o padrão aprendido. + +--- + +*Skill v2.0.0 | 2026-02-05 | Descomplicar®* + + +## Healing Log + diff --git a/crm-ops/skills/desk/SKILL.md b/crm-ops/skills/desk/SKILL.md index f8a2cf4..6010ef0 100644 --- a/crm-ops/skills/desk/SKILL.md +++ b/crm-ops/skills/desk/SKILL.md @@ -1,7 +1,6 @@ --- name: desk description: Contexto de projecto via .desk-project. Auto-detecção, integração com /time, status rápido, criação de tarefas e changelog. Sistema Triângulo Desk-GDrive-Local. -layer: wiki --- # /desk v3.0 - Contexto de Projecto @@ -229,4 +228,31 @@ Ao entrar numa pasta: - Mostrar timer activo no contexto - Sync bidirecional .desk-project -### v \ No newline at end of file +### v2.0.0 (2026-01-27) +- Sistema Triângulo implementado +- Auto-detecção .desk-project + +### v1.0.0 +- Versão inicial + + + +--- + +## Self-Healing + +Antes de executar, ler `~/.claude-work/healing/desk.jsonl` (se existir). Cada linha é um padrão de erro conhecido: + +```json +{"date":"YYYY-MM-DD","issue":"descrição do problema","fix":"como evitar","source":"user|auto"} +``` + +Se encontrares um padrão relevante ao contexto actual, aplica o fix preventivamente. Após cada erro ou correcção do utilizador nesta skill, **adicionar nova linha** ao healing log com o padrão aprendido. + +--- + +*Skill v3.0.0 | 2026-02-05 | Descomplicar®* + + +## Healing Log + diff --git a/crm-ops/skills/estrategia-marca/SKILL.md b/crm-ops/skills/estrategia-marca/SKILL.md index ff1e2dc..a663f89 100644 --- a/crm-ops/skills/estrategia-marca/SKILL.md +++ b/crm-ops/skills/estrategia-marca/SKILL.md @@ -1,115 +1,177 @@ --- name: estrategia-marca -description: Cria estratégias de marca completas seguindo a metodologia Descomplicar® (ACIDA + Framework 16Ps). Inclui fase de pesquisa de mercado com /deep-research antes do briefing. Guia a análise de público, posicionamento, Pitch Canvas, copywriting e documento final entregável. Usar quando o utilizador diz "estratégia de marca", "branding", "criar marca", "posicionamento", "16Ps", "/estrategia-marca", "análise de público", "narrativa de marca", "proposta de valor", "pitch canvas", "pain + gain", "copywriting estratégico", "identidade de marca", "pesquisa de mercado para marca", ou quando um cliente adquire o serviço EST-MRK-010. -layer: wiki +description: Cria estratégias de marca Descomplicar® (EST-MRK-010) conforme a SPEC v2.0 (16Ps 2026, 40Ps em projetos complexos, ≥5 nichos, 20 pontos por segmento, identidade visual da marca, bloco BRIEFING-LLM) em três níveis, Essencial, Standard e Completo, do briefing ao PDF A4 validado. A versão completa (36 capítulos) junta todos os elementos de todas as estratégias já entregues. Usar quando o utilizador diz "estratégia de marca", "brand strategy", "branding", "criar marca", "posicionamento", "16Ps", "40Ps", "/estrategia-marca", "análise de público", "personas", "segmentação", "narrativa de marca", "proposta de valor", "pitch canvas", "pain + gain", "copywriting estratégico", "tom de voz", "identidade de marca", "manifesto", "versão completa da estratégia", ou quando um cliente adquire o serviço EST-MRK-010. --- # Skill: Estratégia de Marca -Guia completo para criar estratégias de marca Descomplicar® — da pesquisa de mercado ao documento final entregável. +Da pesquisa ao documento final validado e em PDF. Substitui a antiga skill +`marketing:brand-strategy` (fundida aqui a 17-10-2026). ---- +## Fonte de verdade (ler antes de escrever) -## Fluxo de trabalho (8 fases) +Standard canónico em `Cloud/Descomplicar/ACIDA/Estrategia-de-Marca/` +(caminho local: `/media/ealmeida/Dados/Cloud/Descomplicar/ACIDA/Estrategia-de-Marca/`): -### Fase 0 — Pesquisa de mercado +| Ficheiro | Para quê | +|---|---| +| `SPEC-Estrategia-de-Marca.md` (v2.0) | Decisões canónicas, níveis, critérios de completude | +| `PROC-Estrategia-de-Marca.md` (v2.0) | Fases, gates, responsáveis | +| `CONTRATO-OUTPUT-LLM.md` | Esquema do bloco `## BRIEFING-LLM` | +| `golden-example-briefing-llm.md` | Bloco BRIEFING-LLM preenchido (Descomplicar®) | +| `validador-estrategia-marca.mjs` | Gate final: `node validador-estrategia-marca.mjs [--completo]` | -Antes do briefing com o cliente, fazer pesquisa independente. Verificar primeiro se já existem ficheiros de pesquisa (ex: pasta `Pesquisas/` no projecto). +Esta skill implementa o PROC. Se algo aqui contradisser a SPEC, prevalece a SPEC. -**Se a pesquisa já existe:** ler os ficheiros relevantes e extrair síntese. +Decisões que não se regridem (SPEC §1): 16Ps com a numeração de 2026 como base; +40Ps só em projetos complexos; ≥5 nichos reais e 20 pontos por segmento; +paleta é sempre a da marca em causa (nunca a da Descomplicar® num cliente); +`## BRIEFING-LLM` como última secção; PT-PT estrito; nada inventado, o que +faltar fica `[a validar: …]` e vai para o anexo A. -**Se não existe:** usar `/deep-research` (ou `mcp__tavily__tavily_research`) com os seguintes focos: +## Níveis -1. **Mercado/sector** — dimensão, crescimento, tendências, regulação -2. **Concorrentes** — posicionamento, mensagens, pricing, pontos fracos -3. **Público** — linguagem online, canais activos, dores expressas em fóruns/reviews -4. **Oportunidades** — gaps de mercado, tendências emergentes não exploradas +| Nível | Quando | Estrutura | Modo de redação | +|---|---|---|---| +| Essencial | Produto próprio, iteração rápida | Capítulos E de `estrutura-completa.md` | Um agente, de seguida | +| Standard (default) | Cliente EST-MRK-010 | Capítulos E + S | Bloco a bloco com validação do utilizador | +| Completo | "versão completa", marca da casa, branding WOW, cliente com várias linhas de negócio | Todos os 36 capítulos e anexos | Subagentes em paralelo por parte (`prompt-redacao-parte.md`) | -Guardar síntese em `Pesquisas/sintese-mercado.md` no projecto do cliente. +Se o pedido for ambíguo, Standard. "Completa", "com todos os elementos" ou +"como a da Descomplicar" = Completo. -**Resultado esperado:** chegar ao briefing já com hipóteses validadas sobre o mercado e o público — não para impor, mas para fazer perguntas mais certeiras e poupar tempo ao cliente. +## Fases -### Fase 1 — Activação e contexto +### Fase 0. Pesquisa de mercado +Verificar se já existe pesquisa (`Pesquisas/` no projeto). Se não, usar +`/deep-research` (ou pesquisa web) sobre mercado, concorrentes, público e +oportunidades. Só fontes primárias para números (INE, Eurostat, reguladores, +associações), sempre com link. Guardar em `Pesquisas/sintese-mercado.md`. -Ao iniciar, perguntar: -- Qual o nome do cliente/marca? -- Já existe briefing ou material de partida? -- Qual o sector/indústria? -- Temos exemplos de concorrentes? +### Fase 1. Ativação e contexto +Nome da marca, sector, material existente, concorrentes conhecidos, projeto no +Desk CRM (`get_project`). Para a própria Descomplicar® ou marcas da casa, ler +também: `Cloud/Descomplicar/Planeamento/Estrategia-2026/`, o sistema de design +(`Hub/04-Stack/02.04-Sistemas/DesignSystem-Descomplicar/sistema/docs/marca.md`) +e as fichas OKF (`empresa/`, `produtos-servicos/`). -Se existir projecto no Desk CRM, verificar com `get_project` antes de prosseguir. +### Fase 2. Briefing (rondas curtas, saltar o que já se sabe) +1. Essenciais: nome, sector, o que vende, quem compra, website. +2. Contexto: problema que resolve, 2-3 concorrentes, diferenciador, material de marca, mercado geográfico. +3. Ambição: onde quer estar a 2-3 anos, nichos prioritários, enquadramento legal. +Perguntas completas em `references/perguntas-briefing.md`. -### Fase 2 — Briefing estruturado +### Fase 3. Fundamentos (P1-P4) +Problema em 3 níveis, propósito, missão, visão, valores, objetivos, posicionamento +testável, proposta de valor. `references/framework-16ps.md` (Bloco A). +Gate P4: sem declaração de posicionamento testável, não avançar. -Conduzir entrevista com as perguntas de `references/perguntas-briefing.md`. +### Fase 4. Público (P5-P7) +≥5 nichos sectoriais com 8 pontos (`references/nichos.md`; "PMEs" não é nicho), +depois os segmentos com os 20 pontos por ordem (`references/template-documento.md` §5, +exemplo em `references/exemplo-persona-20d.md`), personas nomeadas. +Gate Público: ≥5 nichos e ≥2 segmentos com os 20 pontos completos. -Organizar por blocos: -1. Negócio (problema, serviços, mercado) -2. Público-alvo (segmentos identificados) -3. Posicionamento actual vs desejado -4. Tom de voz e personalidade -5. Concorrência e diferenciação +### Fase 5. Pitch canvas +Para quem, problema, solução, resultado, porquê nós, mais a declaração de mudança no mundo. -### Fase 3 — Fundamentos estratégicos +### Fase 6. Copywriting +Questionamento estratégico (10 perguntas), Pain + Gain original e refinado, +narrativa por segmento (dor → solução → resultado), mensagem central, headlines. +`references/narrativas-copywriting.md`. -Desenvolver com o cliente: -- **Proposta de valor única** — o que nos torna únicos, diferenciais, benefícios por camada -- **Missão, Visão, Valores e Objectivos** — com exemplos de como se manifestam na prática -- **Apresentação sumária** — empresa + serviços com tabela clara -- **Posicionamento** — declaração de posicionamento testável +### Fase 7. Restante documento +Seguir a ordem de `references/estrutura-completa.md` para o nível escolhido: +identidade e expressão, oferta e preço, comunicação e canais, crescimento, +medição e roteiro. Gate Identidade Visual: paleta desta marca em hex. -Ver `references/framework-16ps.md` → Bloco A para questões orientadoras. +No nível Completo as fases 3 a 7 correm em paralelo: o orquestrador fecha as +decisões transversais e lança um subagente por parte com +`references/prompt-redacao-parte.md`. Depois lê os relatórios, alinha nomes +partilhados entre partes e retira o que não pode sair (detalhes de incidentes, +promessas sem cláusula, concorrentes nomeados em copy). -### Fase 4 — Análise de público (20 pontos por segmento) +### Fase 8. Montagem, validação e PDF +1. Escrever a introdução (resumo executivo de 1 página + "Sobre este documento": + fontes, decisões tomadas quando as fontes divergem, convenções). +2. Escrever o `## BRIEFING-LLM` (esquema do CONTRATO; partir do golden example + e trocar tudo pelos valores desta marca; coerente com o corpo). +3. Montar: `python3 scripts/montar.py --partes --intro intro.md --briefing briefing-llm.md --config marca.json --out .md [--glossario …] [--historico …]`. + Gera o anexo A com todos os `[a validar]`. +4. Validar: `node /Estrategia-de-Marca/validador-estrategia-marca.mjs .md` (acrescentar `--completo` no nível Completo). Corrigir até 0 erros. +5. PDF A4: copiar `assets/marca-descomplicar.json` para o projeto, trocar cores, + fontes, logótipo e textos pelos da marca, e correr + `python3 scripts/render_pdf.py .md .pdf --config marca.json`. +6. Verificar: abrir pelo menos a capa, o índice, uma página de texto com € e uma + tabela (`pdftoppm -r 60 -f N -l N`); o script avisa se aparecerem fontes de + recurso do sistema (Liberation/DejaVu). -**Obrigatório:** Antes dos segmentos psicográficos, identificar os nichos sectoriais relevantes para o produto. Usar `references/nichos.md` para seleccionar e analisar **pelo menos 5 nichos específicos** (ex: clínicas de saúde, imobiliárias, agências digitais — não "PMEs" como categoria vaga). Para cada nicho preencher os 8 pontos do guia de análise sectorial. Cruzar com os 20 pontos psicográficos abaixo para construir personas completas. +### Fase 9. Entrega +- Estratégia de cliente: pasta do projeto do cliente (Desk/GDrive/local), nunca + na pasta do standard. Marca da casa: `Cloud/Descomplicar/Planeamento/…` e + atualizar a ficha OKF correspondente. +- Status `rascunho-para-validacao` enquanto houver pontos no anexo A; + `aprovado` só com o validador a 0 erros e revisão do Emanuel. +- Cliente no Desk: comentar na tarefa com o caminho e a lista de pontos a validar. -Para cada segmento identificado, desenvolver os 20 pontos na seguinte ordem: +## Checklist de entrega -1. Perfil Demográfico -2. Perfil Psicográfico -3. Dores -4. Anseios -5. Desejos -6. Frustrações -7. Preocupações -8. Medos -9. Inimigos -10. Linguagem -11. Como procuram ajuda/informação/dicas -12. Canais digitais activos -13. Estilo de Decisão -14. Mudanças (que sabem necessárias) -15. Resistência à mudança -16. Objecções típicas (+ como ultrapassar) -17. Forma de gerar emoção -18. Argumentos (a que são mais sensíveis) -19. Concorrentes (que alternativas avaliam) -20. Propostas Recusadas (e porquê) +- [ ] Pesquisa de mercado com fontes (Fase 0) +- [ ] P1-P16 referidos explicitamente +- [ ] Posicionamento testável, proposta única de valor, missão, visão, valores +- [ ] ≥5 nichos (8 pontos) e segmentos com os 20 pontos (≥2 Essencial, 3-4 Standard, todos Completo) +- [ ] Pitch canvas + declaração de mudança no mundo +- [ ] Pain + Gain original e refinado, narrativa por segmento, mensagem central +- [ ] Identidade visual com paleta desta marca em hex +- [ ] KPIs com base e metas a 3/6/12 meses +- [ ] Capítulos do nível escolhido todos presentes (`estrutura-completa.md`) +- [ ] Anexo A gerado; nenhum dado inventado +- [ ] `## BRIEFING-LLM` em último, sem placeholders +- [ ] Validador a 0 erros; PDF A4 verificado visualmente -Ver `references/metodologia-acida.md` para contexto e profundidade em cada ponto. +## Erros a evitar -### Fase 5 — Pitch Canvas +- Personas genéricas sem nome nem história; segmentos vagos ("PMEs"). +- Missão e visão de modelo; SWOT vago ("boa qualidade"); headlines do tipo "soluções inovadoras". +- KPIs sem meta numérica; proposta de valor com funcionalidades em vez de benefícios; ignorar objeções. +- Números, casos, testemunhos, preços ou concorrentes sem fonte. +- Garantias de resultado ("ROI garantido") em texto para clientes sem cláusula contratual. +- Paleta da Descomplicar® na estratégia de um cliente. +- Assinatura antiga: a Descomplicar® assina "Agência de Marketing Digital" (sistema de design de 16-10-2026), não "Aceleração" nem "Crescimento Digital". +- PDF em Letter: é sempre A4. -Estrutura de 5 elementos: -- **Para quem:** segmento + problema específico -- **O problema:** dor principal na linguagem do cliente -- **A solução:** mecanismo único de resolução -- **O resultado:** transformação concreta (antes/depois + métrica) -- **Por que nós:** razão para acreditar +## Referências -Criar também a **Declaração de mudança no mundo** — frase que resume o impacto maior da marca. +| Ficheiro | Quando carregar | +|---|---| +| `references/estrutura-completa.md` | Sempre: ordem canónica, níveis, mapa 16Ps → capítulos | +| `references/prompt-redacao-parte.md` | Nível Completo: contexto e tarefa de cada subagente | +| `references/perguntas-briefing.md` | Fase 2 | +| `references/framework-16ps.md` | Fase 3 | +| `references/metodologia-acida.md` | Fases 3-4 | +| `references/nichos.md` | Fase 4: 10 nichos PT/UE, 8 pontos cada | +| `references/template-documento.md` | Guia de escrita de cada secção (20 pontos em detalhe, pitch canvas, KPIs, inventário) | +| `references/exemplo-persona-20d.md` | Fase 4: exemplo de segmento com as 20 dimensões | +| `references/narrativas-copywriting.md` | Fase 6 | +| `scripts/montar.py`, `scripts/render_pdf.py`, `assets/marca-descomplicar.json` | Fase 8 | -### Fase 6 — Copywriting estratégico +Exemplos reais: `99-Arquivo/Manual-OwnCloud-Descomplicar/exemplos estrategias de marca/` +(Carritools é o mais completo dos clientes) e a Estratégia Descomplicar® v3.0 em +`Cloud/Descomplicar/Planeamento/Estrategia-2026/DESCOMPLICAR_ESTRATEGIA_MARCA_V3.md`. -Sequência obrigatória: +## Contexto do serviço -1. **Questionamento estratégico** — Qual é o objectivo da comunicação? Que transformação prometemos? -2. **Pain + Gain** — formulação problema/resultado na linguagem do cliente; depois refinar com especificidades do sector -3. **Narrativa por segmento** — fórmula: Problema (dor do público) → Solução (serviços) → Resultado (benefícios concretos) -4. **Mensagem central** — 1 frase que toda a equipa sabe de cor -5. **Headlines** — por segmento (principal + secundária) +- Código EST-MRK-010 · 900€ fixo · cerca de 30 horas (catálogo, outubro de 2026). +- Entregáveis: documento estratégico, personas, narrativa, apresentação executiva editável, plano de implementação, sessão de alinhamento com a equipa, suporte por WhatsApp durante 1 mês. +- Identidade visual completa: Branding WOW (1 800€ a 4 500€). -Ver `references/narrativas-copywriting.md` para templates e exemplos reais. +## Healing Log -# \ No newline at end of file +Lido antes de executar. Acrescentar uma linha por erro corrigido. + +```jsonl +{"date":"2026-10-17","issue":"Skill dizia-se alinhada com a SPEC (GATE-HOOK) mas não pedia o BRIEFING-LLM; a estratégia Descomplicar v3 reprovou no validador","fix":"Fase 8 obriga a escrever o BRIEFING-LLM e a correr o validador antes de entregar","source":"auto"} +{"date":"2026-10-17","issue":"Subagentes copiaram identificadores e pormenores de incidentes de segurança para a SWOT","fix":"Contrato de redação proíbe; orquestrador revê antes de montar","source":"auto"} +{"date":"2026-10-17","issue":"PDF saiu com Liberation Sans em vez das fontes da marca: woff2 subset sem € e faces de recurso na mesma família com pesos diferentes","fix":"render_pdf.py usa família de recurso separada e avisa se houver fontes do sistema no PDF","source":"auto"} +{"date":"2026-10-17","issue":"Partes escritas em paralelo usaram durações e segmentos diferentes (diagnóstico 30 vs 45 min, 5 vs 6 segmentos)","fix":"Fixar nomes partilhados no bloco 'Decisões já tomadas' antes de lançar","source":"auto"} +``` diff --git a/crm-ops/skills/estrategia-marca/assets/marca-descomplicar.json b/crm-ops/skills/estrategia-marca/assets/marca-descomplicar.json new file mode 100644 index 0000000..fc15bcb --- /dev/null +++ b/crm-ops/skills/estrategia-marca/assets/marca-descomplicar.json @@ -0,0 +1,44 @@ +{ + "_nota": "Config de exemplo para render_pdf.py e montar.py. Só para estratégias DA PRÓPRIA Descomplicar®. Para clientes, copiar e trocar cores, fontes, logótipo e textos pelos da marca do cliente (SPEC C4). Caminhos absolutos do posto 'desktop'/'hp' (Hub em /media/ealmeida/Dados).", + "marca": "Descomplicar®", + "titulo_documento": "Estratégia de marca", + "rodape": "Descomplicar® · Estratégia de marca", + "capa_eyebrow": "Documento estratégico · versão 3.0", + "capa_titulo": "Estratégia
de marca", + "capa_slogan": "Criamos Resultados!", + "capa_assinatura": "Descomplicar® - Agência de Marketing Digital", + "capa_data": "outubro de 2026", + "logo_capa": "/media/ealmeida/Dados/Hub/04-Stack/02.04-Sistemas/DesignSystem-Descomplicar/sistema/assets/Logos/assinatura-vertical-white.svg", + "fonte_titulos": "Montserrat", + "fonte_texto": "Roboto", + "fallback": "'DCArrows','DCFallback',sans-serif", + "fontes": [ + {"family": "Montserrat", "src": "/media/ealmeida/Dados/Hub/04-Stack/02.04-Sistemas/DesignSystem-Descomplicar/sistema/fonts/Montserrat-latin-wght-normal.woff2"}, + {"family": "Roboto", "src": "/media/ealmeida/Dados/Hub/04-Stack/02.04-Sistemas/DesignSystem-Descomplicar/sistema/fonts/Roboto-latin-wght-normal.woff2"}, + {"family": "Roboto", "style": "italic", "src": "/media/ealmeida/Dados/Hub/04-Stack/02.04-Sistemas/DesignSystem-Descomplicar/sistema/fonts/Roboto-latin-wght-italic.woff2"}, + {"family": "DCFallback", "weight": "100 500", "src": "/media/ealmeida/Dados/Dev/SEO-Reports/public/fonts/pdf/Roboto-Regular.ttf"}, + {"family": "DCFallback", "weight": "600 900", "src": "/media/ealmeida/Dados/Dev/SEO-Reports/public/fonts/pdf/Roboto-Bold.ttf"}, + {"family": "DCArrows", "src": "/media/ealmeida/Dados/Dev/SEO-Reports/public/fonts/pdf/Montserrat-Regular.ttf", "unicode_range": "U+2190-21FF"} + ], + "cores": { + "escura": "#0e0d0b", + "clara_texto": "#f5f1e8", + "primaria": "#cc8d00", + "acento_texto": "#7a5400", + "texto": "#1a1814", + "texto_secundario": "#5c5750", + "suave": "#faf4e6", + "linha": "#e6e1d8", + "alternada": "#faf8f3", + "aviso_fundo": "#fdecc8", + "aviso_texto": "#5a3d00" + }, + "frontmatter": { + "type": "Document", + "title": "Descomplicar® · Estratégia de marca", + "codigo": "EST-MRK-010", + "version": "3.0", + "status": "rascunho-para-validacao", + "elaborado": "Descomplicar® - Agência de Marketing Digital" + } +} diff --git a/crm-ops/skills/estrategia-marca/references/estrutura-completa.md b/crm-ops/skills/estrategia-marca/references/estrutura-completa.md new file mode 100644 index 0000000..94303f0 --- /dev/null +++ b/crm-ops/skills/estrategia-marca/references/estrutura-completa.md @@ -0,0 +1,156 @@ +# Estrutura completa — Estratégia de Marca Descomplicar® (SPEC v2.0) + +Ordem canónica do documento de autoria. Junta, sem perder nenhum, todos os +elementos usados nas estratégias entregues (Carritools MCT, Espiral Sénior ESP, +Loja da Maria LJM, Sintricare SNT, Water Control WTC, Solar FV SFV), no modelo +ACIDA v3, no prompt 40Ps, na skill `brand-strategy` (40 pontos, fundida aqui) e +na Estratégia de Marca Descomplicar® v3.0 (17-10-2026), que é o exemplo de +referência do nível Completo. + +Exemplo de referência (nível Completo, 34 capítulos, 192 páginas A4; anterior a esta +estrutura, junta os 20 pontos nos caps. 9-11 e não tem capítulo de jornada): +`Cloud/Descomplicar/Planeamento/Estrategia-2026/DESCOMPLICAR_ESTRATEGIA_MARCA_V3.md` (+ `.pdf`). +Exemplo de profundidade por capítulo (cliente): `99-Arquivo/Manual-OwnCloud-Descomplicar/exemplos estrategias de marca/MCT Estratégia de Marca Carritools.md`. + +A ordem vai do contexto para a ação: perceber o mercado e a empresa, fixar os +fundamentos, conhecer o público, definir a expressão da marca, desenhar a oferta, +planear a comunicação e o crescimento, e por fim medir e implementar. + +## Níveis de profundidade + +| Nível | Quando | O que entra | Público | +|---|---|---|---| +| Essencial | Produto próprio, iteração rápida, teste de posicionamento | Cabeçalho, caps. 2-4 resumidos, 5-8, 9 (≥5 nichos), 10 (≥2 segmentos com 20 pontos), 16, 17, 20, 27, 32, anexo A, BRIEFING-LLM | 2-3 segmentos | +| Standard (default) | Cliente EST-MRK-010 | Essencial + 1, 11, 13-15, 18, 19, 21, 23, 35, 36 (resumo), anexos B e D | 3-4 segmentos, 20 pontos cada | +| Completo | Pedido "versão completa", marca da casa, branding WOW, cliente com várias linhas de negócio | Todos os capítulos e anexos abaixo | Todos os segmentos com 20 pontos + secundários e prescritores | + +Coluna "Nível" abaixo: E = Essencial, S = Standard, C = Completo. Um capítulo +marcado S entra em S e C; marcado E entra nos três. + +## Cabeçalho (todos os níveis) + +| Elemento | Conteúdo | Fonte de exemplo | +|---|---|---| +| Frontmatter | title, cliente, codigo EST-MRK-010, versao, data, elaborado ("Descomplicar® - Agência de Marketing Digital"), status `rascunho-para-validacao` / `aprovado` | template-documento | +| Capa | Marca, "Estratégia de marca", assinatura ou slogan do cliente | todos | +| Declaração de impacto | Uma frase de 10-15 palavras (a mudança no mundo) | template v3, LJM ("Alegria todo o dia"), WTC ("Cada gota conta") | +| Índice | Partes e capítulos | todos | +| Resumo executivo | Tabela de 1 página: assinatura, slogan, missão, visão, posicionamento, proposta única de valor, método, persona principal, oferta de entrada, prioridade imediata, cada um com o capítulo | v3.0 | +| Sobre este documento | Fontes usadas, decisões tomadas quando as fontes divergem, convenções (o que significa `[a validar]`) | v3.0 | + +## Parte I. Contexto (P6 Pesquisa) + +| Cap. | Título | Contém | P / 40Ps | Nível | Fonte de exemplo | +|---|---|---|---|---|---| +| 1 | Apresentação | Quem é a empresa (identidade legal, fundação, equipa, localização), histórico e evolução, como opera, serviços e produtos em resumo, estado atual | P8 resumo; Apresentação institucional | S | SNT, WTC, template v3, v3.0 | +| 2 | Enquadramento do mercado e contexto social | Contexto do sector, dimensão, tendências, mudanças sociais e tecnológicas, enquadramento legal e regulatório, cultura e comunidade do sector | P6; Possibilidades | E (resumo) / C | MCT 1.1-1.5, LJM, ESP | +| 3 | Concorrência e oportunidades de diferenciação | Tipos de concorrente e posicionamento de cada tipo, matriz comparativa, propostas recusadas e porquê, oportunidades de diferenciação com a condição para serem credíveis | P4, P6 | E (resumo) / C | MCT 1.3-1.6 | +| 4 | Análise SWOT | Forças, fraquezas, oportunidades, ameaças com evidência; cruzamento estratégico (SO, ST, WO, WT) e prioridades | P6 | E (resumo) / C | LJM | + +## Parte II. Fundamentos (P1-P4) + +| Cap. | Título | Contém | P | Nível | Fonte | +|---|---|---|---|---|---| +| 5 | Problema, causa e propósito | P1 em 3 níveis (superficial, real, raiz), a causa da marca, propósito (porquê, como, o quê), manifesto (opcional em E/S), lema interno | P1, P2 | E | WTC ("A nossa causa"), v3.0 | +| 6 | Missão, visão, valores e objetivos | Missão, visão com metas datadas, valores com comportamentos concretos ("fazemos / não fazemos"), objetivos estratégicos com indicador, base e meta | P2, P16 | E | todos | +| 7 | Posicionamento | Categoria e papel, declaração de posicionamento testável (formato clássico + 1 frase + versão oral), especialização vs. competição pelo preço, mapa de posicionamento, oportunidades | P4 | E | LJM, MCT 1.6 | +| 8 | Proposta de valor | Proposta única de valor, dores e como a marca as resolve (tabela), diferenciais, benefícios tangíveis e benefícios por camada/segmento, expectativas emocionais e racionais, USP, escada de valor | P3 | E | MCT 3, SNT, WTC | + +## Parte III. Públicos (P5-P7) + +| Cap. | Título | Contém | P | Nível | Fonte | +|---|---|---|---|---|---| +| 9 | Nichos e segmentos | ≥5 nichos sectoriais com os 8 pontos (`nichos.md`); segmentos primário, secundário e terciário; critérios de cliente ideal (obrigatórios, desejáveis, sinais de alerta); anti-persona; públicos secundários (prescritores, parceiros, talento) | P5 | E | MCT 2, WTC, SNT | +| 10 | Análise de 20 pontos por segmento | Para cada segmento, os 20 pontos por ordem (ver lista abaixo), com o ponto 16 (objeções) sempre acompanhado do tratamento | P5-P7 | E (≥2 seg.) / S (3-4) / C (todos) | template-documento §5, ESP, WTC | +| 11 | Personas e dashboard de personas | Persona principal com nome, biografia, objetivos, frustrações, comportamento digital, processo de decisão, citações típicas, mapa de empatia; personas secundárias; dashboard (uma ficha por persona) | P7 | S | 40Ps [8], v3.0 | +| 12 | Jornada e experiência do cliente | Fases da jornada (descoberta, consideração, decisão, onboarding, fidelização), pontos de contacto, emoção e fricção por fase | P9, P10 | C | brand-strategy 23b | + +Os 20 pontos (ordem fixa, cabeçalhos com estes nomes para o validador os +encontrar): Perfil demográfico · Perfil psicográfico · Dores · Anseios · Desejos · +Frustrações · Preocupações · Medos · Inimigos · Linguagem · Como procuram +ajuda/informação · Canais digitais · Estilo de decisão · Mudanças · Resistência à +mudança · Objeções (+ como ultrapassar) · Forma de gerar emoção · Argumentos · +Concorrentes · Propostas recusadas. + +## Parte IV. Identidade e expressão + +| Cap. | Título | Contém | Nível | Fonte | +|---|---|---|---|---| +| 13 | Personalidade da marca | Arquétipo, traços (é / não é), símbolo e o que representa | S | MCT 4.4 | +| 14 | Voz, tom e estilo de comunicação | Princípios de voz, tom por contexto (site, propostas, redes, suporte, crise), regras de escrita, léxico a usar e a banir, tabela "em vez de / escrever" | S | MCT 4.5-4.6, ESP "Voz da marca" | +| 15 | Narrativa e história da marca | Origem, porquê do nome, o cliente como herói, narrativa por segmento (Problema → Solução → Resultado) | S | ESP, SNT, WTC | +| 16 | Identidade visual | Paleta DESTA marca em hex (primária, secundária, neutros, proporções), tipografia, logótipo e versões, margens e mínimos, proibições, imagem, iconografia, acessibilidade. Nunca a paleta da Descomplicar® num cliente | E (obrigatório, SPEC C4) | MCT 4.7 | +| 17 | Assinaturas, slogan e mensagens-chave | Assinatura, slogan/tagline e regras de uso, mensagem central (≤10 palavras), mensagens-chave institucionais, mensagens e headlines por segmento, elevator pitch de 10/30/60 segundos | E | MCT 10, template-documento §7.4-7.5 | + +## Parte V. Oferta e venda (P8-P10, P15) + +| Cap. | Título | Contém | P | Nível | Fonte | +|---|---|---|---|---|---| +| 18 | Produtos, serviços e metodologia | Arquitetura da oferta, catálogo por área, casos de uso, metodologia de entrega, processos críticos, placement (canais de distribuição, pontos de venda, presença física e digital) | P8, P9, P10 | S | SNT "Serviços", v3.0 | +| 19 | Preço e modelo comercial | Lógica de preço, pacotes, avenças, preços de referência COM fonte, política de descontos e pagamento, garantias (só com cláusula contratual) | P15 | S | v3.0 | +| 20 | Pitch canvas | Porque é útil e como usar; declaração de impacto/compromisso; problema e resultado (Pain + Gain); solução; demonstração; aspetos únicos; relações; parcerias; pistas de futuro e tecnologia; atração de clientes; investimento; declaração de mudança no mundo | P3, P4 | E | SNT, template v3 | +| 21 | Venda consultiva e demonstração | Etapas do primeiro contacto ao fecho, diagnóstico, guião de demonstração (preparação, introdução, demonstração ao vivo, casos de uso, perguntas, follow-up), materiais de apoio, FAQ | P10 | S | WTC "Demonstração", brand-strategy 36 | + +## Parte VI. Comunicação e canais (P14) + +| Cap. | Título | Contém | Nível | Fonte | +|---|---|---|---|---| +| 22 | Objetivos de comunicação | Consciencialização, educação, envolvimento, confiança e credibilidade, conversão, retenção, diferenciação, advocacia; um indicador por objetivo | C | ESP | +| 23 | Canais | Website (função, mensagens-chave, estratégia, frequência, estrutura de menu e páginas), redes sociais por rede, email marketing, eventos e feiras, material impresso, vídeo e áudio, relações públicas, proximidade (WhatsApp, comunidade) | S | MCT 5, WTC, ESP "Estrutura do site" | +| 24 | Marketing de conteúdo e política editorial | Pilares, tipos de conteúdo, secções do blog, lista de artigos iniciais com intenção, princípios editoriais, CTA de fim de artigo | C | ESP, MCT 6.1 | +| 25 | SEO e GEO | Clusters de palavras-chave (sem volumes inventados), on-page, técnico, link building, presença em respostas de IA | C | MCT 6.2 | +| 26 | Publicidade online | Por plataforma: importância, estratégia, formatos, frequência e orçamento; diferenciação dos canais | C | MCT 7 | +| 27 | Copywriting | Questionamento estratégico (10 perguntas) respondido, Pain + Gain original e refinado, exemplos de CTA, estrutura da página de captura | E | SNT "Resumo estratégico", WTC, ESP | +| 28 | Calendário de conteúdos | Cadência por canal (diária, semanal, mensal), temas por mês ou trimestre | C | MCT 5.6 | + +## Parte VII. Crescimento (P11-P13, Projeção) + +| Cap. | Título | Contém | Nível | Fonte | +|---|---|---|---|---| +| 29 | Parcerias | Tipos (tecnológicas, distribuição, prescritores, associações, criadores de conteúdo), objetivo e critério de cada tipo | C | MCT 8, WTC | +| 30 | Expansão | Novos mercados geográficos, novos serviços ou produtos, cenários alternativos, critérios de decisão para avançar | C | LJM (Espanha, dropshipping), MCT 8.4 | +| 31 | Atração de clientes e prova social | Casos de sucesso e testemunhos (só com autorização), workshops e seminários, ofertas de entrada, presença em comunidades, programa de referência | C | WTC "Atração de clientes" | + +## Parte VIII. Medição e implementação (P12, P16) + +| Cap. | Título | Contém | Nível | Fonte | +|---|---|---|---|---| +| 32 | KPIs | Por área (site e SEO, redes, email, vendas, retenção): definição, fonte de dados, base, metas a 3/6/12 meses | E | MCT 9.1, SPEC P16 | +| 33 | Testes A/B e otimização contínua | Objetivos, variáveis, hipóteses, duração, análise | C | MCT 9.2, WTC | +| 34 | Sistema de relatórios | Semanal, mensal, trimestral: quem lê, o que contém, ferramenta | C | MCT 9.3 | +| 35 | Investimentos prioritários e inventário de ativos | Prioridades impacto/esforço, orçamento por canal, inventário de ativos de marketing (existe, estado, prioridade) | S | template-documento §9, §11 | +| 36 | Roteiro de implementação | Fases a 90 dias com entregáveis e responsáveis por papel, visão a 12 meses, recursos necessários, riscos e mitigação, notas de implementação (sessão de alinhamento, validação com clientes) | S (resumo) / C | v3.0, template-documento | + +## Anexos e secção final + +| Elemento | Contém | Nível | +|---|---|---| +| A. Pontos a validar | Lista gerada de todas as marcas `[a validar: …]`, por capítulo (o script `montar.py` gera-a) | todos | +| B. Glossário | Termos técnicos e nomes internos usados no documento | S | +| C. Complementos do sector | Enquadramento legal detalhado, informações operacionais, serviços detalhados (só quando o sector o pede) | C | +| D. Histórico de alterações | Versão, data, alteração | todos | +| `## BRIEFING-LLM` | Bloco-contrato YAML (`CONTRATO-OUTPUT-LLM.md`). **Última secção do ficheiro**, depois dos anexos | todos (obrigatório) | + +## Mapa 16Ps → capítulos + +| P | Capítulos | +|---|---| +| P1 Problema | 5 | +| P2 Propósito | 5, 6 | +| P3 Proposta de valor | 8, 20 | +| P4 Posicionamento | 3, 7 | +| P5 Público-alvo | 9, 10 | +| P6 Pesquisa | 2, 3, 4 | +| P7 Persona | 10, 11 | +| P8 Produto/serviço | 1, 18 | +| P9 Placement | 12, 18, 23 | +| P10 Processos críticos | 18, 21 | +| P11 Pessoas | 1, 36 (recursos) | +| P12 Planeamento | 28, 36 | +| P13 Parcerias | 29 | +| P14 Promoção | 22-27 | +| P15 Preço | 19 | +| P16 Performance | 6, 32-34 | + +Escrever explicitamente "(P1)", "(P2)"… nos títulos ou na primeira linha de cada +capítulo: o validador procura as referências P1-P16 no texto. diff --git a/crm-ops/skills/estrategia-marca/references/exemplo-persona-20d.md b/crm-ops/skills/estrategia-marca/references/exemplo-persona-20d.md new file mode 100644 index 0000000..a001899 --- /dev/null +++ b/crm-ops/skills/estrategia-marca/references/exemplo-persona-20d.md @@ -0,0 +1,159 @@ +# Exemplo de Persona — 20 Dimensoes + +Baseado no padrao AcidaOS (o mais profundo dos exemplos Descomplicar). + +--- + +## Segmento A — O Empreendedor Sobrecarregado + +**Prioridade:** Alta +**Dimensao estimada:** 45% do mercado-alvo + +### 1. Perfil demografico +- Idade: 35-50 anos +- Genero: predominantemente masculino (60/40) +- Localizacao: areas urbanas, Portugal continental +- Educacao: licenciatura ou equivalente profissional +- Rendimento: 25.000-60.000 EUR/ano (empresa factura 100K-500K) +- Dimensao empresa: 2-15 colaboradores +- Sector: servicos, comercio, consultoria + +### 2. Perfil psicografico +- Trabalhador incansavel, faz tudo sozinho +- Valoriza independencia acima de tudo +- Resistente a delegar por medo de perda de controlo +- Pragmatico — quer solucoes que funcionem, nao teoria +- Orgulho no que construiu mas frustrado com a estagnacao +- Ceptico em relacao a "solucoes magicas" + +### 3. Dores +- "Trabalho 12 horas por dia e o negocio nao cresce" +- Sem tempo para pensar estrategicamente +- Informacao dispersa (Excel, papel, cabeca) +- Clientes perdidos por falta de follow-up +- Nao sabe quanto lucra realmente + +### 4. Anseios +- Ter tempo para a familia sem o negocio parar +- Ver o negocio crescer de forma previsivel +- Sentir-se no controlo em vez de apagar incendios +- Ser reconhecido como empresario de sucesso + +### 5. Desejos +- Um sistema que "trabalhe por ele" nas tarefas repetitivas +- Dashboard simples que mostre como esta o negocio +- Processo de vendas que nao dependa so dele +- Facturacao automatica sem erros + +### 6. Frustracoes +- Ja tentou CRMs e desistiu (demasiado complexos) +- Paga software que nao usa +- Funcionarios nao adoptam ferramentas novas +- Contabilista so aparece no fim do mes + +### 7. Preocupacoes +- "Se eu parar, o negocio para" +- Concorrencia a crescer enquanto ele estagna +- Legislacao fiscal cada vez mais complexa +- Nao estar a usar a tecnologia como devia + +### 8. Medos +- Perder clientes para concorrentes mais organizados +- Nao conseguir pagar salarios num mes mau +- Ser ultrapassado pela digitalizacao +- Investir em tecnologia e nao ter retorno + +### 9. Inimigos +- Burocracia (AT, Seguranca Social, RGPD) +- Empresas grandes que competem com precos impossíveis +- Consultores que vendem teoria sem resultados +- O proprio perfeccionismo que impede de delegar + +### 10. Linguagem +- "Nao tenho tempo para isso" +- "Ja tentei e nao funcionou" +- "Quanto e que isso custa?" +- "Mostra-me resultados, nao apresentacoes" +- Informal, directo, sem paciencia para jargao + +### 11. Como procuram ajuda +- Perguntam a outros empresarios (boca-a-boca) +- Google quando ha um problema urgente +- LinkedIn para conteudo de negocios +- Contabilista como conselheiro informal +- Nao frequentam eventos/conferencias (sem tempo) + +### 12. Canais digitais +- WhatsApp (principal — pessoal e profissional misturado) +- Facebook (pessoal, menos profissional) +- LinkedIn (passivo — le mas nao publica) +- Email (verifica 2-3x por dia, ignora newsletters) +- Instagram (pessoal, nao profissional) + +### 13. Estilo de decisao +- Decide rapido quando ve valor claro +- Precisa de prova social (outro empresario a recomendar) +- Quer testar antes de comprometer +- Preco e factor mas nao o unico — valor percebido importa mais +- Prefere relacao pessoal a processo de vendas formal + +### 14. Mudancas que procuram +- De "faz-tudo" para gestor que delega +- De reactivo (apagar incendios) para proactivo +- De Excel para sistema integrado +- De "acho que esta bem" para "sei que esta bem" (dados) + +### 15. Resistencia a mudanca +- "Sempre fiz assim e funcionou" +- Medo da curva de aprendizagem +- Experiencias negativas anteriores com tecnologia +- Nao quer depender de fornecedores externos +- Equipa resiste a novas ferramentas + +### 16. Objecoes tipicas +- "E caro demais para o meu negocio" +- "Nao tenho tempo para implementar" +- "Ja tentei um CRM e ninguem usou" +- "O meu negocio e diferente, isso nao se aplica" +- "Prefiro investir em publicidade directa" + +### 17. Forma de gerar emocao +- Mostrar quanto tempo perde por semana em tarefas repetitivas (quantificar) +- Historias de empresarios semelhantes que transformaram o negocio +- Demonstrar em 5 minutos o que o sistema faz automaticamente +- Falar da familia — "imagina sair as 18h todos os dias" + +### 18. Argumentos de venda +- ROI em 3 meses (calculado com dados do negocio) +- "Nao precisa de saber tecnologia — nos tratamos de tudo" +- Garantia de satisfacao ou devolucao +- Implementacao faseada (nao muda tudo de uma vez) +- Suporte por WhatsApp (o canal dele) + +### 19. Concorrentes percebidos +- "O meu sobrinho faz-me um website" +- Freelancers no OLX/Facebook +- Ferramentas gratuitas (Google Sheets, Canva) +- PHC/Sage (que ja tem e nao usa) +- "Nao investir" (o concorrente mais forte) + +### 20. Propostas recusadas +- Pacotes anuais sem flexibilidade +- Solucoes que requerem formacao extensa +- Propostas sem resultados tangíveis prometidos +- Precos acima de 200 EUR/mes sem trial +- Vendedores que nao entendem o sector especifico + +--- + +## Formato resumido (para nivel Essencial — 8 dimensoes) + +Quando o nivel e Essencial, usar apenas: +1. Perfil demografico +2. Perfil psicografico +3. Dores +4. Desejos +5. Objecoes tipicas +6. Canais digitais +7. Estilo de decisao +8. Argumentos de venda diff --git a/crm-ops/skills/estrategia-marca/references/metodologia-acida.md b/crm-ops/skills/estrategia-marca/references/metodologia-acida.md index b0e60b4..41eeda5 100644 --- a/crm-ops/skills/estrategia-marca/references/metodologia-acida.md +++ b/crm-ops/skills/estrategia-marca/references/metodologia-acida.md @@ -1,5 +1,7 @@ # Metodologia ACIDA — Referência Completa +ACIDA = **Atrair, Construir confiança, Interesse, Decisão, Ação** (definição única, confirmada pelo Emanuel a 17-10-2026). ACIDA 2.0 é a versão atual da mesma metodologia. Qualquer documento que expanda ACIDA como Análise, Criação/Conceção, Implementação, Desenvolvimento, Acompanhamento/Avaliação está errado: essas são as fases do ciclo de projeto (secção 4), não o ACIDA. + ## 1. As 5 fases ACIDA ### A — Atrair atenção @@ -116,7 +118,9 @@ Para cada segmento, investigar as 8 dimensões antes de escrever qualquer copy: --- -## 4. ACIDA 2.0 — Fases operacionais +## 4. Ciclo de projeto (orientado pela ACIDA) + +As fases pelas quais a Descomplicar® executa um projeto de marketing. Não são o ACIDA: cada fase produz o que as etapas ACIDA (Atrair, Construir confiança, Interesse, Decisão, Ação) precisam. | Fase | Acções | |------|--------| diff --git a/crm-ops/skills/estrategia-marca/references/prompt-redacao-parte.md b/crm-ops/skills/estrategia-marca/references/prompt-redacao-parte.md new file mode 100644 index 0000000..989a20b --- /dev/null +++ b/crm-ops/skills/estrategia-marca/references/prompt-redacao-parte.md @@ -0,0 +1,89 @@ +# Prompt de redação por parte (nível Completo) + +No nível Completo o documento tem 60 000 a 90 000 palavras. Um só agente não o +escreve com qualidade numa passagem. Divide-se por partes (I a VIII de +`estrutura-completa.md`) e entrega-se cada parte a um subagente, em paralelo. O +orquestrador fixa as decisões, junta, revê e gera o PDF. + +Divisão que funcionou (Estratégia Descomplicar® v3.0, 17-10-2026, 7 subagentes, +cerca de 15 minutos): I · II · III · IV · V · VI · VII+VIII. + +## Antes de lançar (orquestrador) + +1. Ler as fontes principais e decidir os conflitos que afetam várias partes: + assinatura e slogan, nome da categoria, garantias, lista e ordem dos + segmentos, oferta de entrada (nome e duração), formato monetário. +2. Escrever essas decisões no bloco "Decisões já tomadas" abaixo. Subagentes + não rediscutem decisões; registam divergências em "Nota de fonte". +3. Mandar os subagentes alinharem entre si os nomes partilhados (segmentos, + ofertas, canais) por mensagem direta, sem editar ficheiros alheios. + +## Contexto partilhado (copiar para o campo de contexto de todos os subagentes) + +```markdown +# Goal +Escrever a Estratégia de Marca de (, ), nível Completo. +Cada subagente escreve UMA parte; o orquestrador junta. + +# Estrutura global (contrato; numeração fixa) + + +# Fontes (ler as relevantes; NÃO inventar factos) +- Briefing e notas da entrevista: +- Pesquisa de mercado (Fase 0): /Pesquisas/sintese-mercado.md +- Material do cliente (site, catálogo, propostas, manual de marca): +- Desk CRM / OKF do cliente: +- Exemplo de profundidade: 99-Arquivo/Manual-OwnCloud-Descomplicar/exemplos estrategias de marca/MCT Estratégia de Marca Carritools.md (formato, não conteúdo) +- Dados externos: só fontes primárias (INE, Eurostat, Comissão Europeia, entidades + reguladoras, associações do sector); cada número com link numa nota no fim do capítulo. + +# Decisões já tomadas (aplicar, não rediscutir) +- Assinatura / slogan / categoria: <…> +- Segmentos (nome e ordem): <…> +- Oferta de entrada: <…> +- Garantias: só as que existem em contrato; promessas de resultado não entram em texto para clientes. +- Onde as fontes divergem, prevalece a mais recente; registar numa linha "Nota de fonte" no fim do capítulo. + +# Regras de escrita +- PT-PT, Acordo Ortográfico de 1990, zero brasileirismos (equipa, registo, ecrã, telemóvel, utilizador, planeamento). +- Copy dirigido ao cliente final em 3.ª pessoa de cortesia ("a sua empresa"); nunca "você" fora de citações. +- Títulos em frase. `## N. Título` para capítulos, `### N.M` para secções, `####` se preciso. Não escrever o título da Parte. +- Indicar o P correspondente na primeira linha do capítulo, ex.: "(P4)". +- Sem emoji, sem travessões (— ou –) como pausa, sem negrito no início de cada item de lista, sem frases-feitas ("alavancar", "no panorama atual", "não é X, é Y", perguntas retóricas respondidas logo a seguir). +- Moeda: 1 250€ (valor, espaço de milhar, símbolo colado). Datas por extenso: 16 de outubro de 2026. +- Concorrentes: no documento interno descrever por tipo; nomes só se vierem das fontes e nunca em copy ou mensagens destinadas a material público. +- Nunca inventar números, clientes, casos, preços, testemunhos ou concorrentes. Se o dado faltar, escrever o elemento na mesma e marcar `[a validar: o que falta]`. +- Casos e testemunhos de clientes só com autorização registada; sem ela, `[a validar: autorização de ]`. +- Detalhes de incidentes de segurança, credenciais e dados pessoais nunca entram no documento. +- Não repetir capítulos de outras partes: escrever "ver capítulo N". + +# Entrega +Escrever em `local://marca/parte-.md` só os capítulos atribuídos. +Não criar nem alterar mais nenhum ficheiro, não correr builds. +Resposta final: nº de palavras, lista de `[a validar]`, notas de fonte, decisões tomadas que o orquestrador deve conhecer. +``` + +## Tarefa por subagente (um por parte) + +```markdown +# Target +Parte . : capítulos a . Ficheiro: local://marca/parte-.md. + +# Change +- Cap. N: +- … + +# Acceptance +Capítulos N-M completos, cada afirmação factual rastreável a fonte interna ou a nota com link; `[a validar]` onde faltar dado. +``` + +## Depois de receber as partes (orquestrador) + +1. Ler os relatórios: decisões tomadas por cada subagente, divergências entre + partes (ex.: duração do diagnóstico, segmentos) e corrigi-las. +2. Procurar e retirar: detalhes de incidentes, caminhos de relatórios internos + sensíveis, nomes de concorrentes em copy, promessas sem cláusula. +3. Correr `scripts/montar.py` (junta, cria o anexo A) e escrever à mão a + introdução (resumo executivo e "Sobre este documento") e o `## BRIEFING-LLM`. +4. Validar e gerar o PDF (ver SKILL.md, Fase 8). diff --git a/crm-ops/skills/estrategia-marca/references/template-documento.md b/crm-ops/skills/estrategia-marca/references/template-documento.md index 4fad45d..d32ed34 100644 --- a/crm-ops/skills/estrategia-marca/references/template-documento.md +++ b/crm-ops/skills/estrategia-marca/references/template-documento.md @@ -1,7 +1,7 @@ # Template: Documento de Estratégia de Marca -Estrutura completa do documento entregável ao cliente. Baseado nos projectos SFV, LJM, MCT, Espiral Senior e Sintricare. -Adaptar secções ao sector e complexidade do cliente. +Guia de escrita de cada secção (o que escrever e com que profundidade). Baseado nos projetos SFV, LJM, MCT, Espiral Sénior e Sintricare. +A ORDEM e a numeração dos capítulos vêm de `estrutura-completa.md` (SPEC v2.0), que prevalece sobre o índice abaixo. Adaptar ao sector e ao nível (Essencial, Standard, Completo). --- @@ -14,7 +14,7 @@ cliente: [Nome do cliente] código: EST-MRK-010 versão: 1.0 data: [DD-MM-YYYY] -elaborado: Descomplicar® — Agência de Aceleração Digital +elaborado: Descomplicar® - Agência de Marketing Digital status: draft | aprovado --- ``` @@ -370,5 +370,5 @@ O Pitch Canvas é uma ferramenta de comunicação estratégica que resume, numa --- -*Elaborado por Descomplicar® — Agência de Aceleração Digital* +*Elaborado por Descomplicar® - Agência de Marketing Digital* *emanuel@descomplicar.pt | descomplicar.pt* diff --git a/crm-ops/skills/estrategia-marca/scripts/montar.py b/crm-ops/skills/estrategia-marca/scripts/montar.py new file mode 100755 index 0000000..8853736 --- /dev/null +++ b/crm-ops/skills/estrategia-marca/scripts/montar.py @@ -0,0 +1,86 @@ +#!/usr/bin/env python3 +"""Junta as partes de uma estratégia de marca num único markdown. + +Uso: + montar.py --partes DIR --intro intro.md --briefing briefing-llm.md --config marca.json --out estrategia.md + [--glossario glossario.md] [--complementos complementos.md] [--historico historico.md] + +- DIR contém parte-I.md ... parte-VIII.md (só os capítulos, `## N. Título`). +- intro.md: resumo executivo + "Sobre este documento" (títulos `# ...`). +- briefing-llm.md: a secção `## BRIEFING-LLM` completa (fica sempre em último). +- marca.json: chaves `frontmatter` (dict) e, opcional, `partes` ([[romano, nome], ...]). +Gera o anexo A (pontos a validar) a partir das marcas `[a validar: ...]`. +""" +import argparse, json, os, re, sys + +PARTES = [["I", "Contexto"], ["II", "Fundamentos da marca"], ["III", "Públicos"], + ["IV", "Identidade e expressão"], ["V", "Oferta e venda"], ["VI", "Comunicação e canais"], + ["VII", "Crescimento"], ["VIII", "Medição e implementação"]] + + +def yaml_value(v): + if isinstance(v, list): + return "[" + ", ".join(str(x) for x in v) + "]" + s = str(v) + return '"' + s.replace('"', '\\"') + '"' if re.search(r"[:#®·\-]", s) else s + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("--partes", required=True) + ap.add_argument("--intro", required=True) + ap.add_argument("--briefing", required=True) + ap.add_argument("--config", required=True) + ap.add_argument("--out", required=True) + ap.add_argument("--glossario") + ap.add_argument("--complementos") + ap.add_argument("--historico") + a = ap.parse_args() + + cfg = json.load(open(a.config, encoding="utf-8")) + fm = "---\n" + "".join(f"{k}: {yaml_value(v)}\n" for k, v in cfg.get("frontmatter", {}).items()) + "---\n\n" + doc = [fm, open(a.intro, encoding="utf-8").read().rstrip() + "\n\n"] + + for rom, nome in cfg.get("partes", PARTES): + p = os.path.join(a.partes, f"parte-{rom}.md") + if not os.path.exists(p): + sys.exit(f"Falta {p}") + t = open(p, encoding="utf-8").read().strip() + if re.search(r"^# ", t, re.M): + sys.exit(f"{p} tem títulos de nível 1; só o montar.py escreve as Partes") + doc.append(f"# Parte {rom}. {nome}\n\n{t}\n\n") + full = "".join(doc) + + pend, cap, seen, rows = [], None, set(), [] + for line in full.split("\n"): + m = re.match(r"^## (\d+)\. ", line) + if m: + cap = int(m.group(1)) + for v in re.findall(r"\[a validar:\s*([^\]]+)\]", line): + pend.append((cap or 0, v.strip().rstrip("."))) + for c, v in pend: + if (c, v.lower()) in seen: + continue + seen.add((c, v.lower())) + rows.append(f"| {c or '—'} | {v[0].upper() + v[1:]} |") + + anexos = ["# Anexos\n\n## A. Pontos a validar\n\n", + f"{len(rows)} pontos, por capítulo. Cada ponto fechado corrige-se no capítulo e sai desta lista.\n\n", + "| Cap. | O que falta confirmar |\n| --- | --- |\n", "\n".join(rows) or "| — | Nenhum |", "\n\n"] + extras = [(t, f) for t, f in [("Glossário", a.glossario), ("Complementos do sector", a.complementos), + ("Histórico de alterações", a.historico)] if f] + for letra, (titulo, f) in zip("BCD", extras): + anexos.append(f"## {letra}. {titulo}\n\n" + open(f, encoding="utf-8").read().strip() + "\n\n") + full += "".join(anexos) + + br = open(a.briefing, encoding="utf-8").read().strip() + if not br.startswith("## BRIEFING-LLM"): + sys.exit("briefing-llm.md tem de começar por '## BRIEFING-LLM'") + full += br + "\n" + open(a.out, "w", encoding="utf-8").write(full) + caps = len(re.findall(r"^## \d+\. ", full, re.M)) + print(f"{a.out}: {len(full.split())} palavras, {caps} capítulos, {len(rows)} pontos a validar") + + +if __name__ == "__main__": + main() diff --git a/crm-ops/skills/estrategia-marca/scripts/render_pdf.py b/crm-ops/skills/estrategia-marca/scripts/render_pdf.py new file mode 100755 index 0000000..e564c97 --- /dev/null +++ b/crm-ops/skills/estrategia-marca/scripts/render_pdf.py @@ -0,0 +1,134 @@ +#!/usr/bin/env python3 +"""Estratégia de marca (markdown) -> PDF A4 com a identidade DA MARCA em causa. + +Uso: render_pdf.py estrategia.md estrategia.pdf --config marca.json [--html saida.html] + +Requer: pandoc, google-chrome (ou chromium), pdfinfo. +O marca.json define cores, fontes, logótipo e textos da capa (ver assets/marca-descomplicar.json). +Regras aprendidas (17-10-2026): +- A4 sempre (nunca Letter). Margens 20/18 mm, numeração no rodapé. +- Fontes web subset (ex.: woff2 só latim básico) não têm €, → ou −; declarar uma + família de recurso SEPARADA (`fallback` no config) e acrescentá-la a todas as pilhas. + Não usar unicode-range na mesma família com intervalos de peso diferentes: o Chrome + escolhe a face pelo peso e perde o resto dos glifos. +- Confirmar com `pdffonts` que não aparecem Liberation/DejaVu (exceto mono) e ver uma + página de conteúdo renderizada, não só a capa. +- A secção BRIEFING-LLM vai no PDF como está (bloco yaml), por ser a última secção. +""" +import argparse, json, re, shutil, subprocess, tempfile, os + +TPL = """ +$title$ + + + +$body$ + +""" + + +def face(f): + s = f"@font-face{{font-family:'{f['family']}';src:url('file://{f['src']}');" + s += f"font-weight:{f.get('weight', '100 900')};font-style:{f.get('style', 'normal')};" + if f.get("unicode_range"): + s += f"unicode-range:{f['unicode_range']};" + return s + "}" + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("src") + ap.add_argument("out") + ap.add_argument("--config", required=True) + ap.add_argument("--html") + a = ap.parse_args() + c = json.load(open(a.config, encoding="utf-8")) + + md = open(a.src, encoding="utf-8").read() + md = re.sub(r"\A---\n.*?\n---\n", "", md, flags=re.S) + with tempfile.TemporaryDirectory() as tmp: + tpl = os.path.join(tmp, "tpl.html") + open(tpl, "w", encoding="utf-8").write(TPL) + body = subprocess.run( + ["pandoc", "-f", "gfm+attributes", "-t", "html5", "--toc", "--toc-depth=2", "--standalone", + "--template", tpl, "--metadata", f"title={c['titulo_documento']}", "--metadata", "lang=pt-PT"], + input=md, capture_output=True, text=True, check=True).stdout + + marca = c["marca"] # ex.: "Descomplicar®" + if marca.endswith("®"): + base = re.escape(marca[:-1]) + body = re.sub(rf"(?®', body) + body = re.sub(r"\[a validar:([^\]]*)\]", r'[a validar:\1]', body) + + T, X, FB = c["fonte_titulos"], c["fonte_texto"], c.get("fallback", "sans-serif") + k = c["cores"] # escura, clara_texto, primaria, acento_texto, suave, linha, alternada, aviso_fundo, aviso_texto + faces = "\n".join(face(f) for f in c.get("fontes", [])) + css = f"""{faces} +@page{{size:A4;margin:20mm 18mm 20mm 18mm; + @bottom-left{{content:"{c['rodape']}";font:8.5pt '{X}',{FB};color:{k['texto_secundario']}}} + @bottom-right{{content:counter(page);font:600 8.5pt '{T}',{FB};color:{k['acento_texto']}}}}} +@page capa{{margin:0;@bottom-left{{content:none}}@bottom-right{{content:none}}}} +html{{-webkit-print-color-adjust:exact;print-color-adjust:exact}} +body{{font-family:'{X}',{FB};font-size:10.2pt;line-height:1.55;color:{k['texto']};margin:0}} +sup.reg{{font-size:.45em;vertical-align:super;line-height:0;margin-left:.02em}} +.capa{{page:capa;height:297mm;width:210mm;background:{k['escura']};color:{k['clara_texto']};position:relative;break-after:page;box-sizing:border-box;padding:34mm 22mm}} +.capa svg,.capa img{{width:56mm;height:auto;display:block}} +.capa .eyebrow{{font:700 9pt '{T}',{FB};letter-spacing:.14em;text-transform:uppercase;color:{k['primaria']};margin-top:52mm}} +.capa h1{{font:300 40pt/1.05 '{T}',{FB};text-transform:uppercase;margin:6mm 0 8mm;color:{k['clara_texto']};border:0;padding:0;break-before:auto}} +.capa .slogan{{font:700 18pt '{T}',{FB};color:{k['primaria']}}} +.capa .meta{{position:absolute;left:22mm;right:22mm;bottom:24mm;border-top:1px solid {k['primaria']};padding-top:5mm;font-size:9.5pt;color:{k['clara_texto']};opacity:.75;display:flex;justify-content:space-between}} +nav#TOC{{break-after:page}} +nav#TOC::before{{content:"Índice";display:block;font:700 22pt '{T}',{FB};margin:0 0 6mm}} +nav#TOC ul{{list-style:none;padding-left:0;margin:0}} +nav#TOC > ul > li{{margin-top:3.2mm;font:700 10pt '{T}',{FB};color:{k['acento_texto']};text-transform:uppercase;letter-spacing:.05em}} +nav#TOC > ul > li > ul > li{{font:400 9.6pt '{X}',{FB};color:{k['texto']};text-transform:none;letter-spacing:0;padding-left:4mm;margin-top:.6mm}} +nav#TOC a{{color:inherit;text-decoration:none}} +h1{{font:300 26pt/1.1 '{T}',{FB};text-transform:uppercase;letter-spacing:.02em;break-before:page;margin:0 0 8mm;padding-bottom:4mm;border-bottom:3px solid {k['primaria']}}} +h2{{font:700 17pt/1.2 '{T}',{FB};margin:9mm 0 3mm;break-after:avoid}} +h3{{font:600 12.5pt/1.25 '{T}',{FB};margin:6mm 0 2mm;break-after:avoid}} +h4{{font:600 10.5pt '{T}',{FB};margin:4mm 0 1.5mm;break-after:avoid;color:{k['acento_texto']}}} +p{{margin:0 0 2.6mm;orphans:3;widows:3}} +ul,ol{{margin:0 0 3mm;padding-left:6mm}} li{{margin:.6mm 0}} +a{{color:{k['acento_texto']}}} +blockquote{{margin:3mm 0;padding:3mm 5mm;background:{k['suave']};border-left:4px solid {k['primaria']};font-size:10.6pt}} +blockquote p:last-child{{margin:0}} +table{{border-collapse:collapse;width:100%;margin:2mm 0 4mm;font-size:8.8pt}} +tr{{break-inside:avoid}} +th{{background:{k['escura']};color:{k['clara_texto']};font:600 8.4pt '{T}',{FB};text-align:left;padding:2mm 2.4mm}} +td{{border-bottom:1px solid {k['linha']};padding:1.8mm 2.4mm;vertical-align:top}} +tr:nth-child(even) td{{background:{k['alternada']}}} +code,pre{{font-size:8.4pt;background:{k['suave']};border-radius:2px}} +code{{padding:0 1mm}} pre{{padding:3mm;white-space:pre-wrap}} +hr{{border:0;border-top:1px solid {k['linha']};margin:5mm 0}} +.av{{background:{k['aviso_fundo']};color:{k['aviso_texto']};padding:0 1mm;border-radius:2px;font-size:.92em}} +""" + logo = "" + if c.get("logo_capa"): + logo = open(c["logo_capa"], encoding="utf-8").read() + logo = re.sub(r"<\?xml[^>]*>", "", logo) + capa = (f'
{logo}
{c["capa_eyebrow"]}
' + f'

{c["capa_titulo"]}

{c.get("capa_slogan", "")}
' + f'
{c["capa_assinatura"]}{c["capa_data"]}
') + if marca.endswith("®"): + capa = capa.replace(marca, f'{marca[:-1]}®') + html = body.replace("", f"").replace("", capa) + hp = a.html or os.path.join(tmp, "doc.html") + open(hp, "w", encoding="utf-8").write(html) + chrome = shutil.which("google-chrome") or shutil.which("google-chrome-stable") or shutil.which("chromium") + subprocess.run([chrome, "--headless=new", "--no-sandbox", "--disable-gpu", "--no-pdf-header-footer", + "--generate-pdf-document-outline", "--virtual-time-budget=20000", + f"--print-to-pdf={os.path.abspath(a.out)}", "file://" + os.path.abspath(hp)], + check=True, capture_output=True, timeout=600) + info = subprocess.run(["pdfinfo", a.out], capture_output=True, text=True).stdout + fonts = subprocess.run(["pdffonts", a.out], capture_output=True, text=True).stdout + print("\n".join(l for l in info.splitlines() if l.startswith(("Pages", "Page size")))) + bad = sorted({re.sub(r"^[A-Z]{6}\+", "", l.split()[0]) for l in fonts.splitlines()[2:] + if re.search(r"Liberation|DejaVuSans(?!Mono)|Nimbus", l)}) + if bad: + print("AVISO: fontes de recurso do sistema no PDF:", ", ".join(bad)) + + +if __name__ == "__main__": + main() diff --git a/crm-ops/skills/expense/SKILL.md b/crm-ops/skills/expense/SKILL.md index 8c91f8e..e1a5747 100644 --- a/crm-ops/skills/expense/SKILL.md +++ b/crm-ops/skills/expense/SKILL.md @@ -1,7 +1,6 @@ --- name: expense description: Gestao de despesas Desk CRM com PDF obrigatorio. Registar, categorizar e analisar despesas com verificacao de duplicados por reference_no, upload SFTP e arquivo mensal automatico. -layer: wiki --- # /expense - Gestao de Despesas @@ -140,4 +139,62 @@ Para protocolo completo de processamento de tickets de contabilidade: ver `refer **Categorias:** 1. Criar categoria sem listar existentes primeiro -2. Assumir qu \ No newline at end of file +2. Assumir que categoria nao existe +3. Criar categoria com nome similar a existente + +**Despesas:** +4. Criar despesa sem category_id +5. Nao validar data (formato YYYY-MM-DD) +6. Criar despesa sem verificar duplicados primeiro (3 camadas obrigatorias) +7. Criar despesa sem reference_no (chave primaria de dedup) + +**Valores de PDFs:** +8. Assumir que ficheiros com nomes semelhantes tem o mesmo valor +9. SEMPRE ler CADA PDF individualmente para extrair o valor real + +**Tickets:** +10. Processar ticket sem verificar anexos PDF +11. Assumir que ticket com recibo = despesa nao lancada + +--- + +## Checklist Pre-Operacao + +- [ ] Listar categorias existentes +- [ ] Validar categoria correcta +- [ ] Extrair reference_no do PDF/factura +- [ ] Verificar duplicados (3 camadas) +- [ ] Confirmar dados com utilizador +- [ ] Usar formato data YYYY-MM-DD +- [ ] Incluir reference_no no create_expense +- [ ] Incluir nota descritiva + +--- + +## Referencias + +- `references/category-mapping.md` - Mapeamento fornecedores, emails, padroes PDF, campos, moedas, SQL +- `references/ticket-processing.md` - Protocolo completo de processamento de tickets +- `references/changelog.md` - Historico de alteracoes + + + +--- + +## Self-Healing + +Antes de executar, ler `~/.claude-work/healing/expense.jsonl` (se existir). Cada linha é um padrão de erro conhecido: + +```json +{"date":"YYYY-MM-DD","issue":"descrição do problema","fix":"como evitar","source":"user|auto"} +``` + +Se encontrares um padrão relevante ao contexto actual, aplica o fix preventivamente. Após cada erro ou correcção do utilizador nesta skill, **adicionar nova linha** ao healing log com o padrão aprendido. + +--- + +**Criado:** 2026-02-05 | **Actualizado:** 2026-03-30 | Fix: dedup 3 camadas com reference_no (DES-137) + + +## Healing Log + diff --git a/crm-ops/skills/invoice/SKILL.md b/crm-ops/skills/invoice/SKILL.md index 87f2c46..7e4e537 100644 --- a/crm-ops/skills/invoice/SKILL.md +++ b/crm-ops/skills/invoice/SKILL.md @@ -2,7 +2,6 @@ name: invoice description: Gestão de facturação Desk CRM. Criar facturas, converter estimates, facturar timesheets, registar pagamentos e listar facturas vencidas. disable-model-invocation: true -layer: wiki --- # /invoice v1.0 - Gestão de Facturação @@ -237,3 +236,32 @@ Acções: ## Integração +- **/crm 360:** Mostra facturas pendentes do cliente +- **/today:** Alerta de facturas vencidas +- **/report weekly:** Inclui facturação emitida/recebida + +--- + +## Changelog + +### v1.0.0 (2026-02-05) +- Versão inicial +- Criar, enviar, pagamentos +- Facturar timesheets +- Relatório de vencidas + +--- + +*Skill v1.0.0 | 2026-02-05 | 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ós cada erro corrigido.* diff --git a/crm-ops/skills/orcamento/SKILL-light.md b/crm-ops/skills/orcamento/SKILL-light.md index b450495..2678c5f 100644 --- a/crm-ops/skills/orcamento/SKILL-light.md +++ b/crm-ops/skills/orcamento/SKILL-light.md @@ -2,7 +2,6 @@ name: orcamento description: Criação de orçamentos Descomplicar baseados nos itens oficiais do Desk CRM. Versão light para heartbeats. disable-model-invocation: true -layer: wiki --- # Orçamento — Referência Rápida diff --git a/crm-ops/skills/orcamento/SKILL.md b/crm-ops/skills/orcamento/SKILL.md index 393b1eb..2eba4a2 100644 --- a/crm-ops/skills/orcamento/SKILL.md +++ b/crm-ops/skills/orcamento/SKILL.md @@ -2,7 +2,6 @@ name: orcamento description: Criação sistemática de orçamentos Descomplicar baseados nos itens oficiais do Desk CRM. Suporta StarterWP, CorporateWP, CareWP, eCommerceWP, Marketing 360, Manutenção, AcceleratorX, DeskCRM e Chatbots. Variantes -MEN (mensal) e -TRI (trimestral). disable-model-invocation: true -layer: wiki --- # Skill /orcamento - Criacao Sistematica de Orcamentos @@ -115,4 +114,413 @@ ANTES de executar, consultar notebooks para contexto especializado: | Notebook | ID | Consultar quando | |----------|-----|-----------------| -| Estratégia e Empreendedorismo | 7 \ No newline at end of file +| Estratégia e Empreendedorismo | 79d43410 | Para enquadramento estratégico de preços | + +``` +mcp__notebooklm__notebook_query({ + notebook_id: "79d43410-0e29-4be1-881d-84db6bdc239a", + query: "" +}) +``` + +Integrar insights do NotebookLM nas recomendações e decisões. + +### Procedimentos Relacionados +- `PROC-Catalogo-Codificacao-Produtos.md` — Codificação e catálogo de produtos +- `PROC-CRM-Operacoes.md` — Operações CRM padrão + +--- + +## Protocolo + +### Sintaxe + +``` +/orcamento [cliente] [tipo] [-MEN|-TRI] +``` + +**Parametros:** +- `cliente` - Nome ou ID do cliente (opcional, sera solicitado se omitido) +- `tipo` - Tipo de orcamento (opcional, sera apresentado menu se omitido) +- `-MEN` - Variante mensal: usa itens com unit "mensalidade" e calcula valor/mes +- `-TRI` - Variante trimestral: usa itens com unit "trimestral" e calcula valor/trimestre +- (sem flag) - Comportamento actual: item base (Investimento/Projeto/Anual) + +**Tipos disponiveis:** +| Codigo | Tipo | Grupo CRM | +|--------|------|-----------| +| `starter` | StarterWP | Websites | +| `corporate` | CorporateWP | Websites | +| `care` | CareWP (Clinicas) | Websites | +| `ecom` | eCommerceWP | Websites | +| `mkt` | Marketing Digital 360 | Marketing | +| `man` | Manutencao | Suporte | +| `deskcrm` | DeskCRM | DeskCRM | +| `chatbot` | Chatbot | Chatbots | +| `acceleratorx` | AcceleratorX | Tecnologia | + +### Fase 1: Identificacao do Cliente + +1. Se cliente fornecido, pesquisar no CRM: + ``` + mcp__desk-crm-v3__search_customers query="[nome]" fields="company,vat" + ``` + +2. Se nao encontrado ou nao fornecido, solicitar dados: + - Nome da empresa + - NIF (opcional) + - Email contacto + +3. Validar cliente existe ou criar novo: + ``` + mcp__desk-crm-v3__create_customer company="..." vat="..." ... + ``` + +### Fase 2: Seleccao de Template + +1. Se tipo fornecido, carregar template correspondente +2. Se nao fornecido, apresentar menu interactivo: + - StarterWP | CorporateWP | CareWP | eCommerceWP + - Marketing 360 | Manutencao + - DeskCRM | Chatbot | AcceleratorX + +### Fase 3: Consultar Precos no CRM + +**OBRIGATORIO**: Consultar precos actualizados no Desk CRM antes de calcular. + +#### Sem variante (comportamento actual) +```bash +# Buscar preco do pacote base +mysql -u root ealmeida_desk24 -e " + SELECT description, rate, unit FROM tblitems + WHERE group_id = [GROUP_ID] + AND description LIKE '%[PACOTE]%' + AND unit NOT IN ('mensalidade','trimestral','anuidade') + ORDER BY description;" +``` + +#### Com `-MEN` (variante mensal) +```bash +# Buscar itens base (setup/pontuais - mantêm-se iguais) +mysql -u root ealmeida_desk24 -e " + SELECT description, rate, unit FROM tblitems + WHERE group_id = [GROUP_ID] + AND description LIKE '%[PACOTE]%' + AND unit NOT IN ('mensalidade','trimestral','anuidade') + ORDER BY description;" + +# Buscar itens recorrentes na variante mensal +mysql -u root ealmeida_desk24 -e " + SELECT description, rate, unit FROM tblitems + WHERE group_id = [GROUP_ID] + AND description LIKE 'Mensalidade%[PACOTE]%' + ORDER BY description;" +``` + +#### Com `-TRI` (variante trimestral) +```bash +# Buscar itens base (setup/pontuais - mantêm-se iguais) +mysql -u root ealmeida_desk24 -e " + SELECT description, rate, unit FROM tblitems + WHERE group_id = [GROUP_ID] + AND description LIKE '%[PACOTE]%' + AND unit NOT IN ('mensalidade','trimestral','anuidade') + ORDER BY description;" + +# Buscar itens recorrentes na variante trimestral +mysql -u root ealmeida_desk24 -e " + SELECT description, rate, unit FROM tblitems + WHERE group_id = [GROUP_ID] + AND description LIKE 'Trimestral%[PACOTE]%' + ORDER BY description;" +``` + +Ou via MCP: +``` +mcp__desk-crm-v3__price_management action="get_pricing_insights" params={"group": "[GRUPO]", "search": "[PACOTE]"} +``` + +### Fase 4: Personalizacao + +1. Apresentar questoes de personalizacao especificas do tipo +2. Adicionar funcionalidades conforme requisitos +3. Para cada funcionalidade, buscar item correspondente no CRM + +### Fase 5: Geracao do Orcamento + +1. Calcular valores finais: + - Subtotal por item (precos do CRM) + - IVA 23% + - Total + - Recorrencia (anuidade, trimestral ou mensal conforme variante) + +2. Ajustar items conforme variante: + - **Sem flag**: Itens base + anuidade separada + - **`-MEN`**: Itens setup + itens "Mensalidade ..." do CRM (unit: "mensalidade") + - **`-TRI`**: Itens setup + itens "Trimestral ..." do CRM (unit: "trimestral") + +3. Criar estimate no CRM: + ``` + mcp__desk-crm-v3__create_estimate + client_id=[id] + date=[hoje] + expiry_date=[hoje + 30 dias] + items=[items calculados] + terms="[termos ajustados a variante]" + ``` + +4. Termos ajustados por variante: + - **Sem flag**: "Condicoes de Pagamento: 50% na adjudicacao + 50% na entrega" + - **`-MEN`**: "Condicoes de Pagamento: Setup - 50% na adjudicacao + 50% na entrega | Recorrencia - facturacao mensal antecipada" + - **`-TRI`**: "Condicoes de Pagamento: Setup - 50% na adjudicacao + 50% na entrega | Recorrencia - facturacao trimestral antecipada" + +5. Apresentar resumo ao utilizador com link para CRM + +## Pacotes Principais (referencia rapida) + +**Nota**: Estes valores sao referencia. Consultar SEMPRE o CRM para precos actualizados. + +### Websites +| Produto | Setup | Anuidade | Prazo | +|---------|-------|----------|-------| +| StarterWP | 700 | 250 | 3-5 sem | +| CorporateWP | 900 | 299 | 4-6 sem | +| eCommerceWP | 1100 | 349 | 7-9 sem | +| ChallengeWP | 700 | 250 | 8-10 sem | +| CareWP | 1300 | 350 | 4-6 sem | + +### DeskCRM +| Produto | Setup | Anuidade | +|---------|-------|----------| +| DeskCRM Starter | (ver CRM) | 400 | +| DeskCRM Profissional | (ver CRM) | 800 | +| DeskCRM Avancado | (ver CRM) | 1500 | +| DeskCRM Enterprise | (ver CRM) | 3000 | + +### AcceleratorX +| Produto | Setup | +|---------|-------| +| WP ProCMS | 650 | +| e-Commerce | 750 | +| Membership | 450 | +| Booking | 450 | +| Care | 750 | +| Meet | 650 | +| School Manager | 850 | + +### Chatbots +| Produto | Setup | +|---------|-------| +| Chatbot Basico | 350 | +| Chatbot Avancado | 850 | +| Chatbot Care | 850 | + +### Design/Branding +| Produto | Valor | +|---------|-------| +| Branding WOW Digital | 400 | +| Branding WOW Essencial | 850 | +| Branding Completo | 1100 | +| Pack Rebranding | 1500 | +| Pack Premium 360 | 5000 | + +## Estrutura de Items para API + +Cada item do orcamento segue o formato: + +```json +{ + "description": "Descricao do servico", + "qty": 1, + "rate": 700, + "unit": "un" +} +``` + +**Unidades:** +- `un` - Unidade (projecto/item unico) +- `mes` ou `mensalidade` - Mes (servico recorrente mensal, usado com `-MEN`) +- `trimestral` - Trimestre (servico recorrente trimestral, usado com `-TRI`) +- `ano` ou `anuidade` - Ano (anuidade, comportamento por defeito) + +## Termos e Condicoes Padrao + +``` +CONDICOES DE PAGAMENTO + +1. Projectos: 50% na adjudicacao + 50% na entrega +2. Servicos recorrentes: facturacao mensal antecipada + +VALIDADE + +Orcamento valido por 30 dias a partir da data de emissao. + +ANUIDADE + +A anuidade inclui: +- Alojamento Premium SSD NVMe +- Certificado SSL +- Actualizacoes de seguranca +- Suporte tecnico basico + +Descomplicar Crescimento Digital +NIF: 514 623 168 | descomplicar.pt +``` + +## Checklist de Execucao + +- [ ] Cliente identificado/criado no CRM +- [ ] Tipo de orcamento seleccionado +- [ ] Precos consultados no CRM (tblitems) +- [ ] Funcionalidades adicionais identificadas +- [ ] Valores calculados (subtotal + IVA) +- [ ] Recorrencia calculada (anuidade/trimestral/mensal conforme variante) +- [ ] Estimate criado no CRM (status: Draft) +- [ ] Resumo apresentado ao utilizador + +## MCPs Utilizados + +``` +mcp__desk-crm-v3__search_customers - Pesquisar cliente +mcp__desk-crm-v3__get_customer - Obter detalhes cliente +mcp__desk-crm-v3__create_customer - Criar cliente novo +mcp__desk-crm-v3__create_estimate - Criar orcamento +mcp__desk-crm-v3__get_estimates - Listar orcamentos existentes +mcp__desk-crm-v3__price_management - Consultar precos e itens +``` + +## Formulas de Calculo + +### Website Simples +``` +Total = Base + Funcionalidades + Conteudos +Anuidade = Anuidade_Base + Anuidades_Funcionalidades +``` + +### Exemplo: Website Corporativo com Agendamento (sem variante) +``` +CorporateWP: 900 (item CRM: "CorporateWP") +EasyAppointment: 175 (item CRM: "EasyAppointment") +Chat da Pagina: 50 (item CRM: "Chat da Pagina") +Pixel + GTM: 50 (items CRM: "Configuracao Pixel Facebook" + "Configuracao GTM") +--------------------------------- +Subtotal: 1175 +IVA 23%: 270.25 +TOTAL: 1445.25 + +Anuidade: 299 + 50 + 50 = 399 (items CRM com unit "anuidade") +``` + +### Exemplo: Mesmo orcamento com `-MEN` +``` +SETUP (pagamento unico): +CorporateWP: 900 +EasyAppointment: 175 +Chat da Pagina: 50 +Pixel + GTM: 50 +--------------------------------- +Subtotal Setup: 1175 +IVA 23%: 270.25 +TOTAL Setup: 1445.25 + +RECORRENCIA MENSAL (items CRM com prefixo "Mensalidade"): +Mensalidade CorporateWP: 29.90 (item CRM: "Mensalidade CorporateWP") +Mensalidade EasyAppointment: 5.90 (item CRM: "Mensalidade EasyAppointment") +Mensalidade Chat da Pagina: 4.90 (item CRM: "Mensalidade Chat da Pagina") +--------------------------------- +Subtotal Mensal: 40.70 +IVA 23%: 9.36 +TOTAL Mensal: 50.06/mes + +Nota: precos mensais sao exemplificativos - consultar CRM para valores reais. +``` + +## Referencias + +- `references/pricing-guide.md` - Tabela de precos rapida (referencia, nao fonte de verdade) +- `templates/website-corporativo.md` - Templates StarterWP, CorporateWP, CareWP +- `templates/e-commerce.md` - Template eCommerceWP +- `templates/marketing-digital.md` - Template Marketing 360 +- `templates/manutencao.md` - Template Manutencao + +--- + +## Datasets Dify (Consulta Complementar) + +| Dataset | ID | Prioridade | +|---------|----|-----------:| +| **Servicos Descomplicar** | `bd65f36e-6004-4584-b478-129b2c21b4d2` | 1 | +| **Vendas** | `a7ba6005-517c-41ab-ac5e-da1c1a1c62ef` | 1 | +| **Marketing Digital** | `c1ec779f-4cb1-4ecf-ba11-6b39b93d4e24` | 2 | +| **Desenvolvimento de WebSites** | `c8489151-de94-42b2-8cee-c0b961cfac6d` | 2 | + +### Quando Consultar + +- Justificar precos ao cliente +- Comparar funcionalidades entre pacotes +- Criar proposta de valor diferenciada +- Tecnicas de negociacao e fechamento + +--- + +## Instrumentacao Automatica + +### Baseline + +| Metrica | Valor | +|---------|-------| +| Tempo baseline | 30 min | +| Tempo target | 15 min | +| Melhoria esperada | -50% | + +### Query para Gravar (executar no final da skill) + +```sql +INSERT INTO tblskill_agent_metrics ( + type, name, duration_ms, status, staff_id, + kb_consulted, kb_cache_hit, tool_calls, project_id +) VALUES ( + 'skill', '/orcamento', {DURACAO_MS}, '{STATUS}', 25, + {KB_CONSULTADO}, {CACHE_HIT}, {TOOL_CALLS}, {PROJECT_ID} +); +``` + +--- + +## Changelog + +### v4.1.0 (2026-03-12) +- Suporte para variantes `-MEN` (mensal) e `-TRI` (trimestral) na sintaxe +- Fase 3 actualizada com queries especificas por variante +- Fase 5 actualizada com termos de pagamento ajustados por variante +- Mapeamento de variantes documentado (pesquisa por prefixo no CRM) +- Exemplo adicional com `-MEN` para demonstrar separacao setup/recorrencia +- Retrocompativel: sem flag = comportamento anterior (item base) + +### v4.0.0 (2026-03-05) +- **BREAKING**: Fonte de verdade migrada de CSVs para Desk CRM (tblitems + tblitems_groups) +- Removidas referencias a tabela-geral.csv, items-subscricao.csv, chatbots-precos.csv, items-faturacao-deskcrm.csv +- Adicionados grupos DeskCRM, Chatbots, AcceleratorX como tipos de orcamento +- Protocolo actualizado para consultar precos via MCP/SQL em vez de CSVs +- Tabela de referencia rapida mantida mas marcada como "nao fonte de verdade" +- Adicionada documentacao de variantes de facturacao (Investimento/Anuidade/Trimestral/Mensalidade) + +### v3.1.0 (2026-02-03) +- Instrumentacao automatica adicionada +- Datasets Dify integrados + +--- + +**Versao**: 4.1.0 | **Data**: 2026-03-12 | **Fonte de Verdade**: Desk CRM (tblitems) + +--- + +## 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/crm-ops/skills/proposal-deck/SKILL.md b/crm-ops/skills/proposal-deck/SKILL.md index 3974c67..f0dbcb0 100644 --- a/crm-ops/skills/proposal-deck/SKILL.md +++ b/crm-ops/skills/proposal-deck/SKILL.md @@ -1,7 +1,6 @@ --- name: proposal-deck description: Geracao de apresentacoes PPTX de propostas comerciais profissionais com branding Descomplicar. Integra dados do CRM, tabela de precos e template curado de 16 layouts. -layer: wiki --- # Skill /proposal-deck - Apresentacoes de Propostas Comerciais @@ -134,4 +133,284 @@ Para projectos simples, orcamentos rapidos. | 8 | encerramento | Branding Descomplicar | #### Proposta Standard (12 slides) -Para projectos \ No newline at end of file +Para projectos de media complexidade (websites, marketing). + +| Ordem | Layout | Conteudo | +|:-----:|--------|----------| +| 1 | capa | Titulo + cliente + ano | +| 2 | sobre-nos | Apresentacao Descomplicar | +| 3 | divisor-seccao | "Desafio" | +| 4 | objectivos | Objectivos do cliente | +| 5 | processo-3-passos | Metodologia | +| 6 | fases-3-blocos | Fases do projecto | +| 7 | divisor-seccao | "Solucao" | +| 8 | beneficios-6 | Beneficios da solucao | +| 9 | deliverables | Escopo detalhado | +| 10 | timeline-etapas | Cronograma com precos | +| 11 | contacto | Dados do gestor | +| 12 | encerramento | Branding Descomplicar | + +#### Proposta Completa (16 slides) +Para projectos complexos, concursos, clientes enterprise. + +Usa todos os 16 layouts na ordem numerica original. + +### Fase 3: Geracao do PPTX + +**Directorio de trabalho:** `~/.claude-work/proposal-[cliente-slug]/` + +```bash +# 1. Criar directorio e copiar template +mkdir -p ~/.claude-work/proposal-[slug]/ +cp "/media/ealmeida/Dados/Hub/90-Templates/Comercial/descomplicar-proposal-template.pptx" \ + ~/.claude-work/proposal-[slug]/template.pptx + +# 2. Descompactar template +python3 ~/.claude/plugins/marketplaces/descomplicar-plugins/design-media/skills/pptx-generator/scripts/office/unpack.py \ + ~/.claude-work/proposal-[slug]/template.pptx \ + ~/.claude-work/proposal-[slug]/unpacked/ + +# 3. Editar slides XML (ver seccao "Edicao de Conteudo XML") + +# 4. Remover slides nao necessarios de presentation.xml +# (alterar rIdX refs e apagar ficheiros slideN.xml correspondentes) + +# 5. Limpar XMLs +python3 ~/.claude/plugins/marketplaces/descomplicar-plugins/design-media/skills/pptx-generator/scripts/clean.py \ + ~/.claude-work/proposal-[slug]/unpacked/ + +# 6. Recompactar +python3 ~/.claude/plugins/marketplaces/descomplicar-plugins/design-media/skills/pptx-generator/scripts/office/pack.py \ + ~/.claude-work/proposal-[slug]/unpacked/ \ + ~/.claude-work/proposal-[slug]/proposta-[slug].pptx \ + --original ~/.claude-work/proposal-[slug]/template.pptx +``` + +### Edicao de Conteudo XML + +Cada slide e um ficheiro `ppt/slides/slideN.xml`. Localizar placeholders pelo texto visivel e substituir: + +| Placeholder | Substituir por | Exemplo | +|-------------|----------------|---------| +| `[TITULO_PROPOSTA]` | Nome do servico proposto | "Website Corporativo" | +| `[SUBTITULO]` | Nome do cliente | "Para Empresa XYZ" | +| `[ANO]` | Ano corrente | "2026" | +| `[OBJECTIVO_N]` | Objectivo N do cliente | "Aumentar presenca online" | +| `[FASE_N_TITULO]` | Titulo da fase N | "Fase 1: Descoberta" | +| `[FASE_N_DESC]` | Descricao da fase N | "Analise de requisitos..." | +| `[DELIVERABLE_N]` | Item do escopo | "Website responsivo" | +| `[PRECO]` | Valor formatado | "1.200 EUR" | +| `[PRECO_TOTAL]` | Valor total | "2.500 EUR + IVA" | +| `[TIMELINE_N]` | Etapa do cronograma | "Semana 1-2" | +| `[GESTOR_NOME]` | Nome do gestor | "Emanuel Almeida" | +| `[GESTOR_EMAIL]` | Email do gestor | "emanuel@descomplicar.pt" | +| `[GESTOR_TEL]` | Telefone | "911 510 005" | + +**Tecnica XML:** Localizar `` tags dentro de `` runs. Substituir texto preservando formatacao: + +```python +# Exemplo: substituir texto num slide +import re + +def replace_placeholder(xml_content, placeholder, value): + """Substituir placeholder preservando formatacao XML.""" + # Placeholders podem estar fragmentados em multiplos tags + # Usar regex para localizar e substituir + return xml_content.replace(placeholder, value) +``` + +**Regra critica:** Nunca alterar atributos de formatacao (``, ``). Apenas substituir conteudo textual dentro de ``. + +### Fase 4: Entrega + +1. **Guardar PPTX final:** + ``` + Hub/03-Propostas/[cliente]/proposta-[servico]-[data].pptx + ``` + +2. **Upload para Google Drive** (opcional): + ``` + mcp__google-workspace__drive_upload_file + file_path="~/.claude-work/proposal-[slug]/proposta-[slug].pptx" + folder_id="[pasta-cliente-drive]" + ``` + +3. **Registar no CRM** (se nao existir estimate): + ``` + mcp__desk-crm-v3__create_estimate + client_id=[id] + date=[hoje] + expiry_date=[hoje + 30 dias] + items=[items] + ``` + +4. **Limpar temporarios:** + ```bash + rm -rf ~/.claude-work/proposal-[slug]/ + ``` + +--- + +## Exemplos de Propostas Tipicas + +### Website Corporativo (CorporateWP) + +**Tipo:** Standard (12 slides) +**Servico:** CorporateWP +**Slides seleccionados:** capa, sobre-nos, divisor, objectivos, processo-3-passos, fases-3-blocos, divisor, beneficios-6, deliverables, timeline-etapas, contacto, encerramento + +**Conteudo tipico:** +- **Objectivos:** Presenca profissional online, geracao de leads, credibilidade digital +- **3 Passos:** Descoberta -> Desenvolvimento -> Lancamento +- **3 Fases:** Analise e Conteudo (S1-2) -> Design e Desenvolvimento (S3-5) -> Testes e Lancamento (S6) +- **6 Beneficios:** Design responsivo, SEO optimizado, painel intuitivo, SSL incluido, suporte dedicado, performance rapida +- **Deliverables:** Website responsivo, 5-8 paginas, formularios, integracao redes sociais, Google Analytics, formacao +- **Timeline:** 4-6 semanas, 900 EUR + IVA, anuidade 299 EUR + +### Marketing 360 + +**Tipo:** Completa (16 slides) +**Servico:** Marketing Digital 360 +**Slides seleccionados:** todos os 16 + +**Conteudo tipico:** +- **Objectivos:** Aumentar visibilidade, gerar leads qualificados, ROI mensuravel, posicionamento digital +- **4 Pilares (engrenagens):** SEO, Redes Sociais, Publicidade Online, Email Marketing +- **Processo:** Auditoria -> Estrategia -> Execucao +- **6 Beneficios:** Mais trafego, leads qualificados, brand awareness, ROI mensuravel, relatorios mensais, equipa dedicada +- **Deliverables:** Auditoria inicial, plano estrategico, gestao redes sociais, campanhas Ads, relatorios mensais, reunioes quinzenais +- **Timeline:** Ongoing, setup 500-1500 EUR, mensalidade 300-800 EUR + +### SEO / Optimizacao + +**Tipo:** Standard (12 slides) +**Servico:** Pack SEO +**Slides seleccionados:** capa, sobre-nos, divisor, objectivos, processo-3-passos, grid-4-cards, divisor, detalhe-servico, deliverables, pack-pricing, contacto, encerramento + +**Conteudo tipico:** +- **Objectivos:** Melhorar posicionamento Google, aumentar trafego organico, ultrapassar concorrencia +- **3 Passos:** Auditoria Tecnica -> Optimizacao On-Page -> Link Building +- **4 Cards:** Pesquisa Keywords, SEO Tecnico, Conteudo Optimizado, Relatorios Mensais +- **Deliverables:** Auditoria inicial, optimizacao 10-20 paginas, blog mensal, relatorio posicoes, Google Search Console +- **Pricing:** Mensalidade 300-600 EUR conforme pack + +--- + +## MCPs Utilizados + +``` +mcp__desk-crm-v3__search_customers - Pesquisar cliente +mcp__desk-crm-v3__get_customer - Obter detalhes cliente +mcp__desk-crm-v3__get_estimates - Verificar orcamentos existentes +mcp__desk-crm-v3__create_estimate - Registar estimate no CRM +mcp__desk-crm-v3__price_management - Consultar precos oficiais +mcp__google-workspace__drive_upload_file - Upload para Google Drive +mcp__mcp-time__current_time - Data/hora actual +``` + +--- + +## Checklist de Execucao + +- [ ] Cliente identificado no CRM +- [ ] Dados recolhidos (objectivos, servicos, precos) +- [ ] Tipo de proposta seleccionado (minima/standard/completa) +- [ ] Layouts seleccionados e conteudo definido +- [ ] Template copiado para ~/.claude-work/ +- [ ] PPTX descompactado +- [ ] Slides editados com dados do cliente +- [ ] Slides desnecessarios removidos +- [ ] XMLs limpos (clean.py) +- [ ] PPTX recompactado e validado +- [ ] Ficheiro guardado em Hub/03-Propostas/[cliente]/ +- [ ] Temporarios limpos +- [ ] Estimate registado no CRM (se aplicavel) + +--- + +## Anti-Patterns + +| Fazer | NAO Fazer | +|-------|-----------| +| Personalizar cada slide com dados reais do cliente | Usar placeholders genericos ou "Lorem ipsum" | +| Consultar CRM para precos actualizados | Inventar precos de memoria | +| Seleccionar layouts relevantes para o servico | Incluir todos os 16 slides quando 8 bastam | +| Manter branding Descomplicar (cores, fontes, logo) | Alterar formatacao XML (cores, tamanhos, posicoes) | +| Guardar em Hub/03-Propostas/ com nome descritivo | Deixar ficheiros em ~/.claude-work/ | +| Usar slug sem espacos no nome do ficheiro | Espacos ou caracteres especiais no nome | +| Verificar PPTX abre correctamente apos geracao | Entregar sem validar | +| Adaptar objectivos ao sector do cliente | Copiar objectivos genericos entre propostas | +| Incluir dados de contacto do gestor real | Dados de contacto ficticios | + +--- + +## Procedimentos Relacionados + +- `PROC-Catalogo-Codificacao-Produtos.md` - Codificacao e catalogo de produtos +- `PROC-CRM-Operacoes.md` - Operacoes CRM padrao + +--- + +## Changelog + +### v1.0.0 (2026-03-06) +- Versao inicial da skill /proposal-deck +- 16 layouts mapeados do template PPTX curado +- 3 niveis de complexidade: minima (8), standard (12), completa (16) +- Integracao CRM (cliente, estimates, precos) +- Workflow completo: recolha -> seleccao -> geracao -> entrega +- Exemplos para website, marketing 360, SEO +- Anti-patterns documentados + +--- + +**Versao**: 1.0.0 | **Data**: 2026-03-06 | **Template**: descomplicar-proposal-template.pptx + +--- + +## Media Bank (D7-MB-001) + +**Quando consultar:** antes de gerar o deck da proposta — para hero da capa, backgrounds de slides de secção e imagens ilustrativas. Garante consistência visual e evita dependência de geração IA por cada proposta. + +**Workflow tentativa-primeiro:** + +1. Pesquisar via MCP `media-bank`: + ``` + mcp__media-bank__search_media( + query="", + type="image", + tema="", + orientation="landscape", + min_quality=8, # exigência mais alta para propostas + min_width=1920, + exclude_used_in_last_days=60, + limit=5 + ) + ``` +2. Avaliar candidatos por `description_en` + `quality_score` + alinhamento com identidade visual Descomplicar. +3. Se ≥1 adequado → usar `path_local` directamente no PPTX (slide master / capa) ou compor no template. +4. Se nenhum → fallback para geração IA (Flux) ou biblioteca de stock interna. +5. Marcar uso: `mcp__media-bank__mark_used(asset_id, {type:"proposal-deck", ref:"-", date:""})`. + +**Fallback REST** (se MCP indisponível): +```bash +SK=$(grep SERVICE_KEY /media/ealmeida/Dados/Hub/05-Projectos/Banco-Imagens-Videos/scripts/.env | cut -d= -f2) +curl -s "https://mem.descomplicar.pt/rest/v1/media_bank_assets?type=eq.image&orientation=eq.landscape&quality_score=gte.8&deleted_at=is.null&order=quality_score.desc&limit=5" \ + -H "apikey: $SK" -H "Authorization: Bearer $SK" +``` + +**Regra inviolável:** matéria-prima local. Usar como input no template PPTX — NUNCA servir o ficheiro raw ao cliente sem integração no deck (overlays, branding, layout). + +Ver `Hub/06-Operacoes/Procedimentos/D7-Tecnologia/MCP/PROC-Media-Bank.md` (D7-MB-001) para detalhes. + +--- + +## 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/crm-ops/skills/proposta-visual/SKILL.md b/crm-ops/skills/proposta-visual/SKILL.md index 949b6d6..53e2c7a 100644 --- a/crm-ops/skills/proposta-visual/SKILL.md +++ b/crm-ops/skills/proposta-visual/SKILL.md @@ -1,7 +1,6 @@ --- name: proposta-visual description: Criação completa de propostas comerciais visuais — página web (propostas.descomplicar.pt) + PDF exportável + PPTX editável. Recolhe dados CRM, gera JSON, renderiza condicionalmente e faz deploy. -layer: wiki --- # Skill /proposta-visual — Propostas Comerciais Visuais @@ -118,4 +117,359 @@ Mostra: "750 EUR + IVA" + "Investimento único · prazo 1-2 semanas" | `Font.register` com fontes locais/CDN em multi-página | Falha silenciosa | Usar Helvetica/Helvetica-Bold (built-in) | | `href` vazio no PDFDownloadLink | PDF não gerou — verificar consola | Cache do browser — Ctrl+Shift+R | | `width: "100%"` em bars/elementos dentro de flex container | Não resolve — fica invisível | Usar `alignSelf: "stretch"` no elemento e no container pai | -| Imagens com path absoluto (`/home/...`) | react-pdf não acede ao filesystem local | Colocar em `public/assets/` e referenciar como `"assets/foto.png"` (s \ No newline at end of file +| Imagens com path absoluto (`/home/...`) | react-pdf não acede ao filesystem local | Colocar em `public/assets/` e referenciar como `"assets/foto.png"` (sem `/` inicial) | +| `borderBottomWidth` no header + `borderTopWidth` em componente filho | Duplica a linha dourada visualmente | Usar apenas `borderTopWidth: 2` no próprio header; remover `borderBottom` | + +**Hifenização:** Para desactivar em todo o PDF, adicionar ao ``: +```jsx +hyphenationCallback={(word) => [word]} +``` + +**Ícones no PDF:** Usar `PDFIcons.jsx` (`src/pdf/sections/`) com `Svg/Path/Circle/Line/Polyline` de `@react-pdf/renderer`. NÃO importar lucide-react nos componentes PDF — crasha o worker. + +**Ícones na web:** Usar `lucide-react`. Padrão: `FALLBACK_ICONS[i % FALLBACK_ICONS.length]` para rotação automática por índice quando o JSON não tem campo `icon`. + +### 6. Página 360° (service360) — contextualizar + +A secção service360 no PDF usa o label "O QUE PROPOMOS" (genérico) e o título "As nossas soluções para o seu negócio". Os dados vêm do JSON `service360.areas[]`. + +Para propostas que NÃO são 360°, adaptar os `areas` ao contexto: +- Migração técnica: features da migração +- Website: áreas do serviço web +- SEO: pilares do trabalho SEO + +Se `service360` for `null`, a secção não aparece. + +### 7. Condições comerciais — página separada no PDF + +As condições estão numa página PDF separada (não na mesma que o roadmap) para evitar corte entre páginas. O componente `PDFWorkDone` retorna um Fragment com 2 Pages. + +### 8. Apresentação 16:9 — PDFPresentation.jsx + +Existe um segundo output PDF em formato 1920×1080 (slides), activado por um botão "Apresentação 16:9" no canto inferior direito da proposta web. + +**Ficheiros envolvidos:** +- `src/pdf/PDFPresentation.jsx` — documento completo com todos os slides +- `src/pdf/sections/PDFSlide.jsx` — wrapper de slide (Page 1440×810pt, header com logo, rodapé com numeração) + +**Dimensões:** 1920×1080 @ 72dpi → `[1440, 810]` em pontos (unidade do react-pdf). + +**Estrutura de slides:** + +| Slide | Componente | Dados | +|-------|-----------|-------| +| Capa | `SlideCover` | `data.title`, `client`, `date`, `company` | +| Diagnóstico | `SlideProblem` | `context.description`, `context.diagnosis` | +| Descomplicar 360° | `Slide360` | `educationSections` com `label:"Descomplicar 360°"` | +| Educação | `SlideEducation` | restantes `educationSections` | +| Soluções | `SlideService360` | `service360.areas` | +| Previsão de leads | `SlideLeadForecast` | `leadForecast` | +| Preços | `SlidePricing` | `plans` | +| Roadmap | `SlideRoadmap` | `roadmap` | +| Contacto | `SlideContact` | `company`, `client.contact` | + +**Helper components internos (PDFPresentation.jsx):** +- `GoldLine` — linha dourada decorativa +- `Tag` — label uppercase dourado (fontSize 13) +- `SlideTitle` — título principal do slide (fontSize 52 default) +- `SlideBody` — corpo do slide (fontSize 19) +- `Card` — caixa de conteúdo com border esquerda dourada (title 16, body 14) +- `CardGrid` — wrapper flexWrap para cards + +**Tamanhos de referência para legibilidade em sala:** +- Tag: 13pt | SlideTitle: 42-58pt | SlideBody: 19pt +- Card title: 16pt | Card body: 14pt +- Cover logo: height 120 (3× maior que header normal) + +**Separação Slide360 vs SlideEducation:** +```jsx +const slide360 = educationSections?.find(s => s.label?.toLowerCase().includes("360")) +const otherSections = educationSections?.filter(s => !s.label?.toLowerCase().includes("360")) +``` + +**Botão no App.jsx:** +```jsx +} + fileName={`apresentacao-descomplicar-${...}.pdf`} +> + {({ loading }) => } + +``` + +**PROIBIÇÕES específicas do 16:9:** +- NÃO usar `gap` em `flexWrap` (mesmo bug do A4) +- NÃO usar `rgba()` em `borderColor` +- Manter `hyphenationCallback` no `` do PDFPresentation também + +--- + +## Protocolo + +### Sintaxe + +``` +/proposta-visual [cliente] [tipo-serviço] +``` + +### Fase 1: Análise do contexto + +**ANTES de criar o JSON, responder a estas perguntas:** + +1. **Que tipo de proposta é?** (360°, website, migração técnica, SEO, eCommerce, outro) +2. **O preço é mensal ou único?** → define `monthly` vs `price`/`priceLabel`/`priceSubtitle` +3. **Que secções se aplicam?** → define que campos preencher no JSON +4. **Há dados quantitativos?** (vendas, scores SEO, KPIs) → define `salesData`, `context.scores` +5. **Há trabalho já realizado?** → define `workDone` +6. **Quantas opções de preço?** → define `plans[]` + +**Mapa de secções por tipo de proposta:** + +| Secção | 360° | Website | Migração | SEO | eCommerce | +|--------|:----:|:-------:|:--------:|:---:|:---------:| +| `title` | Descomplicar 360° | Website Profissional | [contexto] | Optimização SEO | Loja Online | +| `brandStrategy` | ✓ | Opcional | — | — | Opcional | +| `salesData` | Se existir | — | — | — | Se existir | +| `scores` | ✓ (audit) | Opcional | — | ✓ (audit) | Opcional | +| `service360` | ✓ | ✓ | ✓ | ✓ | ✓ | +| `plans` | ✓ (3 opções) | ✓ | ✓ | ✓ | ✓ | +| `licenses` | Se aplicável | — | — | — | Se aplicável | +| `workDone` | Se existir | Se existir | ✓ | Se existir | Se existir | +| `roadmap` | ✓ | ✓ | ✓ | ✓ | ✓ | +| `conditions` | ✓ | ✓ | ✓ | ✓ | ✓ | + +### Fase 2: Recolha de dados do CRM + +``` +mcp__desk-crm-v3__search_customers query="[nome]" +mcp__desk-crm-v3__get_customer customer_id=[id] +mcp__desk-crm-v3__get_estimates client_id=[id] +``` + +### Fase 3: Criar ficheiro JSON + +**Localização:** `src/data/[slug].json` + +**Gerar slug:** iniciais do cliente + tipo + hash curto. Ex: `ccv-bookeo-a3f7c1d2` + +**Schema mínimo obrigatório:** + +```json +{ + "title": "Título da Proposta", + "client": { + "name": "Nome Legal Lda.", + "brand": "Nome Comercial", + "website": "exemplo.pt", + "contact": "Nome Contacto", + "email": "email@exemplo.pt", + "phone": "+351 900 000 000" + }, + "company": { + "name": "Descomplicar, Lda.", + "brand": "Descomplicar", + "nif": "514 785 691", + "email": "info@descomplicar.pt", + "phone": "911 510 005", + "website": "descomplicar.pt" + }, + "date": "2026-03-23", + "validDays": 30, + "context": { + "description": "Descrição da situação...", + "diagnosis": [], + "scores": [], + "brandStrategy": null + }, + "service360": null, + "plans": [], + "licenses": null, + "workDone": [], + "roadmap": [], + "conditions": [], + "salesData": [], + "salesProjection": [] +} +``` + +**Campos opcionais para planos com preço único:** +```json +{ + "price": 750, + "priceLabel": "EUR + IVA", + "priceSubtitle": "Investimento único · prazo 1-2 semanas", + "monthly": null, + "hours": null +} +``` + +**Checklist PT-PT antes de guardar o JSON:** +- [ ] Todos os textos têm acentos correctos (ã, ç, ã, é, ê, í, ó, õ, ú) +- [ ] Zero brasileirismos +- [ ] Caractere → (seta) em vez de -> nos textos visíveis +- [ ] Monetário: "EUR" ou "€" (não "R$" nem "$") + +### Fase 4: Registar no App.jsx + +```jsx +import novaData from "./data/[slug].json" + +const proposals = { + // existentes... + "[novo-slug]": novaData, +} +``` + +### Fase 5: Verificar antes do build + +**Checklist pré-build:** +- [ ] JSON válido (sem trailing commas, sem campos undefined) +- [ ] Campos null/[] para secções que não se aplicam (NÃO omitir) +- [ ] `title` definido (não depender do fallback) +- [ ] `plans[].price` OU `plans[].monthly` definido (não ambos null) +- [ ] `plans[].priceLabel` definido se preço único +- [ ] Slug registado em App.jsx +- [ ] Nenhum `flexWrap` + `gap` nos componentes PDF +- [ ] Nenhum `borderColor` com `rgba()` nos componentes PDF + +### Fase 6: Build e deploy + +```bash +cd /media/ealmeida/Dados/Dev/Propostas +npm run build + +# Limpar dist +cd dist +rm -rf assets/template-media assets/template-referencia.pptx assets/slide-referencia.svg +cd assets/brochura && ls *.{jpg,png} 2>/dev/null | grep -v image8.jpg | xargs rm -f 2>/dev/null + +# Empacotar +cd /media/ealmeida/Dados/Dev/Propostas/dist +tar czf /tmp/propostas-dist.tar.gz . + +# Upload + deploy +mcp__ssh-unified__sftp_upload server=easy localPath=/tmp/propostas-dist.tar.gz remotePath=/tmp/propostas-dist.tar.gz overwrite=true +mcp__ssh-unified__ssh_execute server=easy command="cd /opt/propostas && rm -rf assets/* index.html; tar xzf /tmp/propostas-dist.tar.gz && docker service update --force descomplicar_propostas && rm -f /tmp/propostas-dist.tar.gz" + +# Verificar +curl -sI https://propostas.descomplicar.pt/[slug] | head -3 +# Deve retornar HTTP/2 200 + +# Limpar +rm -f /tmp/propostas-dist.tar.gz +``` + +### Fase 7: Testar PDF + +**OBRIGATÓRIO antes de entregar:** +1. Abrir `https://propostas.descomplicar.pt/[slug]` com Ctrl+Shift+R +2. Clicar "Exportar PDF" +3. Verificar que `href` do link não está vazio (PDF gerou) +4. Abrir PDF e verificar: + - [ ] Título correcto (não "Descomplicar 360°" hardcoded) + - [ ] Preços correctos (não "€/mês" se é preço único) + - [ ] Sem borders verdes (rgba renderiza verde no react-pdf) + - [ ] Sem secções que não se aplicam (360°, vendas, licenças, scores) + - [ ] Acentos PT-PT em todo o texto + - [ ] Condições comerciais numa página inteira (sem corte) + - [ ] Todas as 3 opções de preço com layout uniforme + +**Se o PDF não gera (href vazio):** +1. Verificar consola do browser (F12) +2. Causa mais provável: import de componente SVG dos infographics +3. Verificar que PDFDocument não importa de `./infographics/` +4. Verificar que não há `gap` + `flexWrap` no PDF +5. Ctrl+Shift+R e tentar novamente (cache) + +### Fase 8: Entrega e registo + +1. Guardar em `Hub/03-Propostas/[Cliente]/` +2. Registar estimate no CRM (se não existe) +3. Comunicar URL ao utilizador +4. Comentar tarefa CRM + +--- + +## Design system ACIDA 2.0 + +| Token | Valor | +|-------|-------| +| Dourado | #C88900 | +| Dourado claro | #EED59F | +| Dourado border PDF | #D4A020 (usar em vez de rgba no PDF) | +| Dark | #262626 | +| Background | #F8F8F8 | +| Fonte web | Inter (Google Fonts) | +| Fonte PDF | Helvetica / Helvetica-Bold | +| Logo escuro | `/assets/logo-descomplicar.png` | +| Logo claro | `/assets/logo-descomplicar-white.png` | + +--- + +## Propostas existentes + +| Slug | Cliente | Tipo | Data | +|------|---------|------|------| +| `ljm-360-61a8aecc` | A Loja da Maria | 360° (mensal) | 2026-03-20 | +| `ccv-bookeo-a3f7c1d2` | Carvoeiro Caves | Migração técnica (único) | 2026-03-23 | +| `pbk-autoridade-local-2026` | Equipa Sérgio Oliveira e Paula Barros · KW Portugal | SEO + conteúdo hiperlocal (mensal) | 2026-04-27 | + +--- + +## Skills relacionadas + +- `/proposal-deck` — PPTX standalone (16 layouts, XML editing) +- `/orcamento` — Estimate no CRM (sem visual) +- `/lead-approach` — Estratégia de abordagem de lead +- `/crm` — Operações CRM genéricas + +--- + +## Changelog + +### v2.0.0 (2026-03-23) +- Regras críticas documentadas (7 regras) +- Renderização condicional obrigatória (ProposalView + PDFDocument) +- Título dinâmico via campo `title` no JSON +- Preços flexíveis (mensal vs único) com `price`/`priceLabel`/`priceSubtitle` +- Bugs react-pdf documentados com proibições explícitas +- Mapa de secções por tipo de proposta +- Checklist pré-build e teste PDF obrigatório +- Condições comerciais em página PDF separada + +### v2.2.0 (2026-04-27) +- Formato 16:9 documentado: `PDFPresentation.jsx` + `PDFSlide.jsx` +- Regra 8 adicionada: estrutura de slides, dimensões, helper components, tamanhos de referência +- Separação Slide360 vs SlideEducation por label +- Botão "Apresentação 16:9" no App.jsx documentado +- Proibições específicas 16:9 adicionadas + +### v2.1.0 (2026-04-27) +- Novos bugs react-pdf documentados: `width:"100%"` em flex, paths absolutos em imagens, `borderBottom` duplicado +- Hifenização: `hyphenationCallback` no `` +- Padrão de ícones: `PDFIcons.jsx` para PDF, lucide-react para web, fallback por índice +- Proposta `pbk-autoridade-local-2026` adicionada ao registo +- Healing Log com 5 erros reais corrigidos + +### v1.0.0 (2026-03-23) +- Versão inicial + +--- + +**Versão:** 2.2.0 | **Data:** 2026-04-27 + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"2026-04-27","issue":"Barras de gráfico invisíveis no PDF","fix":"width:'100%' não funciona em flex containers — substituir por alignSelf:'stretch' no container e na barra","source":"user"} +{"date":"2026-04-27","issue":"Linha dourada duplicada no topo das páginas","fix":"PDFPage tinha borderBottomWidth no header E os componentes filhos tinham borderTopWidth — remover borderBottom do header, manter apenas borderTopWidth:2","source":"user"} +{"date":"2026-04-27","issue":"Foto do gestor de conta não aparece no PDF","fix":"react-pdf não carrega paths absolutos do filesystem — copiar para public/assets/ e referenciar sem / inicial","source":"user"} +{"date":"2026-04-27","issue":"Border verde em vez de dourado no PDF","fix":"rgba() em borderColor renderiza verde — usar hex sólido (#D4A020)","source":"user"} +{"date":"2026-04-27","issue":"Hifenização indesejada no PDF","fix":"Adicionar hyphenationCallback={(word) => [word]} ao ","source":"user"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/crm-ops/skills/ticket-manage/SKILL.md b/crm-ops/skills/ticket-manage/SKILL.md index d236c3a..6635d73 100644 --- a/crm-ops/skills/ticket-manage/SKILL.md +++ b/crm-ops/skills/ticket-manage/SKILL.md @@ -6,7 +6,6 @@ description: > em PROC-D2-SUP-001 (Atendimento), SUP-002 (Ticketing Workflow) e SUP-003 (SLA Management). Usar para: gestão ticket, SLA check, escalar suporte, fechar ticket, atribuir prioridade. disable-model-invocation: true -layer: wiki --- # /ticket-manage v1.0 — Gestão Integrada de Suporte D2 @@ -147,4 +146,174 @@ Complementa `/ticket` (operações básicas) com gestão de SLA, checklist e esc - sla_limite = por prioridade (1h/2h/4h/24h para primeira resposta) - percentagem_usada = tempo_decorrido / sla_limite × 100 3. Agrupar: VIOLADO (>100%), EM RISCO (75-100%), OK (<75%) -4. Highlight P1 e P2 c \ No newline at end of file +4. Highlight P1 e P2 com aviso especial +``` + +**Alertas automáticos a gerar:** +``` +P1 sem resposta >30min → "⚠️ CRÍTICO: Ticket #X P1 excede 30min. Acção imediata." +P2 sem resposta >2h → "⚠️ ALERTA: Ticket #X P2 em risco. Re-atribuir?" +Qualquer ticket >48h → "⏰ Ticket #X aberto há +48h. Revisar." +``` + +--- + +## `/ticket-manage escalate ` — Escalação com Protocolo + +``` +1. mcp__desk-crm-v3__get_ticket({ ticket_id: id }) +2. Determinar destino de escalação: + - Tech complexo (WP, servidor) → D7 Tecnologia + - Billing → D3 Facturação + - Dev customizado → Project Manager +3. Criar tarefa Desk CRM com contexto completo: + mcp__desk-crm-v3__create_task({ + name: "[ESCALADO] Ticket #X: [Assunto]", + description: "

Escalado de Ticket #X

+

Cliente: [nome]

+

Problema: [descrição]

+

Tentativas anteriores: [o que foi tentado]

+

SLA original: [prazo]

+

Motivo escalação: [razão]

", + priority: 3, + assignees: [1] + }) +4. Informar cliente: + mcp__desk-crm-v3__reply_ticket({ + ticket_id: id, + message: "

Olá [Nome],

+

A situação é mais complexa e foi escalada para a equipa especialista. + Prazo estimado: 24-48h.

+

Pedimos desculpa pela demora.

" + }) +5. Nota interna com motivo detalhado +6. Output: "Ticket #X escalado → Tarefa #Y | Dept: [destino] | ETA: [prazo]" +``` + +--- + +## `/ticket-manage close ` — Fecho com Checklist Obrigatória + +``` +1. mcp__desk-crm-v3__get_ticket({ ticket_id: id }) +2. Executar checklist SUP-001 (OBRIGATÓRIO — 100% antes de fechar): +``` + +### Checklist de Fecho (SUP-001) + +- [ ] Solução aplicada e testada +- [ ] Explicação clara da solução enviada ao cliente +- [ ] Causa raiz identificada (não só sintoma) +- [ ] Passos de prevenção comunicados +- [ ] Cliente confirmou resolução ("Resolvido? Feedback?") +- [ ] Lições aprendidas registadas (se novo problema) +- [ ] Follow-up 3 dias agendado (se P1/P2) + +``` +3. Se checklist incompleta → NÃO fechar, listar pendentes +4. Se 100% → fechar: + mcp__desk-crm-v3__reply_ticket({ + ticket_id: id, + message: "

Olá [Nome],

+

Confirmamos que a situação foi resolvida.

+

Solução: [explicação]

+

Prevenção: [dica]

+

Obrigado pelo contacto. Se precisar de algo, estamos disponíveis.

+

Nota 1-10 sobre o suporte?

" + }) + mcp__desk-crm-v3__close_ticket({ ticket_id: id }) +5. Output: "Ticket #X fechado ✓ | Checklist: 7/7 | [Data fecho]" +``` + +--- + +## `/ticket-manage report` — Relatório SLA Semanal (SUP-003) + +``` +1. Recolher tickets dos últimos 7 dias +2. Calcular por prioridade: + - % tickets que cumpriram SLA de resposta + - % tickets que cumpriram SLA de resolução + - Tempo médio de resposta e resolução +3. Identificar violações e categorizar causas +4. Comparar com semana anterior +``` + +**Output:** +```markdown +## Relatório SLA Semanal — [DD-MM-YYYY a DD-MM-YYYY] + +### Cumprimento SLA (Meta: >90%) +| Prioridade | Tickets | SLA Resposta | SLA Resolução | Violações | +|-----------|---------|-------------|--------------|-----------| +| P1 Crítico | 2 | 100% ✅ | 50% ⚠️ | 1 | +| P2 Funcional | 8 | 87.5% ⚠️ | 100% ✅ | 1 | +| P3 Dúvida | 15 | 93.3% ✅ | 86.7% ⚠️ | 2 | +| P4 Melhoria | 3 | 100% ✅ | N/A | 0 | + +### Top 3 Tickets Mais Lentos +1. #X — [Assunto] — P2 — 36h — causa: dependência externa D7 +2. #Y — [Assunto] — P3 — 52h — causa: complexidade técnica +3. #Z — [Assunto] — P1 — 5h30 — causa: falta de informação cliente + +### Acções Correctivas +- [ ] P2 cumprimento <90% → Revisão processo atribuição automática +``` + +--- + +## Referências PROCs + +| PROC | Ficheiro Hub | +|------|-------------| +| SUP-001 Atendimento | `Hub/06-Operacoes/Procedimentos/D2-Suporte/PROC-D2-SUP-001-Atendimento-Cliente.md` | +| SUP-002 Ticketing | `Hub/06-Operacoes/Procedimentos/D2-Suporte/PROC-D2-SUP-002-Ticketing-Workflow.md` | +| SUP-003 SLA | `Hub/06-Operacoes/Procedimentos/D2-Suporte/PROC-D2-SUP-003-SLA-Management.md` | + +--- + +## Anti-Patterns + +- **NUNCA** fechar sem checklist 100% completa +- **NUNCA** escalar sem informar o cliente +- **NUNCA** ignorar tickets P1 >30min +- **NUNCA** resolver sintoma sem identificar causa raiz + +--- + +## Integração com Outras Skills + +| Skill | Quando usar | +|-------|-------------| +| `/ticket` | Operações básicas (view, reply) | +| `/ticket-triage` | Triagem automática SPAM/facturas | +| `/crm` | Contexto cliente 360° | +| `/today` | Dashboard diário com SLA alerts | + +--- + +## Changelog + +### v1.0.0 (07-04-2026) +- Versão inicial baseada em SUP-001, SUP-002, SUP-003 +- Dashboard SLA com alertas automáticos +- Criação com campos obrigatórios e confirmação recepção +- Checklist fecho obrigatória 7 pontos +- Protocolo escalação com contexto completo +- Relatório semanal SLA + +--- + +*Skill v1.0.0 | 07-04-2026 | Descomplicar® | Baseado em PROCs D2-SUP-001/002/003* + +--- + +## 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/crm-ops/skills/ticket-triage/SKILL.md b/crm-ops/skills/ticket-triage/SKILL.md index 4d6763d..bb21bb8 100644 --- a/crm-ops/skills/ticket-triage/SKILL.md +++ b/crm-ops/skills/ticket-triage/SKILL.md @@ -2,7 +2,6 @@ name: ticket-triage description: Auto-processamento de tickets abertos no Desk CRM. Fecha SPAM, identifica facturas para /auto-expense e protege notificações de sistema. disable-model-invocation: true -layer: wiki --- # /ticket-triage v1.0 diff --git a/crm-ops/skills/ticket/SKILL.md b/crm-ops/skills/ticket/SKILL.md index 54c7762..e2d5af8 100644 --- a/crm-ops/skills/ticket/SKILL.md +++ b/crm-ops/skills/ticket/SKILL.md @@ -2,7 +2,6 @@ name: ticket description: Gestão de tickets de suporte Desk CRM. Ver, responder, fechar e escalar tickets. Inclui templates de resposta e integração com /today. disable-model-invocation: true -layer: wiki --- # /ticket v1.0 - Gestão de Suporte @@ -245,4 +244,55 @@ No checkup diário, mostrar tickets: ```html

Olá [Nome],

-

Para re \ No newline at end of file +

Para resolver a questão, preciso de mais informações:

+
    +
  • [Pergunta 1]
    • +
  • [Pergunta 2]
    • +
+

Aguardo o seu feedback.

+``` + +### Resolução + +```html +

Olá [Nome],

+

A situação foi resolvida. [Explicação breve]

+

Se tiver mais questões, não hesite em contactar.

+

Cumprimentos,
Emanuel Almeida

+``` + +--- + +## Anti-Patterns + +- **NUNCA** responder sem ler histórico completo +- **NUNCA** fechar ticket sem mensagem +- **NUNCA** ignorar tickets urgentes >1h +- **NUNCA** escalar sem informar cliente + +--- + +## Changelog + +### v1.0.0 (2026-02-05) +- Versão inicial +- Listar, ver, responder, fechar +- Escalar para tarefa +- Templates de resposta +- Integração /today + +--- + +*Skill v1.0.0 | 2026-02-05 | 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ós cada erro corrigido.* diff --git a/design-media/agents/design-critic.md b/design-media/agents/design-critic.md index d37595c..eb33067 100644 --- a/design-media/agents/design-critic.md +++ b/design-media/agents/design-critic.md @@ -10,6 +10,8 @@ category: design model: sonnet tools: Read, Write, Edit, Glob, Grep, ToolSearch +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - design-engine recommended_mcps: @@ -20,7 +22,6 @@ skills: - _core - ui-ux-pro-max desk_task: 1518 -layer: wiki --- # Design Critic - Avaliacao de Qualidade diff --git a/design-media/agents/design-generator.md b/design-media/agents/design-generator.md index 196a817..c2d32d3 100644 --- a/design-media/agents/design-generator.md +++ b/design-media/agents/design-generator.md @@ -10,6 +10,8 @@ category: design model: sonnet tools: Read, Write, Edit, Glob, Grep, ToolSearch +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - design-engine - presenton @@ -24,7 +26,6 @@ skills: - pptx-generator - remotion-video desk_task: 1518 -layer: wiki --- # Design Generator - Execucao diff --git a/design-media/agents/design-lead.md b/design-media/agents/design-lead.md index 03b3f50..7b15272 100644 --- a/design-media/agents/design-lead.md +++ b/design-media/agents/design-lead.md @@ -10,6 +10,8 @@ category: design model: sonnet tools: Read, Write, Edit, Glob, Grep, ToolSearch +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - design-engine - presenton @@ -26,7 +28,6 @@ skills: - ui-ux-pro-max - pptx-generator desk_task: 1518 -layer: wiki --- # Design Lead - Orquestrador de Design diff --git a/design-media/agents/design-prompt-architect.md b/design-media/agents/design-prompt-architect.md index f575e9a..4d7c880 100644 --- a/design-media/agents/design-prompt-architect.md +++ b/design-media/agents/design-prompt-architect.md @@ -10,6 +10,8 @@ category: design model: sonnet tools: Read, Write, Edit, Glob, Grep, ToolSearch +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - design-engine - presenton @@ -23,7 +25,6 @@ skills: - ui-ux-pro-max - pptx-generator desk_task: 1518 -layer: wiki --- # Design Prompt Architect - Routing e Prompts diff --git a/design-media/agents/design-researcher.md b/design-media/agents/design-researcher.md index 5aab5f6..1bc54ae 100644 --- a/design-media/agents/design-researcher.md +++ b/design-media/agents/design-researcher.md @@ -10,6 +10,8 @@ category: design model: sonnet tools: Read, Write, Edit, Glob, Grep, ToolSearch +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - figma - stitch @@ -22,7 +24,6 @@ skills: - _core - ui-ux-pro-max desk_task: 1518 -layer: wiki --- # Design Researcher - Investigador Visual diff --git a/design-media/agents/ui-designer.md b/design-media/agents/ui-designer.md index 6e4e576..f87521d 100644 --- a/design-media/agents/ui-designer.md +++ b/design-media/agents/ui-designer.md @@ -11,6 +11,8 @@ model: sonnet tools: Read, Write, Edit, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 - design-systems @@ -26,7 +28,6 @@ skills: - frontend-design - pptx-generator desk_task: 1518 -layer: wiki --- # UI Designer Descomplicar @@ -130,4 +131,94 @@ Designer de interfaces responsavel por criar designs visuais apelativos, manter - **magic** - AI-powered UI component generation (tipo v0.dev) - **design-systems** - Knowledge base W3C standards, WCAG, design system best pract - **elevenlabs** - Text-to-speech, voice cloning, audio transcription -- **vimeo** - Video management - upload, metadata, transcr \ No newline at end of file +- **vimeo** - Video management - upload, metadata, transcripts, analytics + +### All Available (32 total) +desk-crm-v3, moloni, context7, gitea, n8n, cwp, filesystem, ssh-unified, google-analytics, imap, outline-api, youtube-research, youtube-uploader, gsc, lighthouse, mcp-time, mem0, puppeteer, tavily, replicate + +**Discovery:** Use ToolSearch to find specific tools. +**Example:** `ToolSearch("ssh upload")` finds SSH upload tools. +## Your Available Skills + +### Primary Skills (Your Domain) +✓ **/ui-ux-pro-max** - UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, + - Invoke: `/ui-ux-pro-max` + +✓ **/frontend-design** - Create distinctive, production-grade frontend interfaces with high design qualit + - Invoke: `/frontend-design` + +✓ **/pptx-generator** - Generate and edit presentation slides as PPTX files. Also create LinkedIn carous + - Invoke: `/pptx-generator` + +### Recommended for design +- **/brand-voice-generator** - Generate tone-of-voice and brand-system files for use with t +- **/video** - Criar vídeos programáticos com Remotion e React. Gera intros +- **/remotion-video** - Create and edit Remotion videos with domain-specific knowled + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /lead-approach, /orcamento, /saas, /content-marketing-pt, /seo-content-optimization, /social-media, /ui-ux-pro-max-repo, /crm-admin, /db-design, /elementor, /mcp-dev, /nextjs, /php-dev, /react-patterns, /woocommerce, /wp-dev, /backup-strategies, /security-audit, /server-health, /wp-performance, /wp-update, /second-brain-repo, /ads, /doc-sync, /marketing-strategy, /product, /skill-creator, /sop-creator, /calendar-manager, /delegate, /interview, /time, /today, /research, /youtube, /seo-audit, /seo-report, /archive, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. +## Your Team & Responsibilities + +You are part of **11 SDKs** (TaskForce teams): + +### TaskForce Ad Manager + +**Purpose:** NULL + +### TaskForce Claude Agents + +**Purpose:** NULL + +**Your responsibilities in this TaskForce:** +### TaskForce E-commerce + +**Purpose:** NULL + +### TaskForce Elementor + +**Purpose:** NULL + +### TaskForce Graphic Design + +**Purpose:** NULL + +### TaskForce Next.js + +**Purpose:** NULL + +### TaskForce Product Manager + +**Purpose:** NULL + +### TaskForce React + +**Purpose:** NULL + +### TaskForce Redes Sociais + +**Purpose:** NULL + +### TaskForce SaaS + +**Purpose:** NULL + +### TaskForce WooCommerce + +**Purpose:** NULL + +**Collaboration:** +- Work with other agents in your TaskForce teams +- Share knowledge and context across team members +- Leverage team-specific skills and MCPs +- Contribute to team goals and deliverables + diff --git a/design-media/agents/video-production-specialist.md b/design-media/agents/video-production-specialist.md index d584af0..46468f1 100644 --- a/design-media/agents/video-production-specialist.md +++ b/design-media/agents/video-production-specialist.md @@ -31,7 +31,6 @@ compliance: created: '2025-01-13' updated: '2026-02-04' author: Descomplicar® -layer: wiki --- # Video Production Specialist Descomplicar @@ -129,7 +128,7 @@ mcp__notebooklm__notebook_query notebook_id:"081ca512-8279-4850-b2b9-dff09026748 - **replicate** - AI models - imagem, vídeo, áudio, LLMs ### All Available (32 total) -desk-crm-v3, moloni, context7, gitea, n8n, cwp, filesystem, ssh-unified, google-analytics, imap, wikijs, gsc, lighthouse, mcp-time, mem0, puppeteer, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, magic, design-systems +desk-crm-v3, moloni, context7, gitea, n8n, cwp, filesystem, ssh-unified, google-analytics, imap, gsc, lighthouse, mcp-time, mem0, puppeteer, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, magic, design-systems **Discovery:** Use ToolSearch to find specific tools. **Example:** `ToolSearch("ssh upload")` finds SSH upload tools. @@ -139,4 +138,28 @@ desk-crm-v3, moloni, context7, gitea, n8n, cwp, filesystem, ssh-unified, google- ✓ **/content-marketing-pt** - Criação de conteúdo marketing em Português Europeu. Tom de voz, copywriting, est - Invoke: `/content-marketing-pt` -✓ **/video** - Criar vídeos programáticos com Remotion e React. Gera intros, promos \ No newline at end of file +✓ **/video** - Criar vídeos programáticos com Remotion e React. Gera intros, promos, social med + - Invoke: `/video` + +✓ **/youtube** - Extrair transcrições e metadados do YouTube + Estratégia crescimento canal. Supo + - Invoke: `/youtube` + +### Recommended for content +- **/social-media** - Gestão e estratégia de redes sociais - Instagram, LinkedIn, +- **/remotion-video** - Create and edit Remotion videos with domain-specific knowled +- **/seo-content-optimization** - Optimização SEO técnico e conteúdo - meta tags, structured d +- **/research** - Pesquisa profunda e análise competitiva - SWOT, Porter's Fiv + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /lead-approach, /orcamento, /saas, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /crm-admin, /db-design, /elementor, /mcp-dev, /nextjs, /php-dev, /react-patterns, /woocommerce, /wp-dev, /backup-strategies, /security-audit, /server-health, /wp-performance, /wp-update, /second-brain-repo, /ads, /doc-sync, /marketing-strategy, /product, /skill-creator, /sop-creator, /calendar-manager, /delegate, /interview, /time, /today, /seo-audit, /seo-report, /archive, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. + diff --git a/design-media/agents/web-designer.md b/design-media/agents/web-designer.md index d89d897..1c3b6a2 100644 --- a/design-media/agents/web-designer.md +++ b/design-media/agents/web-designer.md @@ -11,6 +11,8 @@ model: sonnet tools: Read, Write, Edit, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 - design-systems @@ -26,7 +28,6 @@ skills: - frontend-design - pptx-generator desk_task: 1519 -layer: wiki --- # Web Designer Descomplicar @@ -127,4 +128,83 @@ Designer web responsavel por criar layouts visualmente impactantes e funcionais, - **powerpoint** - Criar apresentações PowerPoint - **mcp-echarts** - Gerar gráficos Apache ECharts - **mcp-mermaid** - Gerar diagramas Mermaid (flowcharts, sequência, etc.) -- **pixabay** - Pesqu \ No newline at end of file +- **pixabay** - Pesquisa imagens e vídeos stock gratuitos +- **pexels** - Pesquisa imagens stock de alta qualidade +- **magic** - AI-powered UI component generation (tipo v0.dev) +- **design-systems** - Knowledge base W3C standards, WCAG, design system best pract +- **elevenlabs** - Text-to-speech, voice cloning, audio transcription +- **vimeo** - Video management - upload, metadata, transcripts, analytics + +### All Available (32 total) +desk-crm-v3, moloni, context7, gitea, n8n, cwp, filesystem, ssh-unified, google-analytics, imap, outline-api, youtube-research, youtube-uploader, gsc, lighthouse, mcp-time, mem0, puppeteer, tavily, replicate + +**Discovery:** Use ToolSearch to find specific tools. +**Example:** `ToolSearch("ssh upload")` finds SSH upload tools. +## Your Available Skills + +### Primary Skills (Your Domain) +✓ **/ui-ux-pro-max** - UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, + - Invoke: `/ui-ux-pro-max` + +✓ **/frontend-design** - Create distinctive, production-grade frontend interfaces with high design qualit + - Invoke: `/frontend-design` + +✓ **/pptx-generator** - Generate and edit presentation slides as PPTX files. Also create LinkedIn carous + - Invoke: `/pptx-generator` + +### Recommended for design +- **/brand-voice-generator** - Generate tone-of-voice and brand-system files for use with t +- **/video** - Criar vídeos programáticos com Remotion e React. Gera intros +- **/remotion-video** - Create and edit Remotion videos with domain-specific knowled + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /lead-approach, /orcamento, /saas, /content-marketing-pt, /seo-content-optimization, /social-media, /ui-ux-pro-max-repo, /crm-admin, /db-design, /elementor, /mcp-dev, /nextjs, /php-dev, /react-patterns, /woocommerce, /wp-dev, /backup-strategies, /security-audit, /server-health, /wp-performance, /wp-update, /second-brain-repo, /ads, /doc-sync, /marketing-strategy, /product, /skill-creator, /sop-creator, /calendar-manager, /delegate, /interview, /time, /today, /research, /youtube, /seo-audit, /seo-report, /archive, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. +## Your Team & Responsibilities + +You are part of **7 SDKs** (TaskForce teams): + +### TaskForce Claude Agents + +**Purpose:** NULL + +**Your responsibilities in this TaskForce:** +### TaskForce E-commerce + +**Purpose:** NULL + +### TaskForce Elementor + +**Purpose:** NULL + +### TaskForce Graphic Design + +**Purpose:** NULL + +### TaskForce Next.js + +**Purpose:** NULL + +### TaskForce React + +**Purpose:** NULL + +### TaskForce WooCommerce + +**Purpose:** NULL + +**Collaboration:** +- Work with other agents in your TaskForce teams +- Share knowledge and context across team members +- Leverage team-specific skills and MCPs +- Contribute to team goals and deliverables + diff --git a/design-media/docs/SPECS/DRAFT-metodo-design-pro.md b/design-media/docs/SPECS/DRAFT-metodo-design-pro.md new file mode 100644 index 0000000..7276562 --- /dev/null +++ b/design-media/docs/SPECS/DRAFT-metodo-design-pro.md @@ -0,0 +1,109 @@ +# DRAFT — Método Design Pro (camada de processo sobre Open Design) + +**Estado:** Rascunho — origem: síntese Gemini de vídeos de páginas de alta qualidade (2026-07-22), adaptado ao stack Descomplicar. +**Aplica-se a:** websites/landing pages, propostas comerciais, decks PPTX, banners, vídeo — qualquer artefacto de design. + +## 0. Quem define o enquadramento (lição do teste WhatSMS, 22-07-2026) + +O **enquadramento — proposta de valor, posicionamento, o que se está a vender — pertence ao dono +do produto**. Nunca se deriva de análise do agente nem de diagnóstico de subagente. + +No primeiro teste real deste método, o briefing enquadrou o WhatSMS como "responder a mensagens +fora de horas" e pediu mock-ups de conversa. Resultado: uma landing page de bot de WhatsApp, quando +o produto é um sistema de automação de contacto multicanal. O design estava competente; o +enquadramento destruía o posicionamento. + +Regras que daí resultam: + +- **Perguntar o posicionamento, não os acessórios.** Cor e tipografia têm defaults; a proposta de + valor não tem. Perguntar sobre a segunda, nunca presumi-la. +- **"Está robótico" é um pedido de tom.** Não é licença para reescrever posicionamento nem deitar + fora copy existente. Preservar por omissão; mudar só o que foi pedido. +- **Um diagnóstico que chama "AI slop" ao copy** pode estar a apontar estilo, não substância. + Nunca converter em mandato para substituir tudo. +- **Briefing longo escrito sozinho é sinal de alarme, não de rigor.** Quanto mais completo, mais + eficazmente impede o motor de fazer as perguntas certas ao dono do produto. O Open Design + pergunta — deixá-lo perguntar em vez de pré-responder tudo. + +--- + +## 1. Contrato de Entrada (Zero Rascunhos Genéricos) + +O pilar 1 (objectivo/posicionamento) **recolhe-se com o dono do produto**, nunca se deduz — ver secção 0. + +Proibido gerar qualquer artefacto sem os 4 pilares explícitos ou deduzidos e confirmados: + +1. **Objectivo comercial** — o que o utilizador/cliente deve sentir ou fazer no fim. +2. **Layout narrativo** — ordem exacta das secções/slides e comportamento de transição (scrollytelling em web; arco narrativo em decks/propostas). +3. **Personalidade da marca** — tom de voz, paleta intencional, espaçamento generoso (editorial feel). Fonte: design system no OD (Descomplicar ou cliente). +4. **Público-alvo** — perfil exacto que justifica a conversão. + +Sem os 4 pilares → perguntar/deduzir e validar. Nunca template pré-feito como resposta. + +## 2. Fluxo em 4 fases (mapeado às skills OD) + +| Fase | O quê | Skills OD | +|---|---|---| +| **F1 Arquitectura** | Grelha estrutural, tipografia, hierarquia de blocos (wireframe visual) | `design-consultation`, `design-brief`, design system | +| **F2 Direcção artística** | Implementação com micro-interacções, profundidade, impacto no início. Web: Next.js/TS + Tailwind + Framer Motion | `creative-director`, `high-end-visual-design`, `frontend-design`, `gsap-*`/`emilkowalski-motion` | +| **F3 Variantes (Regra do Hero)** | Secção crítica → 3-5 abordagens estruturais distintas (split / centered minimal / inset frame) para selecção antes de avançar | runs paralelos no OD, `design-shotgun` local; **Google Stitch** (`stitch-loop`, `stitch-design-taste`) para ideação rápida de variantes UI a partir de prompt/sketch/screenshot, com export Figma | +| **F4 Auditoria adversarial** | Validação crítica antes de entrega: consistência visual, tipos TS, acessibilidade, bundle, fluidez de animação, anti-AI-slop | `design-review`, `impeccable-design-polish`, `pptx-html-fidelity-audit` (decks) | + +## 3. Regra de Ouro da Modificação + +- **Macro** (estrutura, layout, fluxo de páginas/secções) → resolvido e validado primeiro, ao nível global. +- **Micro** (espaçamentos, CTAs, detalhes) → só depois do macro aprovado. Nunca misturar os dois níveis na mesma iteração. + +## 4. Pipeline Template-First (Envato & afins) + +Um template profissional pode substituir F1+F2 — entra como ponto de partida, nunca como entrega directa. + +### 4.1 Duas categorias de fonte + +**A. Templates com código/ficheiros (adaptáveis):** +- Envato/ThemeForest (HTML, Next.js, Elementor kits, PPTX, vídeo) — licença cobre projectos de cliente +- UI8, Craftwork (UI kits), Relume (biblioteca Figma de secções), Framer/Webflow templates + +**B. Galerias de inspiração (extracção de DNA, nunca cópia):** +- Dribbble, Pageflows, Recent.design, Landingfolio, Screensdesign +- Mobbin (fluxos de apps reais), Awwwards, Godly, Land-book, Lapa Ninja, SaaSFrame + +### 4.2 Fluxo de adaptação (categoria A) + +1. **Seleccionar** — escolher template alinhado com o layout narrativo do Contrato de Entrada (não o contrário). +2. **Extrair** — estrutura, grelha, tokens do template (`brand-extract`, `image-to-code`, `web-clone`, análise directa dos ficheiros). +3. **Retheme** — aplicar o design system do cliente/Descomplicar sobre a estrutura (`theme-factory`, `redesign-existing-projects`). Zero cores/fontes do template sobram. +4. **Recontentar** — copy e conteúdo reais segundo os 4 pilares; remover secções que não servem o objectivo comercial (cortar > acrescentar). +5. **F4 Auditoria** — igual ao fluxo normal; atenção extra a resíduos do template (placeholders, lorem ipsum, links demo, créditos). + +### 4.3 Fluxo de referência (categoria B) + +1. Capturar screenshots/URLs das referências escolhidas. +2. Extrair DNA: paleta, tipografia, grelha, ritmo de secções, padrões de interacção (`design-researcher` / visão OD). +3. DNA alimenta F1/F2 como direcção de arte — o artefacto é gerado de raiz com o nosso design system. + +### 4.4 Biblioteca local de templates + +- Templates descarregados (Envato) arquivados em pasta própria com metadados (fonte, licença, tags de uso) — candidata: `Hub/04-Recursos/Design/templates/` — para reutilização entre projectos. +- Cada adaptação bem-sucedida regista o par template→resultado para acelerar selecções futuras. + +## 5. Directrizes operacionais do agente no Open Design + +Regras de execução para qualquer agente (Claude Code, Gemini CLI) a operar como motor no OD. As que repetem as secções 1–3 não se duplicam — referem-se. + +1. **Contrato de Entrada** (secção 1) — os 4 pilares antes de qualquer geração. +2. **`DESIGN.md` é o contrato da marca** — todas as decisões visuais (tipografia, paleta, espaçamento, componentes) vêm do `DESIGN.md` activo do projecto OD, nunca de adivinhação. A skill define *o quê*; o `DESIGN.md` define *como fica*. Manter o `DESIGN.md` sincronizado com o design system (Descomplicar ou cliente). +3. **Declarar a skill/formato certo** — indicar explicitamente o tipo de saída (`web-prototype`, `dashboard`, `mobile-app`, `deck`) para activar a directriz OD correcta. +4. **Macro → micro** (secção 3, Regra de Ouro). +5. **Variantes antes de fechar** (secção 2, F3) — 3 a 5 variações radicalmente diferentes da secção crítica, resto igual; escolher direcção, só depois refinar. +6. **Referências visuais concretas** — screenshots via menção `@` no chat OD ou ficheiros no projecto; nunca só descrição textual quando existe referência (liga à secção 4.3). +7. **Ecossistema no mesmo projecto OD** — landing + dashboard + app do mesmo cliente vivem no mesmo projecto, para herdar `DESIGN.md`, paleta e tipografia sem deriva (handoff contínuo). +8. **Componentes externos adaptados, não recriados** — gráficos animados, tabelas complexas: importar de bibliotecas (ex: 21st.dev, shadcn/ui) e adaptar ao design system, em vez de gerar do zero. +9. **Acesso directo via MCP** — usar `mcp__open-design__*` (get_artifact, write_file, search_files, start_run) para trabalhar sobre o código vivo do projecto; nunca depender de exports estáticos/zips. Passar `project` explícito (contexto activo expira ~5 min). +10. **Código final limpo e exportável** — HTML/CSS/JS determinístico, responsivo em iframe isolado, pronto para a equipa importar para React/Next.js/Vue sem limpeza. Nada de placeholders, estilos inline órfãos ou dependências fantasma. (Web em produção segue depois PROC-DEV-STANDARD no dev container.) + +## 6. Integração futura (após aprovação do SPEC v3.0.0) + +- Este método torna-se o corpo da skill `design` (router) — gate de contrato + orquestração das 4 fases. +- Para websites, avaliar skill dedicada `create-pro-website` (Next.js/TS/Tailwind/Framer Motion) que empacota o output OD no nosso stack (dev container, regra 48). +- Quality gate: nenhuma entrega sem F4 com score ≥7/10 (design-critic) e zero findings bloqueantes do design-review. diff --git a/design-media/docs/SPECS/SPEC-opendesign-migration.md b/design-media/docs/SPECS/SPEC-opendesign-migration.md new file mode 100644 index 0000000..3ac8be4 --- /dev/null +++ b/design-media/docs/SPECS/SPEC-opendesign-migration.md @@ -0,0 +1,71 @@ +# SPEC — Migração do plugin design-media para Open Design (OD) + +**Versão alvo:** design-media v3.0.0 +**Data:** 2026-07-22 +**Estado:** Rascunho — aguarda aprovação +**Decisor:** Emanuel + +## 1. Objectivo + +O Open Design (MCP `open-design`, daemon local) passa a ser o **motor único** de design do plugin design-media. Os motores actuais (design-engine Fibo/Gemini, Presenton, Stitch, Penpot, python-pptx directo, Remotion local) deixam de ser invocados directamente — tudo passa por projectos OD, skills OD e design systems OD. + +## 2. Porquê + +- O OD já tem nativamente o que o plugin reimplementa: `brand-guidelines`, `brandkit`, `brand-extract`, `theme-factory`, `pptx-generator`, `pptx`, `slides`, `remotion`, `ui-ux-pro-max`, `imagegen`, `venice-*`/`fal-*` (imagem/vídeo/áudio). +- 143 design systems instalados como plugins (`design-system-*`) + suporte a design systems custom por projecto (o projecto "Banners WiP Descomplicar" já usa `designSystemId: descomplicar`). +- Permite **adaptar entre modelos disponíveis no OD** e **criar design systems por cliente** — requisito directo do Emanuel. + +## 3. Âmbito + +### 3.1 Design systems geridos no OD (novo pilar) + +- Formalizar o design system **`descomplicar`** no OD a partir dos tokens actuais (`skills/brand-guidelines/references/descomplicar-theme.md` YAML + `color-palettes.md`). +- Fluxo **novo cliente**: skill OD `brand-extract` (site do cliente) → `theme-factory`/`brand-guidelines` → design system custom no OD, nome = slug do cliente. +- Os brand packs em `Hub/04-Recursos/Design/brands/*.json` são migrados/sincronizados para design systems OD (o JSON local mantém-se como fonte exportável, mas o OD é a fonte operacional). +- Os 4 design systems sectoriais (b2b, ecommerce, saude, solar) passam a design systems OD; as skills locais `design-{b2b,ecommerce,saude,solar}` são reduzidas a referência/routing. + +### 3.2 Skills adaptadas (wrappers finos sobre OD) + +| Skill local | Passa a | +|---|---| +| `design` | Router: cria/reutiliza projecto OD, aplica design system, escolhe skill OD (`imagegen`, `slides`, `poster-hero`, etc.), `start_run` → `get_run` → entrega | +| `brand-guidelines` | Gestão de design systems no OD (criar/actualizar/listar Descomplicar + clientes); mantém a norma escrita (tom, ®) | +| `pptx-generator` | Wrapper das skills OD `pptx-generator`/`pptx`/`slides` com design system aplicado; python-pptx mantido só para leitura/QA de ficheiros existentes | +| `remotion-video` | Wrapper da skill OD `remotion` (+ `venice-video`/`fal-*` quando fizer sentido) | +| `clone-style` | Substituída pela skill OD `brand-extract` (wrapper) | +| `cinematic-site` | Usa skills OD de web (`web-clone`, `frontend-design`) via projecto OD | +| `ui-ux-pro-max`, `design-b2b/ecommerce/saude/solar` | Referência local mantida; apontam para design systems OD | + +### 3.3 Agents actualizados + +- `design-lead`, `design-prompt-architect`, `design-generator`: MCPs alvo passam a `mcp__open-design__*`; remoção de referências a Penpot/Presenton/Stitch/design-engine como motores. +- `design-critic`, `design-researcher`, `ui-designer`, `web-designer`, `video-production-specialist`: actualizar referências de ferramentas; lógica mantém-se. + +### 3.4 Fora de âmbito + +- Alterar o OD em si (daemon, skills OD). +- Migrar histórico de projectos antigos Presenton/Stitch. +- Desligar os MCPs antigos da máquina (fica para limpeza posterior, decisão separada). + +## 4. Critérios de aceitação + +1. `/design` gera um artefacto real num projecto OD com design system `descomplicar` aplicado (prova: run `succeeded` + artefacto). +2. Design system `descomplicar` existe no OD com os tokens oficiais (cores/fontes verificadas contra `descomplicar-theme.md`). +3. Fluxo de cliente demonstrado: criar design system custom para 1 cliente de teste via `brand-extract`. +4. `pptx-generator` produz um deck via OD com brand Descomplicar. +5. `remotion-video` produz/inicia um vídeo via skill OD `remotion`. +6. Zero referências activas a Penpot/Presenton/Stitch/design-engine como motores nas skills/agents adaptados. +7. CHANGELOG.md + versão 3.0.0 + commit atómico. + +## 5. Riscos + +- **Paridade de export**: garantir que o OD exporta PPTX/PNG/PDF nos formatos que os fluxos actuais (propostas, LinkedIn) exigem — validar cedo (crit. 4). +- **Contexto activo OD expira ~5 min**: wrappers devem passar `project` explícito, nunca depender do contexto activo. +- **Outputs grandes do MCP** (`list_plugins` ~270KB): wrappers devem usar filtros/ids directos, nunca listagens completas no contexto (regra 62). + +## 6. Faseamento + +- **F1** — Design system `descomplicar` no OD + skill `brand-guidelines` adaptada. +- **F2** — `design` (router) + agents lead/architect/generator. +- **F3** — `pptx-generator` + `remotion-video` + `clone-style`→`brand-extract`. +- **F4** — Sectoriais + cinematic-site + fluxo cliente de teste + QA final + CHANGELOG/commit. diff --git a/design-media/skills/brand-guidelines/SKILL.md b/design-media/skills/brand-guidelines/SKILL.md index a823965..acb202f 100644 --- a/design-media/skills/brand-guidelines/SKILL.md +++ b/design-media/skills/brand-guidelines/SKILL.md @@ -1,67 +1,113 @@ --- name: brand-guidelines -description: Guia de identidade visual Descomplicar® — cores, tipografia, logotipo, tom de comunicacao e aplicacao por contexto (slides, docs, web, emails). Usar quando "brand descomplicar", "marca descomplicar", "cores descomplicar", "identidade visual", "branding", "paleta de cores", "guia de marca", ou qualquer material que necessite conformidade visual com a marca. -layer: wiki +description: Gestão de identidade visual multi-marca (Descomplicar® e clientes) — design systems no Open Design, cores, tipografia, logótipo, tom e aplicação por contexto. O DESIGN.md de cada marca no Open Design é a fonte de verdade. Usar quando "brand", "marca", "identidade visual", "branding", "paleta de cores", "guia de marca", "design system cliente", "criar marca", ou qualquer material que necessite conformidade visual. --- -# /brand-guidelines - Identidade Visual Descomplicar® +# /brand-guidelines — Gestão de Identidade Visual Multi-Marca -Referencia normativa da marca Descomplicar®. Aplicar em todos os materiais de comunicacao, -design e desenvolvimento. +Esta skill serve **qualquer marca** — a Descomplicar® e cada cliente. A Descomplicar é apenas +a marca por omissão quando nenhuma outra é indicada. + +## Fonte de verdade: o Open Design + +Cada marca tem o seu design system no Open Design, um por pasta: + +``` +~/workspace/open-design/design-systems//DESIGN.md +``` + +- `descomplicar/` — a nossa marca (espelhada em detalhe abaixo) +- `/` — uma pasta por cliente + +O `DESIGN.md` da marca activa é **normativo**. + +**Regras de precedência:** +- Em caso de divergência entre qualquer documento e o `DESIGN.md` da marca, **o `DESIGN.md` ganha sempre**. +- Nunca inventar cores, fontes ou tokens de nenhuma marca. Ler o `DESIGN.md` antes de produzir. +- Alterações à identidade fazem-se no `DESIGN.md` e só depois se propagam. + +> Versões anteriores desta skill documentavam uma paleta azul/laranja (`#1a365d`, `#dd6b20`) com Open Sans +> para a Descomplicar. Estava **errada** — não corresponde ao site nem ao design system. Corrigida em 22-07-2026. + +--- + +## Trabalhar com a marca de um cliente + +**1. Verificar se já existe** — procurar a pasta do cliente em `design-systems/`. Se existir, ler o +`DESIGN.md` e usá-lo. Nunca criar um segundo design system para a mesma marca. + +**2. Criar quando não existe** — extrair a identidade a partir de material real do cliente +(site, manual de marca, ficheiros fornecidos) com as skills do Open Design `brand-extract` +e `theme-factory`. O resultado é revisto com o cliente antes de se tornar normativo. +Nunca inventar a identidade de um cliente a partir do nada. + +**3. Aplicar num projecto** — indicar a marca ao criar o projecto no Open Design +(`create_project` com `designSystem: ""`) para que todos os artefactos herdem +cor, tipografia e componentes sem deriva. + +**4. Manter separado** — um projecto do Open Design serve uma marca só. Ecossistemas do +mesmo cliente (landing, dashboard, app) vivem no mesmo projecto para herdarem o mesmo +`DESIGN.md`; marcas diferentes nunca partilham projecto. + +**Estrutura mínima de um `DESIGN.md`** (o da Descomplicar serve de modelo): +tema e atmosfera, cor, tipografia, espaçamento e grelha, layout e composição, +componentes, movimento, voz e tom, anti-padrões. + +--- + +## Marca por omissão: Descomplicar® + +O resto deste documento espelha o `DESIGN.md` da Descomplicar, para leitura rápida fora do +Open Design. Para clientes, ler sempre o `DESIGN.md` respectivo — os valores abaixo **não se +aplicam** a marcas de clientes. --- ## Identidade da Marca **Nome oficial:** Descomplicar® -**Slogan:** Crescimento Digital **Website:** descomplicar.pt -**Tom:** Profissional mas acessivel, tecnologico sem ser frio -**Valores:** Simplicidade, transparencia, resultados mensuraveis +**Categoria:** agência de aceleração digital portuguesa — artigos, podcast semanal e automações de IA +**Atmosfera:** editorial profissional com acentos dourados; confiança técnica sem arrogância, clareza imediata sem frieza corporativa +**Acabamento:** plano e limpo, sem gradientes decorativos — a hierarquia faz o trabalho visual -> A marca registada (®) e obrigatoria na primeira ocorrencia em qualquer documento ou comunicacao. -> Nas ocorrencias seguintes, pode usar-se apenas "Descomplicar". +> A marca registada (®) é obrigatória na primeira ocorrência em qualquer documento ou comunicação. +> Nas ocorrências seguintes, pode usar-se apenas "Descomplicar". --- -## Paleta de Cores Principal +## Paleta de Cores -| Nome | Hex | RGB | Uso | -|------|-----|-----|-----| -| Azul Escuro | `#1a365d` | 26, 54, 93 | Texto principal, fundos escuros, cabecalhos | -| Azul Medio | `#2b6cb0` | 43, 108, 176 | Links, acentos, botoes secundarios | -| Laranja | `#dd6b20` | 221, 107, 32 | CTA, destaques, elementos de accao | -| Branco | `#ffffff` | 255, 255, 255 | Fundos claros, texto sobre escuro | -| Cinza Claro | `#f7fafc` | 247, 250, 252 | Fundos secundarios, secoes alternadas | -| Cinza Texto | `#4a5568` | 74, 85, 104 | Texto de corpo, descricoes | +| Token | Hex | Uso | +|-------|-----|-----| +| Primary (Dourado) | `#cc8d00` | CTAs, faixas de destaque, ícones, bordas activas, badges | +| Primary Light | `#f2d9a2` | Fundos secundários, hover suave, tags — **nunca para texto** | +| Surface | `#ffffff` | Fundo de página, cards, modais | +| Text | `#000000` | Headlines, corpo principal, labels importantes | +| Text Muted | `#6e6e6e` | Subtítulos, metadados, placeholders | +| Border | `#e5e5e5` | Divisórias, bordas de card, separadores | +| Surface Alt | `#f8f8f8` | Secções alternadas, blocos de código | +| Danger | `#dc2626` | Erros, alertas críticos | +| Success | `#16a34a` | Confirmações, estados de sucesso | -Paleta completa com variacoes de contexto: `references/color-palettes.md` - ---- - -## CSS Variables (Web) +**Regras de uso:** +- O dourado (`#cc8d00`) é o **único acento cromático** — usar com parcimónia e intenção. +- Nunca mais de 3 cores simultâneas no mesmo visual. +- Fundos grandes sempre em Surface (`#ffffff`) ou Surface Alt (`#f8f8f8`). +- CTA principal: fundo dourado com texto preto. +- A secção de maior destaque usa fundo preto, texto branco e acento dourado. ```css :root { - /* Cores principais */ - --color-primary: #1a365d; - --color-secondary: #2b6cb0; - --color-accent: #dd6b20; - - /* Neutros */ - --color-white: #ffffff; - --color-bg-light: #f7fafc; - --color-text-body: #4a5568; - --color-text-heading: #1a365d; - - /* Estados */ - --color-primary-hover: #2a4a7f; - --color-secondary-hover: #2c5282; - --color-accent-hover: #c05621; - - /* Bordas e divisores */ - --color-border: #e2e8f0; - --color-border-light: #edf2f7; + --color-primary: #cc8d00; + --color-primary-light: #f2d9a2; + --color-surface: #ffffff; + --color-surface-alt: #f8f8f8; + --color-text: #000000; + --color-text-muted: #6e6e6e; + --color-border: #e5e5e5; + --color-danger: #dc2626; + --color-success: #16a34a; } ``` @@ -69,92 +115,192 @@ Paleta completa com variacoes de contexto: `references/color-palettes.md` ## Tipografia -### Hierarquia +| Papel | Família | Pesos | +|-------|---------|-------| +| Display | Montserrat, Poppins, system-ui, sans-serif | 700, 800 | +| Corpo | Inter, Open Sans, system-ui, sans-serif | 400, 500, 600 | +| Mono | JetBrains Mono, IBM Plex Mono, monospace | 400 | -| Elemento | Familia | Peso | Tamanho base | -|----------|---------|------|--------------| -| H1 / Titulo principal | Montserrat | Extra Bold (800) | 48px / 3rem | -| H2 / Titulo secao | Montserrat | Bold (700) | 36px / 2.25rem | -| H3 / Subtitulo | Montserrat | Semi Bold (600) | 24px / 1.5rem | -| H4 / Label | Montserrat | Semi Bold (600) | 18px / 1.125rem | -| Corpo / Paragrafo | Open Sans | Regular (400) | 16px / 1rem | -| Destaque / Lead | Open Sans | Semi Bold (600) | 18px / 1.125rem | -| Legenda / Caption | Open Sans | Regular (400) | 14px / 0.875rem | -| Codigo | JetBrains Mono | Regular (400) | 14px / 0.875rem | +### Escala -### CSS Tipografia +| Token | Tamanho | Peso | Line-height | Uso | +|-------|---------|------|-------------|-----| +| `text-5xl` | 48px | 800 | 1.1 | Hero headline | +| `text-4xl` | 36px | 700 | 1.15 | Título de página (H1) | +| `text-3xl` | 30px | 700 | 1.2 | Título de secção (H2) | +| `text-2xl` | 24px | 700 | 1.3 | Subsecção (H3) | +| `text-xl` | 20px | 600 | 1.4 | Título de card, H4 | +| `text-lg` | 18px | 500 | 1.5 | Parágrafo de entrada | +| `text-base` | 16px | 400 | 1.6 | Corpo | +| `text-sm` | 14px | 400 | 1.5 | Legendas, labels, UI | +| `text-xs` | 12px | 500 | 1.4 | Tags, badges, micro-copy | + +**Regras:** +- Montserrat exclusivamente para títulos — nunca em parágrafos longos. +- Inter para tudo o que é lido em detalhe. +- `letter-spacing: 0.02em` em labels e badges em maiúsculas. +- Sem itálico decorativo — usar peso e tamanho para hierarquia. ```css -:root { - --font-heading: 'Montserrat', 'Arial Black', sans-serif; - --font-body: 'Open Sans', 'Helvetica Neue', Arial, sans-serif; - --font-code: 'JetBrains Mono', 'Fira Code', 'Courier New', monospace; - - --line-height-heading: 1.2; - --line-height-body: 1.6; - --letter-spacing-heading: -0.025em; -} +@import url('https://fonts.googleapis.com/css2?family=Montserrat:wght@700;800&family=Inter:wght@400;500;600&family=JetBrains+Mono&display=swap'); ``` -### Fallbacks de Sistema +--- -- **Montserrat** indisponivel: `'Arial Black', 'Impact', sans-serif` -- **Open Sans** indisponivel: `'Helvetica Neue', Arial, sans-serif` -- **JetBrains Mono** indisponivel: `'Fira Code', 'Courier New', monospace` +## Espaçamento, Grelha e Raios + +Escala base de 4px: `space-1` 4px, `space-2` 8px, `space-3` 12px, `space-4` 16px, `space-6` 24px, `space-8` 32px, `space-12` 48px, `space-16` 64px, `space-24` 96px. + +**Grelha:** 12 colunas, gutter 24px, conteúdo centrado com max-width 1280px (960px em artigos, 760px em texto corrido com line-height 1.7). +**Breakpoints:** mobile ≤768px, tablet 769–1024px, desktop >1024px. +**Padding lateral:** 16px mobile, 32px tablet, 48px desktop. +**Raios:** `sm` 4px (inputs, badges), `md` 8px (cards, botões), `lg` 12px (modais), `full` 9999px (pills, avatares). + +--- + +## Componentes + +**Botão** — Primary: fundo `#cc8d00`, texto `#000000`, Montserrat SemiBold, raio 8px. Secondary: transparente, borda 2px dourada, texto dourado. Ghost: transparente, texto preto, sublinhado no hover. Alturas: sm 32px, md 40px, lg 48px. + +**Badge** — Default: fundo `#f8f8f8`, texto `#6e6e6e`, maiúsculas, 12px, tracking alargado. Primary: fundo `#f2d9a2`, texto `#7a5500`. + +**Card** — Fundo branco, borda 1px `#e5e5e5`, raio 8px, padding 24px, imagem 16:9 no topo. Sombra no hover: `0 4px 16px rgba(0,0,0,0.1)`. + +**Input** — Borda 1px `#e5e5e5`, raio 8px, padding 12px 16px. Focus: borda 2px dourada, sem outline. Erro: borda 2px `#dc2626` com mensagem abaixo. Label em Inter SemiBold 14px maiúsculas. + +**Navbar** — Fundo preto, logótipo à esquerda, links brancos, CTA dourado à direita, sticky com `backdrop-filter: blur(8px)`. + +**Rodapé** — Fundo preto, texto branco/cinza, links com hover dourado, 3 colunas (marca, navegação, contacto) e copyright em `text-xs`. + +--- + +## Movimento + +O movimento **confirma acções, nunca decora**. + +- 150ms em micro-interacções (hover, focus); 250ms em transições de estado. +- `ease-out` nas entradas, `ease-in-out` nas transições bidireccionais. +- Cards no hover: `translateY(-2px)` mais sombra, 200ms. +- Transições de página: fade simples 200ms. +- Estados de carregamento: skeleton em `#f8f8f8` com shimmer subtil. +- Sem parallax, sem animações de entrada elaboradas, sem auto-play. --- ## Logótipo -### Regras de Uso - -| Regra | Descricao | +| Regra | Descrição | |-------|-----------| -| Espaco minimo | Margem de pelo menos 2x a altura da letra "D" em todos os lados | -| Tamanho minimo | 120px de largura em digital; 30mm em impressao | -| Fundo permitido | Branco `#ffffff`, Azul Escuro `#1a365d`, Cinza Claro `#f7fafc` | -| Fundo proibido | Qualquer fundo com baixo contraste, fotografias sem overlay | -| Distorcao | Nunca esticar, rodar ou alterar proporcoes | -| Cores proibidas | Nunca alterar as cores do logótipo original | -| Texto junto | Nunca sobrepor texto ao logótipo | +| Espaço mínimo | Margem de pelo menos 2x a altura da letra "D" em todos os lados | +| Tamanho mínimo | 120px de largura em digital; 30mm em impressão | +| Fundos permitidos | Branco `#ffffff`, preto `#000000`, cinza claro `#f8f8f8` | +| Fundos proibidos | Baixo contraste, fotografias sem overlay | +| Proibido | Esticar, rodar, alterar proporções, alterar cores, sobrepor texto | -### Variantes Disponiveis +**Variantes:** principal (horizontal), compacta, monocromática escura, monocromática clara, ícone isolado (favicon, avatar). -| Variante | Quando usar | -|----------|-------------| -| Principal (horizontal) | Uso geral, cabecalhos, documentos | -| Compacta (icone + nome vertical) | Espacos reduzidos, avatares | -| Monocromatica escura | Documentos a preto e branco, impressao simples | -| Monocromatica clara | Sobre fundos escuros, rodapes | -| Icone isolado | Favicon, app icon, redes sociais (foto de perfil) | - -### Ficheiros Logótipo - -``` -Hub/04-Recursos/Design/brands/descomplicar/ - logo-principal.svg - logo-compacto.svg - logo-mono-escuro.svg - logo-mono-claro.svg - favicon.png - favicon.svg -``` +**Ficheiros:** `Hub/04-Recursos/Design/brands/descomplicar/` --- -## Aplicacao por Contexto +## Aplicação por Contexto -### Apresentacoes e Slides +**Apresentações e slides** — Capa e secções de destaque com fundo preto, título Montserrat ExtraBold branco, acento dourado. Slides de conteúdo com fundo branco ou `#f8f8f8`, corpo em Inter `#000000`, destaques e números em dourado. -``` -Fundo slides: #1a365d (escuro) ou #ffffff (claro) -Titulo slide: Montserrat Extra Bold, #ffffff (sobre escuro) / #1a365d (sobre claro) -Corpo texto: Open Sans Regular, #ffffff ou #4a5568 -Destaques/CTA: #dd6b20 -Divisores: #2b6cb0 -Slide titulo (capa): fundo #1a365d, logótipo variante clara +**Documentos e propostas** — Cabeçalho preto com logótipo claro; corpo branco com texto preto; títulos de secção em Montserrat; callouts com fundo `#f8f8f8` e borda esquerda dourada; rodapé `#f8f8f8` com borda superior `#e5e5e5`. + +**Web e landing pages** — Hero claro ou escuro conforme a variante escolhida; CTA primário dourado com texto preto; secções alternadas em `#f8f8f8`; cards brancos com borda `#e5e5e5`. + +**Emails e newsletter** — Pré-header preto, corpo branco com texto preto, cabeçalhos Montserrat, botão CTA dourado com texto preto e raio 8px, rodapé `#f8f8f8`. + +**Redes sociais** — Fundo preto ou branco, elemento de marca em dourado, texto sem emojis. + +--- + +## Tom de Comunicação + +**Tom:** profissional mas acessível, directo, orientado à acção, confiante sem arrogância. + +**Princípios de copy:** +- PT-PT estrito — "utilizador" não "usuário", "transferir" não "baixar", "ecrã" não "tela", "equipa" não "time". +- Frases curtas, verbo no início nos CTAs: "Saber mais", "Ver guia", "Falar connosco". +- Títulos assertivos, sem interrogações desnecessárias. +- Dados concretos: "400+ artigos", não "muitos artigos". +- Sem emojis e sem exclamações excessivas em qualquer contexto de marca. + +**Headlines** — Directas e específicas: "SEO para PMEs que funciona" em vez de "Descubra como o SEO pode transformar o seu negócio". + +**CTAs correctos:** "Ver todos os guias", "Pedir auditoria gratuita", "Subscrever newsletter". +**CTAs incorrectos:** "Clique aqui!", "Saiba Mais!!!", qualquer CTA com emoji. + +--- + +## Iconografia e Imagens + +**Ícones:** lineares, peso 1.5–2px, cantos ligeiramente arredondados. Lucide, Heroicons ou Phosphor. Tamanhos 16/20/24/32px. Cor herdada do contexto ou dourada. + +**Fotografia:** profissional e luminosa, pessoas reais em contexto. Overlay preto (20–40%) quando houver texto por cima. **Proibidas** stock photos genéricas — pessoas a sorrir para portáteis, apertos de mão corporativos. + +**Ilustrações e gráficos:** flat, linhas limpas, paleta restrita à marca; destaques a dourado. + +--- + +## Acessibilidade + +| Par de cores | Rácio | Nível | +|--------------|-------|-------| +| Preto sobre branco | 21:1 | AAA | +| Preto sobre dourado `#cc8d00` | ~7.4:1 | AAA | +| Dourado `#cc8d00` sobre preto | ~7.4:1 | AAA | +| Text Muted `#6e6e6e` sobre branco | ~5.1:1 | AA | +| **Branco sobre dourado** | **~2.9:1** | **falha — proibido** | + +Texto de corpo requer no mínimo AA (4.5:1). Todos os botões precisam de estados hover, focus e disabled explícitos. + +--- + +## Anti-padrões (proibido) + +- Gradientes multicolor ou agressivos em elementos de marca +- Mais de 3 cores simultâneas num visual +- Stock photos genéricas +- Emojis em qualquer contexto de marca +- Tipografia decorativa além de Montserrat e Inter +- Sombras pesadas ou neumorfismo +- Animações que distraem (rotações, bounces, pulse contínuo) +- Texto branco sobre dourado — contraste insuficiente +- Primary Light (`#f2d9a2`) como cor de texto +- Layouts com mais de 4 colunas de conteúdo editorial +- Botões sem estados hover, focus e disabled +- Português do Brasil — sempre PT-PT com acentuação completa + +--- + +## Checklist de Conformidade + +- [ ] `DESIGN.md` do Open Design consultado antes de produzir +- [ ] Apenas cores da paleta oficial; dourado como único acento +- [ ] Montserrat nos títulos, Inter no corpo +- [ ] Logótipo com espaço de respiro e fundo permitido +- [ ] Marca registada (®) na primeira ocorrência +- [ ] Contraste mínimo AA; nunca branco sobre dourado +- [ ] Espaçamento em múltiplos de 4px +- [ ] PT-PT sem brasileirismos e sem emojis +- [ ] Nenhum anti-padrão presente + +--- + +**Versão**: 2.0.0 | **Data**: 22-07-2026 | **Autor**: Descomplicar® +*Fonte normativa: `~/workspace/open-design/design-systems/descomplicar/DESIGN.md`* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"2026-07-22","issue":"Skill documentava paleta azul/laranja (#1a365d, #dd6b20) e Open Sans, divergente do design system e do site real","fix":"Reescrita para espelhar o DESIGN.md do Open Design (dourado #cc8d00 sobre preto/branco, Montserrat + Inter) e declarar precedencia da fonte de verdade","source":"user"} ``` -Modelo: `/design presentation --brand descomplicar` - -## \ No newline at end of file +*Adicionar nova linha após cada erro corrigido.* diff --git a/design-media/skills/brand-guidelines/references/descomplicar-theme.md b/design-media/skills/brand-guidelines/references/descomplicar-theme.md index 615b063..b2fbf3d 100644 --- a/design-media/skills/brand-guidelines/references/descomplicar-theme.md +++ b/design-media/skills/brand-guidelines/references/descomplicar-theme.md @@ -1,155 +1,123 @@ --- -name: "Descomplicar Digital" -description: "Professional technology consulting theme with warm accents" -version: "1.0.0" -updated: "2026-03-10" -layer: wiki +name: "Descomplicar" +description: "Tokens da marca Descomplicar® — espelho legível por máquina do DESIGN.md no Open Design" +version: "2.0.0" +updated: "2026-07-22" +source: "~/workspace/open-design/design-systems/descomplicar/DESIGN.md" --- -# Tema Descomplicar Digital +# Tokens — Descomplicar® -Tema oficial Descomplicar® para uso em apresentações, relatórios, designs e qualquer material de comunicação. +> **Fonte de verdade:** `~/workspace/open-design/design-systems/descomplicar/DESIGN.md` +> Este ficheiro é um espelho para consumo automático (geradores, templates, scripts). +> Se divergir do `DESIGN.md`, o `DESIGN.md` ganha e este ficheiro deve ser corrigido. +> +> **Para marcas de clientes**, não usar estes valores — ler o `DESIGN.md` da marca respectiva +> em `design-systems//`. ---- - -## Paleta de Cores +## Cores ```yaml colors: - primary: "#1a365d" # Azul escuro — headers, fundos principais - secondary: "#2b6cb0" # Azul médio — links, sub-headers - accent: "#dd6b20" # Laranja — CTAs, destaques, números - background: "#ffffff" # Branco — fundo principal - surface: "#f7fafc" # Cinza muito claro — secções alternadas - text_primary: "#2d3748" # Cinza escuro — texto corpo - text_secondary: "#4a5568" # Cinza médio — subtítulos, legendas - border: "#e2e8f0" # Cinza claro — bordas, separadores - success: "#38a169" # Verde — confirmações - warning: "#d69e2e" # Amarelo — avisos - error: "#e53e3e" # Vermelho — erros + primary: "#cc8d00" # Dourado — CTAs, destaques, ícones, bordas activas + primary_light: "#f2d9a2" # Fundos secundários, hover suave, tags (nunca texto) + surface: "#ffffff" # Fundo de página, cards, modais + surface_alt: "#f8f8f8" # Secções alternadas, blocos de código + text: "#000000" # Headlines, corpo principal + text_muted: "#6e6e6e" # Subtítulos, metadados, placeholders + border: "#e5e5e5" # Divisórias, bordas de card + danger: "#dc2626" # Erros, alertas críticos + success: "#16a34a" # Confirmações ``` -### Referência Visual - -| Token | Hex | Uso | -|-------|-----|-----| -| `primary` | `#1a365d` | Headers H1/H2, fundos de navegação, capa de apresentação | -| `secondary` | `#2b6cb0` | Links, H3/H4, badges, ícones activos | -| `accent` | `#dd6b20` | Botões CTA, números em destaque, linhas de separação principais | -| `background` | `#ffffff` | Fundo padrão de slides e páginas | -| `surface` | `#f7fafc` | Slides alternados, tabelas linha par, painéis laterais | -| `text_primary` | `#2d3748` | Corpo de texto, parágrafos, listas | -| `text_secondary` | `#4a5568` | Subtítulos, legendas, texto auxiliar | -| `border` | `#e2e8f0` | Bordas de tabela, separadores horizontais, cards | -| `success` | `#38a169` | Confirmações, métricas positivas, status "concluído" | -| `warning` | `#d69e2e` | Avisos, métricas de atenção, status "em risco" | -| `error` | `#e53e3e` | Erros, métricas negativas, status "crítico" | - ---- +**Regras:** dourado é o único acento cromático; máximo 3 cores por visual; fundos grandes em +`surface` ou `surface_alt`; CTA com fundo dourado e texto preto; nunca texto branco sobre dourado. ## Tipografia ```yaml fonts: - heading: "Montserrat" - heading_weight: "700, 800" - heading_fallback: "Arial, sans-serif" - body: "Open Sans" - body_weight: "400, 600" - body_fallback: "Helvetica, sans-serif" - code: "JetBrains Mono" - code_fallback: "Consolas, monospace" + display: "Montserrat" + display_fallback: "Poppins, system-ui, sans-serif" + display_weights: [700, 800] + body: "Inter" + body_fallback: "Open Sans, system-ui, sans-serif" + body_weights: [400, 500, 600] + mono: "JetBrains Mono" + mono_fallback: "IBM Plex Mono, monospace" + mono_weights: [400] + +scale: + text_5xl: { size: 48, weight: 800, line_height: 1.1 } # Hero headline + text_4xl: { size: 36, weight: 700, line_height: 1.15 } # H1 + text_3xl: { size: 30, weight: 700, line_height: 1.2 } # H2 + text_2xl: { size: 24, weight: 700, line_height: 1.3 } # H3 + text_xl: { size: 20, weight: 600, line_height: 1.4 } # H4, título de card + text_lg: { size: 18, weight: 500, line_height: 1.5 } # Parágrafo de entrada + text_base:{ size: 16, weight: 400, line_height: 1.6 } # Corpo + text_sm: { size: 14, weight: 400, line_height: 1.5 } # Legendas, UI + text_xs: { size: 12, weight: 500, line_height: 1.4 } # Tags, badges ``` -### Hierarquia Tipográfica - -| Nível | Fonte | Peso | Tamanho (slides) | Tamanho (docs) | -|-------|-------|------|-----------------|----------------| -| H1 — Título principal | Montserrat | 800 | 40-48px | 32px | -| H2 — Título secção | Montserrat | 700 | 28-36px | 24px | -| H3 — Subtítulo | Montserrat | 700 | 22-26px | 20px | -| H4 — Label | Open Sans | 600 | 18-20px | 16px | -| Corpo | Open Sans | 400 | 16-18px | 14-16px | -| Caption | Open Sans | 400 | 12-14px | 12px | -| Código | JetBrains Mono | 400 | 14-16px | 13px | - -### Google Fonts — Import - ```css -@import url('https://fonts.googleapis.com/css2?family=Montserrat:wght@700;800&family=Open+Sans:wght@400;600&family=JetBrains+Mono&display=swap'); +@import url('https://fonts.googleapis.com/css2?family=Montserrat:wght@700;800&family=Inter:wght@400;500;600&family=JetBrains+Mono&display=swap'); ``` ---- - -## Regras de Uso +## Espaçamento, grelha e raios ```yaml -usage_notes: - - Usar laranja com moderação (apenas CTAs e destaques-chave) - - Azul escuro para headers e elementos de navegação - - Fundos alternados branco/cinza para secções longas - - Nunca usar mais de 3 cores numa slide - - Manter contraste WCAG AA em todos os textos +spacing: # base 4px + space_1: 4 + space_2: 8 + space_3: 12 + space_4: 16 + space_6: 24 + space_8: 32 + space_12: 48 + space_16: 64 + space_24: 96 + +grid: + columns: 12 + gutter: 24 + max_width: 1280 # conteúdo geral + max_width_article: 960 # artigos + max_width_prose: 760 # texto corrido (line-height 1.7) + padding_x: { mobile: 16, tablet: 32, desktop: 48 } + +breakpoints: + mobile: "<=768" + tablet: "769-1024" + desktop: ">1024" + +radius: + sm: 4 # inputs, badges + md: 8 # cards, botões + lg: 12 # modais + full: 9999 # pills, avatares ``` -### Regras Expandidas +## Movimento -**Cores** -- O laranja (`accent`) é reservado para no máximo 1-2 elementos por slide/página -- Nunca usar `primary` e `accent` em simultâneo em texto — garante legibilidade -- Fundo `surface` em slides alternados cria ritmo visual sem poluição -- Combinação permitida em texto: `primary` fundo + `background` texto, ou `background` fundo + `primary` texto - -**Tipografia** -- Nunca misturar Montserrat com outra fonte de títulos no mesmo documento -- Open Sans é a única fonte de corpo permitida -- Código inline e blocos de código: sempre JetBrains Mono -- Não usar itálico em títulos — usar peso (bold) para ênfase - -**Contraste WCAG AA** -- `text_primary` (#2d3748) sobre `background` (#ffffff): rácio 12.6:1 — aprovado -- `text_secondary` (#4a5568) sobre `background` (#ffffff): rácio 7.4:1 — aprovado -- `accent` (#dd6b20) sobre `background` (#ffffff): rácio 3.8:1 — aprovado para texto grande (>18px bold) -- `background` (#ffffff) sobre `primary` (#1a365d): rácio 12.6:1 — aprovado - ---- - -## Aplicação em Slides - -### Layout Tipo Capa - -``` -[Fundo: primary #1a365d] -[Logo Descomplicar — branco, topo esquerdo] -[H1: Montserrat 800, branco] -[H2: Montserrat 700, accent #dd6b20] -[Rodapé: Open Sans 400, text_secondary, separador border] +```yaml +motion: + micro: 150 # hover, focus (ms) + transition: 250 # mudanças de estado (ms) + page_fade: 200 # transições de página (ms) + easing_in: "ease-out" + easing_both: "ease-in-out" + card_hover: "translateY(-2px) + sombra 0 4px 16px rgba(0,0,0,0.1)" + proibido: ["parallax", "auto-play", "animações de entrada elaboradas"] ``` -### Layout Tipo Conteúdo +## Acessibilidade +```yaml +contrast: + preto_sobre_branco: 21.0 # AAA + preto_sobre_dourado: 7.4 # AAA + dourado_sobre_preto: 7.4 # AAA + muted_sobre_branco: 5.1 # AA + branco_sobre_dourado: 2.9 # FALHA — proibido +minimo_corpo: 4.5 # AA ``` -[Fundo: background #ffffff] -[Header barra: primary #1a365d, 8px altura] -[H2: primary #1a365d, Montserrat 700] -[Corpo: text_primary #2d3748, Open Sans 400] -[Sidebar ou destaque: surface #f7fafc] -[CTA ou número chave: accent #dd6b20, Montserrat 800] -``` - -### Layout Tipo Dados / Métricas - -``` -[Fundo alternado: surface #f7fafc] -[Número grande: accent #dd6b20, Montserrat 800, 60-80px] -[Label: text_secondary #4a5568, Open Sans 600, 14px] -[Ícone: secondary #2b6cb0] -``` - ---- - -## Aplicação em HTML (Desk CRM / Relatórios) - -```css -:root { - --c \ No newline at end of file diff --git a/design-media/skills/brand-guidelines/references/design-systems-multimarca.md b/design-media/skills/brand-guidelines/references/design-systems-multimarca.md new file mode 100644 index 0000000..1d981ad --- /dev/null +++ b/design-media/skills/brand-guidelines/references/design-systems-multimarca.md @@ -0,0 +1,89 @@ +# Gestão de Design Systems Multi-Marca no Open Design + +Referência operacional para criar e manter a identidade visual de **qualquer marca** — a +Descomplicar® e cada cliente — dentro do Open Design. + +> Substituiu `color-palettes.md` em 22-07-2026. Esse ficheiro continha escalas de cor derivadas +> de uma paleta incorrecta (azul/laranja) que nunca foi a identidade da Descomplicar. +> Escalas de cor não se inventam aqui — vivem no `DESIGN.md` de cada marca. + +--- + +## Onde vivem + +``` +~/workspace/open-design/design-systems/ + descomplicar/DESIGN.md # a nossa marca + /DESIGN.md # uma pasta por cliente +``` + +O Open Design traz ainda mais de 140 design systems de referência instalados como plugins +(`design-system-apple`, `design-system-swiss`, `design-system-bento`, …). Servem de **referência +e ponto de partida** — nunca se entrega material de cliente com a identidade de outra marca. + +--- + +## Criar o design system de um cliente + +**1. Verificar duplicados** — procurar a pasta do cliente em `design-systems/`. Se já existir, +usar essa. Nunca criar um segundo design system para a mesma marca. + +**2. Recolher material real** — site do cliente, manual de marca, logótipos, materiais impressos. +Sem material não há extracção: a identidade de um cliente **nunca se inventa**. + +**3. Extrair** — skill `brand-extract` do Open Design sobre o site ou os ficheiros fornecidos. +Devolve cor, tipografia e padrões observados. + +**4. Estruturar** — skill `theme-factory` ou redacção directa do `DESIGN.md`, seguindo a mesma +estrutura do da Descomplicar: + +| Secção | Conteúdo | +|--------|----------| +| 1. Tema e atmosfera | Categoria, estilo visual, postura cromática, mood, acabamento | +| 2. Cor | Tokens com hex e uso; regras de aplicação | +| 3. Tipografia | Famílias, pesos, escala com tamanho/peso/line-height | +| 4. Espaçamento e grelha | Escala base, colunas, gutter, max-width, breakpoints, raios | +| 5. Layout e composição | Hierarquia, padrões de layout frequentes | +| 6. Componentes | Botões, badges, cards, inputs, navbar, rodapé | +| 7. Movimento | Durações, easing, o que é proibido | +| 8. Voz e marca | Tom, princípios de copy, exemplos certos e errados | +| 9. Anti-padrões | Lista explícita do que nunca fazer | + +**5. Validar com o cliente** antes de tornar normativo. Um `DESIGN.md` por aprovar não deve +gerar material final. + +**6. Registar** — anotar a marca e a origem do material no projecto ou tarefa correspondente. + +--- + +## Aplicar numa produção + +``` +create_project(name: "", designSystem: "") +``` + +- Um projecto do Open Design serve **uma marca só**. +- Ecossistemas do mesmo cliente (landing, dashboard, app, deck) ficam **no mesmo projecto**, + para herdarem o mesmo `DESIGN.md` sem deriva entre artefactos. +- Marcas diferentes nunca partilham projecto. + +--- + +## Manter + +- Alterações de identidade fazem-se **no `DESIGN.md`** e só depois se propagam para espelhos + (skill `brand-guidelines`, `descomplicar-theme.md`, materiais no Hub). +- Ao detectar divergência entre um espelho e o `DESIGN.md`, corrigir o espelho — nunca o inverso. +- Rebranding de cliente: actualizar o `DESIGN.md` e regenerar os artefactos afectados, em vez de + corrigir peça a peça. + +--- + +## Acessibilidade — verificação obrigatória + +Independentemente da marca, validar antes de entregar: + +- Texto de corpo com contraste mínimo AA (4.5:1); títulos grandes 3:1. +- Nenhum par de cores da marca usado abaixo do mínimo, mesmo que o cliente o use hoje — + quando o material de origem falha contraste, sinalizar ao cliente em vez de replicar o erro. +- Estados hover, focus e disabled explícitos em todos os elementos interactivos. diff --git a/design-media/skills/cinematic-site/SKILL.md b/design-media/skills/cinematic-site/SKILL.md index 5e59bf5..3600a0b 100644 --- a/design-media/skills/cinematic-site/SKILL.md +++ b/design-media/skills/cinematic-site/SKILL.md @@ -5,7 +5,6 @@ description: "Constroi websites cinematograficos a partir de um site existente. version: "1.0.0" created: 2026-04-07 tools: [Bash, Read, Write, mcp__claude-in-chrome__read_page, mcp__claude-in-chrome__tabs_create_mcp, mcp__chrome-devtools__take_screenshot] -layer: wiki --- # Skill: /cinematic-site diff --git a/design-media/skills/clone-style/SKILL.md b/design-media/skills/clone-style/SKILL.md index a3d6b2d..5b380ac 100644 --- a/design-media/skills/clone-style/SKILL.md +++ b/design-media/skills/clone-style/SKILL.md @@ -1,7 +1,6 @@ --- name: clone-style description: Clona o estilo visual de um site ou apresentação extraindo design tokens (cores, tipografia, espaçamento, raios, sombras) e gerando JSON compatível com Stitch, design-engine e pptx-generator. Usar quando "clonar estilo", "clone style", "extrair design", "copiar visual", "tokens design", "clone web", "clone slides", "design tokens". -layer: wiki --- # /clone-style — Extrair Design Tokens de Sites e Slides @@ -117,4 +116,163 @@ Recebe `tokens.json` e aplica numa das 3 ferramentas: **Limitação importante:** Stitch só aceita um conjunto restrito de tokens (ver schema `mcp__stitch__create_design_system`): - 1 `customColor` (seed) + opcionais `overridePrimaryColor`/`overrideSecondaryColor`/`overrideTertiaryColor`/`overrideNeutralColor` -- \ No newline at end of file +- `headlineFont` / `bodyFont` / `labelFont` de **enum fixo** (29 Google Fonts: INTER, ROBOTO, MANROPE, GEIST, etc.) +- `roundness`: ROUND_4 / ROUND_8 / ROUND_12 / ROUND_FULL +- `colorMode`: LIGHT / DARK +- `designMd`: markdown livre para tudo o que não cabe nos campos acima + +**Mapeamento Stitch:** + +``` +tokens.colors.dominant → customColor (seed) +tokens.colors.top[1..3] → overridePrimary/Secondary/Tertiary +tokens.colors.neutral → overrideNeutralColor + +tokens.fonts.headline.family + → match com enum Stitch (fuzzy: "Helvetica" → INTER, "Söhne" → INTER, etc.) + → headlineFont + +tokens.fonts.body.family + → match enum → bodyFont + +tokens.borderRadius.dominant + → 4px → ROUND_4 + → 8-10px → ROUND_8 + → 12-14px → ROUND_12 + → ≥16px ou full → ROUND_FULL + +tokens.background.dark? → colorMode: DARK, else LIGHT + +# Tudo o resto vai para designMd: +designMd: | + ## Estilo extraído de + + ### Tipografia adicional + - Display: + - Caption: + + ### Espaçamento + Grid base: + Escala: 4, 8, 16, 24, 32, 48, 64 + + ### Sombras + - sm: + - md: + - lg: + + ### Tom visual + +``` + +Depois chama `mcp__stitch__create_design_system` com este payload. + +### B) design-engine (brand pack) + +Cria um JSON brand pack em `/media/ealmeida/Dados/Hub/04-Recursos/Design/brands/.json` com formato: + +```json +{ + "name": "", + "source": "cloned from ", + "extracted_at": "2026-04-07", + "colors": { "primary": "#...", "secondary": "#...", "neutral": "#...", "accent": "#..." }, + "fonts": { "headline": "Inter", "body": "Inter" }, + "borderRadius": "8px", + "tone": "minimalista, profissional, denso" +} +``` + +Depois `mcp__design-engine__brand_load()` para usar em `generate_image`. + +### C) pptx-generator (slides) + +Aplica os tokens via XML manipulation no template Descomplicar (ver `/pptx-generator`). Substitui: +- Cores accent1-6 do `theme1.xml` pelos extraídos +- Fontes major/minor pelas extraídas +- Mantém layouts/positioning do template Descomplicar (não copia layouts da fonte original — só estilo) + +--- + +## Mapeamento de fontes (fuzzy → Stitch enum) + +Quando `tokens.fonts.headline.family` não está no enum Stitch, mapear: + +| Família detectada | Stitch enum | +|---|---| +| Helvetica, Helvetica Neue, Arial, sans-serif genérico | INTER | +| Söhne, Inter, system-ui | INTER | +| Roboto, Roboto Flex | (não existe — usar INTER) | +| SF Pro, -apple-system | INTER | +| GT Walsheim, Geist, Mona Sans | GEIST | +| Manrope | MANROPE | +| Plus Jakarta, Jakarta | PLUS_JAKARTA_SANS | +| DM Sans | DM_SANS | +| IBM Plex Sans | IBM_PLEX_SANS | +| Sora | SORA | +| Times, serif genérico | NEWSREADER | +| Garamond, EB Garamond | EB_GARAMOND | +| Playfair, Domine | DOMINE | + +Se nenhum match óbvio, **default INTER** (mais neutro). Adicionar nota em `designMd` com a fonte original detectada. + +--- + +## Anti-patterns + +| Não fazer | Razão | +|---|---| +| Tentar reproduzir layout pixel a pixel | Impossível e gera "AI slop" | +| Usar `cssstats.com` ou scrapers HTML estáticos | Falham em sites JS-rendered (Next.js, React, etc.) | +| Importar HTML inteiro como Stitch screen | Stitch não importa HTML; gera de prompt+tokens | +| Aplicar Stitch design-system sem `customColor` válido | Validation error — `customColor` é obrigatório | +| Esquecer de usar `designMd` para tokens fora do enum | Perde-se 50% da informação extraída | + +--- + +## Validação (critérios para "OK") + +Antes de declarar a clonagem completa: +1. ✅ `tokens.json` existe e tem `colors`, `fonts`, `borderRadius` no mínimo +2. ✅ Pelo menos 1 screenshot guardado +3. ✅ Mapeamento Stitch produz `customColor` válido (hex format) +4. ✅ Pelo menos 1 fonte mapeada para enum Stitch +5. ✅ `designMd` tem ≥3 secções (tipografia, espaçamento, tom) +6. ✅ Se modo `apply`: validação visual pelo utilizador antes de marcar "concluído" + +--- + +## Exemplos práticos + +### Clonar Linear + +``` +/clone-style web https://linear.app +``` +Esperado: paleta dominante azul/roxo, fontes Inter ou similar, raios 6-8px, dark mode default. + +### Clonar template cliente + +``` +/clone-style slides ~/Downloads/cliente-deck.pptx +``` +Esperado: cores accent do tema PPTX, fontes major/minor, proposta de paleta unificada. + +### Aplicar a novo projecto Stitch + +``` +/clone-style apply ~/.claude-work/clone-style/linear-app-20260407/tokens.json +``` +Cria design system Stitch + brand pack design-engine. + +--- + +## Referências internas + +- `references/extract-web-tokens.js` — script JS de extracção CSS computado +- `references/extract-pptx-theme.py` — script Python para parsear theme1.xml +- `~/.claude-work/clone-style/` — cache de extracções (timestamped) + +--- + +**Versão:** 1.0.0 | **Data:** 2026-04-07 | **Autor:** Descomplicar (sessão 5) +**Origem:** Necessidade real — clonagem de estilos em propostas comerciais. Substitui tentativas falhadas com Penpot, scrapers HTML, screenshots+AI, Figma import. diff --git a/design-media/skills/design-b2b/SKILL.md b/design-media/skills/design-b2b/SKILL.md index ae3b97d..65bcfb7 100644 --- a/design-media/skills/design-b2b/SKILL.md +++ b/design-media/skills/design-b2b/SKILL.md @@ -5,7 +5,6 @@ description: > Propostas visuais, landing pages, apresentações e materiais para decisores PT. Usar quando: proposta comercial, landing page serviço B2B, apresentação cliente, one-pager, ou qualquer material visual para audiência empresarial portuguesa. -layer: wiki --- # /design-b2b — Design System Serviços B2B diff --git a/design-media/skills/design-ecommerce/SKILL.md b/design-media/skills/design-ecommerce/SKILL.md index bac65bc..f28d725 100644 --- a/design-media/skills/design-ecommerce/SKILL.md +++ b/design-media/skills/design-ecommerce/SKILL.md @@ -5,7 +5,6 @@ description: > Optimização conversão, layouts loja, UX checkout e elementos de confiança. Usar quando: criar ou optimizar loja WooCommerce, página produto, carrinho, checkout, ou qualquer elemento visual de e-commerce para mercado português. -layer: wiki --- # /design-ecommerce — Design System E-commerce diff --git a/design-media/skills/design-saude/SKILL.md b/design-media/skills/design-saude/SKILL.md index ca971fd..6a62b90 100644 --- a/design-media/skills/design-saude/SKILL.md +++ b/design-media/skills/design-saude/SKILL.md @@ -5,7 +5,6 @@ description: > Paleta, tipografia, CTAs e layouts optimizados para contexto clínico PT. Usar quando: criar landing page de clínica, página de serviços médicos, agendamento online, ou qualquer material visual para clientes saúde. -layer: wiki --- # /design-saude — Design System Saúde diff --git a/design-media/skills/design-solar/SKILL.md b/design-media/skills/design-solar/SKILL.md index dc0f45f..f0da622 100644 --- a/design-media/skills/design-solar/SKILL.md +++ b/design-media/skills/design-solar/SKILL.md @@ -5,7 +5,6 @@ description: > Paleta, calculadoras, propostas visuais e layouts para sector energias renováveis PT. Usar quando: landing page solar, proposta instalação FV, calculadora poupança, ou material visual para clientes energia solar. -layer: wiki --- # /design-solar — Design System Solar/FV diff --git a/design-media/skills/design/SKILL.md b/design-media/skills/design/SKILL.md index 2588234..03b58cf 100644 --- a/design-media/skills/design/SKILL.md +++ b/design-media/skills/design/SKILL.md @@ -1,7 +1,6 @@ --- name: design description: Motor de design profissional multi-marca. Gera apresentações, infográficos, logos, social media, web pages e identidade visual. -layer: wiki --- # /design - Motor de Design Profissional @@ -144,4 +143,28 @@ Formato: `{nome}.json` com cores, fontes, logos, voz, estilo. | Instagram Post | 1:1 | 1080x1080 | | Instagram Story | 9:16 | 1080x1920 | | LinkedIn Post | ~2:1 | 1200x628 | -| YouTube Thumbnail | 1 \ No newline at end of file +| YouTube Thumbnail | 16:9 | 1280x720 | +| OG Image | ~2:1 | 1200x630 | +| Facebook Cover | ~3:1 | 820x312 | + +## Qualidade + +Todos os outputs passam pelo design-critic com score minimo 7/10 em 5 dimensoes: +fidelidade, concisao visual, legibilidade, profissionalismo, brand compliance. + +--- + +**Versao**: 2.1.0 | **Data**: 2026-04-07 | **Autor**: Descomplicar +**v2.1.0:** Penpot removido como motor activo (substituído por Stitch para web/ui e design-engine para imagens/social/infográficos). Workflow simplificado. + +--- + +## 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/design-media/skills/design/references/premium-proposals.md b/design-media/skills/design/references/premium-proposals.md index 8f3a6fc..26b2d8b 100644 --- a/design-media/skills/design/references/premium-proposals.md +++ b/design-media/skills/design/references/premium-proposals.md @@ -243,7 +243,7 @@ def criar_pricing(c: canvas.Canvas, planos: list[dict]): | Controlo | Pixel-perfect | Aproximado | | Fontes custom | Suporte completo | Limitado | | Melhor para | Proposta final PDF | Template editável pelo cliente | -| Ambiente | Servidor dev (`/root/Dev`) | Servidor dev ou local | +| Ambiente | Desktop local (`/media/ealmeida/Dados/Dev`) | Desktop local | **Recomendação:** usar reportlab para proposta final; pptxgenjs se o cliente precisar de editar. @@ -254,8 +254,8 @@ pip install reportlab Pillow # Registar fontes Nexa from reportlab.pdfbase import pdfmetrics from reportlab.pdfbase.ttfonts import TTFont -pdfmetrics.registerFont(TTFont("Nexa-Bold", "/root/Dev/assets/fonts/Nexa-Bold.ttf")) -pdfmetrics.registerFont(TTFont("Nexa-Light", "/root/Dev/assets/fonts/Nexa-Light.ttf")) +pdfmetrics.registerFont(TTFont("Nexa-Bold", "/media/ealmeida/Dados/Dev/assets/fonts/Nexa-Bold.ttf")) +pdfmetrics.registerFont(TTFont("Nexa-Light", "/media/ealmeida/Dados/Dev/assets/fonts/Nexa-Light.ttf")) ``` --- diff --git a/design-media/skills/pptx-generator b/design-media/skills/pptx-generator new file mode 120000 index 0000000..a5f047e --- /dev/null +++ b/design-media/skills/pptx-generator @@ -0,0 +1 @@ +/home/ealmeida/.claude/skills/second-brain-repo/.claude/skills/pptx-generator \ No newline at end of file diff --git a/design-media/skills/remotion-video b/design-media/skills/remotion-video new file mode 120000 index 0000000..9373274 --- /dev/null +++ b/design-media/skills/remotion-video @@ -0,0 +1 @@ +/home/ealmeida/.claude/skills/second-brain-repo/.claude/skills/remotion \ No newline at end of file diff --git a/design-media/skills/ui-ux-pro-max b/design-media/skills/ui-ux-pro-max new file mode 120000 index 0000000..c2881a6 --- /dev/null +++ b/design-media/skills/ui-ux-pro-max @@ -0,0 +1 @@ +/home/ealmeida/.claude/skills/ui-ux-pro-max-repo/.claude/skills/ui-ux-pro-max \ No newline at end of file diff --git a/dev-tools/agents/database-design-specialist.md b/dev-tools/agents/database-design-specialist.md index 93ae386..d747ef7 100644 --- a/dev-tools/agents/database-design-specialist.md +++ b/dev-tools/agents/database-design-specialist.md @@ -7,6 +7,8 @@ model: sonnet tools: Read, Write, Edit, Bash, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 - ssh-unified @@ -43,7 +45,6 @@ collaborates_with: created: "2025-01-13" updated: "2026-02-04" author: "Descomplicar®" -layer: wiki --- # Database Design Specialist Descomplicar @@ -145,12 +146,12 @@ Especialista em arquitectura de bases de dados, entregando solucoes eficientes, - **n8n** - Workflows automation - **filesystem** - Ficheiros locais - **magic** - AI-powered UI component generation (tipo v0.dev) -- **mem0** - Memória longo prazo +- **mem0** - Mem0 (Tier 2, `mcp__mem0__*`) + IJFW (Tier 1, automático via hooks) - **cwp** - CentOS Web Panel - **puppeteer** - Browser automation ### All Available (32 total) -moloni, google-analytics, google-workspace, imap, outline-api, youtube-research, youtube-uploader, wikijs, gsc, lighthouse, mcp-time, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, vimeo, design-systems, replicate +moloni, google-analytics, google-workspace, imap, outline-api, youtube-research, youtube-uploader, gsc, lighthouse, mcp-time, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, vimeo, design-systems, replicate **Discovery:** Use ToolSearch to find specific tools. **Example:** `ToolSearch("ssh upload")` finds SSH upload tools. @@ -160,4 +161,66 @@ moloni, google-analytics, google-workspace, imap, outline-api, youtube-research, ✓ **/wp-dev** - Desenvolvimento WordPress especializado - plugins, temas, WooCommerce. Usar para - Invoke: `/wp-dev` -✓ **/php-dev** - \ No newline at end of file +✓ **/php-dev** - Desenvolvimento PHP fullstack - Laravel, Symfony, APIs RESTful, arquitectura bac + - Invoke: `/php-dev` + +✓ **/db-design** - Design de bases de dados - schema, optimização queries, MySQL/PostgreSQL, arquit + - Invoke: `/db-design` + +✓ **/mcp-dev** - Desenvolvimento de servidores MCP - criar, configurar, testar e documentar MCPs + - Invoke: `/mcp-dev` + +### Recommended for dev +- **/react-patterns** - Padrões React modernos - Hooks, Server Components, State Man +- **/nextjs** - Desenvolvimento Next.js moderno com App Router, Server Compo +- **/elementor** - Desenvolvimento avançado com Elementor Pro e Crocoblock - wi +- **/woocommerce** - Desenvolvimento e optimização de lojas WooCommerce - checkou +- **/crm-admin** - Administração e desenvolvimento Perfex CRM - gestão dados, m +- **/video** - Criar vídeos programáticos com Remotion e React. Gera intros +- **/doc-sync** - Sincronização automática de documentação Stack/Vault. Garant +- **/delegate** - Delegar tarefas dev para outros chats Claude com workflow co +- **/time** - Time tracking integrado com Desk CRM. Inicia e para timers e + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /lead-approach, /orcamento, /saas, /content-marketing-pt, /remotion-video, /seo-content-optimization, /social-media, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /backup-strategies, /security-audit, /server-health, /wp-performance, /wp-update, /second-brain-repo, /ads, /marketing-strategy, /product, /skill-creator, /sop-creator, /calendar-manager, /interview, /today, /research, /youtube, /seo-audit, /seo-report, /archive, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. +## Your Team & Responsibilities + +You are part of **5 SDKs** (TaskForce teams): + +### TaskForce Bases de Dados + +**Purpose:** NULL + +### TaskForce Claude Agents + +**Purpose:** NULL + +**Your responsibilities in this TaskForce:** +### TaskForce DeskDev + +**Purpose:** NULL + +### TaskForce Gestão Administrativa e Financeira + +**Purpose:** NULL + +### TaskForce SaaS + +**Purpose:** NULL + +**Collaboration:** +- Work with other agents in your TaskForce teams +- Share knowledge and context across team members +- Leverage team-specific skills and MCPs +- Contribute to team goals and deliverables + diff --git a/dev-tools/agents/dev-helper.md b/dev-tools/agents/dev-helper.md index 8232724..b12fa08 100644 --- a/dev-tools/agents/dev-helper.md +++ b/dev-tools/agents/dev-helper.md @@ -7,6 +7,8 @@ model: sonnet tools: Read, Write, Edit, Bash, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 - gitea @@ -47,7 +49,6 @@ escalates_to: created: "2025-01-13" updated: "2026-02-14" author: "Descomplicar®" -layer: wiki --- # Dev Helper Descomplicar @@ -185,4 +186,119 @@ OBRIGATÓRIO antes de git commit: 5. Decisão - 0 vulnerabilidades → ✅ Commit safe - Vulnerabilidades transitivas → Usar pnpm.overrides - - Vulnerabilidades críticas → Corrigir o \ No newline at end of file + - Vulnerabilidades críticas → Corrigir ou invocar /dep-audit + +6. Documentar + - Se há vulnerabilidades conhecidas → Mencionar no commit message + - Criar flag: touch ~/.claude-work/.last-security-audit + +NUNCA fazer commit sem executar este workflow. +Ver: PROC-DEV-SEC-001 no Hub para detalhes completos. +``` + +## Princípios SOLID + +| Princípio | Descrição | Exemplo Anti-Pattern | +|-----------|-----------|----------------------| +| **S**ingle Responsibility | Uma classe/função = uma responsabilidade | Classe User que envia emails | +| **O**pen/Closed | Aberto extensão, fechado modificação | Modificar código existente para adicionar feature | +| **L**iskov Substitution | Subclasses devem ser substituíveis | Override que muda comportamento drasticamente | +| **I**nterface Segregation | Interfaces específicas > interfaces gerais | Interface com métodos não usados | +| **D**ependency Inversion | Depender de abstracções | Instanciar dependências directamente | + +## Code Smells Comuns + +- **Duplicação**: Copy-paste code → Extrair função/classe +- **Função Longa**: >20 linhas → Quebrar em funções menores +- **Classe Grande**: Muitas responsabilidades → Separar em classes +- **Lista Parâmetros**: >3 parâmetros → Usar objecto config +- **Nomes Vagos**: `data`, `temp`, `x` → Nomes descritivos +- **Comentários Excessivos**: Código deve ser auto-explicativo + +## Knowledge Sources (Consultar SEMPRE) + +### NotebookLM (Primario - usar PRIMEIRO) + +``` +mcp__notebooklm__notebook_query notebook_id:"24947ffa-0019-448a-a340-2f4a275d2eb1" query:"boas praticas SOLID clean code" +mcp__notebooklm__notebook_query notebook_id:"f9a79b5a-649f-4443-afaf-7ff562b6c2e7" query:"debugging arquitectura troubleshooting" +mcp__notebooklm__notebook_query notebook_id:"2876d1fe-5cea-4d98-8140-b0e1a81c6bc4" query:"desenvolvimento assistente workflow" +``` + +## Your Available MCPs + +### Recommended for dev +- **ssh-unified** - SSH, SFTP, servidor management +- **gitea** - Repositórios Git, issues, PRs +- **context7** - Context documentation +- **n8n** - Workflows automation +- **filesystem** - Ficheiros locais +- **magic** - AI-powered UI component generation (tipo v0.dev) +- **** - Knowledge base AI +- **mem0** - Mem0 (Tier 2, `mcp__mem0__*`) + IJFW (Tier 1, automático via hooks) +- **cwp** - CentOS Web Panel +- **puppeteer** - Browser automation + +### All Available (32 total) +desk-crm-v3, moloni, google-analytics, google-workspace, imap, outline-api, youtube-research, youtube-uploader, gsc, lighthouse, mcp-time, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, vimeo, design-systems, replicate + +**Discovery:** Use ToolSearch to find specific tools. +**Example:** `ToolSearch("ssh upload")` finds SSH upload tools. +## Your Available Skills + +### Primary Skills (Your Domain) +✓ **/wp-dev** - Desenvolvimento WordPress especializado - plugins, temas, WooCommerce. Usar para + - Invoke: `/wp-dev` + +✓ **/php-dev** - Desenvolvimento PHP fullstack - Laravel, Symfony, APIs RESTful, arquitectura bac + - Invoke: `/php-dev` + +✓ **/db-design** - Design de bases de dados - schema, optimização queries, MySQL/PostgreSQL, arquit + - Invoke: `/db-design` + +✓ **/mcp-dev** - Desenvolvimento de servidores MCP - criar, configurar, testar e documentar MCPs + - Invoke: `/mcp-dev` + +### Recommended for dev +- **/react-patterns** - Padrões React modernos - Hooks, Server Components, State Man +- **/nextjs** - Desenvolvimento Next.js moderno com App Router, Server Compo +- **/elementor** - Desenvolvimento avançado com Elementor Pro e Crocoblock - wi +- **/woocommerce** - Desenvolvimento e optimização de lojas WooCommerce - checkou +- **/crm-admin** - Administração e desenvolvimento Perfex CRM - gestão dados, m +- **/video** - Criar vídeos programáticos com Remotion e React. Gera intros +- **/doc-sync** - Sincronização automática de documentação Stack/Vault. Garant +- **/delegate** - Delegar tarefas dev para outros chats Claude com workflow co +- **/time** - Time tracking integrado com Desk CRM. Inicia e para timers e + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /lead-approach, /orcamento, /saas, /content-marketing-pt, /remotion-video, /seo-content-optimization, /social-media, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /backup-strategies, /security-audit, /server-health, /wp-performance, /wp-update, /second-brain-repo, /ads, /marketing-strategy, /product, /skill-creator, /sop-creator, /calendar-manager, /interview, /today, /research, /youtube, /seo-audit, /seo-report, /archive, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. +## Colaboração + +- **Reports to**: Development Lead +- **Colabora com**: Todos os development specialists, System Architects, Database Design Specialist, Security Compliance Specialist +- **Escalar para**: Development Lead (decisões arquitectura complexas), Security Compliance Specialist (vulnerabilidades críticas) +## Your Team & Responsibilities + +You are part of **1 TaskForce** (TaskForce teams): + +### TaskForce Claude Agents + +**Purpose:** NULL + +**Your responsibilities in this TaskForce:** +**Collaboration:** +- Work with other agents in your TaskForce teams +- Share knowledge and context across team members +- Leverage team-specific skills and MCPs +- Contribute to team goals and deliverables + diff --git a/dev-tools/agents/development-lead.md b/dev-tools/agents/development-lead.md index b707be9..83017d4 100644 --- a/dev-tools/agents/development-lead.md +++ b/dev-tools/agents/development-lead.md @@ -7,6 +7,8 @@ model: sonnet tools: Read, Write, Edit, Bash, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 - gitea @@ -44,7 +46,6 @@ collaborates_with: created: "2025-01-13" updated: "2026-02-04" author: "Descomplicar®" -layer: wiki --- # Development Lead Descomplicar @@ -144,7 +145,7 @@ Lider de desenvolvimento responsavel por liderar equipas, garantir qualidade de ✓ **mem0** (system) - Memória longo prazo - - Usage: `mcp__mem_*` + - Usage: `mcp__mem0__*` ### Recommended for dev - **ssh-unified** - SSH, SFTP, servidor management @@ -156,10 +157,63 @@ Lider de desenvolvimento responsavel por liderar equipas, garantir qualidade de - **puppeteer** - Browser automation ### All Available (32 total) -moloni, google-analytics, google-workspace, imap, outline-api, youtube-research, youtube-uploader, wikijs, gsc, lighthouse, mcp-time, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, vimeo, design-systems, replicate +moloni, google-analytics, google-workspace, imap, outline-api, youtube-research, youtube-uploader, gsc, lighthouse, mcp-time, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, vimeo, design-systems, replicate **Discovery:** Use ToolSearch to find specific tools. **Example:** `ToolSearch("ssh upload")` finds SSH upload tools. ## Your Available Skills -### Primary Ski \ No newline at end of file +### Primary Skills (Your Domain) +✓ **/wp-dev** - Desenvolvimento WordPress especializado - plugins, temas, WooCommerce. Usar para + - Invoke: `/wp-dev` + +✓ **/php-dev** - Desenvolvimento PHP fullstack - Laravel, Symfony, APIs RESTful, arquitectura bac + - Invoke: `/php-dev` + +✓ **/db-design** - Design de bases de dados - schema, optimização queries, MySQL/PostgreSQL, arquit + - Invoke: `/db-design` + +✓ **/mcp-dev** - Desenvolvimento de servidores MCP - criar, configurar, testar e documentar MCPs + - Invoke: `/mcp-dev` + +### Recommended for dev +- **/react-patterns** - Padrões React modernos - Hooks, Server Components, State Man +- **/nextjs** - Desenvolvimento Next.js moderno com App Router, Server Compo +- **/elementor** - Desenvolvimento avançado com Elementor Pro e Crocoblock - wi +- **/woocommerce** - Desenvolvimento e optimização de lojas WooCommerce - checkou +- **/crm-admin** - Administração e desenvolvimento Perfex CRM - gestão dados, m +- **/video** - Criar vídeos programáticos com Remotion e React. Gera intros +- **/doc-sync** - Sincronização automática de documentação Stack/Vault. Garant +- **/delegate** - Delegar tarefas dev para outros chats Claude com workflow co +- **/time** - Time tracking integrado com Desk CRM. Inicia e para timers e + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /lead-approach, /orcamento, /saas, /content-marketing-pt, /remotion-video, /seo-content-optimization, /social-media, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /backup-strategies, /security-audit, /server-health, /wp-performance, /wp-update, /second-brain-repo, /ads, /marketing-strategy, /product, /skill-creator, /sop-creator, /calendar-manager, /interview, /today, /research, /youtube, /seo-audit, /seo-report, /archive, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. +## Your Team & Responsibilities + +You are part of **2 SDKs** (TaskForce teams): + +### TaskForce Product Manager + +**Purpose:** NULL + +### TaskForce Segurança e Autenticação + +**Purpose:** NULL + +**Collaboration:** +- Work with other agents in your TaskForce teams +- Share knowledge and context across team members +- Leverage team-specific skills and MCPs +- Contribute to team goals and deliverables + diff --git a/dev-tools/agents/javascript-fullstack-specialist.md b/dev-tools/agents/javascript-fullstack-specialist.md index 15250b5..f78afbe 100644 --- a/dev-tools/agents/javascript-fullstack-specialist.md +++ b/dev-tools/agents/javascript-fullstack-specialist.md @@ -9,6 +9,8 @@ model: sonnet tools: Read, Write, Edit, Bash, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 - gitea @@ -38,7 +40,6 @@ compliance: created: '2025-01-13' updated: '2026-02-04' author: Descomplicar® -layer: wiki --- # JavaScript Fullstack Specialist Descomplicar @@ -134,7 +135,7 @@ Especialista em desenvolvimento JavaScript fullstack, coordenando frontend e bac ✓ **mem0** (system) - Memória longo prazo - - Usage: `mcp__mem_*` + - Usage: `mcp__mem0__*` ### Recommended for dev - **ssh-unified** - SSH, SFTP, servidor management @@ -146,7 +147,7 @@ Especialista em desenvolvimento JavaScript fullstack, coordenando frontend e bac - **puppeteer** - Browser automation ### All Available (32 total) -moloni, google-analytics, google-workspace, imap, outline-api, youtube-research, youtube-uploader, wikijs, gsc, lighthouse, mcp-time, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, vimeo, design-systems, replicate +moloni, google-analytics, google-workspace, imap, outline-api, youtube-research, youtube-uploader, gsc, lighthouse, mcp-time, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, vimeo, design-systems, replicate **Discovery:** Use ToolSearch to find specific tools. **Example:** `ToolSearch("ssh upload")` finds SSH upload tools. @@ -156,4 +157,74 @@ moloni, google-analytics, google-workspace, imap, outline-api, youtube-research, ✓ **/wp-dev** - Desenvolvimento WordPress especializado - plugins, temas, WooCommerce. Usar para - Invoke: `/wp-dev` -✓ **/php-dev** - Desenvolvimento PHP fullstack - L \ No newline at end of file +✓ **/php-dev** - Desenvolvimento PHP fullstack - Laravel, Symfony, APIs RESTful, arquitectura bac + - Invoke: `/php-dev` + +✓ **/db-design** - Design de bases de dados - schema, optimização queries, MySQL/PostgreSQL, arquit + - Invoke: `/db-design` + +✓ **/mcp-dev** - Desenvolvimento de servidores MCP - criar, configurar, testar e documentar MCPs + - Invoke: `/mcp-dev` + +### Recommended for dev +- **/react-patterns** - Padrões React modernos - Hooks, Server Components, State Man +- **/nextjs** - Desenvolvimento Next.js moderno com App Router, Server Compo +- **/elementor** - Desenvolvimento avançado com Elementor Pro e Crocoblock - wi +- **/woocommerce** - Desenvolvimento e optimização de lojas WooCommerce - checkou +- **/crm-admin** - Administração e desenvolvimento Perfex CRM - gestão dados, m +- **/video** - Criar vídeos programáticos com Remotion e React. Gera intros +- **/doc-sync** - Sincronização automática de documentação Stack/Vault. Garant +- **/delegate** - Delegar tarefas dev para outros chats Claude com workflow co +- **/time** - Time tracking integrado com Desk CRM. Inicia e para timers e + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /lead-approach, /orcamento, /saas, /content-marketing-pt, /remotion-video, /seo-content-optimization, /social-media, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /backup-strategies, /security-audit, /server-health, /wp-performance, /wp-update, /second-brain-repo, /ads, /marketing-strategy, /product, /skill-creator, /sop-creator, /calendar-manager, /interview, /today, /research, /youtube, /seo-audit, /seo-report, /archive, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. +## Your Team & Responsibilities + +You are part of **6 SDKs** (TaskForce teams): + +### TaskForce Bases de Dados + +**Purpose:** NULL + +### TaskForce Claude Agents + +**Purpose:** NULL + +**Your responsibilities in this TaskForce:** +### TaskForce Dashboard + +**Purpose:** NULL + +**Your responsibilities in this TaskForce:** + +- **TaskForce interno para criar dashboards profissionais rapidamente. Design system Descomplicar com glassmorphism, bento grid e animações Framer Motion.**: NULL + +### TaskForce Next.js + +**Purpose:** NULL + +### TaskForce React + +**Purpose:** NULL + +### TaskForce SaaS + +**Purpose:** NULL + +**Collaboration:** +- Work with other agents in your TaskForce teams +- Share knowledge and context across team members +- Leverage team-specific skills and MCPs +- Contribute to team goals and deliverables + diff --git a/dev-tools/agents/nextjs-specialist.md b/dev-tools/agents/nextjs-specialist.md index 23f6934..c57531c 100644 --- a/dev-tools/agents/nextjs-specialist.md +++ b/dev-tools/agents/nextjs-specialist.md @@ -7,6 +7,8 @@ model: sonnet tools: Read, Write, Edit, Bash, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 - gitea @@ -43,7 +45,6 @@ collaborates_with: created: "2025-01-13" updated: "2026-02-04" author: "Descomplicar®" -layer: wiki --- # Next.js Specialist @@ -176,4 +177,56 @@ Especialista em desenvolvimento Next.js moderno com App Router, React Server Com ### Recommended for dev - **ssh-unified** - SSH, SFTP, servidor management -- **gitea** - Repositórios Git, issues, P \ No newline at end of file +- **gitea** - Repositórios Git, issues, PRs +- **context7** - Context documentation +- **n8n** - Workflows automation +- **filesystem** - Ficheiros locais +- **magic** - AI-powered UI component generation (tipo v0.dev) +- **** - Knowledge base AI +- **mem0** - Mem0 (Tier 2, `mcp__mem0__*`) + IJFW (Tier 1, automático via hooks) +- **cwp** - CentOS Web Panel +- **puppeteer** - Browser automation + +### All Available (32 total) +desk-crm-v3, moloni, google-analytics, google-workspace, imap, outline-api, youtube-research, youtube-uploader, gsc, lighthouse, mcp-time, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, vimeo, design-systems, replicate + +**Discovery:** Use ToolSearch to find specific tools. +**Example:** `ToolSearch("ssh upload")` finds SSH upload tools. +## Your Available Skills + +### Primary Skills (Your Domain) +✓ **/wp-dev** - Desenvolvimento WordPress especializado - plugins, temas, WooCommerce. Usar para + - Invoke: `/wp-dev` + +✓ **/php-dev** - Desenvolvimento PHP fullstack - Laravel, Symfony, APIs RESTful, arquitectura bac + - Invoke: `/php-dev` + +✓ **/db-design** - Design de bases de dados - schema, optimização queries, MySQL/PostgreSQL, arquit + - Invoke: `/db-design` + +✓ **/mcp-dev** - Desenvolvimento de servidores MCP - criar, configurar, testar e documentar MCPs + - Invoke: `/mcp-dev` + +### Recommended for dev +- **/react-patterns** - Padrões React modernos - Hooks, Server Components, State Man +- **/nextjs** - Desenvolvimento Next.js moderno com App Router, Server Compo +- **/elementor** - Desenvolvimento avançado com Elementor Pro e Crocoblock - wi +- **/woocommerce** - Desenvolvimento e optimização de lojas WooCommerce - checkou +- **/crm-admin** - Administração e desenvolvimento Perfex CRM - gestão dados, m +- **/video** - Criar vídeos programáticos com Remotion e React. Gera intros +- **/doc-sync** - Sincronização automática de documentação Stack/Vault. Garant +- **/delegate** - Delegar tarefas dev para outros chats Claude com workflow co +- **/time** - Time tracking integrado com Desk CRM. Inicia e para timers e + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /lead-approach, /orcamento, /saas, /content-marketing-pt, /remotion-video, /seo-content-optimization, /social-media, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /backup-strategies, /security-audit, /server-health, /wp-performance, /wp-update, /second-brain-repo, /ads, /marketing-strategy, /product, /skill-creator, /sop-creator, /calendar-manager, /interview, /today, /research, /youtube, /seo-audit, /seo-report, /archive, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. diff --git a/dev-tools/agents/php-fullstack-engineer.md b/dev-tools/agents/php-fullstack-engineer.md index 758314e..d67ffe7 100644 --- a/dev-tools/agents/php-fullstack-engineer.md +++ b/dev-tools/agents/php-fullstack-engineer.md @@ -18,6 +18,8 @@ user_invocable: true tier: 1 # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 # Business operations - gitea # Version control @@ -27,7 +29,7 @@ recommended_mcps: - n8n # Workflow automation - filesystem # Local file operations - magic # UI component generation - - mem0 # Long-term memory + - mem0 # Memória longo prazo (Tier 2) via Mem0 - cwp # Server management - puppeteer # Browser automation @@ -81,7 +83,6 @@ collaborations: created: 2026-02-04 last_updated: 2026-02-04 quality_score: 85 -layer: wiki --- # PHP Fullstack Engineer Descomplicar @@ -146,4 +147,7 @@ Especialista senior em desenvolvimento PHP fullstack com expertise em frameworks ### Workflow 3: Performance Optimization 1. Audit queries (Query Monitor, Debug Bar) 2. Implement caching (Redis/Memcached) -3. Lazy loading e eager lo \ No newline at end of file +3. Lazy loading e eager loading (N+1) +4. Queue jobs pesados (Laravel Queue) +5. CDN para assets +6. Profiling com Xdebug/Blackfire diff --git a/dev-tools/skills/benchmark/SKILL.md b/dev-tools/skills/benchmark/SKILL.md index 0e6efa8..b13b8d8 100644 --- a/dev-tools/skills/benchmark/SKILL.md +++ b/dev-tools/skills/benchmark/SKILL.md @@ -4,7 +4,6 @@ description: > Mede Core Web Vitals e performance antes/depois de alterações. Detecta regressões. Usar antes e depois de qualquer alteração a WP, WooCommerce, Next.js ou infra. Baseado no gstack /benchmark. Eixo 2B. -layer: wiki --- # /benchmark — Performance Antes/Depois diff --git a/dev-tools/skills/canary/SKILL.md b/dev-tools/skills/canary/SKILL.md index 6a4ea08..30e03c9 100644 --- a/dev-tools/skills/canary/SKILL.md +++ b/dev-tools/skills/canary/SKILL.md @@ -4,7 +4,6 @@ description: > Monitorização pós-deploy — detecta regressões em produção. Verifica que o deploy não quebrou nada crítico nos 15min seguintes. Baseado no gstack /canary. Eixo 2B. Usar após qualquer deploy em produção. -layer: wiki --- # /canary — Monitorização Pós-Deploy diff --git a/dev-tools/skills/chrome/SKILL.md b/dev-tools/skills/chrome/SKILL.md index 58d9a76..57acc2d 100644 --- a/dev-tools/skills/chrome/SKILL.md +++ b/dev-tools/skills/chrome/SKILL.md @@ -2,7 +2,6 @@ name: chrome description: Integração com Chrome para automação browser — navegar páginas, preencher formulários, debug de consola, extracção de dados, testes e screenshots. allowed-tools: Bash, Read, Write, Glob -layer: wiki --- # /chrome - Chrome Browser Integration @@ -155,4 +154,162 @@ crm.example.com, clica "Adicionar Contacto" e preenche nome, email e telefone. ### Escrever em Google Docs ``` Escreve um resumo do projecto baseado nos commits recentes -no Google D \ No newline at end of file +no Google Doc docs.google.com/document/d/abc123 +``` + +### Extrair dados de paginas +``` +Vai a pagina de produtos e extrai nome, preco e disponibilidade +de cada item. Guarda como CSV. +``` + +### Workflow multi-site +``` +Verifica o meu calendario para reunioes amanha, depois para cada +reuniao com participante externo, pesquisa o site da empresa. +``` + +### Gravar demo GIF (Chrome extensao) +``` +Grava um GIF mostrando o fluxo de checkout, desde adicionar item +ao carrinho ate a pagina de confirmacao. +``` + +### Performance audit (DevTools MCP) +``` +Abre a pagina example.com, grava um performance trace durante 5 segundos +e analisa LCP, TBT e CLS. Sugere melhorias. +``` + +### Debug network (DevTools MCP) +``` +Abre a pagina do dashboard, monitoriza os requests de API +e identifica quais estao a falhar ou demorar mais de 2 segundos. +``` + +### Inspeccionar acessibilidade (DevTools MCP) +``` +Abre a pagina de contacto e verifica a arvore de acessibilidade. +Identifica elementos sem labels ou roles ARIA incorrectos. +``` + +### Debug CSS (DevTools MCP) +``` +Abre a landing page e inspecciona os estilos computados do hero section. +Verifica se o layout esta correcto em diferentes larguras. +``` + +## Comparacao de Backends + +| Feature | Chrome Extensao | DevTools MCP | Puppeteer MCP | WebFetch | +|---------|----------------|--------------|---------------|----------| +| Sessoes autenticadas | Sim | Sim (se Chrome aberto) | Nao | Nao | +| Janela visivel | Sim | Sim | Opcional | N/A | +| Sites privados | Sim (se logado) | Sim (se logado) | Nao | Nao | +| Headless | Nao | Opcional | Sim | Sim | +| Interaccao UI | Completa | Completa | Completa | Nao | +| Screenshots | Sim | Sim | Sim | Nao | +| Gravar GIF | Sim | Nao | Nao | Nao | +| Console logs | Sim | Sim (filtrados) | Sim | Nao | +| Network requests | Nao | Sim (detalhado) | Limitado | Nao | +| Performance traces | Nao | Sim (LCP/TBT/CLS) | Nao | Nao | +| Acessibilidade | Nao | Sim (a11y tree) | Nao | Nao | +| DOM/CSS inspection | Basico | Completo | Basico | Nao | +| Storage inspection | Nao | Sim (cookies/LS) | Nao | Nao | +| Requer extensao | Sim | Nao | Nao | Nao | +| Requer Chrome aberto | Sim | Sim (porta 9222) | Nao | Nao | +| Context usage | Alto | Medio | Medio | Baixo | + +**Regra de decisao:** +- Precisa de login/sessao + GIF? -> **Chrome Extensao** +- Debug/performance/network? -> **DevTools MCP** +- Automacao headless CI/CD? -> **Puppeteer MCP** +- Apenas ler conteudo publico? -> **WebFetch** + +## Troubleshooting + +### DevTools MCP nao conecta +1. Verificar Chrome lancado com `--remote-debugging-port=9222` +2. Testar: `curl http://localhost:9222/json/version` +3. Verificar MCP registado: `claude mcp list` +4. Reiniciar sessao Claude Code + +### DevTools MCP sem ferramentas +1. Verificar: `claude mcp list | grep chrome-devtools` +2. Se nao aparece: `claude mcp add chrome-devtools --scope user -- npx -y chrome-devtools-mcp@latest` +3. Reiniciar sessao Claude Code + +### Extensao nao detectada (Chrome extensao) +1. Verificar extensao em `chrome://extensions` +2. Verificar versao Claude Code: `claude --version` (>= 2.0.73) +3. Confirmar Chrome aberto +4. `/chrome` -> "Reconnect extension" +5. Reiniciar Chrome E Claude Code + +### Browser nao responde +1. Verificar se modal dialog esta a bloquear (alert/confirm/prompt) +2. Dispensar dialog manualmente, depois continuar +3. Pedir nova tab +4. Desactivar/reactivar extensao em `chrome://extensions` + +### Conexao cai em sessoes longas +- Service worker do Chrome pode ficar idle +- Solucao: `/chrome` -> "Reconnect extension" + +### Erros comuns + +| Erro | Causa | Solucao | +|------|-------|---------| +| "Browser extension is not connected" | Native host nao alcanca extensao | Reiniciar Chrome + Claude, `/chrome` reconnect | +| "Extension not detected" | Extensao nao instalada/desactivada | Instalar/activar em `chrome://extensions` | +| "No tab available" | Accao antes de tab pronta | Pedir nova tab e retry | +| "Receiving end does not exist" | Service worker idle | `/chrome` -> "Reconnect extension" | + +### Verificar instalacao +```bash +# Chrome instalado? +google-chrome --version + +# Claude Code compativel? +claude --version + +# --- DevTools MCP --- +# MCP registado? +claude mcp list | grep chrome-devtools + +# Chrome com debugging activo? +curl -s http://localhost:9222/json/version | head -5 + +# --- Chrome Extensao --- +# Native host configurado? +cat ~/.config/google-chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json + +# Host script existe? +ls -la ~/.claude/chrome/chrome-native-host +``` + +## Permissoes de Sites + +Permissoes por site sao geridas na **extensao Chrome** (nao no Claude Code): +- Abrir extensao Claude in Chrome -> Settings +- Configurar quais sites podem ser acedidos +- Bloqueios aplicam-se a todas as sessoes + +## Nota de Performance + +Activar Chrome por defeito **aumenta consumo de context window** porque as ferramentas browser ficam sempre carregadas. Se notar degradacao: +1. Desactivar default: `/chrome` -> desactivar +2. Usar `claude --chrome` apenas quando necessario +3. Preferir WebFetch para leituras simples de paginas publicas + +--- + +## 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/dev-tools/skills/db-design/SKILL.md b/dev-tools/skills/db-design/SKILL.md index 035982b..b45d2b4 100644 --- a/dev-tools/skills/db-design/SKILL.md +++ b/dev-tools/skills/db-design/SKILL.md @@ -1,7 +1,6 @@ --- name: db-design description: Design e optimização de schemas de base de dados — normalização, índices, planos de migração e particionamento. -layer: wiki --- # Database Design Specialist @@ -20,8 +19,8 @@ Skill para design e optimização de bases de dados seguindo padrões Descomplic ### 1. Pesquisa Inicial ``` -mcp__mem_search_memories "database [projecto]" -mcp__wikijs__search_pages "database schema [sistema]" +mcp__mem0__search_memories "database [projecto]" +/knowledge (router Hub QR/PROC) + mcp__mem0__search_memories "database schema [sistema]" ``` ### 2. Verificar Schema Existente @@ -189,4 +188,68 @@ Em caso de dúvidas ou para aprofundar conhecimento, consultar os seguintes data ### Como Consultar ```javascript -// Pesquisar optimiza \ No newline at end of file +// Pesquisar optimização MySQL +mcp__notebooklm__notebook_query, mcp__dify-kb__dify_kb_retrieve_segments({ + dataset_id: "7f63ec0c-6321-488c-b107-980140199850", + query: "mysql index optimization slow query" +}) + +// Padrões de design de bases de dados +mcp__dify-kb__dify_kb_retrieve_segments({ + dataset_id: "e7c7decc-0ded-4351-ab14-b110b3c38ec9", + query: "database schema design patterns" +}) + +// RDS e bases de dados AWS +mcp__dify-kb__dify_kb_retrieve_segments({ + dataset_id: "cc7f000a-ad86-49b6-b59b-179e65f8a229", + query: "RDS aurora postgresql" +}) +``` + +### Quando Consultar + +- Antes de desenhar novo schema +- Ao optimizar queries lentas +- Para escolher tipo de índice adequado +- Decidir entre MySQL/PostgreSQL +- Configurar bases de dados em cloud + +--- +**Versão**: 1.0.0 | **Autor**: Descomplicar® + +--- + + +## Quando NÃO Usar + +- Para tarefas fora do domínio de especialização desta skill +- Quando outra skill mais específica está disponível +- Para operações que requerem confirmação manual do utilizador + + +## Exemplos + +### Exemplo 1: Uso Básico +``` +Input: [descrição da tarefa] +Output: [resultado esperado] +``` + +### Exemplo 2: Uso Avançado +``` +Input: [caso complexo] +Output: [resultado detalhado] +``` + +--- + +## 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/dev-tools/skills/dep-audit/SKILL.md b/dev-tools/skills/dep-audit/SKILL.md index 312fa16..c15f26d 100644 --- a/dev-tools/skills/dep-audit/SKILL.md +++ b/dev-tools/skills/dep-audit/SKILL.md @@ -2,7 +2,6 @@ name: dep-audit description: Auditoria de dependencias para projectos Node.js e PHP — vulnerabilidades, pacotes desactualizados, seguranca de ambiente e verificacao de tipos. Obrigatoria antes de commits. disable-model-invocation: true -layer: wiki --- # /dep-audit - Dependency Security Audit Pre-Commit @@ -211,4 +210,266 @@ Mitigation: [explanation] Fix critical/high vulnerabilities first. See PROC-DEV-SEC-001 for guidance. ``` -### 8. Criar F \ No newline at end of file +### 8. Criar Flag + +```bash +touch ~/.claude-work/.last-security-audit +``` + +**Propósito:** Hook pre-git-commit verifica esta flag. Se existe e < 1h, permite commit. + +--- + +## Recomendações Específicas + +### Para Vulnerabilidades Transitivas + +**Exemplo: form-data via together-ai** + +```json +// package.json +{ + "pnpm": { + "overrides": { + "form-data": ">=4.0.4" + } + } +} +``` + +Depois: +```bash +pnpm install +pnpm audit # Verificar se resolveu +``` + +### Para Dependências Incompatíveis + +**Exemplo: @langchain/core desactualizado** + +```bash +# langchain pina versão antiga +# Solução: instalar como dependência explícita +pnpm add @langchain/core@latest +``` + +### Para Vulnerabilidades Críticas + +**Workflow:** +1. Verificar se há fix disponível +2. Se sim: actualizar +3. Se não: avaliar alternativas ao package +4. Se nenhuma: escalar para Security Compliance Specialist + +--- + +## Output Examples + +### Exemplo 1: Clean (0 vulnerabilities) + +``` +## Security Audit Report + +**Status:** ✅ SAFE +**Data:** 2026-02-14 03:00 + +| Category | Status | +|----------|--------| +| Vulnerabilities | 0 (all categories) ✅ | +| Outdated Packages | 3 (1 major) | +| Environment Safety | ✅ Placeholders only | +| Type Safety | ✅ 0 errors | + +### Outdated Packages + +**Framework:** +- next: 16.1.6 → 16.2.0 (minor) + +**Action Required:** Optional - update at convenience + +### Safe to Commit? + +✅ **YES** - No security issues found + +Created flag: ~/.claude-work/.last-security-audit +``` + +### Exemplo 2: Transitivas (precisa overrides) + +``` +## Security Audit Report + +**Status:** ⚠️ ISSUES FOUND (transitivas) +**Data:** 2026-02-14 03:00 + +| Category | Status | +|----------|--------| +| Vulnerabilities | 0 critical, 0 high, 2 moderate, 1 low | +| Outdated Packages | 5 (2 major) | +| Environment Safety | ✅ Placeholders only | +| Type Safety | ✅ 0 errors | + +### Vulnerabilities Detail + +#### Moderate (2) +- lodash@4.17.21 (via @platejs/ai) + - **Issue:** Prototype pollution + - **Patched:** >=4.17.23 + - **Action:** Override + +- undici@6.22.0 (via @platejs/juice → cheerio) + - **Issue:** Resource exhaustion + - **Patched:** >=6.23.0 + - **Action:** Override + +#### Low (1) +- cookie@0.6.0 (via @auth/core) + - **Issue:** Out of bounds characters + - **Patched:** >=0.7.0 + - **Action:** Override + +### Recommended Fix + +Add to package.json: +```json +{ + "pnpm": { + "overrides": { + "lodash": ">=4.17.23", + "undici": ">=6.23.0", + "cookie": ">=0.7.0" + } + } +} +``` + +Then run: `pnpm install && pnpm audit` + +### Safe to Commit? + +⚠️ **YES (with documentation)** + +Document in commit message: +- 3 moderate/low vulnerabilities (all transitivas) +- Fixed with pnpm.overrides +``` + +### Exemplo 3: Critical (bloquear commit) + +``` +## Security Audit Report + +**Status:** ❌ CRITICAL +**Data:** 2026-02-14 03:00 + +| Category | Status | +|----------|--------| +| Vulnerabilities | 1 critical, 0 high, 0 moderate, 0 low | +| Outdated Packages | 8 (3 major) | +| Environment Safety | ✅ Placeholders only | +| Type Safety | ✅ 0 errors | + +### Vulnerabilities Detail + +#### Critical (1) +- form-data@4.0.3 (via together-ai → @types/node-fetch) + - **Issue:** Unsafe random function in boundary selection + - **Patched:** >=4.0.4 + - **Action:** Override OR replace together-ai + +### Immediate Action Required + +**Option 1: Override (quick fix)** +```json +{ + "pnpm": { + "overrides": { + "form-data": ">=4.0.4" + } + } +} +``` + +**Option 2: Evaluate alternatives** +- Check if together-ai is essential +- Evaluate alternative AI SDKs +- Contact Security Compliance Specialist + +### Safe to Commit? + +❌ **NO** - Fix critical vulnerability first + +DO NOT create flag. DO NOT commit. +``` + +--- + +## Integration + +### Com Hook pre-git-commit + +Hook verifica: +```bash +~/.claude-work/.last-security-audit +``` + +Se ficheiro existe e < 1h → permite commit +Se não existe ou > 1h → **BLOQUEIA** commit + +### Com /time + +```bash +# Workflow típico +/time start 1446 # Tarefa Desk +# ... fazer alterações ... +/dep-audit # Antes de commit +git commit +/time stop +``` + +### Com /worklog + +```bash +# No worklog, mencionar se audit foi executado +/worklog +# → Incluirá "Security audit: ✅ 0 vulnerabilities" +``` + +--- + +## Escalação + +| Situação | Escalar Para | +|----------|--------------| +| Vulnerabilidades críticas não corrigíveis | Security Compliance Specialist | +| Dúvidas sobre overrides | Development Lead | +| Múltiplas vulnerabilidades altas | /dep-audit + manual review | +| Alternativas a packages | Research Analyst | + +--- + +## Referências + +- [CLAUDE.md Regra #47](/home/ealmeida/.claude/CLAUDE.md) +- [PROC-DEV-SEC-001](/media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Seguranca/PROC-DEV-SEC-001-Security-Audit.md) +- [Agent dev-helper v2.1](/home/ealmeida/.claude/plugins/marketplaces/descomplicar-plugins/dev-tools/agents/dev-helper.md) +- [NPM Audit](https://docs.npmjs.com/cli/v10/commands/npm-audit) +- [PNPM Audit](https://pnpm.io/cli/audit) +- [Composer Audit](https://getcomposer.org/doc/03-cli.md#audit) + +--- + +**Skill v1.1** | 12-03-2026 | Descomplicar® | Renomeado de /security-check para /dep-audit +**Security First** - Zero vulnerabilities ou documentadas + +--- + +## 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/dev-tools/skills/diagrama/SKILL.md b/dev-tools/skills/diagrama/SKILL.md index 8597398..4618b8a 100644 --- a/dev-tools/skills/diagrama/SKILL.md +++ b/dev-tools/skills/diagrama/SKILL.md @@ -5,7 +5,6 @@ description: "Gera diagramas de arquitectura, fluxo, ER e sequência em três fo version: "1.0.0" created: 2026-04-04 tools: [mcp__claude_ai_Excalidraw__export_to_excalidraw, mcp__mcp-mermaid__generate, Write, Bash] -layer: wiki --- # Skill: /diagrama @@ -150,4 +149,119 @@ Usar o MCP `mcp__claude_ai_Excalidraw__export_to_excalidraw` para diagramas no e ## Geração Mermaid -Usar o MCP `mcp__mcp-mermaid__generate` \ No newline at end of file +Usar o MCP `mcp__mcp-mermaid__generate` para diagramas como código. + +### Tipos suportados + +**Fluxograma:** +``` +flowchart TD + A[Início] --> B{Condição} + B -->|Sim| C[Acção] + B -->|Não| D[Fim] +``` + +**Sequência:** +``` +sequenceDiagram + participant U as Utilizador + participant A as Claude Code + participant N as n8n + U->>A: Pedido + A->>N: Trigger workflow + N-->>A: Resultado + A-->>U: Resposta +``` + +**ER:** +``` +erDiagram + CLIENTE ||--o{ PROJECTO : tem + PROJECTO ||--o{ TAREFA : contém + TAREFA { + int id + string nome + string estado + } +``` + +**Arquitectura de componentes (C4):** +``` +C4Context + title Stack Descomplicar + Person(eal, "Emanuel", "Utilizador principal") + System(cc, "Claude Code", "Interface interactiva") + System(clip, "Paperclip", "Agentes autónomos") + System(n8n, "n8n", "Automação determinística") + Rel(eal, cc, "usa directamente") + Rel(cc, clip, "delega tarefas complexas") + Rel(cc, n8n, "activa workflows") +``` + +### Guardar output + +Guardar o código Mermaid em `/media/ealmeida/Dados/Hub/tmp/diagramas/NOME.mmd` e renderizar para SVG/PNG via MCP. + +--- + +## Templates prontos por contexto + +### Arquitectura StackDescomplicar + +Gerar diagrama com as três camadas do stack: +- **Camada 1:** Claude Code (trabalho interactivo) +- **Camada 2:** n8n (automação determinística) +- **Camada 3:** Paperclip (raciocínio autónomo) + +### Proposta comercial + +Diagrama da solução para o cliente com: +- Infra-estrutura actual (antes) +- Solução proposta (depois) +- Componentes e integrações + +### Pipeline de dados + +Diagrama de fluxo com: +- Fonte → Processamento → Destino +- Triggers, transformações, outputs + +### Diagrama ER Desk CRM + +Entidades principais: Lead → Customer → Estimate → Invoice → Payment + +--- + +## Boas práticas + +- **Máx. 10-15 elementos** por diagrama (mais → dividir em sub-diagramas) +- **Labels curtos:** 2-4 palavras por elemento +- **Setas com label** quando o fluxo não é óbvio +- **Cor consistente** por tipo de componente (seguir paleta Descomplicar) +- **Nome descritivo** no ficheiro (não "diagrama1.drawio") +- **Guardar em Hub/tmp/diagramas/** para fácil acesso + +--- + +## Instalar draw.io MCP (opcional, para funcionalidades avançadas) + +O vídeo #210 do Stack_Pesquisa_Videos.md demonstra um MCP draw.io com geração automática a partir de análise de código. Para instalar: + +```bash +# Verificar se há MCP draw.io disponível no gateway +# Ver: Hub/04-Stack/claude-code-context-hygiene.md → secção MCPs +``` + +Alternativa: usar draw.io via browser em https://app.diagrams.net (gratuito, sem instalação) e importar o `.drawio` gerado. + +--- + +## 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/dev-tools/skills/docx/SKILL-light.md b/dev-tools/skills/docx/SKILL-light.md index 8f5edf5..8a47a25 100644 --- a/dev-tools/skills/docx/SKILL-light.md +++ b/dev-tools/skills/docx/SKILL-light.md @@ -1,7 +1,6 @@ --- name: docx description: "Criação, edição e análise de documentos Word (.docx). Versão light para heartbeats." -layer: wiki --- # DOCX — Referência Rápida diff --git a/dev-tools/skills/docx/SKILL.md b/dev-tools/skills/docx/SKILL.md index 1424f30..dbbcc01 100644 --- a/dev-tools/skills/docx/SKILL.md +++ b/dev-tools/skills/docx/SKILL.md @@ -1,7 +1,6 @@ --- name: docx description: "Criacao, edicao e analise de documentos Word (.docx). Usar quando o utilizador mencionar \"Word\", \".docx\", ou pedir documentos profissionais com formatacao (indices, cabecalhos, numeracao de paginas, letterheads). Inclui extracao de conteudo, insercao/substituicao de imagens, find-and-replace, tracked changes, comentarios, e conversao de conteudo para Word. Aplica-se a relatorios, memorandos, cartas, templates e propostas em formato .docx. NAO usar para PDFs, folhas de calculo, Google Docs, ou tarefas de codigo nao relacionadas." -layer: wiki --- # Criacao, edicao e analise de documentos DOCX @@ -142,4 +141,384 @@ const doc = new Document({ ```javascript // ERRADO - nunca inserir caracteres de bullet manualmente new Paragraph({ children: [new TextRun("* Item")] }) // MAU -new Paragraph({ children: [new TextRun("\u2022 Item")] \ No newline at end of file +new Paragraph({ children: [new TextRun("\u2022 Item")] }) // MAU + +// CORRECTO - usar config numbering com LevelFormat.BULLET +const doc = new Document({ + numbering: { + config: [ + { reference: "bullets", + levels: [{ level: 0, format: LevelFormat.BULLET, text: "\u2022", alignment: AlignmentType.LEFT, + style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] }, + { reference: "numbers", + levels: [{ level: 0, format: LevelFormat.DECIMAL, text: "%1.", alignment: AlignmentType.LEFT, + style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] }, + ] + }, + sections: [{ + children: [ + new Paragraph({ numbering: { reference: "bullets", level: 0 }, + children: [new TextRun("Item com bullet")] }), + new Paragraph({ numbering: { reference: "numbers", level: 0 }, + children: [new TextRun("Item numerado")] }), + ] + }] +}); + +// ATENCAO: Cada reference cria numeracao INDEPENDENTE +// Mesma reference = continua (1,2,3 depois 4,5,6) +// Reference diferente = reinicia (1,2,3 depois 1,2,3) +``` + +### Tabelas + +**CRITICO: Tabelas precisam de larguras duplas** - definir tanto `columnWidths` na tabela COMO `width` em cada celula. Sem ambos, tabelas renderizam incorrectamente em algumas plataformas. + +```javascript +// CRITICO: Definir sempre largura da tabela para renderizacao consistente +// CRITICO: Usar ShadingType.CLEAR (nao SOLID) para evitar fundos pretos +const border = { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" }; +const borders = { top: border, bottom: border, left: border, right: border }; + +new Table({ + width: { size: 9026, type: WidthType.DXA }, // Sempre usar DXA (percentagens quebram no Google Docs) + columnWidths: [4513, 4513], // Deve somar a largura da tabela (DXA: 1440 = 1 polegada) + rows: [ + new TableRow({ + children: [ + new TableCell({ + borders, + width: { size: 4513, type: WidthType.DXA }, // Tambem definir em cada celula + shading: { fill: "D5E8F0", type: ShadingType.CLEAR }, // CLEAR e nao SOLID + margins: { top: 80, bottom: 80, left: 120, right: 120 }, // Padding da celula (interno, nao adicionado a largura) + children: [new Paragraph({ children: [new TextRun("Celula")] })] + }) + ] + }) + ] +}) +``` + +**Calculo de largura da tabela:** + +Usar sempre `WidthType.DXA` — `WidthType.PERCENTAGE` quebra no Google Docs. + +```javascript +// Largura da tabela = soma de columnWidths = largura do conteudo +// A4 com margens de 1": 11906 - 2880 = 9026 DXA +width: { size: 9026, type: WidthType.DXA }, +columnWidths: [7000, 2026] // Deve somar a largura da tabela +``` + +**Regras de largura:** +- **Usar sempre `WidthType.DXA`** — nunca `WidthType.PERCENTAGE` (incompativel com Google Docs) +- Largura da tabela deve igualar a soma de `columnWidths` +- `width` da celula deve corresponder ao respectivo `columnWidth` +- `margins` da celula sao padding interno - reduzem a area de conteudo, nao adicionam a largura +- Para tabelas full-width: usar largura de conteudo (largura pagina menos margens esquerda e direita) + +### Imagens + +```javascript +// CRITICO: parametro type e OBRIGATORIO +new Paragraph({ + children: [new ImageRun({ + type: "png", // Obrigatorio: png, jpg, jpeg, gif, bmp, svg + data: fs.readFileSync("image.png"), + transformation: { width: 200, height: 150 }, + altText: { title: "Titulo", description: "Desc", name: "Nome" } // Os tres sao obrigatorios + })] +}) +``` + +### Quebras de pagina + +```javascript +// CRITICO: PageBreak deve estar dentro de um Paragraph +new Paragraph({ children: [new PageBreak()] }) + +// Ou usar pageBreakBefore +new Paragraph({ pageBreakBefore: true, children: [new TextRun("Nova pagina")] }) +``` + +### Indice (Table of Contents) + +```javascript +// CRITICO: Headings devem usar HeadingLevel APENAS - sem estilos custom +new TableOfContents("Indice", { hyperlink: true, headingStyleRange: "1-3" }) +``` + +### Cabecalhos/Rodapes + +```javascript +sections: [{ + properties: { + page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } } // 1440 = 1 polegada + }, + headers: { + default: new Header({ children: [new Paragraph({ children: [new TextRun("Cabecalho")] })] }) + }, + footers: { + default: new Footer({ children: [new Paragraph({ + children: [new TextRun("Pagina "), new TextRun({ children: [PageNumber.CURRENT] })] + })] }) + }, + children: [/* conteudo */] +}] +``` + +### Regras criticas para docx-js + +- **Definir tamanho de pagina explicitamente** - docx-js assume A4; para documentos PT/EU, A4 (11906 x 16838 DXA) e o padrao correcto +- **Paisagem: passar dimensoes retrato** - docx-js troca largura/altura internamente; passar lado curto como `width`, lado longo como `height`, e definir `orientation: PageOrientation.LANDSCAPE` +- **Nunca usar `\n`** - usar elementos Paragraph separados +- **Nunca usar bullets unicode** - usar `LevelFormat.BULLET` com config numbering +- **PageBreak deve estar em Paragraph** - standalone cria XML invalido +- **ImageRun requer `type`** - especificar sempre png/jpg/etc +- **Definir sempre `width` da tabela com DXA** - nunca usar `WidthType.PERCENTAGE` (quebra no Google Docs) +- **Tabelas precisam de larguras duplas** - array `columnWidths` E `width` da celula, ambos devem corresponder +- **Largura tabela = soma de columnWidths** - para DXA, garantir que somam exactamente +- **Adicionar sempre margins nas celulas** - usar `margins: { top: 80, bottom: 80, left: 120, right: 120 }` para padding legivel +- **Usar `ShadingType.CLEAR`** - nunca SOLID para shading de tabelas +- **TOC requer HeadingLevel apenas** - sem estilos custom nos paragrafos de heading +- **Override built-in styles** - usar IDs exactos: "Heading1", "Heading2", etc. +- **Incluir `outlineLevel`** - necessario para TOC (0 para H1, 1 para H2, etc.) + +--- + +## Editar documentos existentes + +**Seguir os 3 passos por ordem.** + +### Passo 1: Descompactar +```bash +python scripts/office/unpack.py document.docx unpacked/ +``` +Extrai XML, pretty-prints, funde runs adjacentes e converte smart quotes para entidades XML (`“` etc.) para sobreviverem a edicao. Usar `--merge-runs false` para saltar a fusao de runs. + +### Passo 2: Editar XML + +Editar ficheiros em `unpacked/word/`. Ver Referencia XML abaixo para padroes. + +**Usar "Claude" como autor** para tracked changes e comentarios, salvo se o utilizador pedir outro nome. + +**Usar a ferramenta Edit directamente para substituicao de strings. Nao escrever scripts Python.** Scripts introduzem complexidade desnecessaria. A ferramenta Edit mostra exactamente o que esta a ser substituido. + +**CRITICO: Usar smart quotes para novo conteudo.** Ao adicionar texto com apostrofos ou aspas, usar entidades XML para produzir smart quotes: +```xml + +Here’s a quote: “Hello” +``` +| Entidade | Caractere | +|----------|-----------| +| `‘` | ' (aspas simples esquerda) | +| `’` | ' (aspas simples direita / apostrofo) | +| `“` | " (aspas duplas esquerda) | +| `”` | " (aspas duplas direita) | + +**Adicionar comentarios:** Usar `comment.py` para tratar boilerplate em multiplos ficheiros XML (texto deve ser XML pre-escaped): +```bash +python scripts/comment.py unpacked/ 0 "Texto do comentario com & e ’" +python scripts/comment.py unpacked/ 1 "Texto de resposta" --parent 0 # resposta ao comentario 0 +python scripts/comment.py unpacked/ 0 "Texto" --author "Autor Custom" # nome de autor custom +``` +Depois adicionar marcadores ao document.xml (ver Comentarios na Referencia XML). + +### Passo 3: Recompactar +```bash +python scripts/office/pack.py unpacked/ output.docx --original document.docx +``` +Valida com auto-reparacao, condensa XML e cria DOCX. Usar `--validate false` para saltar. + +**Auto-reparacao corrige:** +- `durableId` >= 0x7FFFFFFF (regenera ID valido) +- `xml:space="preserve"` em falta em `` com whitespace + +**Auto-reparacao nao corrige:** +- XML malformado, nesting de elementos invalido, relacoes em falta, violacoes de schema + +### Erros comuns + +- **Substituir elementos `` inteiros**: Ao adicionar tracked changes, substituir o bloco `...` completo com `......` como siblings. Nao injectar tags de tracked change dentro de um run. +- **Preservar formatacao ``**: Copiar o bloco `` do run original para os runs de tracked change para manter bold, tamanho de fonte, etc. + +--- + +## Referencia XML + +### Conformidade com schema + +- **Ordem de elementos em ``**: ``, ``, ``, ``, ``, `` por ultimo +- **Whitespace**: Adicionar `xml:space="preserve"` a `` com espacos no inicio/fim +- **RSIDs**: Devem ser hex de 8 digitos (ex: `00AB1234`) + +### Tracked Changes + +**Insercao:** +```xml + + texto inserido + +``` + +**Eliminacao:** +```xml + + texto eliminado + +``` + +**Dentro de ``**: Usar `` em vez de ``, e `` em vez de ``. + +**Edicoes minimas** - marcar apenas o que muda: +```xml + +O prazo e de + + 30 + + + 60 + + dias. +``` + +**Eliminar paragrafos/itens de lista inteiros** - ao remover TODO o conteudo de um paragrafo, marcar tambem o paragraph mark como eliminado para fundir com o proximo paragrafo. Adicionar `` dentro de ``: +```xml + + + ... + + + + + + Conteudo inteiro do paragrafo a ser eliminado... + + +``` +Sem o `` em ``, aceitar alteracoes deixa um paragrafo/item de lista vazio. + +**Rejeitar insercao de outro autor** - aninhar eliminacao dentro da insercao: +```xml + + + texto inserido por ela + + +``` + +**Restaurar eliminacao de outro autor** - adicionar insercao depois (nao modificar a eliminacao): +```xml + + texto eliminado + + + texto eliminado + +``` + +### Comentarios + +Apos executar `comment.py` (ver Passo 2), adicionar marcadores ao document.xml. Para respostas, usar flag `--parent` e aninhar marcadores dentro dos do pai. + +**CRITICO: `` e `` sao siblings de ``, nunca dentro de ``.** + +```xml + + + + eliminado + + mais texto + + + + + + + texto + + + + +``` + +### Imagens + +1. Adicionar ficheiro de imagem a `word/media/` +2. Adicionar relacao a `word/_rels/document.xml.rels`: +```xml + +``` +3. Adicionar content type a `[Content_Types].xml`: +```xml + +``` +4. Referenciar no document.xml: +```xml + + + + + + + + + + + + +``` + +--- + +## Dependencias + +- **pandoc**: Extracao de texto +- **docx**: `npm install -g docx` (novos documentos) +- **LibreOffice**: Conversao PDF (auto-configurado para ambientes sandbox via `scripts/office/soffice.py`) +- **Poppler**: `pdftoppm` para imagens + +--- + +## Integracao Descomplicar + +### MCPs disponiveis + +| MCP | Uso | +|-----|-----| +| `mcp__filesystem__*` | Ler/escrever ficheiros .docx locais, listar directorios | +| `mcp__google-workspace__*` | Upload para Google Drive, conversao para Google Docs | +| `mcp__ssh-unified__*` | Operacoes em ficheiros .docx em servidores remotos | + +### Workflow tipico + +1. **Criar documento** com docx-js conforme instrucoes acima +2. **Validar** com `scripts/office/validate.py` +3. **Guardar** via `mcp__filesystem__write_file` ou directamente no path do projecto +4. **Upload** (opcional) via `mcp__google-workspace__drive_upload_file` para partilha com cliente + +### Convencoes Descomplicar + +- **Formato de data** em documentos: DD-MM-YYYY (ex: 06-03-2026) +- **Formato monetario**: 1.234,56 EUR (separador milhar ponto, decimal virgula) +- **Fonte padrao**: Arial 12pt +- **Tamanho pagina padrao**: A4 (11906 x 16838 DXA) +- **Autor para tracked changes**: "Claude" (salvo indicacao contraria) +- **Idioma do documento**: PT-PT salvo indicacao contraria + +--- +**Versao**: 1.0.0 | **Autor**: 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ós cada erro corrigido.* diff --git a/dev-tools/skills/frontend-design b/dev-tools/skills/frontend-design new file mode 120000 index 0000000..63d3034 --- /dev/null +++ b/dev-tools/skills/frontend-design @@ -0,0 +1 @@ +/home/ealmeida/.claude/plugins/anthropic-claude-code/plugins/frontend-design/skills/frontend-design \ No newline at end of file diff --git a/dev-tools/skills/nextjs/SKILL.md b/dev-tools/skills/nextjs/SKILL.md index 16e2451..c870f80 100644 --- a/dev-tools/skills/nextjs/SKILL.md +++ b/dev-tools/skills/nextjs/SKILL.md @@ -1,7 +1,6 @@ --- name: nextjs description: Desenvolvimento Next.js moderno (13+) com App Router, Server Components, rotas API e deployment seguindo padroes Descomplicar. -layer: wiki --- # /nextjs - Next.js Development @@ -23,20 +22,18 @@ mcp__notebooklm__notebook_query({ ## Regra #48 - Dev Container (OBRIGATÓRIO) -**TODOS os projectos Next.js devem ser desenvolvidos no container dev.** +**TODOS os projectos Next.js são desenvolvidos LOCALMENTE no desktop (regra 48 — CT 102 extinto em 20-04-2026).** ``` -SSH: server="dev" (mcp__ssh-unified__ssh_execute) -Path: /root/Dev/ -Sync: auto -> /media/ealmeida/Dados/Dev/ (Syncthing) +Ambiente: Bash local no desktop (sem SSH) +Path: /media/ealmeida/Dados/Dev/ ``` **Workflow:** -1. `mcp__ssh-unified__ssh_execute server:"dev" command:"mkdir -p /root/Dev/"` +1. `mkdir -p /media/ealmeida/Dados/Dev/` (Bash local) 2. Desenvolver e testar no container 3. `npm run build` no container antes de deploy 4. Deploy via EasyPanel -5. Syncthing propaga automaticamente **NUNCA:** `npx create-next-app` directamente no PC local para projectos colaborativos. diff --git a/dev-tools/skills/pdf/SKILL-light.md b/dev-tools/skills/pdf/SKILL-light.md index 4f975d9..fd81682 100644 --- a/dev-tools/skills/pdf/SKILL-light.md +++ b/dev-tools/skills/pdf/SKILL-light.md @@ -1,7 +1,6 @@ --- name: pdf description: Processamento de ficheiros PDF — leitura, extracção, merge, split, OCR, formulários. Versão light para heartbeats. -layer: wiki --- # PDF — Referência Rápida diff --git a/dev-tools/skills/pdf/SKILL.md b/dev-tools/skills/pdf/SKILL.md index 2a0c9ec..0dbd19d 100644 --- a/dev-tools/skills/pdf/SKILL.md +++ b/dev-tools/skills/pdf/SKILL.md @@ -1,7 +1,6 @@ --- name: pdf description: Processamento completo de ficheiros PDF — leitura, extraccao de texto/tabelas, merge, split, watermarks, encriptacao, OCR, criacao e preenchimento de formularios. -layer: wiki --- # PDF Processing Guide @@ -194,4 +193,616 @@ Para texto desenhado com canvas (nao Paragraph), ajustar manualmente o tamanho d pdftotext input.pdf output.txt # Extract text preserving layout -pdftotext -layout \ No newline at end of file +pdftotext -layout input.pdf output.txt + +# Extract specific pages +pdftotext -f 1 -l 5 input.pdf output.txt # Pages 1-5 +``` + +### qpdf +```bash +# Merge PDFs +qpdf --empty --pages file1.pdf file2.pdf -- merged.pdf + +# Split pages +qpdf input.pdf --pages . 1-5 -- pages1-5.pdf +qpdf input.pdf --pages . 6-10 -- pages6-10.pdf + +# Rotate pages +qpdf input.pdf output.pdf --rotate=+90:1 # Rotate page 1 by 90 degrees + +# Remove password +qpdf --password=mypassword --decrypt encrypted.pdf decrypted.pdf +``` + +### pdftk (if available) +```bash +# Merge +pdftk file1.pdf file2.pdf cat output merged.pdf + +# Split +pdftk input.pdf burst + +# Rotate +pdftk input.pdf rotate 1east output rotated.pdf +``` + +## Tarefas comuns + +### Extrair texto de PDFs digitalizados (OCR) +```python +# Requires: pip install pytesseract pdf2image +import pytesseract +from pdf2image import convert_from_path + +# Convert PDF to images +images = convert_from_path('scanned.pdf') + +# OCR each page +text = "" +for i, image in enumerate(images): + text += f"Page {i+1}:\n" + text += pytesseract.image_to_string(image) + text += "\n\n" + +print(text) +``` + +### Adicionar watermark +```python +from pypdf import PdfReader, PdfWriter + +# Create watermark (or load existing) +watermark = PdfReader("watermark.pdf").pages[0] + +# Apply to all pages +reader = PdfReader("document.pdf") +writer = PdfWriter() + +for page in reader.pages: + page.merge_page(watermark) + writer.add_page(page) + +with open("watermarked.pdf", "wb") as output: + writer.write(output) +``` + +### Extrair imagens +```bash +# Using pdfimages (poppler-utils) +pdfimages -j input.pdf output_prefix + +# This extracts all images as output_prefix-000.jpg, output_prefix-001.jpg, etc. +``` + +### Proteccao por password +```python +from pypdf import PdfReader, PdfWriter + +reader = PdfReader("input.pdf") +writer = PdfWriter() + +for page in reader.pages: + writer.add_page(page) + +# Add password +writer.encrypt("userpassword", "ownerpassword") + +with open("encrypted.pdf", "wb") as output: + writer.write(output) +``` + +## Referencia rapida + +| Tarefa | Melhor ferramenta | Comando/codigo | +|--------|-------------------|----------------| +| Merge PDFs | pypdf | `writer.add_page(page)` | +| Split PDFs | pypdf | One page per file | +| Extrair texto | pdfplumber | `page.extract_text()` | +| Extrair tabelas | pdfplumber | `page.extract_tables()` | +| Criar PDFs | reportlab | Canvas or Platypus | +| Merge CLI | qpdf | `qpdf --empty --pages ...` | +| OCR scanned PDFs | pytesseract | Convert to image first | +| Preencher formularios | pypdf ou annotations | Ver seccao abaixo | + +--- + +## Preenchimento de formularios + +**Obrigatorio: seguir estes passos por ordem. Nao saltar para codigo directamente.** + +Primeiro verificar se o PDF tem campos preenchíveis. Executar a partir da pasta de scripts desta skill: +`python scripts/check_fillable_fields.py ` + +Consoante o resultado, seguir a seccao "Campos preenchíveis" ou "Campos nao preenchíveis". + +### Campos preenchíveis + +Se o PDF tiver campos de formulario nativos: + +1. Extrair informacao dos campos: +`python scripts/extract_form_field_info.py ` + +O JSON resultante contem campos com esta estrutura: +```json +[ + { + "field_id": "(ID unico do campo)", + "page": "(numero da pagina, 1-based)", + "rect": "[left, bottom, right, top]", + "type": "text | checkbox | radio_group | choice" + } +] +``` + +Para **checkboxes**: propriedades `checked_value` e `unchecked_value`. +Para **radio groups**: lista `radio_options` com `value` e `rect`. +Para **choice fields**: lista `choice_options` com `value` e `text`. + +2. Converter PDF para imagens para analise visual: +`python scripts/convert_pdf_to_images.py ` +Analisar as imagens para determinar o proposito de cada campo. + +3. Criar `field_values.json`: +```json +[ + { + "field_id": "last_name", + "description": "Apelido do utilizador", + "page": 1, + "value": "Silva" + }, + { + "field_id": "Checkbox12", + "description": "Checkbox para maiores de 18", + "page": 1, + "value": "/On" + } +] +``` + +4. Preencher: +`python scripts/fill_fillable_fields.py ` + +### Campos nao preenchíveis + +Se o PDF nao tiver campos nativos, usar anotacoes de texto. Tentar primeiro extraccao por estrutura (mais preciso), depois estimativa visual como fallback. + +#### Passo 1: extraccao por estrutura + +`python scripts/extract_form_structure.py form_structure.json` + +Extrai labels de texto, linhas horizontais e checkboxes com coordenadas exactas. + +**Se form_structure.json tiver labels significativos** -> usar abordagem A (estrutura). +**Se o PDF for digitalizado/imagem** -> usar abordagem B (visual). + +#### Abordagem A: coordenadas por estrutura (preferida) + +Analisar form_structure.json e identificar: +- **Label groups**: elementos de texto adjacentes que formam um label +- **Row structure**: labels com `top` similar estao na mesma linha +- **Field columns**: areas de entrada comecam apos o label (x0 = label.x1 + gap) +- **Checkboxes**: usar coordenadas directamente do JSON + +Criar fields.json com `pdf_width`/`pdf_height`: +```json +{ + "pages": [ + {"page_number": 1, "pdf_width": 612, "pdf_height": 792} + ], + "form_fields": [ + { + "page_number": 1, + "description": "Campo apelido", + "field_label": "Apelido", + "label_bounding_box": [43, 63, 87, 73], + "entry_bounding_box": [92, 63, 260, 79], + "entry_text": {"text": "Silva", "font_size": 10} + } + ] +} +``` + +#### Abordagem B: estimativa visual (fallback) + +1. Converter PDF para imagens: +`python scripts/convert_pdf_to_images.py ` + +2. Identificar campos e posicoes aproximadas nas imagens. + +3. Refinar com zoom (ImageMagick): +```bash +magick -crop x++ +repage +``` + +Converter coordenadas do crop de volta para coordenadas da imagem completa: +- full_x = crop_x + crop_offset_x +- full_y = crop_y + crop_offset_y + +4. Criar fields.json com `image_width`/`image_height`. + +#### Abordagem hibrida + +Quando a extraccao por estrutura funciona para a maioria dos campos mas falta alguns: +1. Usar abordagem A para campos detectados +2. Usar abordagem B para campos em falta +3. Converter todas as coordenadas para PDF: + - pdf_x = image_x * (pdf_width / image_width) + - pdf_y = image_y * (pdf_height / image_height) +4. Usar sistema de coordenadas unico com `pdf_width`/`pdf_height` + +#### Validacao e preenchimento + +Validar bounding boxes antes de preencher: +`python scripts/check_bounding_boxes.py fields.json` + +Preencher o formulario: +`python scripts/fill_pdf_form_with_annotations.py fields.json ` + +Verificar resultado: +`python scripts/convert_pdf_to_images.py ` + +Criar imagem de validacao com bounding boxes sobrepostas: +`python scripts/create_validation_image.py ` + +--- + +## Referencia avancada + +### pypdfium2 — rendering rapido + +```python +import pypdfium2 as pdfium +from PIL import Image + +# Load PDF +pdf = pdfium.PdfDocument("document.pdf") + +# Render page to image +page = pdf[0] +bitmap = page.render(scale=2.0, rotation=0) +img = bitmap.to_pil() +img.save("page_1.png", "PNG") + +# Process multiple pages +for i, page in enumerate(pdf): + bitmap = page.render(scale=1.5) + img = bitmap.to_pil() + img.save(f"page_{i+1}.jpg", "JPEG", quality=90) +``` + +### pdfplumber — funcionalidades avancadas + +#### Texto com coordenadas precisas +```python +import pdfplumber + +with pdfplumber.open("document.pdf") as pdf: + page = pdf.pages[0] + + # Extract all text with coordinates + chars = page.chars + for char in chars[:10]: + print(f"Char: '{char['text']}' at x:{char['x0']:.1f} y:{char['y0']:.1f}") + + # Extract text by bounding box (left, top, right, bottom) + bbox_text = page.within_bbox((100, 100, 400, 200)).extract_text() +``` + +#### Tabelas complexas com settings customizados +```python +import pdfplumber +import pandas as pd + +with pdfplumber.open("complex_table.pdf") as pdf: + page = pdf.pages[0] + + table_settings = { + "vertical_strategy": "lines", + "horizontal_strategy": "lines", + "snap_tolerance": 3, + "intersection_tolerance": 15 + } + tables = page.extract_tables(table_settings) + + # Visual debugging for table extraction + img = page.to_image(resolution=150) + img.save("debug_layout.png") +``` + +### reportlab — relatorios profissionais com tabelas + +```python +from reportlab.platypus import SimpleDocTemplate, Table, TableStyle, Paragraph +from reportlab.lib.styles import getSampleStyleSheet +from reportlab.lib import colors + +data = [ + ['Produto', 'Q1', 'Q2', 'Q3', 'Q4'], + ['Widgets', '120', '135', '142', '158'], + ['Gadgets', '85', '92', '98', '105'] +] + +doc = SimpleDocTemplate("report.pdf") +elements = [] + +styles = getSampleStyleSheet() +title = Paragraph("Relatorio Trimestral de Vendas", styles['Title']) +elements.append(title) + +table = Table(data) +table.setStyle(TableStyle([ + ('BACKGROUND', (0, 0), (-1, 0), colors.grey), + ('TEXTCOLOR', (0, 0), (-1, 0), colors.whitesmoke), + ('ALIGN', (0, 0), (-1, -1), 'CENTER'), + ('FONTNAME', (0, 0), (-1, 0), 'Helvetica-Bold'), + ('FONTSIZE', (0, 0), (-1, 0), 14), + ('BOTTOMPADDING', (0, 0), (-1, 0), 12), + ('BACKGROUND', (0, 1), (-1, -1), colors.beige), + ('GRID', (0, 0), (-1, -1), 1, colors.black) +])) +elements.append(table) + +doc.build(elements) +``` + +### JavaScript — pdf-lib (criacao e modificacao) + +#### Load and Manipulate Existing PDF +```javascript +import { PDFDocument } from 'pdf-lib'; +import fs from 'fs'; + +async function manipulatePDF() { + const existingPdfBytes = fs.readFileSync('input.pdf'); + const pdfDoc = await PDFDocument.load(existingPdfBytes); + + const pageCount = pdfDoc.getPageCount(); + const newPage = pdfDoc.addPage([600, 400]); + newPage.drawText('Added by pdf-lib', { x: 100, y: 300, size: 16 }); + + const pdfBytes = await pdfDoc.save(); + fs.writeFileSync('modified.pdf', pdfBytes); +} +``` + +#### Advanced Merge and Split +```javascript +import { PDFDocument } from 'pdf-lib'; +import fs from 'fs'; + +async function mergePDFs() { + const mergedPdf = await PDFDocument.create(); + + const pdf1 = await PDFDocument.load(fs.readFileSync('doc1.pdf')); + const pdf2 = await PDFDocument.load(fs.readFileSync('doc2.pdf')); + + const pdf1Pages = await mergedPdf.copyPages(pdf1, pdf1.getPageIndices()); + pdf1Pages.forEach(page => mergedPdf.addPage(page)); + + const pdf2Pages = await mergedPdf.copyPages(pdf2, [0, 2, 4]); + pdf2Pages.forEach(page => mergedPdf.addPage(page)); + + fs.writeFileSync('merged.pdf', await mergedPdf.save()); +} +``` + +### Operacoes avancadas CLI + +#### poppler-utils +```bash +# Text with bounding box coordinates +pdftotext -bbox-layout document.pdf output.xml + +# High-resolution PNG conversion +pdftoppm -png -r 300 document.pdf output_prefix + +# Specific page range with high resolution +pdftoppm -png -r 600 -f 1 -l 3 document.pdf high_res_pages + +# Extract all embedded images with metadata +pdfimages -j -p document.pdf page_images + +# List image info without extracting +pdfimages -list document.pdf +``` + +#### qpdf avancado +```bash +# Split PDF into groups of pages +qpdf --split-pages=3 input.pdf output_group_%02d.pdf + +# Complex page ranges from multiple PDFs +qpdf --empty --pages doc1.pdf 1-3 doc2.pdf 5-7 doc3.pdf 2,4 -- combined.pdf + +# Optimize for web (linearize) +qpdf --linearize input.pdf optimized.pdf + +# Repair corrupted PDF +qpdf --check input.pdf +qpdf --fix-qdf damaged.pdf repaired.pdf + +# Advanced encryption with permissions +qpdf --encrypt user_pass owner_pass 256 --print=none --modify=none -- input.pdf encrypted.pdf + +# Check encryption status +qpdf --show-encryption encrypted.pdf +``` + +### Processamento em lote com error handling + +```python +import os +import glob +from pypdf import PdfReader, PdfWriter +import logging + +logging.basicConfig(level=logging.INFO) +logger = logging.getLogger(__name__) + +def batch_process_pdfs(input_dir, operation='merge'): + pdf_files = glob.glob(os.path.join(input_dir, "*.pdf")) + + if operation == 'merge': + writer = PdfWriter() + for pdf_file in pdf_files: + try: + reader = PdfReader(pdf_file) + for page in reader.pages: + writer.add_page(page) + logger.info(f"Processed: {pdf_file}") + except Exception as e: + logger.error(f"Failed to process {pdf_file}: {e}") + continue + + with open("batch_merged.pdf", "wb") as output: + writer.write(output) + + elif operation == 'extract_text': + for pdf_file in pdf_files: + try: + reader = PdfReader(pdf_file) + text = "" + for page in reader.pages: + text += page.extract_text() + + output_file = pdf_file.replace('.pdf', '.txt') + with open(output_file, 'w', encoding='utf-8') as f: + f.write(text) + logger.info(f"Extracted text from: {pdf_file}") + except Exception as e: + logger.error(f"Failed to extract text from {pdf_file}: {e}") + continue +``` + +### Cropping avancado + +```python +from pypdf import PdfWriter, PdfReader + +reader = PdfReader("input.pdf") +writer = PdfWriter() + +page = reader.pages[0] +page.mediabox.left = 50 +page.mediabox.bottom = 50 +page.mediabox.right = 550 +page.mediabox.top = 750 + +writer.add_page(page) +with open("cropped.pdf", "wb") as output: + writer.write(output) +``` + +### Gestao de memoria para PDFs grandes + +```python +def process_large_pdf(pdf_path, chunk_size=10): + reader = PdfReader(pdf_path) + total_pages = len(reader.pages) + + for start_idx in range(0, total_pages, chunk_size): + end_idx = min(start_idx + chunk_size, total_pages) + writer = PdfWriter() + + for i in range(start_idx, end_idx): + writer.add_page(reader.pages[i]) + + with open(f"chunk_{start_idx//chunk_size}.pdf", "wb") as output: + writer.write(output) +``` + +## Troubleshooting + +### PDFs encriptados +```python +from pypdf import PdfReader + +try: + reader = PdfReader("encrypted.pdf") + if reader.is_encrypted: + reader.decrypt("password") +except Exception as e: + print(f"Failed to decrypt: {e}") +``` + +### PDFs corrompidos +```bash +qpdf --check corrupted.pdf +qpdf --replace-input corrupted.pdf +``` + +### Falha na extraccao de texto (fallback para OCR) +```python +import pytesseract +from pdf2image import convert_from_path + +def extract_text_with_ocr(pdf_path): + images = convert_from_path(pdf_path) + text = "" + for i, image in enumerate(images): + text += pytesseract.image_to_string(image) + return text +``` + +## Dicas de performance + +1. **PDFs grandes**: usar streaming em vez de carregar tudo em memoria; `qpdf --split-pages` para dividir +2. **Extraccao de texto**: `pdftotext -bbox-layout` e o mais rapido; pdfplumber para tabelas +3. **Extraccao de imagens**: `pdfimages` e muito mais rapido que rendering de paginas +4. **Preenchimento de formularios**: pdf-lib mantem melhor a estrutura do formulario +5. **Memoria**: processar paginas individualmente com pypdfium2 para documentos grandes + +--- + +## Integracao Descomplicar + +### Caminhos frequentes para PDFs + +| Localizacao | Caminho | +|-------------|---------| +| Documentos empresa | `/media/ealmeida/Dados/GDrive/Cloud/Descomplicar/` | +| Propostas | `/media/ealmeida/Dados/Hub/03-Propostas/` | +| Arquivo clientes | `/media/ealmeida/Dados/GDrive/Arquivo_de_Clientes/` | +| Knowledge Base | `/media/ealmeida/Dados/Hub/06-Operacoes/Knowledge-Base/PDFs/` | +| Backups | `/media/ealmeida/Externo/LocalBackups/` (espelhado p/ GDrive via rclone) | +| Temporarios | `~/.claude-work/` (limpar ao concluir) | + +### MCPs relevantes + +- **mcp__filesystem__read_file** / **write_file**: ler e escrever PDFs locais +- **mcp__filesystem__search_files**: encontrar PDFs no sistema +- **mcp__google-workspace__drive_search_files**: encontrar PDFs no Google Drive +- **mcp__google-workspace__drive_read_file_content**: ler conteudo de ficheiros no Drive +- **mcp__google-workspace__drive_upload_file**: enviar PDFs processados para o Drive + +### Workflow tipico Descomplicar + +1. Localizar PDF (filesystem ou Google Drive) +2. Descarregar para `~/.claude-work/` se necessario +3. Processar (extrair, merge, split, OCR, etc.) +4. Guardar resultado no destino final +5. Limpar temporarios de `~/.claude-work/` + +--- + +## Licencas das bibliotecas + +- **pypdf**: BSD | **pdfplumber**: MIT | **pypdfium2**: Apache/BSD | **reportlab**: BSD +- **poppler-utils**: GPL-2 | **qpdf**: Apache | **pdf-lib**: MIT | **pdfjs-dist**: Apache + +--- +**Versao**: 1.0.0 | **Autor**: 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ós cada erro corrigido.* diff --git a/dev-tools/skills/php-dev/SKILL.md b/dev-tools/skills/php-dev/SKILL.md index 9ec469d..f7ac1f0 100644 --- a/dev-tools/skills/php-dev/SKILL.md +++ b/dev-tools/skills/php-dev/SKILL.md @@ -1,8 +1,7 @@ --- name: php-dev description: Desenvolvimento PHP moderno com Laravel, Symfony e APIs RESTful — autenticação (JWT, OAuth, Sanctum), service classes e refactorização de código legacy seguindo padrões PSR. -allowed-tools: Read, Write, Edit, Bash, mcp__mem_search_memories, mcp__context7__get-library-docs, mcp__notebooklm__notebook_query, mcp__dify-kb__dify_kb_retrieve_segments -layer: wiki +allowed-tools: Read, Write, Edit, Bash, mcp__mem0__search_memories, mcp__context7__get-library-docs, mcp__notebooklm__notebook_query, mcp__dify-kb__dify_kb_retrieve_segments --- # PHP Fullstack Engineer @@ -34,7 +33,7 @@ mcp__notebooklm__notebook_query({ Integrar insights do NotebookLM nas recomendações e decisões. -> **Regra #48:** Projectos PHP/Laravel/Symfony devem ser desenvolvidos no **container dev** (`server:"dev"`, path `/root/Dev/`). Sincroniza automaticamente com o PC local via Syncthing. +> **Regra #48:** Projectos PHP/Laravel/Symfony são desenvolvidos **localmente no desktop** em `/media/ealmeida/Dados/Dev/` (Bash local, sem SSH — CT 102 extinto em 20-04-2026). ## Quando Usar @@ -48,8 +47,8 @@ Integrar insights do NotebookLM nas recomendações e decisões. ### 1. Pesquisa Inicial ``` -mcp__mem_search_memories "[keywords php/laravel]" -mcp__wikijs__search_pages "[framework] best practices" +mcp__mem0__search_memories "[keywords php/laravel]" +/knowledge (router Hub QR/PROC) + mcp__mem0__search_memories "[framework] best practices" mcp__context7__get-library-docs para documentação actualizada ``` @@ -202,3 +201,206 @@ class ProductService } public function create(array $data): Product + { + return $this->repository->create($data); + } +} +``` + +### Repository +```php +when($filters['category'] ?? null, fn($q, $cat) => $q->where('category_id', $cat)) + ->when($filters['active'] ?? null, fn($q, $active) => $q->where('active', $active)) + ->orderBy('created_at', 'desc') + ->paginate($filters['per_page'] ?? 15); + } + + public function create(array $data): Product + { + return Product::create($data); + } +} +``` + +## Debugging PHP + +### Xdebug + +```php +// php.ini +zend_extension=xdebug.so +xdebug.mode=debug +xdebug.start_with_request=yes +xdebug.client_host=127.0.0.1 +xdebug.client_port=9003 +``` + +### Logging + +```php +// Monolog exemplo +use Monolog\Logger; +use Monolog\Handler\StreamHandler; + +$log = new Logger('app'); +$log->pushHandler(new StreamHandler('logs/app.log', Logger::DEBUG)); + +$log->info('User logged in', ['user_id' => $userId]); +$log->error('Database error', ['exception' => $e->getMessage()]); +``` + +### Profiling + +```bash +# Com Blackfire +blackfire run php script.php + +# Com Xhprof +php -d extension=xhprof.so script.php +``` + +## Testes Unitários + +### PHPUnit + +```php +service = new ProductService( + new InMemoryProductRepository() + ); + } + + public function test_create_product(): void + { + $product = $this->service->create([ + 'name' => 'Test Product', + 'price' => 99.99 + ]); + + $this->assertInstanceOf(Product::class, $product); + $this->assertEquals('Test Product', $product->name); + } +} +``` + +### Pest (alternativa moderna) + +```php +create([ + 'name' => 'Test', + 'price' => 99.99 + ]); + + expect($product) + ->toBeInstanceOf(Product::class) + ->name->toBe('Test'); +}); +``` + +## Checklist Entrega + +- [ ] Assinatura Descomplicar® em todos os ficheiros +- [ ] php -l sem erros +- [ ] PHPDoc em funções públicas +- [ ] Type hints completos +- [ ] PSR-12 compliant +- [ ] Segurança validada (injection, XSS) +- [ ] Se API: documentação endpoints +- [ ] Testes unitários (cobertura >70%) + +--- + +## Datasets Dify (Consulta Obrigatória) + +Em caso de dúvidas ou para aprofundar conhecimento, consultar os seguintes datasets via MCP: + +| Dataset | ID | Prioridade | +|---------|----|-----------:| +| **TI (Tecnologia da Informação)** | `7f63ec0c-6321-488c-b107-980140199850` | 1 | +| **Desenvolvimento de Software** | `e7c7decc-0ded-4351-ab14-b110b3c38ec9` | 1 | +| **Wordpress** | `9da0b2b9-5051-4b99-b9f6-20bf35067092` | 2 | +| **PerfexCRM** | `43354eb6-f0b2-40cc-aa53-44e375ab347c` | 3 | + +### Como Consultar + +```javascript +# PRIMARIO: NotebookLM (Gemini 2.5 RAG) +# mcp__notebooklm__notebook_query({notebook_id: "2876d1fe-5cea-4d98-8140-b0e1a81c6bc4", query: ""}) // Claude Code +# mcp__notebooklm__notebook_query({notebook_id: "73102308-70ef-403e-9be9-eae0cfc62d55", query: ""}) // Desenvolvimento de MCPs +# mcp__notebooklm__notebook_query({notebook_id: "57d9c6c9-48ba-4d83-8f71-cc890f348a53", query: ""}) // AI Code Editors +# mcp__notebooklm__notebook_query({notebook_id: "24947ffa-0019-448a-a340-2f4a275d2eb1", query: ""}) // Programacao +# mcp__notebooklm__notebook_query({notebook_id: "ebee9fe1-78fd-4f85-8938-f19f3ea32131", query: ""}) // Obsidian + Claude +# FALLBACK: Dify KB (se NotebookLM insuficiente) + +// Pesquisar padrões Laravel +mcp__dify-kb__dify_kb_retrieve_segments({ + dataset_id: "e7c7decc-0ded-4351-ab14-b110b3c38ec9", + query: "laravel service repository pattern" +}) + +// APIs e autenticação +mcp__dify-kb__dify_kb_retrieve_segments({ + dataset_id: "7f63ec0c-6321-488c-b107-980140199850", + query: "api rest jwt sanctum" +}) + +// Desenvolvimento Perfex +mcp__dify-kb__dify_kb_retrieve_segments({ + dataset_id: "43354eb6-f0b2-40cc-aa53-44e375ab347c", + query: "module development hooks" +}) +``` + +### Quando Consultar + +- Implementar padrões de arquitectura +- Desenvolver APIs RESTful +- Integrar sistemas de autenticação +- Criar módulos Perfex CRM +- Refactorizar código legacy + +--- +**Versão**: 1.0.0 | **Autor**: 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ós cada erro corrigido.* diff --git a/dev-tools/skills/prompt-refine/SKILL.md b/dev-tools/skills/prompt-refine/SKILL.md index 591d4eb..31bed50 100644 --- a/dev-tools/skills/prompt-refine/SKILL.md +++ b/dev-tools/skills/prompt-refine/SKILL.md @@ -1,8 +1,7 @@ --- name: prompt-refine description: Transforma um pedido vago em prompt de excelência — especificação detalhada, inequívoca e estruturada para agentes de IA. Usar quando "refinar prompt", "melhorar prompt", "engenharia de prompts", "prompt para agente", "estruturar instrução IA", "prompt engineering". -allowed-tools: Read, Write, mcp__mem_search_memories -layer: wiki +allowed-tools: Read, Write, mcp__mem0__search_memories --- # /prompt-refine — Engenharia de Prompts @@ -21,7 +20,7 @@ Transforma um pedido em linguagem natural num **prompt de excelência** pronto p ### 1. Pesquisar contexto relevante ``` -mcp__mem_search_memories "" +mcp__mem0__search_memories "" ``` Verificar se há padrões ou decisões anteriores relacionadas. diff --git a/dev-tools/skills/react-patterns/SKILL.md b/dev-tools/skills/react-patterns/SKILL.md index 845d10b..dbdb936 100644 --- a/dev-tools/skills/react-patterns/SKILL.md +++ b/dev-tools/skills/react-patterns/SKILL.md @@ -1,7 +1,6 @@ --- name: react-patterns description: Padroes modernos React (18+/19) -- hooks, context, composicao, memoizacao, lazy loading e Server Components. -layer: wiki --- # React Patterns @@ -23,7 +22,7 @@ mcp__notebooklm__notebook_query({ }) ``` -> **Regra #48:** Projectos React devem ser desenvolvidos no **container dev** (`server:"dev"`, path `/root/Dev/`). Sincroniza via Syncthing. +> **Regra #48:** Projectos React são desenvolvidos **localmente no desktop** em `/media/ealmeida/Dados/Dev/` (Bash local, sem SSH — CT 102 extinto em 20-04-2026). ## Quando Usar @@ -178,4 +177,27 @@ components/ ui/ # Componentes base (Button, Input, Card) features/ # Componentes feature-specific layouts/ # Layout components - providers/ # Context \ No newline at end of file + providers/ # Context providers + +hooks/ + useAuth.ts + useLocalStorage.ts + useDebounce.ts +``` + +## Referencias + +- `references/composition-patterns.md` - Compound components, providers, dependency injection (Vercel Engineering) +- `references/custom-hooks.md` - useDebounce, useLocalStorage, useFetch com codigo completo + +--- + +## 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/dev-tools/skills/skill-creator/SKILL.md b/dev-tools/skills/skill-creator/SKILL.md index dfc2dda..737c6e8 100644 --- a/dev-tools/skills/skill-creator/SKILL.md +++ b/dev-tools/skills/skill-creator/SKILL.md @@ -1,7 +1,6 @@ --- name: skill-creator description: Criar, melhorar e empacotar skills para o sistema de plugins Descomplicar. Usar quando o utilizador pede para criar uma nova skill, actualizar uma skill existente, ou quando é necessário estruturar conhecimento especializado em formato skill. Inclui padrões Anthropic oficiais (progressive disclosure, graus de liberdade) adaptados ao ecossistema Descomplicar com PT-PT estrito. -layer: wiki --- # Skill Creator @@ -137,4 +136,65 @@ Calibrar o nível de especificidade ao risco da tarefa: - [ ] Scripts testados (se incluídos) - [ ] Sem ficheiros auxiliares (README.md, CHANGELOG.md, etc.) -**Padrões Descompl \ No newline at end of file +**Padrões Descomplicar:** +- [ ] Assinatura Descomplicar® no código (quando aplicável) +- [ ] MCPs relevantes referenciados +- [ ] Monetário em EUR sem casas decimais desnecessárias + +--- + +### Passo 6: Empacotar + +**Script de packaging Anthropic** (quando disponível): +```bash +python scripts/package_skill.py +# ou com output directory: +python scripts/package_skill.py ./dist +``` + +O script valida frontmatter, naming conventions, estrutura de directórios, e gera ficheiro `.skill` (zip com extensão .skill). + +Se não estiver disponível, verificar manualmente com o checklist do Passo 5. + +--- + +## Anti-Padrões a Evitar + +**Má skill (demasiado vaga):** +```yaml +description: Ajuda com PHP. +``` + +**Má skill (conteúdo duplicado em references e SKILL.md):** +Documentar a mesma informação em dois locais — viola o princípio progressive disclosure. + +**Má skill (ficheiros auxiliares):** +Criar README.md, CHANGELOG.md, INSTALLATION_GUIDE.md — não devem existir numa skill. + +**Boa skill:** +```yaml +description: > + Desenvolvimento PHP moderno com Laravel e Symfony — autenticação JWT/OAuth, + service classes, refactorização legacy. Usar quando: (1) criar APIs RESTful, + (2) implementar autenticação, (3) desenvolver service classes, (4) refactorizar + código PHP existente. +``` + +--- + +## Exemplos Concretos: Bom vs Mau + +Ver `references/anthropic-patterns.md` para exemplos detalhados de progressive disclosure. +Ver `references/descomplicar-standards.md` para exemplos de skills Descomplicar bem estruturadas. + +--- + +## 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/dev-tools/skills/skill-creator/references/descomplicar-standards.md b/dev-tools/skills/skill-creator/references/descomplicar-standards.md index 3a0d9d9..69fdddd 100644 --- a/dev-tools/skills/skill-creator/references/descomplicar-standards.md +++ b/dev-tools/skills/skill-creator/references/descomplicar-standards.md @@ -35,7 +35,7 @@ description: > name: nome-da-skill description: > Descrição da skill. Usar quando [contexto]. -allowed-tools: Read, Write, Edit, Bash, mcp__mem_search_memories +allowed-tools: Read, Write, Edit, Bash, mcp__mem0__search_memories --- ``` @@ -120,10 +120,10 @@ Para skills que aprendem com execuções anteriores: ## Memória Pesquisar experiência anterior antes de começar: -`mcp__mem_search_memories "[keywords relevantes]"` +`mcp__mem0__search_memories "[keywords relevantes]"` Guardar aprendizagens ao concluir: -`mcp__mem_save_memory { text: "[domínio/skill] ..." }` +`mcp__mem0__save_memory { content: "...", tags: ["domínio", "skill"] }` ``` --- @@ -213,7 +213,7 @@ O Anthropic define apenas `name` e `description` como obrigatórios. O sistema D name: nome-da-skill description: > Descrição completa com triggers. -allowed-tools: Read, Write, Edit, Bash, mcp__mem_search_memories, mcp__notebooklm__notebook_query +allowed-tools: Read, Write, Edit, Bash, mcp__mem0__search_memories, mcp__notebooklm__notebook_query --- ``` @@ -292,7 +292,7 @@ description: > ## Protocolo obrigatório -1. Pesquisar memória: `mcp__mem_search_memories "[keywords]"` +1. Pesquisar memória: `mcp__mem0__search_memories "[keywords]"` 2. Consultar NotebookLM: ver tabela em references/notebooklm-context.md 3. Implementar com padrões Laravel: ver references/laravel-patterns.md diff --git a/dev-tools/skills/webapp-testing/SKILL.md b/dev-tools/skills/webapp-testing/SKILL.md index 703e2f5..e2e707d 100644 --- a/dev-tools/skills/webapp-testing/SKILL.md +++ b/dev-tools/skills/webapp-testing/SKILL.md @@ -1,7 +1,6 @@ --- name: webapp-testing description: Testes e automacao de aplicacoes web locais com Playwright — verificacao de frontend, debug de UI, screenshots, logs de consola e gestao de ciclo de vida de servidores. -layer: wiki --- # Web Application Testing @@ -114,4 +113,46 @@ with sync_playwright() as p: | MCP | Uso com webapp-testing | |-----|----------------------| -| `chrome-devtools` | Performance traces, network inspection \ No newline at end of file +| `chrome-devtools` | Performance traces, network inspection, DOM/CSS debugging — usar via skill /chrome | +| `claude-in-chrome` | Testes em sites autenticados com sessao activa — usar via skill /chrome | +| `lighthouse` | Auditorias completas de performance, SEO, a11y — complementa testes Playwright | +| `puppeteer` | Alternativa headless para automacao simples sem Playwright | + +### Workflow tipico Descomplicar + +1. **Desenvolvimento local**: Playwright (esta skill) para testes funcionais headless +2. **Debug visual**: /chrome (DevTools MCP) para inspeccao DOM/CSS/network em tempo real +3. **Performance**: /chrome (DevTools MCP traces) + MCP lighthouse para auditorias +4. **CI/CD**: Scripts Playwright commitados no repositorio, executados em pipeline Gitea Actions + +### Executar no servidor dev (regra #48) + +Para testes que requerem Node.js/Python: +```bash +# Via SSH MCP para o servidor dev +cd /media/ealmeida/Dados/Dev/projecto && python test_automation.py # Bash local no desktop +``` + +### Instalacao Playwright (se necessario) + +```bash +pip install playwright +playwright install chromium +``` + +No desktop, Playwright está disponível nos projectos em `/media/ealmeida/Dados/Dev`. + +--- +**Versao**: 1.0.0 | **Autor**: 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ós cada erro corrigido.* diff --git a/dev-tools/skills/xlsx/SKILL.md b/dev-tools/skills/xlsx/SKILL.md index 6ac8898..bf41f6d 100644 --- a/dev-tools/skills/xlsx/SKILL.md +++ b/dev-tools/skills/xlsx/SKILL.md @@ -1,7 +1,6 @@ --- name: xlsx description: Criacao, edicao e analise de ficheiros Excel (.xlsx, .xlsm, .csv, .tsv) — formulas, formatacao, modelos financeiros e integracao com facturacao Moloni. -layer: wiki --- # Excel / XLSX Specialist @@ -131,4 +130,257 @@ df.describe() # Estatisticas df.to_excel('output.xlsx', index=False) ``` -# \ No newline at end of file +## Workflows Excel + +## CRITICO: Usar formulas, NAO valores hardcoded + +**Usar SEMPRE formulas Excel em vez de calcular valores em Python e hardcoda-los.** Isto garante que a folha permanece dinamica e actualizavel. + +### ERRADO - Hardcoding de valores calculados +```python +# Mau: calcular em Python e hardcodar resultado +total = df['Vendas'].sum() +sheet['B10'] = total # Hardcoda 5000 + +# Mau: calcular taxa de crescimento em Python +growth = (df.iloc[-1]['Receita'] - df.iloc[0]['Receita']) / df.iloc[0]['Receita'] +sheet['C5'] = growth # Hardcoda 0.15 + +# Mau: calculo Python para media +avg = sum(values) / len(values) +sheet['D20'] = avg # Hardcoda 42.5 +``` + +### CORRECTO - Usar formulas Excel +```python +# Bom: deixar Excel calcular a soma +sheet['B10'] = '=SUM(B2:B9)' + +# Bom: taxa de crescimento como formula Excel +sheet['C5'] = '=(C4-C2)/C2' + +# Bom: media usando funcao Excel +sheet['D20'] = '=AVERAGE(D2:D19)' +``` + +Isto aplica-se a TODOS os calculos - totais, percentagens, racios, diferencas, etc. A folha deve poder recalcular quando os dados de origem mudam. + +## Workflow comum +1. **Escolher ferramenta**: pandas para dados, openpyxl para formulas/formatacao +2. **Criar/Carregar**: Criar novo workbook ou carregar ficheiro existente +3. **Modificar**: Adicionar/editar dados, formulas e formatacao +4. **Guardar**: Escrever para ficheiro +5. **Recalcular formulas (OBRIGATORIO SE USAR FORMULAS)**: Usar o script scripts/recalc.py + ```bash + python scripts/recalc.py output.xlsx + ``` +6. **Verificar e corrigir erros**: + - O script retorna JSON com detalhes de erros + - Se `status` for `errors_found`, verificar `error_summary` para tipos e localizacoes + - Corrigir os erros identificados e recalcular novamente + - Erros comuns a corrigir: + - `#REF!`: Referencias de celula invalidas + - `#DIV/0!`: Divisao por zero + - `#VALUE!`: Tipo de dados errado na formula + - `#NAME?`: Nome de formula nao reconhecido + +### Criar novos ficheiros Excel + +```python +# Usando openpyxl para formulas e formatacao +from openpyxl import Workbook +from openpyxl.styles import Font, PatternFill, Alignment + +wb = Workbook() +sheet = wb.active + +# Adicionar dados +sheet['A1'] = 'Descricao' +sheet['B1'] = 'Valor' +sheet.append(['Linha', 'de', 'dados']) + +# Adicionar formula +sheet['B2'] = '=SUM(A1:A10)' + +# Formatacao +sheet['A1'].font = Font(bold=True, color='FF0000') +sheet['A1'].fill = PatternFill('solid', start_color='FFFF00') +sheet['A1'].alignment = Alignment(horizontal='center') + +# Largura da coluna +sheet.column_dimensions['A'].width = 20 + +wb.save('output.xlsx') +``` + +### Editar ficheiros Excel existentes + +```python +# Usando openpyxl para preservar formulas e formatacao +from openpyxl import load_workbook + +# Carregar ficheiro existente +wb = load_workbook('existente.xlsx') +sheet = wb.active # ou wb['NomeFolha'] para folha especifica + +# Trabalhar com multiplas folhas +for sheet_name in wb.sheetnames: + sheet = wb[sheet_name] + print(f"Folha: {sheet_name}") + +# Modificar celulas +sheet['A1'] = 'Novo Valor' +sheet.insert_rows(2) # Inserir linha na posicao 2 +sheet.delete_cols(3) # Eliminar coluna 3 + +# Adicionar nova folha +new_sheet = wb.create_sheet('NovaFolha') +new_sheet['A1'] = 'Dados' + +wb.save('modificado.xlsx') +``` + +## Recalcular formulas + +Ficheiros Excel criados ou modificados com openpyxl contem formulas como strings mas nao valores calculados. Usar o script `scripts/recalc.py` para recalcular formulas: + +```bash +python scripts/recalc.py [timeout_segundos] +``` + +Exemplo: +```bash +python scripts/recalc.py output.xlsx 30 +``` + +O script: +- Configura automaticamente a macro LibreOffice na primeira execucao +- Recalcula todas as formulas em todas as folhas +- Analisa TODAS as celulas a procura de erros Excel (#REF!, #DIV/0!, etc.) +- Retorna JSON com localizacoes e contagens detalhadas de erros +- Funciona em Linux e macOS + +## Checklist de verificacao de formulas + +Verificacoes rapidas para garantir que as formulas funcionam correctamente: + +### Verificacao essencial +- [ ] **Testar 2-3 referencias exemplo**: Verificar que obtem valores correctos antes de construir modelo completo +- [ ] **Mapeamento de colunas**: Confirmar que colunas Excel correspondem (ex.: coluna 64 = BL, nao BK) +- [ ] **Offset de linhas**: Lembrar que linhas Excel sao 1-indexed (DataFrame linha 5 = Excel linha 6) + +### Armadilhas comuns +- [ ] **Tratamento de NaN**: Verificar valores nulos com `pd.notna()` +- [ ] **Colunas distantes**: Dados FY frequentemente em colunas 50+ +- [ ] **Multiplas correspondencias**: Pesquisar todas as ocorrencias, nao apenas a primeira +- [ ] **Divisao por zero**: Verificar denominadores antes de usar `/` em formulas (#DIV/0!) +- [ ] **Referencias erradas**: Verificar que todas as referencias apontam para celulas pretendidas (#REF!) +- [ ] **Referencias entre folhas**: Usar formato correcto (Folha1!A1) para ligar folhas + +### Estrategia de teste de formulas +- [ ] **Comecar pequeno**: Testar formulas em 2-3 celulas antes de aplicar amplamente +- [ ] **Verificar dependencias**: Confirmar que todas as celulas referenciadas existem +- [ ] **Testar edge cases**: Incluir zero, negativos e valores muito grandes + +### Interpretar output do scripts/recalc.py +O script retorna JSON com detalhes de erros: +```json +{ + "status": "success", + "total_errors": 0, + "total_formulas": 42, + "error_summary": { + "#REF!": { + "count": 2, + "locations": ["Folha1!B5", "Folha1!C10"] + } + } +} +``` + +## Boas praticas + +### Seleccao de biblioteca +- **pandas**: Melhor para analise de dados, operacoes em massa e exportacao simples +- **openpyxl**: Melhor para formatacao complexa, formulas e funcionalidades especificas do Excel + +### Trabalhar com openpyxl +- Indices de celula sao 1-based (row=1, column=1 refere-se a celula A1) +- Usar `data_only=True` para ler valores calculados: `load_workbook('ficheiro.xlsx', data_only=True)` +- **Atencao**: Se aberto com `data_only=True` e guardado, as formulas sao substituidas por valores e perdidas permanentemente +- Para ficheiros grandes: Usar `read_only=True` para leitura ou `write_only=True` para escrita +- Formulas sao preservadas mas nao avaliadas — usar scripts/recalc.py para actualizar valores + +### Trabalhar com pandas +- Especificar tipos de dados para evitar problemas de inferencia: `pd.read_excel('ficheiro.xlsx', dtype={'id': str})` +- Para ficheiros grandes, ler colunas especificas: `pd.read_excel('ficheiro.xlsx', usecols=['A', 'C', 'E'])` +- Tratar datas correctamente: `pd.read_excel('ficheiro.xlsx', parse_dates=['coluna_data'])` + +## Estilo de codigo +**IMPORTANTE**: Ao gerar codigo Python para operacoes Excel: +- Escrever codigo Python minimo e conciso sem comentarios desnecessarios +- Evitar nomes de variaveis verbosos e operacoes redundantes +- Evitar print statements desnecessarios + +**Para os ficheiros Excel em si**: +- Adicionar comentarios em celulas com formulas complexas ou pressupostos importantes +- Documentar fontes de dados para valores hardcoded +- Incluir notas para calculos-chave e seccoes do modelo + +--- + +## Integracao Descomplicar + +### Acesso a ficheiros via MCP filesystem +```python +# Ler ficheiros do sistema local +mcp__filesystem__read_file(path="/media/ealmeida/Dados/...") + +# Listar ficheiros para encontrar spreadsheets +mcp__filesystem__list_directory(path="/media/ealmeida/Dados/GDrive/Cloud/Descomplicar/") +``` + +### Integracao com Moloni (facturacao) +Para exportar dados de facturacao Moloni para Excel: +```python +# Obter facturas do Moloni +mcp__moloni__moloni_documents_invoices_getall(company_id=..., year=2026) + +# Obter produtos +mcp__moloni__moloni_products_products_getall(company_id=..., category_id=...) + +# Obter clientes +mcp__moloni__moloni_entities_customers_getall(company_id=...) +``` + +### Integracao com Desk CRM +Para exportar dados do CRM para Excel: +```python +# Relatorio de clientes +mcp__desk-crm-v3__get_customers(limit=100) + +# Relatorio de facturas +mcp__desk-crm-v3__invoice_analytics(period="this_year") + +# Relatorio de despesas +mcp__desk-crm-v3__expense_analytics(period="this_year") +``` + +### Tabela de precos Descomplicar +O ficheiro de referencia de precos esta em: +`/media/ealmeida/Dados/GDrive/Cloud/Descomplicar/Servicos/tabela-geral.csv` + +--- +**Versao**: 1.0.0 | **Autor**: 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ós cada erro corrigido.* diff --git a/dev-tools/skills/youtube-extract/SKILL.md b/dev-tools/skills/youtube-extract/SKILL.md index c345666..9fa5ee2 100644 --- a/dev-tools/skills/youtube-extract/SKILL.md +++ b/dev-tools/skills/youtube-extract/SKILL.md @@ -5,7 +5,6 @@ description: "Extrai transcrições e metadados de vídeos, playlists e canais Y version: "1.0.0" created: 2026-04-04 tools: [Bash] -layer: wiki --- # Skill: /youtube-extract diff --git a/gestao/.claude-plugin/plugin.json b/gestao/.claude-plugin/plugin.json index 460e5d1..4408cee 100644 --- a/gestao/.claude-plugin/plugin.json +++ b/gestao/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "gestao", "description": "Project management, time tracking, daily checkups, worklogs, reflections, knowledge management, archiving and compliance auditing. Backed by NotebookLM notebooks.", - "version": "1.4.0", + "version": "1.7.0", "author": { "name": "Descomplicar - Crescimento Digital", "url": "https://descomplicar.pt" @@ -13,6 +13,9 @@ "projectos", "tempo", "worklog", + "qw", + "recapitulacao", + "memoria", "produtividade", "conhecimento", "compliance", diff --git a/gestao/agents/analytics-insights-agent.md b/gestao/agents/analytics-insights-agent.md index 39e4d1c..1af057f 100644 --- a/gestao/agents/analytics-insights-agent.md +++ b/gestao/agents/analytics-insights-agent.md @@ -7,6 +7,8 @@ model: sonnet tools: Read, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 - google-analytics @@ -45,7 +47,6 @@ escalates_to: created: "2025-01-13" updated: "2026-02-04" author: "Descomplicar®" -layer: wiki --- # Analytics Insights Agent Descomplicar @@ -156,6 +157,76 @@ mcp__notebooklm__notebook_query notebook_id:"76647e0f-3ae2-4c00-a0a8-f457aebf565 - **pexels** - Pesquisa imagens stock de alta qualidade - **tavily** - AI-powered search API - web search optimizado para LLMs - **** - Knowledge base AI -- **mem0** - Memória longo prazo +- **mem0** - Mem0 (Tier 2, `mcp__mem0__*`) + IJFW (Tier 1, automático via hooks) - **elevenlabs** - Text-to-speech, voice cloning, audio transcription -- **vimeo** - Video management - uploa \ No newline at end of file +- **vimeo** - Video management - upload, metadata, transcripts, analytics +- **replicate** - AI models - imagem, vídeo, áudio, LLMs + +### All Available (32 total) +moloni, context7, gitea, n8n, cwp, filesystem, ssh-unified, imap, outline-api, gsc, lighthouse, mcp-time, puppeteer, mcp-mermaid, mcp-echarts, powerpoint, penpot, magic, design-systems + +**Discovery:** Use ToolSearch to find specific tools. +**Example:** `ToolSearch("ssh upload")` finds SSH upload tools. +## Your Available Skills + +### Primary Skills (Your Domain) +✓ **/lead-approach** - Abordagem estratégica de leads - análise, estratégia e primeiro contacto. Usar q + - Invoke: `/lead-approach` + +✓ **/marketing-strategy** - Estratégia de marketing digital integrada - análise mercado, posicionamento, mix + - Invoke: `/marketing-strategy` + +✓ **/ads** - Gestão de campanhas de publicidade paga (PPC) - Google Ads, Meta Ads, LinkedIn A + - Invoke: `/ads` + +### Recommended for marketing +- **/social-media** - Gestão e estratégia de redes sociais - Instagram, LinkedIn, +- **/content-marketing-pt** - Criação de conteúdo marketing em Português Europeu. Tom de v +- **/seo-content-optimization** - Optimização SEO técnico e conteúdo - meta tags, structured d +- **/youtube** - Extrair transcrições e metadados do YouTube + Estratégia cre +- **/research** - Pesquisa profunda e análise competitiva - SWOT, Porter's Fiv + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /orcamento, /saas, /remotion-video, /video, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /crm-admin, /db-design, /elementor, /mcp-dev, /nextjs, /php-dev, /react-patterns, /woocommerce, /wp-dev, /backup-strategies, /security-audit, /server-health, /wp-performance, /wp-update, /second-brain-repo, /doc-sync, /product, /skill-creator, /sop-creator, /calendar-manager, /delegate, /interview, /time, /today, /seo-audit, /seo-report, /archive, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. +## Colaboração + +- **Reports to**: Master Orchestrator +- **Colabora com**: Performance Optimization Engineer, Finance Manager, Marketing Planning Expert, Database Design Specialist +- **Escalar para**: Master Orchestrator (decisões estratégicas), Database Design Specialist (queries complexas) +## Your Team & Responsibilities + +You are part of **4 SDKs** (TaskForce teams): + +### TaskForce Ad Manager + +**Purpose:** NULL + +### TaskForce Claude Agents + +**Purpose:** NULL + +**Your responsibilities in this TaskForce:** +### TaskForce Deep Research + +**Purpose:** NULL + +### TaskForce Product Manager + +**Purpose:** NULL + +**Collaboration:** +- Work with other agents in your TaskForce teams +- Share knowledge and context across team members +- Leverage team-specific skills and MCPs +- Contribute to team goals and deliverables + diff --git a/gestao/agents/compliance-auditor.md b/gestao/agents/compliance-auditor.md index 819bc8d..feeb5b3 100644 --- a/gestao/agents/compliance-auditor.md +++ b/gestao/agents/compliance-auditor.md @@ -7,13 +7,14 @@ model: sonnet tools: Read, Write, Edit, Bash, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 - filesystem recommended_mcps: - gitea - mem0 - - wikijs skills: - _core - today @@ -38,7 +39,6 @@ compliance: created: '2026-02-14' updated: '2026-02-14' author: Descomplicar® -layer: wiki --- # Compliance Auditor - Auditor de Conformidade Descomplicar® @@ -199,4 +199,332 @@ Verifica cada regra: - Hook é executável? 2. ANALISAR últimos commits - - Security a \ No newline at end of file + - Security audit mencionado? + - Vulnerabilidades documentadas? + - Formato correcto? + +3. EXECUTAR audit agora + - pnpm/npm/yarn audit + - composer audit (PHP) + - safety check (Python) + +4. VALIDAR resultados + - 0 vulnerabilidades? ✅ + - Vulnerabilidades documentadas? ⚠️ + - Vulnerabilidades não documentadas? ❌ + +5. REPORTAR + - Status compliance + - Acções necessárias + - Timeline de correção +``` + +### Workflow 3: Auditoria de Skills/Agents + +```bash +1. LER componente completo + - Frontmatter + - Description + - System prompt (agents) + - Conteúdo SKILL.md + +2. VERIFICAR referenciação + - Secção "Referências e Documentação"? + - Links file:// para PROCs? + - Descrição clara de cada PROC? + +3. DETECTAR procedimentos embeddados + - Checklists longas (>10 itens)? + - Troubleshooting extenso? + - Standards detalhados? + - Workflows complexos? + +4. AVALIAR qualidade + - Description triggering adequado? + - Frontmatter completo? + - Estrutura de pastas correcta? + +5. GERAR score 0-10 + - 8-10: Excelente + - 5-7: Atenção (melhorias sugeridas) + - 0-4: Crítico (refactoring necessário) +``` + +--- + +## 📊 Formato de Relatório + +### Relatório de Auditoria de Projeto + +```markdown +# Relatório Compliance: [Nome Projeto] + +**Data:** YYYY-MM-DD HH:MM +**Auditor:** compliance-auditor v1.0 +**Score Global:** X/100 + +--- + +## Resumo Executivo + +[Parágrafo resumo: projeto está compliant ou não, principais issues] + +--- + +## Conformidade por Categoria + +### 1. Estrutura de Projeto (X/20) +- [✅/❌] .desk-project existe +- [✅/❌] README.txt presente +- [✅/❌] Git configurado +- [✅/❌] Pastas seguem convenção + +### 2. Security & Code Quality (X/30) +- [✅/❌] Security audit executado (Regra #47) +- [✅/❌] Git hooks instalados +- [✅/❌] 0 vulnerabilidades critical/high +- [✅/❌] Linting passes +- [✅/❌] Sem API keys hardcoded + +### 3. Processos (X/25) +- [✅/❌] Commits seguem template +- [✅/❌] SPEC.md quando aplicável +- [✅/❌] Phase gates validados +- [✅/❌] CI/CD configurado + +### 4. Documentação (X/15) +- [✅/❌] README completo +- [✅/❌] Comments adequados +- [✅/❌] Changelog mantido + +### 5. Regras CLAUDE.md (X/10) +- [✅/❌] Sem violações detectadas +- [✅/❌] Backup configurado (Regra #31) +- [✅/❌] Refs cruzadas (Regra #26) + +--- + +## Issues Detectadas + +### 🔴 Críticas (Bloqueiam Deploy) +1. **[Categoria] - [Issue]** + - Descrição + - Impacto + - Regra violada: #X + - Acção: [passo a passo] + +### ⚠️ Avisos (Recomendado Corrigir) +1. **[Categoria] - [Issue]** + - Descrição + - Sugestão + +### ℹ️ Informativas +1. **[Categoria] - [Observação]** + - Descrição + - Opcional + +--- + +## Recomendações Prioritárias + +1. [Acção imediata P1] +2. [Acção importante P2] +3. [Melhoria opcional P3] + +--- + +## Timeline de Correção + +- **Críticas:** <24h +- **Avisos:** <1 semana +- **Informativas:** Próximo sprint + +--- + +## Próxima Auditoria + +Data sugerida: [+1 mês ou após correções] +``` + +--- + +## 🎯 Critérios de Compliance + +### Score 90-100 (Excelente) +- ✅ Todas as regras seguidas +- ✅ 0 issues críticas +- ✅ Documentação completa +- ✅ Security audit passing +- ✅ Processos validados + +### Score 70-89 (Bom) +- ✅ Maioria regras seguidas +- ⚠️ Issues menores apenas +- ✅ Documentação presente +- ✅ Security OK + +### Score 50-69 (Aceitável) +- ⚠️ Algumas violações +- ⚠️ Issues médias +- ⚠️ Documentação incompleta +- ⚠️ Security com avisos + +### Score 30-49 (Crítico) +- ❌ Violações importantes +- ❌ Issues críticas +- ❌ Pouca documentação +- ❌ Security vulnerável + +### Score 0-29 (Bloqueado) +- ❌ Múltiplas violações críticas +- ❌ Sem documentação +- ❌ Security comprometido +- 🚫 **Deploy BLOQUEADO** + +--- + +## 📚 Referências e Documentação + +**SEMPRE consultar antes de auditar:** + +### Regras Core +- **[CLAUDE.md global](file:///home/ealmeida/.claude/CLAUDE.md)** - 47 Regras obrigatórias +- **[CLAUDE.md Hub](file:///media/ealmeida/Dados/Hub/CLAUDE.md)** - Regras específicas Hub + +### Procedimentos +- **[INDEX Procedimentos](file:///media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/INDEX.md)** - 36 procedimentos, 8 departamentos +- **[D7-Tecnologia](file:///media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D7-Tecnologia/INDEX.md)** - 28 procedimentos técnicos + +### Standards e Templates +- **[Security Audit Analysis](file:///home/ealmeida/.claude/projects/-media-ealmeida-Dados-Hub/memory/security-incident-analysis.md)** - Regra #47 detalhada +- **[Commit Template](file:///home/ealmeida/.git/templates/COMMIT_MSG_SECURITY_TEMPLATE.txt)** - Template commits security + +### Skills de Validação +- **/validate-component** - Validar skills/agents +- **/index-update** - Validar INDEX.md +- **/proc-creator** - Criar procedimentos + +--- + +## 🔄 Integração com Sistema + +### Triggers Automáticos +- **Pre-commit hook:** Validar antes de commit +- **Pre-deploy:** Auditar antes de deploy +- **Weekly:** Auditoria semanal de projectos activos +- **Monthly:** Auditoria completa de compliance + +### Integrações +- **Desk CRM:** Reportar issues como tarefas +- **Git:** Bloquear commits não-compliant +- **CI/CD:** Quality gate em pipeline +- **/today:** Secção compliance diária + +--- + +## 🚨 Anti-Patterns + +**NUNCA:** +- ❌ Aprovar projeto com score <50 +- ❌ Ignorar violações de regras críticas (Regra #47, #38, #23) +- ❌ Auditar sem ler as regras actualizadas +- ❌ Sugerir correções que violam outras regras +- ❌ Dar score sem justificação detalhada + +**SEMPRE:** +- ✅ Ler CLAUDE.md antes de auditar +- ✅ Verificar regras actualizadas (changelog) +- ✅ Consultar procedimentos relevantes +- ✅ Gerar relatório estruturado +- ✅ Propor acções correctivas concretas +- ✅ Validar que correções não quebram outras regras + +--- + +## 📈 Métricas de Sucesso + +### Indicadores Primários +1. **Taxa de Compliance:** Meta >85% projectos com score >70 +2. **Violações Críticas:** Meta 0 violações de Regras #1-#10 +3. **Security Compliance:** Meta 100% projectos com Regra #47 +4. **Tempo Correção:** Meta <7 dias para issues críticas + +### Indicadores Secundários +5. **Auditorias Regulares:** Meta mensal por projecto +6. **Issues Recorrentes:** Meta <10% reincidência +7. **Documentação:** Meta 100% projectos com README.txt +8. **Processos:** Meta 90% commits seguem template + +--- + +## 🤝 Colaboração + +### Reports to +- Emanuel Almeida (decisões de compliance) +- Master Orchestrator (coordenação multi-agente) + +### Colabora com +- **security-compliance-specialist:** Security audits +- **dev-helper:** Code quality +- **worklog-agent:** Tracking de compliance +- **spec-writer:** Validação de specs + +### Delega para +- **validate-component:** Validação skills/agents específica +- **security-auditor:** Análise vulnerabilidades (quando criado) + +--- + +## 📞 Comandos Rápidos + +```bash +# Auditar projeto actual +compliance-auditor audit . + +# Auditar projeto específico +compliance-auditor audit /path/to/project + +# Auditar skill/agent +compliance-auditor validate-component /path/to/skill + +# Verificar Regra #47 +compliance-auditor check-security-audit . + +# Auditoria de procedimento +compliance-auditor validate-proc /path/to/PROC-*.md + +# Relatório compliance geral +compliance-auditor report-all +``` + +--- + +## 🔧 MCPs Disponíveis + +### Primary MCPs +- **desk-crm-v3:** Reportar issues, criar tarefas +- **filesystem:** Ler ficheiros, estrutura projecto + +### Recommended +- **gitea:** Verificar repos, commits, branches +- **mem0:** Guardar padrões de compliance +- **/knowledge (router Hub QR/PROC):** Consultar standards curados + +--- + +## 🎓 Skills Disponíveis + +### Primary Skills +- **/validate-component:** Validar skills/agents para compliance +- **/today:** Incluir secção compliance no checkup diário +- **/worklog:** Registar auditorias e issues + +### Core Skills +- **/_core:** Sacred Rules e Excellence Standards +- **/knowledge:** Consultar KB de standards +- **/desk:** Contexto projeto via .desk-project + +--- + +*Agent v1.0.0 | 2026-02-14 | Plugin gestao | Descomplicar®* +*Created em resposta ao incidente de segurança - Sistema de 5 Camadas de Defesa* diff --git a/gestao/agents/hr-specialist.md b/gestao/agents/hr-specialist.md new file mode 100644 index 0000000..ec29c0c --- /dev/null +++ b/gestao/agents/hr-specialist.md @@ -0,0 +1,213 @@ +--- +name: hr-specialist +description: > + Especialista de RH D4 para onboarding, contratos, férias e gestão de colaboradores. + Executor autónomo baseado nos PROCs D4-RH-001/002/004. Usar para: onboarding novo + colaborador, gestão contratos, férias, offboarding, checklist RH, integração equipa. +role: Especialista de RH D4 +domain: HR, Operations +model: sonnet +tools: Read, Glob, Grep, ToolSearch + +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. +primary_mcps: + - desk-crm-v3 + - google-workspace +recommended_mcps: + - mem0 + - mcp-time + +primary_skills: + - onboarding + - calendar-manager + - today +recommended_skills: + - worklog + - crm + +desk_project: 65 +tags: + - agent + - rh + - d4 + - onboarding + - contratos + - ferias +version: "1.0" +status: active +quality_score: 75 +compliance: + sacred_rules: true + data_sources: true + +reports_to: Emanuel Almeida +collaborates_with: + - support-specialist + - project-manager +escalates_to: + - Emanuel Almeida (decisões contratuais, rescisões, conflitos) + - D3 Contabilidade (processamento salarial, IRS) + +created: "2026-04-08" +updated: "2026-04-08" +author: "Descomplicar®" +--- + +# HR Specialist Descomplicar + +Especialista de RH D4 responsável pela gestão do ciclo de vida de colaboradores: onboarding, contratos, férias e offboarding. Opera de forma autónoma seguindo os PROCs D4-RH. + +## System Prompt + +Você é o especialista de RH D4 da Descomplicar®. A sua missão é garantir que todo o ciclo de vida de colaboradores é gerido com rigor, cumprindo obrigações legais portuguesas e mantendo a Descomplicar® como um bom sítio para trabalhar. + +### Regras Obrigatórias (checklist antes de agir) + +- [ ] **Lei Laboral PT**: Verificar sempre se acção cumpre Código do Trabalho português +- [ ] **Confidencialidade**: Dados de colaboradores são sensíveis — nunca partilhar fora do contexto +- [ ] **Documentação**: Todo contrato, férias ou decisão relevante fica registada no Desk CRM +- [ ] **Onboarding completo**: Checklist 100% antes de marcar colaborador como operacional +- [ ] **Escalar decisões**: Rescisões, alterações contratuais e conflitos sobem a Emanuel +- [ ] **Calendário**: Férias e ausências sempre sincronizadas no Google Calendar da equipa + +### Prioridades de Actuação + +1. **Onboarding novo colaborador** — Checklist completa, contas criadas, contrato assinado +2. **Gestão férias** — Aprovação, registo, cobertura, sincronização calendário +3. **Renovações/alterações contratuais** — Rigor legal, arquivo completo +4. **Offboarding** — Entrega equipamento, revogação acessos, contas desactivadas +5. **Conflitos/queixas** — Escalar a Emanuel imediatamente + +### Output Format Padrão + +```markdown +## Acção RH — [Tipo] — [Colaborador] + +### Estado +- **Tipo:** [Onboarding/Ferias/Contrato/Offboarding] +- **Colaborador:** [Nome] +- **Data:** [DD-MM-YYYY] +- **PROC aplicado:** [D4-RH-00X] + +### Acção Tomada +[Descrição] + +### Checklist +- [x] Item 1 +- [ ] Item 2 — pendente (responsável + prazo) + +### Próximo Passo +[Acção seguinte + responsável + prazo] +``` + +## Responsabilidades + +- Onboarding completo de novos colaboradores (contas, docs, equipamento, integração) +- Gestão de contratos: criação, renovação, alterações, arquivo digital +- Aprovação e registo de férias com verificação de cobertura +- Offboarding limpo: entrega equipamento + revogação acessos + documentação +- Acompanhamento do período experimental +- Registo de avaliações de desempenho e feedback +- Ligação com D3 Contabilidade para processamento salarial + +## Workflows + +### Workflow 1: Onboarding Novo Colaborador + +``` +1. Invocar skill /onboarding → recolher dados do novo colaborador +2. Ler PROC-D4-RH-001-Onboarding-Colaborador.md (checklist completa) +3. Criar tarefa no Desk CRM projecto #65 com checklist derivada do PROC +4. Criar contas necessárias (Google Workspace, Desk CRM, Gitea, etc) +5. Gerar contrato via PROC-D4-RH-002-Contratos.md +6. Preparar equipamento (laptop, acessos físicos) +7. Dia 1: reunião de boas-vindas + tour ferramentas +8. Dia 7: check-in + ajustes +9. Dia 30: revisão período experimental +10. Só marcar tarefa como done após checklist 100% +``` + +### Workflow 2: Gestão de Férias + +``` +1. Pedido de férias chega via Desk/email +2. Ler PROC-D4-RH-004-Ferias.md para regras +3. Verificar saldo dias disponíveis +4. Verificar cobertura durante ausência (quem substitui) +5. Validar conflitos com outros colaboradores ausentes +6. Aprovar ou escalar a Emanuel se há risco operacional +7. Registar no Desk CRM + Google Calendar da equipa +8. Enviar confirmação ao colaborador +``` + +### Workflow 3: Alteração Contratual + +``` +1. Ler PROC-D4-RH-002-Contratos.md +2. Preparar minuta com alterações claramente marcadas +3. Escalar a Emanuel para validação ANTES de enviar ao colaborador +4. Após aprovação: enviar ao colaborador para revisão +5. Assinar (ambas as partes) e arquivar no GDrive confidencial +6. Registar alteração no Desk CRM como tarefa concluída +7. Notificar D3 Contabilidade se há impacto salarial +``` + +### Workflow 4: Offboarding + +``` +1. Recolher data última + motivo (amigável/demissão/rescisão) +2. Preparar carta de cessação via PROC-D4-RH-002 +3. Calcular valores finais: férias não gozadas, subsídios, 13º/14º +4. Escalar a D3 Contabilidade para processamento +5. Revogar acessos: Google Workspace, Desk, Gitea, servidores, VPN +6. Recolher equipamento (laptop, telemóvel, chaves) +7. Registar saída no Desk CRM + arquivo histórico +8. Exit interview (se aplicável) e registar aprendizagens +``` + +## Knowledge Sources + +### Referências PROCs (Consultar SEMPRE) + +``` +Read: /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D4-RH/PROC-D4-RH-001-Onboarding-Colaborador.md +Read: /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D4-RH/PROC-D4-RH-002-Contratos.md +Read: /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D4-RH/PROC-D4-RH-004-Ferias.md +``` + +### Desk CRM + +``` +mcp__desk-crm-v3__create_task({ project_id: 65, title, checklist }) +mcp__desk-crm-v3__add_task_checklist_item({ task_id, description }) +mcp__desk-crm-v3__update_task({ task_id, status }) +``` + +### Google Workspace + +``` +mcp__google-workspace__gmail_send_email (boas-vindas, confirmações) +mcp__google-workspace__create_calendar_event (férias, onboarding) +mcp__google-workspace__drive_create_folder (pasta pessoal do colaborador) +``` + +## Métricas de Sucesso + +| Métrica | Meta | +|---------|------| +| Tempo médio onboarding completo | <7 dias úteis | +| Checklist onboarding cumprida | 100% | +| Férias sem conflitos de cobertura | 100% | +| Contratos arquivados no próprio dia | >95% | +| Período experimental falhado | <10% | + +## Colaboração + +- **Reporta a**: Emanuel Almeida +- **Colabora com**: support-specialist (onboarding de suporte), project-manager (alocação a projectos) +- **Escalar para**: Emanuel (rescisões, contratuais, conflitos), D3 Contabilidade (salarial) + +--- + +**Tarefa Desk:** #65 · G4.3 (Plano Resolução Gaps Q2 2026) · criado 08-04-2026 diff --git a/gestao/agents/project-manager.md b/gestao/agents/project-manager.md index de2ef8a..8f11ae2 100644 --- a/gestao/agents/project-manager.md +++ b/gestao/agents/project-manager.md @@ -10,6 +10,8 @@ model: sonnet tools: Read, Write, Edit, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 - google-workspace @@ -38,7 +40,6 @@ compliance: created: '2025-01-13' updated: '2026-02-04' author: Descomplicar® -layer: wiki --- # Project Manager Descomplicar @@ -124,16 +125,64 @@ Gestor de projectos responsavel por planeamento, coordenacao de equipas multidis ### Recommended for business - **moloni** - Facturação - **imap** - Email IMAP -- **mem0** - Memória longo prazo +- **mem0** - Mem0 (Tier 2, `mcp__mem0__*`) + IJFW (Tier 1, automático via hooks) - **** - Knowledge base AI - **outline-api** - Outline documentation ### All Available (32 total) -context7, gitea, n8n, cwp, filesystem, ssh-unified, google-analytics, youtube-research, youtube-uploader, wikijs, gsc, lighthouse, mcp-time, puppeteer, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, magic, vimeo, design-systems, replicate +context7, gitea, n8n, cwp, filesystem, ssh-unified, google-analytics, youtube-research, youtube-uploader, gsc, lighthouse, mcp-time, puppeteer, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, magic, vimeo, design-systems, replicate **Discovery:** Use ToolSearch to find specific tools. **Example:** `ToolSearch("ssh upload")` finds SSH upload tools. ## Your Available Skills ### Primary Skills (Your Domain) -✓ **/crm-ops** - Operacoes CRM seguras com verificacoes obri \ No newline at end of file +✓ **/crm-ops** - Operacoes CRM seguras com verificacoes obrigatorias de duplicados e confirmacoes + - Invoke: `/crm-ops` + +✓ **/orcamento** - Criação sistemática de orçamentos Descomplicar®. Usar quando o utilizador pedir + - Invoke: `/orcamento` + +✓ **/billing-check** - Comparação de horas trabalhadas (Desk CRM) vs horas facturadas (Moloni). Identif + - Invoke: `/billing-check` + +✓ **/lead-approach** - Abordagem estratégica de leads - análise, estratégia e primeiro contacto. Usar q + - Invoke: `/lead-approach` + +### Recommended for business +- **/ecommerce** - Estratégia e arquitectura e-commerce - funil conversão, plat +- **/saas** - Arquitectura e desenvolvimento SaaS - multi-tenant, billing, +- **/product** - Gestão de produto e planeamento features - discovery, RICE p +- **/time** - Time tracking integrado com Desk CRM. Inicia e para timers e + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/content-marketing-pt, /remotion-video, /seo-content-optimization, /social-media, /video, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /crm-admin, /db-design, /elementor, /mcp-dev, /nextjs, /php-dev, /react-patterns, /woocommerce, /wp-dev, /backup-strategies, /security-audit, /server-health, /wp-performance, /wp-update, /second-brain-repo, /ads, /doc-sync, /marketing-strategy, /skill-creator, /sop-creator, /calendar-manager, /delegate, /interview, /today, /research, /youtube, /seo-audit, /seo-report, /archive, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. +## Your Team & Responsibilities + +You are part of **2 SDKs** (TaskForce teams): + +### TaskForce Claude Agents + +**Purpose:** NULL + +**Your responsibilities in this TaskForce:** +### TaskForce Product Manager + +**Purpose:** NULL + +**Collaboration:** +- Work with other agents in your TaskForce teams +- Share knowledge and context across team members +- Leverage team-specific skills and MCPs +- Contribute to team goals and deliverables + diff --git a/gestao/agents/reflect-agent.md b/gestao/agents/reflect-agent.md index d766741..223ba3a 100644 --- a/gestao/agents/reflect-agent.md +++ b/gestao/agents/reflect-agent.md @@ -8,6 +8,8 @@ model: haiku tools: Read, Write, Edit, Glob, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 - mem0 @@ -36,7 +38,6 @@ compliance: created: '2025-01-13' updated: '2026-02-04' author: Descomplicar® -layer: wiki --- # Reflect Agent Descomplicar @@ -103,12 +104,11 @@ Corre silenciosamente sem interromper fluxo principal. ✓ **mem0** (system) - Memória longo prazo - - Usage: `mcp__mem_*` + - Usage: `mcp__mem0__*` ### Recommended for knowledge - **notebooklm** - KB primaria (Gemini 2.5 RAG) - `mcp__notebooklm__notebook_query` - **** - Knowledge base AI (fallback) -- **wikijs** - Wiki documentation - **design-systems** - Knowledge base W3C standards, WCAG, design system best pract - **outline-api** - Outline documentation - **context7** - Context documentation @@ -141,4 +141,8 @@ moloni, gitea, n8n, cwp, filesystem, ssh-unified, google-analytics, google-works - **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det ### All Available (53 total) -/billing-check, /crm-ops, /ecommerce, /lead-approach, /orcamento, /saas, /content-marketing-pt, /remotion-video, /seo-content-optimization, /social-media, /video, /ui-ux-pro-max-repo, /bran \ No newline at end of file +/billing-check, /crm-ops, /ecommerce, /lead-approach, /orcamento, /saas, /content-marketing-pt, /remotion-video, /seo-content-optimization, /social-media, /video, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /crm-admin, /db-design, /elementor, /mcp-dev, /nextjs, /php-dev, /react-patterns, /woocommerce, /wp-dev, /backup-strategies, /security-audit, /server-health, /wp-performance, /wp-update, /second-brain-repo, /ads, /doc-sync, /marketing-strategy, /product, /skill-creator, /calendar-manager, /delegate, /interview, /time, /today, /youtube, /seo-audit, /seo-report, /archive + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. + diff --git a/gestao/agents/software-project-planner.md b/gestao/agents/software-project-planner.md index e4f3bf2..b579e28 100644 --- a/gestao/agents/software-project-planner.md +++ b/gestao/agents/software-project-planner.md @@ -9,6 +9,8 @@ model: sonnet tools: Read, Write, Edit, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 - google-workspace @@ -36,7 +38,6 @@ compliance: created: '2025-01-13' updated: '2026-02-04' author: Descomplicar® -layer: wiki --- # Software Project Planner Descomplicar @@ -139,5 +140,64 @@ Planeador de projectos de software responsavel por transformar requisitos em roa - **filesystem** - Ficheiros locais - **magic** - AI-powered UI component generation (tipo v0.dev) - **** - Knowledge base AI -- **mem0** - Memória longo prazo -- **cwp** - CentOS Web Pane \ No newline at end of file +- **mem0** - Mem0 (Tier 2, `mcp__mem0__*`) + IJFW (Tier 1, automático via hooks) +- **cwp** - CentOS Web Panel +- **puppeteer** - Browser automation + +### All Available (32 total) +moloni, google-analytics, google-workspace, imap, outline-api, youtube-research, youtube-uploader, gsc, lighthouse, mcp-time, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, vimeo, design-systems, replicate + +**Discovery:** Use ToolSearch to find specific tools. +**Example:** `ToolSearch("ssh upload")` finds SSH upload tools. +## Your Available Skills + +### Primary Skills (Your Domain) +✓ **/wp-dev** - Desenvolvimento WordPress especializado - plugins, temas, WooCommerce. Usar para + - Invoke: `/wp-dev` + +✓ **/php-dev** - Desenvolvimento PHP fullstack - Laravel, Symfony, APIs RESTful, arquitectura bac + - Invoke: `/php-dev` + +✓ **/db-design** - Design de bases de dados - schema, optimização queries, MySQL/PostgreSQL, arquit + - Invoke: `/db-design` + +✓ **/mcp-dev** - Desenvolvimento de servidores MCP - criar, configurar, testar e documentar MCPs + - Invoke: `/mcp-dev` + +### Recommended for dev +- **/react-patterns** - Padrões React modernos - Hooks, Server Components, State Man +- **/nextjs** - Desenvolvimento Next.js moderno com App Router, Server Compo +- **/elementor** - Desenvolvimento avançado com Elementor Pro e Crocoblock - wi +- **/woocommerce** - Desenvolvimento e optimização de lojas WooCommerce - checkou +- **/crm-admin** - Administração e desenvolvimento Perfex CRM - gestão dados, m +- **/video** - Criar vídeos programáticos com Remotion e React. Gera intros +- **/doc-sync** - Sincronização automática de documentação Stack/Vault. Garant +- **/delegate** - Delegar tarefas dev para outros chats Claude com workflow co +- **/time** - Time tracking integrado com Desk CRM. Inicia e para timers e + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /lead-approach, /orcamento, /saas, /content-marketing-pt, /remotion-video, /seo-content-optimization, /social-media, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /backup-strategies, /security-audit, /server-health, /wp-performance, /wp-update, /second-brain-repo, /ads, /marketing-strategy, /product, /skill-creator, /sop-creator, /calendar-manager, /interview, /today, /research, /youtube, /seo-audit, /seo-report, /archive, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. +## Your Team & Responsibilities + +You are part of **1 TaskForce** (TaskForce teams): + +### TaskForce Product Manager + +**Purpose:** NULL + +**Collaboration:** +- Work with other agents in your TaskForce teams +- Share knowledge and context across team members +- Leverage team-specific skills and MCPs +- Contribute to team goals and deliverables + diff --git a/gestao/agents/time-management-agent.md b/gestao/agents/time-management-agent.md index 037974e..fcd789f 100644 --- a/gestao/agents/time-management-agent.md +++ b/gestao/agents/time-management-agent.md @@ -7,6 +7,8 @@ model: sonnet tools: Read, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - mcp-time - desk-crm-v3 @@ -47,7 +49,6 @@ escalates_to: created: "2026-02-04" updated: "2026-02-04" author: "Descomplicar®" -layer: wiki --- # Time Management Agent Descomplicar diff --git a/gestao/agents/wiki-knowledge-agent.md b/gestao/agents/wiki-knowledge-agent.md index 9369ac5..7b1deeb 100644 --- a/gestao/agents/wiki-knowledge-agent.md +++ b/gestao/agents/wiki-knowledge-agent.md @@ -1,12 +1,14 @@ --- name: wiki-knowledge-agent -description: "USAR PROATIVAMENTE para gestão de conhecimento, documentação Wiki.js, pesquisa de artigos, criação de páginas KB. Especialista em organização de conhecimento técnico e documentação." +description: "SUSPENSO (LLM Wiki suspensa 09-07-2026 — regra 53): usar /knowledge (router Hub QR/PROC) + mcp__mem0__search_memories. Manter apenas para eventual reactivação da Wiki.js." role: Especialista em gestão de conhecimento e Wiki.js domain: Knowledge, Documentation model: sonnet tools: Read, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - wikijs - desk-crm-v3 @@ -48,7 +50,6 @@ escalates_to: created: "2026-02-04" updated: "2026-02-04" author: "Descomplicar®" -layer: wiki --- # Wiki Knowledge Agent Descomplicar @@ -213,4 +214,101 @@ tags: [tag1, tag2, tag3] editor: markdown --- -# [Títu \ No newline at end of file +# [Título] + +## Propósito +[Objectivo desta documentação] + +## Contexto +[Background e motivação] + +## Conteúdo Principal +[Informação detalhada] + +## Exemplos +[Casos de uso práticos] + +## Referências +- Link 1 +- Link 2 + +## Actualizado +Última actualização: YYYY-MM-DD +Por: [Autor] +``` + +## Regras de Operação + +### SEMPRE + +- Pesquisar antes de criar (evitar duplicação) +- Usar Markdown consistente +- Adicionar tags relevantes +- Manter histórico de versões +- Cross-reference documentos relacionados + +### NUNCA + +- Criar duplicados sem verificar +- Apagar sem backup +- Ignorar versionamento +- Usar HTML quando Markdown é suficiente +- Deixar páginas órfãs (sem links) + +## Casos de Uso + +### 1. Documentar Nova Skill + +``` +User: "Documenta a skill /orcamento no Wiki" +Agent: +1. Search duplicados +2. Create página em /Technical/Skills/orcamento +3. Estrutura: propósito, uso, exemplos +4. Tags: skill, business, orçamento +5. Link para Desk task #1415 +``` + +### 2. Pesquisar Solução + +``` +User: "Como resolver erro SSL no CWP?" +Agent: +1. Search Wiki.js: "SSL CWP erro" +2. Encontra: /Solutions/SSL-CWP-Renovation +3. Apresenta: passos de resolução +4. Sugere: artigos relacionados +``` + +### 3. Actualizar Procedimento + +``` +User: "Actualiza SOP de backup com novo script" +Agent: +1. Get página /Procedures/Backup-Strategy +2. Read conteúdo actual +3. Merge novo script +4. Update metadata (data, versão) +5. Preserva histórico anterior +``` + +## Métricas de Qualidade + +- Cobertura de documentação: > 80% +- Páginas órfãs: < 5% +- Duplicados: 0 +- Actualização regular: Mensal +- Cross-references: > 3 por página + +## Limitações + +- Depende de conectividade Wiki.js +- Versionamento limitado ao sistema +- Sync manual quando automação falha + +--- + +**Versão:** 1.0.0 +**Última actualização:** 2026-02-04 +**Desk CRM:** Projecto #65, Milestone 274 +**Wiki.js:** https://wiki.descomplicar.pt diff --git a/gestao/skills/aiktop-tasks/SKILL.md b/gestao/skills/aiktop-tasks/SKILL.md index 3d3dfc6..adbc60b 100644 --- a/gestao/skills/aiktop-tasks/SKILL.md +++ b/gestao/skills/aiktop-tasks/SKILL.md @@ -2,7 +2,6 @@ name: aiktop-tasks description: Executa tarefas agendadas para AikTop no Desk CRM. Detecta tarefas vencidas com tag "aiktop" atribuídas ao staff 25, executa a instrução da descrição, fecha a tarefa e comenta o resultado. Usar quando "aiktop tasks", "executar tarefas aiktop", "task queue ai". disable-model-invocation: true -layer: wiki --- # /aiktop-tasks v1.0 @@ -98,7 +97,7 @@ SE invocado directamente: | **Prioridade** | Conforme urgência | **Exemplos de descrições válidas:** -- "Verificar logs `/root/Dev/imap-cleaner/cron.log` e `/root/Dev/auto-expense/auto-expense.log`. Reportar se houve erros ou se o pipeline correu bem." +- "Verificar logs `/media/ealmeida/Dados/Dev/imap-cleaner/cron.log` e `/media/ealmeida/Dados/Dev/auto-expense/auto-expense.log` (execução local via systemd user timers). Reportar se houve erros ou se o pipeline correu bem." - "Correr /imap-triage e reportar faturas detectadas." - "Verificar tarefas overdue no Desk CRM e sugerir as 3 mais urgentes." @@ -107,7 +106,7 @@ SE invocado directamente: ## Wrapper Script (dev server) ```bash -# /root/Dev/aiktop-tasks/run-aiktop-tasks.sh +# /media/ealmeida/Dados/Dev/aiktop-tasks/run-aiktop-tasks.sh #!/bin/bash export IS_SANDBOX=1 LOG="$HOME/Dev/aiktop-tasks/aiktop-tasks.log" @@ -118,7 +117,7 @@ echo "$(date) [END] exit=$EXIT_CODE" >> "$LOG" exit $EXIT_CODE ``` -**Cron:** `*/15 * * * * /root/Dev/aiktop-tasks/run-aiktop-tasks.sh` +**Agendamento:** systemd user timer local (15 em 15 min) a correr `/media/ealmeida/Dados/Dev/aiktop-tasks/run-aiktop-tasks.sh` --- diff --git a/gestao/skills/archive/SKILL.md b/gestao/skills/archive/SKILL.md index a508cb6..da898e7 100644 --- a/gestao/skills/archive/SKILL.md +++ b/gestao/skills/archive/SKILL.md @@ -2,7 +2,6 @@ name: archive description: Arquivamento inteligente de projectos e notas concluídos. Move itens finalizados para arquivo com organização adequada. Usar quando "archive", "arquivar", "mover para arquivo", "cleanup", "organizar concluídos". disable-model-invocation: true -layer: wiki --- # /archive - Arquivamento Automatico @@ -233,4 +232,4 @@ Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de exe {"date":"","issue":"","fix":"","source":"user|auto"} ``` -*Adicionar no \ No newline at end of file +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/calendar-manager/SKILL.md b/gestao/skills/calendar-manager/SKILL.md index 4650d60..17fd92b 100644 --- a/gestao/skills/calendar-manager/SKILL.md +++ b/gestao/skills/calendar-manager/SKILL.md @@ -1,7 +1,6 @@ --- name: calendar-manager description: Gestao do Google Calendar e automacao de agendamento. Cria eventos, gere disponibilidade e sincroniza calendarios. -layer: wiki --- # Calendar Manager @@ -158,4 +157,33 @@ mcp__google_workspace__get_events({ // Criar evento mcp__google_workspace__create_event({ user_google_email: 'emanuelalmeidaa@gmail.com', - calendar_id: 'emanuelalmeidaa@gmail.com' \ No newline at end of file + calendar_id: 'emanuelalmeidaa@gmail.com', + summary: 'Titulo', + start_time: '2026-02-04T14:30:00', + end_time: '2026-02-04T15:30:00', + timezone: 'Europe/Lisbon' +}); +``` + +## Quando NAO Usar + +- Para tarefas fora do dominio de calendario/agendamento +- Quando outra skill mais especifica esta disponivel +- Para operacoes que requerem aprovacao manual obrigatoria + +## References + +- **Workflows detalhados:** `references/workflows-detalhados.md` +- **MCP tools e constantes:** `references/mcp-tools-referencia.md` + +--- + +## 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/gestao/skills/cleanup-downloads/SKILL.md b/gestao/skills/cleanup-downloads/SKILL.md index 1b70efb..42f8c25 100644 --- a/gestao/skills/cleanup-downloads/SKILL.md +++ b/gestao/skills/cleanup-downloads/SKILL.md @@ -1,7 +1,6 @@ --- name: cleanup-downloads description: Limpeza e triagem da pasta Transferências (Downloads). Verifica cada ficheiro individualmente, apaga descartáveis, classifica o restante por categoria. Usar quando "transferências", "downloads", "limpar downloads", "cleanup", "limpeza pasta". -layer: wiki --- # Cleanup Downloads diff --git a/gestao/skills/clip-agent/SKILL.md b/gestao/skills/clip-agent/SKILL.md index 08402ac..8e9e583 100644 --- a/gestao/skills/clip-agent/SKILL.md +++ b/gestao/skills/clip-agent/SKILL.md @@ -2,7 +2,6 @@ name: clip-agent description: Gerir agente Paperclip individual — estado, config, AGENTS.md, histórico runs, issues. Aceita nome como argumento. Usar quando "clip agent", "agente clip", "ver agente", "estado do CTO". context: fork -layer: wiki --- # /clip-agent — Gerir Agente Paperclip @@ -163,4 +162,234 @@ AND principal_id = '{{AGENT_ID}}'; Para adicionar `tasks:assign` (necessário para delegação): ```sql -INSERT INTO principal_permissi \ No newline at end of file +INSERT INTO principal_permission_grants (company_id, principal_type, principal_id, permission_key, granted_by_user_id) +VALUES ('ebe10308-efd7-453f-86ab-13e6fe84004f', 'agent', '{{AGENT_ID}}', 'tasks:assign', 'local-board'); +``` + +**ATENÇÃO:** Este grant só funciona se o agente tiver membership activa (ver secção acima). + +### Passo 7: Verificar adapter_config (CRITICO) + +Agentes sem `dangerouslySkipPermissions: true` ficam bloqueados — todos os comandos bash sao rejeitados. + +```sql +SELECT name, + adapter_config->>'dangerouslySkipPermissions' as skip_perms, + adapter_config->>'cwd' as cwd, + adapter_config->>'model' as model, + adapter_config->>'timeoutSec' as timeout, + adapter_config->>'maxTurnsPerRun' as max_turns +FROM agents WHERE id = '{{AGENT_ID}}'; +``` + +**Alertar se:** +- `skip_perms` != `true` → agente vai ficar bloqueado em todos os comandos bash +- `cwd` = NULL → agente corre em directório temporário sem acesso ao Hub +- `cwd` = `/media/ealmeida/Dados/Hub` → **CRITICO: CWD aponta para Hub raiz (6.4GB), Claude Code indexa tudo, causa token burn massivo** — usar `/media/ealmeida/Dados/Hub/04-Stack/02.06-Clip` +- `model` = NULL → usa modelo default (pode não ser o desejado) + +**Corrigir agente (CWD correcto para Clip):** +```sql +UPDATE agents SET adapter_config = adapter_config || '{"dangerouslySkipPermissions": true, "cwd": "/media/ealmeida/Dados/Hub/04-Stack/02.06-Clip", "model": "gemini-2.5-flash", "graceSec": 20, "timeoutSec": 900}'::jsonb +WHERE id = '{{AGENT_ID}}'; +``` + +**Política de adapters por nível (actualizado 07-04-2026):** `opencode_local` foi **completamente removido** (modelos indisponíveis). Distribuição actual: +- **C-Level (5)** — CEO, CDO, CFO, CGO, CTO: `claude_local` com `claude-sonnet-4-6` (decisão estratégica, exige raciocínio premium) +- **Especialistas/Directores (59)**: `gemini_local` com `gemini-2.5-flash` (execução, custo baixo) +- **Analyst on-demand (1)** — Reality Checker: `process` com `claude-sonnet-4-6` (sem heartbeat) + +**Configurar `claude_local` (template canónico — C-Level):** +```json +{ + "cwd": "/media/ealmeida/Dados/Hub/04-Stack/02.06-Clip", + "model": "claude-sonnet-4-6", + "command": "claude", + "dangerouslySkipPermissions": true, + "timeoutSec": 900, + "graceSec": 20, + "instructionsFilePath": "" +} +``` +Modelos válidos: `claude-opus-4-6`, `claude-sonnet-4-6`, `claude-haiku-4-6`, `claude-sonnet-4-5-20250929`, `claude-haiku-4-5-20251001`. + +**Configurar `gemini_local` (template canónico):** +```json +{ + "cwd": "/media/ealmeida/Dados/Hub/04-Stack/02.06-Clip", + "yolo": true, + "model": "gemini-2.5-flash", + "command": "/home/ealmeida/.paperclip/gemini-wrapper.sh", + "sandbox": false, + "newSession": true, + "instructionsFilePath": "" +} +``` + +Campos: +- `command` — wrapper Gemini CLI local em `/home/ealmeida/.paperclip/gemini-wrapper.sh` +- `model` — `gemini-2.5-flash` (default) ou `gemini-2.5-pro` (CEO/tarefas pesadas) +- `yolo: true` — auto-aprovar comandos (equivalente a `dangerouslySkipPermissions` do claude_local) +- `sandbox: false` — sem sandbox de filesystem +- `newSession: true` — sessão nova por run +- `cwd` — `/media/ealmeida/Dados/Hub/04-Stack/02.06-Clip` (NUNCA usar Hub raiz) +- `instructionsFilePath` — path absoluto para AGENTS.md + +**Migrar agente para gemini_local (SQL):** +```sql +UPDATE agents +SET adapter_type = 'gemini_local', + adapter_config = jsonb_build_object( + 'cwd', COALESCE(adapter_config->>'cwd', '/media/ealmeida/Dados/Hub/04-Stack/02.06-Clip'), + 'yolo', true, + 'model', 'gemini-2.5-flash', + 'command', '/home/ealmeida/.paperclip/gemini-wrapper.sh', + 'sandbox', false, + 'newSession', true, + 'instructionsFilePath', adapter_config->>'instructionsFilePath' + ), + updated_at = NOW() +WHERE id = '{{AGENT_ID}}'; +``` + +**Nota sobre API REST vs SQL:** O endpoint `PATCH /api/agents/:id` valida `adapterType` contra enum desactualizada que não inclui `gemini_local` (devolve HTTP 400). Workaround actual: SQL directo na BD Paperclip (`postgres://paperclip:paperclip@localhost:54329/paperclip`). Quando a validação for actualizada, preferir sempre API com header `User-Agent: node` (Cloudflare bloqueia `curl/*`). + +**Agentes analyst/read-only (ex: Reality Checker):** usar `adapter_type: process` com `adapter_config.model: "claude-sonnet-4-6"` e `instructionsBundleMode: "external"`. Estes agentes são invocados manualmente (heartbeat desactivado por design), não consomem budget em modo autónomo. + +### Passo 7b: Sessão e tokens (INC-12) + +`agent_task_sessions` não tem campo de tokens — o consumo está em `heartbeat_runs.usage_json`. Verificar erros "Prompt is too long" e consumo nas últimas runs. + +```sql +-- Erros "Prompt is too long" recentes +SELECT hr.status, LEFT(hr.error, 80) as erro, hr.started_at::timestamp(0) +FROM heartbeat_runs hr +WHERE hr.agent_id = '{{AGENT_ID}}' +AND hr.status IN ('failed','error') +AND hr.error ILIKE '%too long%' +AND hr.started_at > NOW() - INTERVAL '48 hours' +ORDER BY hr.started_at DESC LIMIT 5; + +-- Consumo token nas últimas runs bem-sucedidas +SELECT ROUND(COALESCE((hr.usage_json->>'cache_read_input_tokens')::numeric,0)/1000,0) as cache_read_k, + ROUND(COALESCE((hr.usage_json->>'input_tokens')::numeric,0)/1000,0) as input_k, + ROUND(COALESCE((hr.usage_json->>'output_tokens')::numeric,0)/1000,0) as output_k, + hr.started_at::timestamp(0) +FROM heartbeat_runs hr +WHERE hr.agent_id = '{{AGENT_ID}}' +AND hr.status = 'succeeded' +AND hr.usage_json IS NOT NULL +ORDER BY hr.started_at DESC LIMIT 3; +``` + +Se existirem erros "too long" → forçar rotação: +```sql +DELETE FROM agent_task_sessions +WHERE agent_id = '{{AGENT_ID}}' +AND company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'; +``` + +### Passo 7c: Validar instructionsFilePath (INC-07) + +O Paperclip **não usa `cwd` para resolver `instructionsFilePath`** — o path é sempre relativo ao processo do servidor, não ao CWD do agente. Deve ser **sempre absoluto**. + +```sql +SELECT adapter_config->>'instructionsFilePath' as instructions_path +FROM agents WHERE id = '{{AGENT_ID}}'; +``` + +**Alertar se:** +- `instructionsFilePath` não começa com `/` → **CRITICO: path relativo, AGENTS.md não carrega** +- Path absoluto mas ficheiro não existe → CRITICO + +**Corrigir path relativo:** +```sql +UPDATE agents +SET adapter_config = jsonb_set( + adapter_config, + '{instructionsFilePath}', + to_jsonb('/media/ealmeida/Dados/Hub/04-Stack/02.06-Clip/' || (adapter_config->>'instructionsFilePath')) + ) +WHERE id = '{{AGENT_ID}}' +AND adapter_config->>'instructionsFilePath' NOT LIKE '/%'; +``` + +## Wakeup manual de agente + +Para forcar um agente a acordar imediatamente (ex: testar, desbloquear): + +```sql +DO $$ +DECLARE wakeup_id uuid; +BEGIN + INSERT INTO agent_wakeup_requests (company_id, agent_id, source, trigger_detail, reason, payload, status, requested_at, created_at, updated_at) + VALUES ('ebe10308-efd7-453f-86ab-13e6fe84004f', '{{AGENT_ID}}', 'on_demand', 'manual', '{{RAZAO}}', '{}'::jsonb, 'queued', NOW(), NOW(), NOW()) + RETURNING id INTO wakeup_id; + + INSERT INTO heartbeat_runs (company_id, agent_id, invocation_source, trigger_detail, status, wakeup_request_id, context_snapshot, created_at, updated_at) + VALUES ('ebe10308-efd7-453f-86ab-13e6fe84004f', '{{AGENT_ID}}', 'on_demand', 'manual', 'queued', wakeup_id, '{"wakeReason": "manual_wakeup"}'::jsonb, NOW(), NOW()); +END $$; +``` + +**Nota:** UPDATE directo em issues nao dispara wakeOnDemand — e preciso o par wakeup_request + heartbeat_run. + +## Criar agente novo via SQL (checklist OBRIGATÓRIA) + +Ao criar agente directamente na BD (fora do fluxo OpenClaw), executar TODOS os passos: + +1. `INSERT INTO agents (...)` — dados do agente, incluindo: + - `adapter_type: 'process'` + - `adapter_config`: campos obrigatórios: `model`, `instructionsFilePath` (absoluto!), `instructionsRootPath`, `instructionsEntryFile: "AGENTS.md"`, `instructionsBundleMode: "external"` + - Para agentes autónomos: adicionar `dangerouslySkipPermissions: true`, `cwd`, `timeoutSec` +2. `INSERT INTO company_memberships (...)` — **sem isto, permissões não funcionam** (agentes criados via SQL não recebem membership automática) +3. `INSERT INTO principal_permission_grants (...)` — se precisa de `tasks:assign` (C-Level, Directores) +4. Criar `AGENTS.md` no path absoluto definido em `instructionsFilePath` +5. Verificar: `instructionsFilePath` não começa com `/` → AGENTS.md não carrega (ver Passo 7c) + +## Acções disponíveis + +Se o utilizador pedir: +- **Editar AGENTS.md:** Abrir ficheiro com Read/Edit +- **Alterar config:** `UPDATE agents SET runtime_config = '...' WHERE id = '{{AGENT_ID}}';` +- **Pausar:** `UPDATE agents SET status = 'paused', pause_reason = '...', paused_at = NOW() WHERE id = '{{AGENT_ID}}';` +- **Despausar:** `UPDATE agents SET status = 'idle', pause_reason = NULL, paused_at = NULL WHERE id = '{{AGENT_ID}}';` +- **Wakeup:** Usar bloco SQL acima (wakeup_request + heartbeat_run) +- **Corrigir permissoes:** Usar UPDATE adapter_config acima +- **Atribuir skill:** `curl -s -X POST http://localhost:3100/api/agents/{{AGENT_ID}}/skills/sync -H "Content-Type: application/json" -H "Authorization: Bearer $PAPERCLIP_API_KEY" -d '{"desiredSkills": ["key1", "key2"]}'` +- **Ver skills empresa:** query company_skills acima + +### Safety gate: verificacao de dependencias (OBRIGATORIO antes de DELETE/remocao) + +Antes de apagar ou remover qualquer agente, executar SEMPRE: +```sql +SELECT 'budget_policies' as tabela, COUNT(*) as refs FROM budget_policies WHERE scope_type='agent' AND scope_id='{{AGENT_ID}}' +UNION ALL +SELECT 'budget_incidents', COUNT(*) FROM budget_incidents WHERE scope_type='agent' AND scope_id='{{AGENT_ID}}' +UNION ALL +SELECT 'heartbeat_runs', COUNT(*) FROM heartbeat_runs WHERE agent_id='{{AGENT_ID}}' +UNION ALL +SELECT 'issues', COUNT(*) FROM issues WHERE assignee_agent_id='{{AGENT_ID}}' +UNION ALL +SELECT 'issue_comments', COUNT(*) FROM issue_comments WHERE author_agent_id='{{AGENT_ID}}'; +``` + +- Se refs > 0 em budget_policies ou budget_incidents: apagar essas refs PRIMEIRO, senao o dashboard fica com "Agent not found" +- Se refs > 0 em issues: reatribuir ou fechar as issues antes +- Mostrar resultado ao utilizador e confirmar antes de prosseguir +- NUNCA apagar agente sem verificar e limpar dependencias + +Confirmar sempre antes de executar accoes destrutivas. + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"2026-04-07","issue":"API skill attribution sem Authorization header — chamada rejeitada com 401","fix":"Adicionar -H 'Authorization: Bearer $PAPERCLIP_API_KEY' ao curl POST /api/agents/:id/skills/sync","source":"auto"} +{"date":"2026-04-07","issue":"Agente criado via SQL sem membership ficou com Board access required em todos os endpoints","fix":"Sempre inserir em company_memberships após INSERT em agents. Agentes via SQL não recebem membership automática — só via fluxo OpenClaw/hiring","source":"auto"} +{"date":"2026-04-07","issue":"instructionsBundleMode em falta na adapter_config — AGENTS.md não carregava","fix":"Incluir instructionsBundleMode: 'external' + instructionsRootPath + instructionsEntryFile: 'AGENTS.md' na adapter_config","source":"auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/clip-health/SKILL.md b/gestao/skills/clip-health/SKILL.md index d84c4dc..729d9b9 100644 --- a/gestao/skills/clip-health/SKILL.md +++ b/gestao/skills/clip-health/SKILL.md @@ -2,7 +2,6 @@ name: clip-health description: Diagnóstico rápido Paperclip — serviço, BD, heartbeats falhados, budget, disco. Usar quando "clip health", "saúde clip", "diagnóstico paperclip", "clip problemas". context: fork -layer: wiki --- # /clip-health — Diagnostico Paperclip @@ -183,4 +182,217 @@ Invocar tool MCP: `mcp__paperclip__diag_agents_missing_heartbeat` ### Check 13: Routine triggers com kind errado ou next_run_at NULL -Invocar tool MCP: `mcp__pap \ No newline at end of file +Invocar tool MCP: `mcp__paperclip__diag_routine_triggers_broken` + +- 0 = OK +- 1+ = CRITICO (routines nao vao disparar — kind deve ser 'schedule' e next_run_at populado) + +### Check 14: Issues PUBLICAR NOTICIA sem assignee + +```sql +SELECT COUNT(*) FROM issues +WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f' +AND title LIKE 'PUBLICAR NOTICIA%' +AND status = 'todo' +AND assignee_agent_id IS NULL; +``` + +- 0 = OK +- 1+ = AVISO (cron assign-copywriter.sh devia atribuir a cada 5 min — verificar crontab) + +### Check 15: Qualidade artigos publicados (ultimas 24h) + +Verificar artigos recentes no WordPress via SSH (server): + +```bash +cd /home/ealmeida/public_html && wp --allow-root post list --post_type=post --post_status=publish --category=noticias --date_query='{"after":"1 day ago"}' --fields=ID,post_title --format=csv 2>/dev/null +``` + +Para CADA artigo recente, verificar: + +**15a. Acentuacao** — procurar palavras sem acento: +```bash +cd /home/ealmeida/public_html && wp --allow-root post get POST_ID --field=post_content 2>/dev/null | sed 's/<[^>]*>//g' | grep -oP '\b\w+cao\b|\b\w+sao\b|\bnao\b|\b\w+vel\b' | head -20 +``` +Palavras terminadas em "cao", "sao" (sem til) ou "nao" indicam acentuacao em falta. + +**15b. Links HTML sem aspas:** +```bash +cd /home/ealmeida/public_html && wp --allow-root post get POST_ID --field=post_content 2>/dev/null | grep -oP 'href=[^"'\''"][^ >]+' | head -10 +``` +Se output nao vazio = links sem aspas. + +**15c. Titulo com maiusculas indevidas:** +```bash +cd /home/ealmeida/public_html && wp --allow-root post get POST_ID --field=post_title 2>/dev/null +``` +Verificar: so primeira palavra e nomes proprios devem ter maiuscula. + +- 0 problemas = OK +- 1-3 = AVISO (artigos com defeitos cosmeticos) +- 4+ = CRITICO (Copywriter nao esta a cumprir quality gates — actualizar AGENTS.md) + +### Check 16: Cron assign-copywriter activo + +```bash +crontab -l | grep assign-copywriter +``` + +- Presente = OK +- Ausente = CRITICO (issues PUBLICAR NOTICIA nunca serao atribuidas ao Copywriter) + +### Check 17: Pipeline noticias end-to-end (ultimas 24h) + +```sql +-- Routines disparadas +SELECT COUNT(*) as routines_fired FROM routine_triggers rt +JOIN routines r ON rt.routine_id = r.id +WHERE r.title LIKE 'Pesquisa diaria%noticias%' +AND rt.last_fired_at > NOW() - INTERVAL '24 hours'; + +-- Issues de pesquisa concluidas +SELECT COUNT(*) as pesquisas_done FROM issues +WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f' +AND title LIKE 'Pesquisa diaria%' +AND status = 'done' +AND created_at > NOW() - INTERVAL '24 hours'; + +-- Issues PUBLICAR NOTICIA criadas e concluidas +SELECT + COUNT(*) as total, + COUNT(*) FILTER (WHERE status = 'done') as done, + COUNT(*) FILTER (WHERE status IN ('todo','in_progress')) as pendentes +FROM issues +WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f' +AND title LIKE 'PUBLICAR NOTICIA%' +AND created_at > NOW() - INTERVAL '24 hours'; +``` + +- routines_fired >= 3 E pesquisas_done >= 1 E done >= 5 = OK +- Qualquer zero = AVISO (pipeline com falhas) +- routines_fired = 0 = CRITICO (routines nao disparam) + +### Check 18: Issues blocked sem impedimento real (INC-07) + +Invocar tool MCP: `mcp__paperclip__diag_false_blockers` + +Para cada issue blocked, verificar se o assignee está em erro: +```sql +SELECT a.name, a.status FROM agents a +WHERE a.id = (SELECT assignee_agent_id FROM issues WHERE identifier = '{{ID}}'); +``` + +- Issue `blocked` + assignee `active/idle/running` + sub-tasks activas > 0 = **FALSO BLOCKER** (deveria ser `in_progress`) +- Issue `blocked` + assignee `error/paused` = blocker legítimo +- Issue `blocked` + sem sub-tasks + sem comentário de impedimento = suspeito, alertar + +Resultado: +- 0 falsos blockers = OK +- 1+ falsos blockers = AVISO (listar e recomendar correcção para `in_progress`) + +--- + +### Check 19: Sessões com tokens excessivos (INC-12) + +Previne "Prompt is too long" e token burn massivo. Monitoriza via usage_json dos heartbeats recentes. + +Top agentes com maior consumo de tokens nas últimas 24h: + +Invocar tool MCP: `mcp__paperclip__diag_heartbeat_token_usage(hours=24)` + +Contagem de erros "Prompt is too long" activos (sinal imediato): + +Invocar tool MCP: `mcp__paperclip__diag_prompt_too_long_errors(hours=24)` + +- 0 erros = OK +- 1+ erros = CRITICO (forçar rotação de sessão) + +**Forçar rotação de sessão (apaga histórico, fresh start):** +```sql +DELETE FROM agent_task_sessions +WHERE agent_id = '{{AGENT_ID}}' +AND company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'; +``` + +--- + +### Check 20: Routines presas in_progress >4h (INC-08) + +Issues de routine que ficam `in_progress` sem actividade bloqueiam todos os futuros disparos da mesma routine (constraint `issues_open_routine_execution_uq`). A ligação issue→routine está em `routine_runs.linked_issue_id` (não existe `issues.routine_id`). + +Invocar tool MCP: `mcp__paperclip__diag_stuck_routines(hours=4)` + +- 0 = OK +- 1+ = CRITICO (routine bloqueada — cancelar a issue presa para desbloquear futuros disparos) + +**Desbloquear routine (cancelar issue presa):** +```sql +UPDATE issues SET status = 'cancelled', updated_at = NOW() +WHERE identifier = '{{IDENTIFIER}}' +AND company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'; +``` + +--- + +### Check 21: Zombie parents — issues pai com sub-tasks todas concluídas (AP-09) + +Issues pai que ficam abertas indefinidamente quando todas as sub-tasks estão `done` ou `cancelled`. Poluem o dashboard e impedem distinguir trabalho parado de trabalho já feito. + +Invocar tool MCP: `mcp__paperclip__diag_zombie_parents` + +- 0 = OK +- 1+ = AVISO (fechar manualmente ou alertar CEO para verificar e fechar) + +--- + +## Formato de output + +``` +## Clip Health — [data/hora] + +| Check | Estado | Detalhe | +|-------|--------|---------| +| Servico | OK/CRITICO | N processos activos / stopped | +| POSIX shared memory | OK/AVISO/CRITICO | /dev/shm/PostgreSQL.* presente / em falta | +| Base de dados | OK/CRITICO | Xmb, N agentes, N issues | +| Heartbeats 24h | OK/AVISO/CRITICO | N falhas | +| Budget | OK/AVISO/CRITICO | [agente] a X% | +| Disco | OK/AVISO/CRITICO | X% livre (Xgb) | +| API Health | OK/AVISO/CRITICO | status:ok / board access / timeout | +| Gateway | OK/AVISO | responde / timeout | +| Refs orfas | OK/CRITICO | N budget_policies orfas | +| Instancias | OK/CRITICO | N processos na porta 310x | +| Porta/Tunnel | OK/CRITICO | tunnel:X servidor:Y | +| Permissoes bash | OK/CRITICO | N agentes sem dangerouslySkipPermissions | +| Heartbeats config | OK/AVISO | N agentes sem heartbeat enabled | +| Routine triggers | OK/CRITICO | N triggers com kind errado ou next_run_at NULL | +| Auto-assign noticias | OK/AVISO | N issues PUBLICAR NOTICIA sem assignee | +| Qualidade artigos | OK/AVISO/CRITICO | N artigos com acentos/links/titulos errados | +| Cron assign-copywriter | OK/CRITICO | activo / ausente | +| Pipeline noticias 24h | OK/AVISO/CRITICO | N routines, N pesquisas, N publicadas | +| Falsos blockers | OK/AVISO | N issues blocked sem impedimento real | +| Tokens excessivos | OK/AVISO/CRITICO | N agentes >500K tokens cached | +| Routines presas | OK/CRITICO | N issues rotina paradas >4h | +| Zombie parents | OK/AVISO | N issues pai com todas as subs concluídas | + +**Score:** N/22 OK + +### Detalhes (se existirem alertas) +[listar heartbeats falhados, budget alto, artigos com defeitos, pipeline parado] + +### Accoes recomendadas +[listar accoes concretas para resolver alertas] +``` + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"2026-04-07","issue":"Check 1 usava systemctl que nunca existe (Paperclip corre via pnpm dev)","fix":"Substituir por ps aux | grep paperclip + check POSIX shared memory /dev/shm/PostgreSQL.*","source":"auto"} +{"date":"2026-04-07","issue":"Check 6 usava npx paperclipai doctor que não existe no projecto local","fix":"Substituir por curl localhost:3100/health — distingue: ok / board access (BD operacional) / timeout (servidor morto)","source":"auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/clip-instructions/SKILL.md b/gestao/skills/clip-instructions/SKILL.md index 598f702..49b982a 100644 --- a/gestao/skills/clip-instructions/SKILL.md +++ b/gestao/skills/clip-instructions/SKILL.md @@ -4,7 +4,6 @@ description: Editar e gerir AGENTS.md de agentes Paperclip — ver, editar, reve context: fork version: "1.0.0" created: 2026-04-07 -layer: wiki --- # /clip-instructions — Gerir AGENTS.md dos Agentes @@ -181,4 +180,5 @@ curl -s -X POST "http://localhost:3100/api/agents/{{AGENT_ID}}/config-revisions/ ## Healing Log ```jsonl -{"date":"2026-04-07","issue":"instructionsFilePath relativo — AGENTS.md não carregava \ No newline at end of file +{"date":"2026-04-07","issue":"instructionsFilePath relativo — AGENTS.md não carregava após criação via SQL","fix":"Path deve ser sempre absoluto. Verificar com query adapter_config->>'instructionsFilePath' NOT LIKE '/%'","source":"auto"} +``` diff --git a/gestao/skills/clip-issue/SKILL.md b/gestao/skills/clip-issue/SKILL.md index 21ec5f5..02d2938 100644 --- a/gestao/skills/clip-issue/SKILL.md +++ b/gestao/skills/clip-issue/SKILL.md @@ -2,7 +2,6 @@ name: clip-issue description: Criar e gerir issues Paperclip — lançar objectivos ao CEO, ver progresso, comentar. Usar quando "clip issue", "criar issue", "lançar objectivo", "ver issues clip". Issues seguem cadeia de delegação hierárquica. context: fork -layer: wiki --- # /clip-issue — Gerir Issues Paperclip @@ -145,4 +144,57 @@ Release liberta a issue de volta a `todo`. **Checkout via API:** ```bash -curl -s -X POST "http://localhost:3100/api/issues/{{ISSUE_ID}}/che \ No newline at end of file +curl -s -X POST "http://localhost:3100/api/issues/{{ISSUE_ID}}/checkout" \ + -H "Authorization: Bearer $PAPERCLIP_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"agentId": "{{AGENT_ID}}"}' +``` + +**Release via API:** +```bash +curl -s -X POST "http://localhost:3100/api/issues/{{ISSUE_ID}}/release" \ + -H "Authorization: Bearer $PAPERCLIP_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{}' +``` + +**Fallback via BD (se API falhar):** +```sql +-- Checkout manual +UPDATE issues SET status = 'in_progress', updated_at = NOW() +WHERE id = '{{ISSUE_ID}}' +AND company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f' +RETURNING identifier, title, status; + +-- Release manual +UPDATE issues SET status = 'todo', updated_at = NOW() +WHERE id = '{{ISSUE_ID}}' +AND company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f' +RETURNING identifier, title, status; +``` + +**Nota:** O par checkout/release é importante para o pipeline do Paperclip — evita que dois agentes peguem na mesma issue em simultâneo. + +## Formato de output + +Adaptar ao modo. Para lista: +``` +## Issues Clip — [data] + +| # | Titulo | Status | Prioridade | Assignee | +... + +Total: N abertas (N critical, N high, N medium, N low) +``` + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"2026-04-07","issue":"author_user_id = 'board' em comentários — não é user_id válido, comentário não aparecia no dashboard","fix":"Usar 'v1N5OccPn9DGq6iog7qW9nEvnXYFT3iO' (ID real de Emanuel no Paperclip)","source":"auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/clip-org/SKILL.md b/gestao/skills/clip-org/SKILL.md index 7078a24..d6948b2 100644 --- a/gestao/skills/clip-org/SKILL.md +++ b/gestao/skills/clip-org/SKILL.md @@ -2,7 +2,6 @@ name: clip-org description: Org chart Paperclip — hierarquia completa, reports, gaps por preencher. Usar quando "clip org", "organigrama", "hierarquia clip", "quem reporta a quem". Inclui modelo de governance e cadeias de delegação. context: fork -layer: wiki --- # /clip-org — Org Chart Paperclip diff --git a/gestao/skills/clip-routine/SKILL.md b/gestao/skills/clip-routine/SKILL.md index 88ac220..0fbcf36 100644 --- a/gestao/skills/clip-routine/SKILL.md +++ b/gestao/skills/clip-routine/SKILL.md @@ -2,7 +2,6 @@ name: clip-routine description: Gerir routines Paperclip — listar crons activos, ver execuções, criar/editar routines. Usar quando "clip routine", "routines clip", "crons paperclip", "automações clip". context: fork -layer: wiki --- # /clip-routine — Gerir Routines Paperclip @@ -166,4 +165,185 @@ ORDER BY r.title; ### Ver execucoes de uma routine ```sql -SELECT rr.status, rr.triggered \ No newline at end of file +SELECT rr.status, rr.triggered_at, rr.completed_at, LEFT(rr.error, 80) as erro +FROM routine_runs rr +JOIN routines r ON rr.routine_id = r.id +WHERE r.company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f' +AND LOWER(r.title) LIKE LOWER('%{{TITULO}}%') +ORDER BY rr.triggered_at DESC LIMIT 10; +``` + +## Modo criar routine (nova) + +### Passo 1: Obter CEO ID + +```sql +SELECT id FROM agents +WHERE name = 'CEO' AND company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'; +``` + +### Passo 2: Obter projecto + +```sql +SELECT id, name FROM projects +WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'; +``` + +### Passo 3: Criar routine (SEMPRE atribuída ao CEO) + +```sql +INSERT INTO routines (id, company_id, project_id, title, description, assignee_agent_id, priority, status, created_at, updated_at) +VALUES ( + gen_random_uuid(), + 'ebe10308-efd7-453f-86ab-13e6fe84004f', + '{{PROJECT_ID}}', + '{{TITULO}}', + 'CADEIA: CEO → {{C_LEVEL}} → {{DIRECTOR}} → {{ESPECIALISTA}}. {{DESCRICAO_TAREFA}}', + '{{CEO_ID}}', + '{{PRIORIDADE}}', + 'active', + NOW(), NOW() +) +RETURNING id, title; +``` + +### Passo 4: Criar cron trigger + +**CRITICO:** O kind DEVE ser `'schedule'` (nao `'cron'`). O scheduler do Paperclip so processa triggers com `kind = 'schedule'`. Tambem e OBRIGATORIO popular `next_run_at` — sem ele o scheduler ignora o trigger. + +```sql +-- Calcular next_run_at antes de inserir +-- Para crons diarios (ex: 0 8 * * *), usar: +-- (CURRENT_DATE + 1) AT TIME ZONE 'Europe/Lisbon' + INTERVAL '{{HORA}} hours' +-- Para crons recorrentes (ex: 0 */4 * * *), calcular proximo slot + +INSERT INTO routine_triggers (id, company_id, routine_id, kind, label, enabled, cron_expression, timezone, next_run_at, created_at, updated_at) +VALUES ( + gen_random_uuid(), + 'ebe10308-efd7-453f-86ab-13e6fe84004f', + '{{ROUTINE_ID}}', + 'schedule', + '{{LABEL}}', + true, + '{{CRON_EXPRESSION}}', + 'Europe/Lisbon', + {{NEXT_RUN_AT}}, + NOW(), NOW() +) +RETURNING id, cron_expression, next_run_at; +``` + +**Exemplos de next_run_at:** +- `0 8 * * *` → `(CURRENT_DATE + 1) AT TIME ZONE 'Europe/Lisbon' + INTERVAL '8 hours'` +- `0 */6 * * *` → `date_trunc('hour', NOW()) + INTERVAL '6 hours'` +- `0 9 * * 1` → proxima segunda-feira as 09h + +Confirmar sempre com o utilizador: título, cadeia, cron, projecto. + +### Diagnostico: routines que nao disparam + +Se routines nao disparam, verificar: + +Invocar tool MCP: `mcp__paperclip__diag_routine_triggers_broken` + +Corrigir com: +```sql +UPDATE routine_triggers SET kind = 'schedule', next_run_at = {{NEXT_RUN}}, updated_at = NOW() +WHERE id = '{{TRIGGER_ID}}'; +``` + +### Diagnostico: pipeline noticias + +Se noticias nao estao a ser publicadas, verificar esta cadeia: + +``` +1. Routine triggers → kind='schedule'? next_run_at populado? last_fired_at recente? +2. CEO heartbeat → apanha a issue da routine? delega ao CGO? +3. CGO → delega ao Intelligence Researcher? +4. Intelligence Researcher → cria issues PUBLICAR NOTICIA? (assignee fica NULL — normal) +5. Cron assign-copywriter.sh → atribui ao Copywriter a cada 5 min? +6. Copywriter → acorda com wakeOnDemand? publica no WordPress? +7. Artigo publicado → acentuacao OK? links com aspas? titulo normalizado? +``` + +Verificar ponto a ponto com: +```sql +-- Ponto 1: triggers +SELECT r.title, rt.kind, rt.next_run_at, rt.last_fired_at +FROM routine_triggers rt JOIN routines r ON rt.routine_id = r.id +WHERE r.title LIKE 'Pesquisa diaria%noticias%' ORDER BY rt.cron_expression; + +-- Ponto 4-5: issues PUBLICAR NOTICIA +SELECT i.title, i.status, a.name as assignee, i.created_at +FROM issues i LEFT JOIN agents a ON i.assignee_agent_id = a.id +WHERE i.title LIKE 'PUBLICAR NOTICIA%' AND i.created_at > NOW() - INTERVAL '24 hours' +ORDER BY i.created_at DESC; + +-- Ponto 6: Copywriter runs +SELECT hr.status, hr.started_at FROM heartbeat_runs hr +JOIN agents a ON hr.agent_id = a.id WHERE a.name = 'Copywriter' +AND hr.started_at > NOW() - INTERVAL '24 hours' ORDER BY hr.started_at DESC; + +-- Ponto 7: artigos publicados (via SSH server) +-- wp --allow-root post list --category=noticias --date_query='{"after":"1 day ago"}' --fields=ID,post_title +``` + +## Cadeias de delegação por área + +| Área | Cadeia | +|------|--------| +| Infraestrutura/WP/Backups/SSL | CEO → CTO → Dir. Infraestrutura → Especialista | +| Desenvolvimento/MCPs/N8N | CEO → CTO → Dir. Desenvolvimento/Automação → Especialista | +| Email/Tickets/Processos | CEO → COO → Dir. Suporte/Operações → Especialista | +| Financeiro/Facturação | CEO → CFO → Dir. Financeiro → Finance Manager | +| Marketing/SEO/Conteúdo/Ads | CEO → CMO → Dir. relevante → Especialista | +| Vendas/Leads/Propostas | CEO → CRO → Dir. Comercial → Especialista | +| Inteligência/Pesquisa | CEO → CGO → Dir. IA/Estratégia → Especialista | +| Analytics/Dados | CEO → CDO → Analytics Agent | + +## Formato de output + +Para modo lista (heartbeats): +``` +## Heartbeats Clip — [data] + +| Agente | Tier | Intervalo | Enabled | Último HB | OK 24h | Fail 24h | +... +``` + +Para modo lista (routines): +``` +## Routines Clip — [data] + +| Título | Cron | Assignee | Cadeia | Próximo run | Enabled | +... + +Total: 5 routines activas no Paperclip (4 atribuídas ao CEO, 1 ao COO) + 9 migradas para n8n +``` + +Para modo ver: +``` +## Routine: {{NOME}} + +**Cadeia:** {{cadeia_delegação}} +**Cron:** {{cron}} | **Enabled:** {{enabled}} +**Último trigger:** {{last_triggered_at}} + +### Últimas 10 execuções +| Status | Triggered | Completed | Erro | +... + +Taxa sucesso 24h: N/N (N%) +``` + +--- + +## 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/gestao/skills/clip-skill/SKILL.md b/gestao/skills/clip-skill/SKILL.md index 4fc0d1f..3c40651 100644 --- a/gestao/skills/clip-skill/SKILL.md +++ b/gestao/skills/clip-skill/SKILL.md @@ -2,7 +2,6 @@ name: clip-skill description: Gerir company skills no Paperclip — listar, instalar, atribuir a agentes, auditar cobertura. Usar quando "clip skill", "skills clip", "instalar skill", "atribuir skill", "skills paperclip". context: fork -layer: wiki --- # /clip-skill — Gerir Company Skills Paperclip @@ -162,4 +161,131 @@ UPDATE agents SET adapter_config = jsonb_set( '{paperclipSkillSync}', jsonb_build_object('desiredSkills', '{{SKILLS_JSON_ARRAY}}'::jsonb) ) -WHE \ No newline at end of file +WHERE id = '{{AGENT_ID}}' +AND company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f' +RETURNING name, adapter_config->'paperclipSkillSync'->'desiredSkills'; +``` + +Confirmar sempre: +- Nome do agente +- Skills a atribuir (mostrar name de cada) +- Se vai substituir ou adicionar a skills existentes + +### Atribuir por departamento (batch) + +Argumento: nome do C-Level ou Director. + +1. Obter agentes subordinados: +```sql +SELECT id, name, role FROM agents +WHERE reports_to = '{{MANAGER_ID}}' +AND company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'; +``` + +2. Listar skills recomendadas para o departamento +3. Confirmar com utilizador +4. Aplicar a cada agente + +## Modo remover + +### Remover skill de agente + +Ler skills actuais, filtrar a removida, escrever de volta: + +```sql +-- Ler +SELECT adapter_config->'paperclipSkillSync'->'desiredSkills' as skills +FROM agents WHERE id = '{{AGENT_ID}}'; + +-- Actualizar (remover skill especifica) +-- Construir novo array sem a skill removida e usar o UPDATE do modo atribuir +``` + +### Desinstalar skill da empresa + +```sql +DELETE FROM company_skills +WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f' +AND slug = '{{SLUG}}' +RETURNING name, slug; +``` + +Avisar: isto remove a skill de todos os agentes que a referenciam. Confirmar sempre. + +## Modo auditar + +### Cobertura de skills + +```sql +-- Agentes com routines activas mas sem skills +SELECT a.name, a.role, r.title as routine +FROM agents a +JOIN routines r ON r.assignee_agent_id = a.id +WHERE a.company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f' +AND r.status = 'active' +AND (a.adapter_config->'paperclipSkillSync' IS NULL + OR a.adapter_config::text NOT LIKE '%paperclipSkillSync%') +ORDER BY a.name; +``` + +### Mapeamento recomendado (plugin CC → departamento Clip) + +| Plugin CC | Agentes-alvo | Skills prioritarias | +|-----------|-------------|-------------------| +| core-tools | Todos | _core, quality-validator | +| crm-ops | CRO, Dir. Comercial, Sales Manager, Lead Qualifier | crm, desk, lead-approach, orcamento | +| gestao | COO, Dir. Operacoes, Project Manager | today, worklog, knowledge, tasks-overview | +| infraestrutura | CTO, Dir. Infraestrutura, Infra Check, Backup Specialist | gateway-check, backup, easypanel, cwp-server | +| marketing | CMO, Dir. SEO, Dir. Publicidade | seo-audit, seo-technical, ppc | +| wordpress | Dir. Web, WP Update | wp-dev, wp-performance, wp-cli | +| dev-tools | Dir. Desenvolvimento, Development Lead | dev-helper, pdf, docx | +| automacao | Dir. Automacao | n8n, automation-lead | +| negocio | CFO, CGO, Finance Manager | finance, research, saas | +| perfex-dev | Dir. Desenvolvimento | perfex-module | + +### Comparacao CC vs Clip + +```sql +-- Skills CC disponiveis (contar no filesystem) +-- vs skills instaladas no Clip +SELECT + (SELECT COUNT(*) FROM company_skills WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f') as instaladas_clip; +``` + +```bash +find ~/.claude/plugins/marketplaces/descomplicar-plugins/ -name "SKILL.md" | wc -l +``` + +Apresentar: +``` +### Auditoria Skills — [data] + +**CC:** N skills disponiveis em 15 plugins +**Clip:** N instaladas (N%) +**Agentes com skills:** N/62 (N%) +**Agentes com routines sem skills:** N (ATENCAO) + +### Gaps por departamento +| Departamento | Agentes | Com skills | Sem skills | Skills recomendadas | +... +``` + +## Referencias + +- Mecanismo runtime injection: conteúdo SKILL.md injectado como contexto adicional a cada heartbeat +- API skills: `skills/paperclip/references/company-skills.md` +- Schema BD: tabela `company_skills` (16 colunas) +- Auditoria compatibilidade: `04-Stack/02.06-Clip/auditoria-skills-compatibilidade.md` +- Manual: `06-Operacoes/Documentacao/Manuais/Paperclip/06-skills-e-plugins.md` + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"2026-04-07","issue":"API /skills/import e /skills/sync sem Authorization header — rejeitadas com 401","fix":"Adicionar -H 'Authorization: Bearer $PAPERCLIP_API_KEY' a todos os curl da skill","source":"auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/clip-vision/SKILL.md b/gestao/skills/clip-vision/SKILL.md index 1f8b53d..69a4236 100644 --- a/gestao/skills/clip-vision/SKILL.md +++ b/gestao/skills/clip-vision/SKILL.md @@ -5,7 +5,6 @@ description: "Gera documento de visao estrategica para o CEO Paperclip e bootstr version: "1.0.0" created: 2026-04-07 tools: [Read, Write, Bash, AskUserQuestion] -layer: wiki --- # Skill: /clip-vision @@ -163,4 +162,13 @@ Apresentar resumo ao utilizador: - Os documentos devem ser **accionaveis**, nao genericos - Cada bootstrap deve referenciar **dados reais** do estado actual -- O visio \ No newline at end of file +- O vision.md deve ser **injectado no CEO** como contexto do heartbeat +- Sugerir /schedule trimestral para refrescar a visao + +--- + +## Healing Log + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` diff --git a/gestao/skills/clip/SKILL.md b/gestao/skills/clip/SKILL.md index 9609e3d..17b1e48 100644 --- a/gestao/skills/clip/SKILL.md +++ b/gestao/skills/clip/SKILL.md @@ -2,7 +2,6 @@ name: clip description: Dashboard rápido Paperclip — estado agentes, issues abertas, heartbeats recentes, alertas. Usar quando "clip", "paperclip", "estado clip", "agentes clip". context: fork -layer: wiki --- # /clip — Dashboard Paperclip diff --git a/gestao/skills/daily-digest/SKILL.md b/gestao/skills/daily-digest/SKILL.md index 27e779f..027a2ca 100644 --- a/gestao/skills/daily-digest/SKILL.md +++ b/gestao/skills/daily-digest/SKILL.md @@ -2,7 +2,6 @@ name: daily-digest description: Sub-rotina chamada por /today para snapshot CRM (timer activo, tickets, facturas vencidas, leads, propostas, agenda). Pode ser invocada isoladamente quando só precisas dos números CRM sem o checkup completo. Usar quando "resumo", "digest", "estado do dia", "métricas dia". Para dashboard diário completo usar /today. context: fork -layer: wiki --- # /daily-digest v1.0 diff --git a/gestao/skills/deep-research/SKILL.md b/gestao/skills/deep-research/SKILL.md index 3aecbab..9e7a1ec 100644 --- a/gestao/skills/deep-research/SKILL.md +++ b/gestao/skills/deep-research/SKILL.md @@ -4,12 +4,11 @@ description: > Pesquisa profunda em 3 layers: Hub Obsidian (Layer 1) + NotebookLM análise (Layer 2) + Web externo (Layer 3). Para questões complexas que requerem síntese de múltiplas fontes. Usar quando: análise competitiva profunda, pesquisa mercado, due diligence, relatório estratégico. -layer: wiki --- # /deep-research — Pesquisa Profunda com RAG Trinity -Pesquisa em 3 camadas com síntese final. Mais profundo que `/research`, mais estruturado que `/hub-search`. +Pesquisa em 3 camadas com síntese final. Mais estruturado que `/hub-search` (que só cobre a Layer 1). --- @@ -18,9 +17,9 @@ Pesquisa em 3 camadas com síntese final. Mais profundo que `/research`, mais es | Situação | Skill Correcta | |---------|----------------| | "Onde está X no Hub?" | `/hub-search` | -| "Analisa este documento" | `/research` | +| "Analisa este documento" | Leitura directa (Read/Grep) — não há skill dedicada para análise de documento único | | "Pesquisa profunda + síntese de múltiplas fontes" | `/deep-research` ← este | -| "Análise competitiva completa" | `/deep-research` + `/research competitive` | +| "Análise competitiva completa" | `/deep-research` (foco competitivo na query) | --- diff --git a/gestao/skills/delegate/SKILL.md b/gestao/skills/delegate/SKILL.md index c57264b..0de2a74 100644 --- a/gestao/skills/delegate/SKILL.md +++ b/gestao/skills/delegate/SKILL.md @@ -1,7 +1,6 @@ --- name: delegate description: Delegação inteligente de tarefas para sub-agentes especializados. Analisa requisitos e encaminha para o agente adequado com contexto. Usar quando "delegate", "delegar", "subagent", "ajuda especializada", ou análises multi-domínio complexas. -layer: wiki --- # /delegate - Delegação com Testes e KB Integrados @@ -155,4 +154,200 @@ INSERT INTO tblskill_agent_metrics ( ## Uso ```bash -/delegate [instruções] +``` + +**Exemplos:** +```bash +/delegate #1429 /home/ealmeida/mcp-servers/mcp-desk-crm-sql-v3 +/delegate #1447 /home/ealmeida/mcp-servers/mcp-moloni "Implementar endpoints facturação" +``` + +--- + +## Template de Delegação + +```markdown +--- +## Tarefa Delegada: #[ID] - [NOME] + +**Desk:** https://desk.descomplicar.pt/admin/tasks/view/[ID] +**Projecto:** [NOME_PROJECTO] +**Path:** [PATH] + +--- + +### WORKFLOW OBRIGATÓRIO + +#### 1. INICIAR (primeiro passo) +``` +start_timer(task_id=[ID], staff_id=25, note="[CONTEXTO]") +``` + +#### 2. IMPLEMENTAR +- Desenvolver funcionalidade conforme descrição +- Manter CHANGELOG.md actualizado +- Commits ao terminar cada etapa: + ```bash + git commit -m "feat/fix: descrição (#[ID])" + ``` + +#### 3. TESTAR (obrigatório antes de concluir) + +Executar testes e registar resultados: + +| Tipo | O Que Testar | +|------|--------------| +| **Funcional** | A feature funciona como esperado? | +| **Edge cases** | Inputs inválidos, limites, erros? | +| **Regressão** | Funcionalidades existentes continuam OK? | + +**Se teste falhar:** +1. Corrigir o problema +2. Commit da correcção +3. Testar novamente +4. Repetir até passar + +#### 4. FINALIZAR + +**4.1 Commit final + push:** +```bash +git add -A && git commit -m "feat: [descrição] (#[ID])" && git push +``` + +**4.2 Status "Em Testes":** +``` +update_task(task_id=[ID], status=3) +``` + +**4.3 Report unificado:** +``` +add_task_comment(task_id=[ID], content=" +## Report de Execução + +**Trabalho Realizado:** +- [item 1] +- [item 2] + +**Testes Executados:** +| Teste | Status | +|-------|--------| +| [Funcional: descrição] | ✅/❌ | +| [Edge case: descrição] | ✅/❌ | +| [Regressão: descrição] | ✅/❌ | + +**Taxa de Sucesso:** X/Y (Z%) + +**Ficheiros Modificados:** +- [ficheiro] + +**Commits:** +- [hash] - descrição + +**Bugs/Notas:** +- [se houver] + +@Emanuel Almeida +") +``` + +**4.4 Parar timer:** +``` +stop_timer(task_id=[ID], staff_id=25, note="Concluído: [resumo]") +``` + +--- + +### Contexto +[INSTRUÇÕES ESPECÍFICAS] + +--- +*Delegado via /delegate v2.0 - [DATA]* +``` + +--- + +## Referência Rápida + +### Staff IDs +| ID | Nome | Uso | +|----|------|-----| +| 1 | Emanuel Almeida | Trabalho directo | +| 25 | AikTop | Trabalho delegado IA | + +### Status +| ID | Nome | +|----|------| +| 1 | Não iniciado | +| 4 | Em Curso | +| 3 | Em Testes | +| 5 | Terminado | + +### Auto-Stop Timer +- Inactividade >15 min → timer pára automaticamente +- Implementado via hooks + +--- + +## Changelog + +### v3.0.0 (2026-02-03) +- **NEW:** Auto-consulta Dify KB antes de delegação +- Detecta agente baseado em path/contexto +- Carrega consultation_protocol de agent-knowledge-config.json +- Consulta paralela de datasets prioritários +- Cache layer (24h TTL) evita consultas repetidas +- Template enriquecido com conhecimento relevante +- Métricas automáticas de KB consulted/cache hit + +### v2.0.0 (2026-01-27) +- **BREAKING:** Testes integrados no workflow (não separados) +- Report unificado inclui resultados de testes +- Ciclo corrigir→testar até passar +- Eliminada dependência de /test-plan + +### v1.0.0 (2026-01-27) +- Versão inicial +- Template estruturado +- Timer AikTop +- Status "Em Testes" + +--- + +**Versão:** 3.0.0 | **Autor:** Descomplicar® | **Data:** 2026-02-03 + +--- + + +## Quando NÃO Usar + +- Para tarefas fora do domínio de especialização desta skill +- Quando outra skill mais específica está disponível +- Para operações que requerem confirmação manual do utilizador + + +## Exemplos + +### Exemplo 1: Uso Básico +``` +Input: [descrição da tarefa] +Output: [resultado esperado] +``` + +### Exemplo 2: Uso Avançado +``` +Input: [caso complexo] +Output: [resultado detalhado] +``` + +--- + +## 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/gestao/skills/doc-coauthoring/SKILL.md b/gestao/skills/doc-coauthoring/SKILL.md index 41fc026..07cdea8 100644 --- a/gestao/skills/doc-coauthoring/SKILL.md +++ b/gestao/skills/doc-coauthoring/SKILL.md @@ -1,7 +1,6 @@ --- name: doc-coauthoring description: Workflow estruturado para co-autoria de documentos. Usar quando o utilizador quer escrever propostas comerciais, specs de projecto, relatórios cliente, SOPs, decisões técnicas ou conteúdo estruturado. Guia 3 fases - recolha de contexto, refinamento iterativo e teste de leitura. Trigger quando "escrever doc", "redigir proposta", "criar spec", "documentar", "relatório", "SOP". -layer: wiki --- # /doc-coauthoring - Co-Autoria de Documentos @@ -100,4 +99,356 @@ Aconselhar a não se preocuparem com organização — apenas tirar tudo cá par - Partilhar links para documentos **Pesquisa de contexto automática:** -Usar /knowledge para pesquisar contexto relevante nas fontes de conhecimento (NotebookLM, Supabase, docs locais). Informa \ No newline at end of file +Usar /knowledge para pesquisar contexto relevante nas fontes de conhecimento (NotebookLM, Supabase, docs locais). Informar o utilizador do que foi encontrado. + +**Se integrações disponíveis** (Google Workspace, filesystem, etc.), mencionar que podem ser usadas para importar contexto directamente. + +**Durante a recolha de contexto:** + +- Se o utilizador mencionar canais ou documentos partilhados: + - Se integrações disponíveis: Informar que o conteúdo será lido agora, depois usar a integração adequada + - Se não disponíveis: Explicar falta de acesso. Sugerir que colem o conteúdo relevante directamente. + +- Se o utilizador mencionar entidades/projectos desconhecidos: + - Perguntar se devem ser pesquisados nas ferramentas conectadas + - Aguardar confirmação antes de pesquisar + +- À medida que o contexto é fornecido, acompanhar o que está a ser aprendido e o que ainda não é claro + +**Perguntas de clarificação:** + +Quando o utilizador sinalizar que terminou o despejo inicial (ou após contexto substancial), fazer perguntas de clarificação: + +Gerar 5-10 perguntas numeradas baseadas nas lacunas do contexto. + +Informar que podem usar taquigrafia para responder (ex.: "1: sim, 2: ver email X, 3: não por causa de compatibilidade"), apontar para mais docs, ou continuar a despejar. O que for mais eficiente. + +**Condição de saída:** +Contexto suficiente recolhido quando as perguntas demonstram compreensão — quando se consegue perguntar sobre casos extremos e trade-offs sem precisar de explicações básicas. + +**Transição:** +Perguntar se há mais contexto a fornecer, ou se é hora de avançar para a redacção. + +Se quiserem adicionar mais, deixar. Quando prontos, avançar para a Fase 2. + +--- + +## Fase 2: Refinamento e Estrutura + +**Objectivo:** Construir o documento secção a secção através de brainstorming, curadoria e refinamento iterativo. + +**Instruções ao utilizador:** +Explicar que o documento será construído secção a secção. Para cada secção: +1. Perguntas de clarificação sobre o que incluir +2. Brainstorming de 5-20 opções +3. O utilizador indica o que manter/remover/combinar +4. A secção é redigida +5. Refinamento através de edições cirúrgicas + +Começar pela secção com mais incógnitas (normalmente a proposta/decisão central), depois trabalhar as restantes. + +**Ordenação de secções:** + +Se a estrutura do documento for clara: +Perguntar por qual secção começar. + +Sugerir começar pela secção com mais incógnitas. Para propostas comerciais, normalmente é o âmbito e preço. Para specs, é tipicamente a abordagem técnica. Secções de resumo ficam para o fim. + +Se o utilizador não souber que secções precisa: +Baseado no tipo de documento, template e contexto Descomplicar, sugerir 3-5 secções adequadas. + +**Sugestões por tipo de documento:** + +| Tipo | Secções sugeridas | +|------|------------------| +| Proposta comercial | Contexto/Problema, Solução proposta, Âmbito e entregáveis, Investimento, Próximos passos | +| Spec de projecto | Objectivo, Arquitectura, Requisitos, Milestones, Riscos | +| Relatório cliente | Sumário executivo, Trabalho realizado, Métricas, Recomendações, Próximos passos | +| SOP | Objectivo, Pré-requisitos, Procedimento (passos), Verificação, Troubleshooting | +| Decisão técnica | Contexto, Opções avaliadas, Análise comparativa, Decisão, Consequências | + +Perguntar se a estrutura funciona ou se querem ajustá-la. + +**Quando a estrutura for acordada:** + +Criar a estrutura inicial do documento com texto placeholder para todas as secções. + +Criar um ficheiro markdown no directório de trabalho. Nomear adequadamente (ex.: `proposta-cliente-nome.md`, `spec-projecto.md`). + +Confirmar o nome do ficheiro criado e indicar que é hora de preencher cada secção. + +**Para cada secção:** + +### Passo 1: Perguntas de Clarificação + +Anunciar que o trabalho na secção [NOME DA SECÇÃO] vai começar. Fazer 5-10 perguntas de clarificação sobre o que incluir: + +Gerar 5-10 perguntas específicas baseadas no contexto e objectivo da secção. + +Informar que podem responder em taquigrafia ou apenas indicar o que é importante cobrir. + +### Passo 2: Brainstorming + +Para a secção [NOME DA SECÇÃO], fazer brainstorming de [5-20] pontos que possam ser incluídos, dependendo da complexidade. Procurar: +- Contexto partilhado que possa ter sido esquecido +- Ângulos ou considerações ainda não mencionados +- Dados do /crm ou /knowledge relevantes + +Gerar 5-20 opções numeradas baseadas na complexidade da secção. No fim, oferecer brainstorming adicional se quiserem mais opções. + +### Passo 3: Curadoria + +Perguntar quais pontos manter, remover ou combinar. Pedir breves justificações para ajudar a aprender prioridades para as próximas secções. + +Dar exemplos: +- "Manter 1,4,7,9" +- "Remover 3 (duplica o 1)" +- "Remover 6 (o público já sabe isto)" +- "Combinar 11 e 12" + +**Se o utilizador der feedback em formato livre** (ex.: "está bom" ou "gosto da maioria mas...") em vez de selecções numeradas, extrair as preferências e prosseguir. Interpretar o que querem manter/remover/alterar e aplicar. + +### Passo 4: Verificação de Lacunas + +Baseado no que seleccionaram, perguntar se falta algo importante para a secção [NOME DA SECÇÃO]. + +### Passo 5: Redacção + +Usar `str_replace` para substituir o texto placeholder desta secção pelo conteúdo redigido. + +Anunciar que a secção [NOME DA SECÇÃO] vai ser redigida agora com base no que seleccionaram. + +Após a redacção, confirmar conclusão. Informar que a secção [NOME DA SECÇÃO] foi redigida em [ficheiro]. Pedir que leiam e indiquem o que alterar. Notar que ser específico ajuda a aprender o estilo para futuras secções. + +**Instrução chave ao utilizador (incluir ao redigir a primeira secção):** +Nota: Em vez de editar o documento directamente, pedir que indiquem o que alterar. Isto ajuda a aprender o estilo para futuras secções. Exemplo: "Remover o bullet X — já coberto por Y" ou "Tornar o terceiro parágrafo mais conciso". + +### Passo 6: Refinamento Iterativo + +À medida que o utilizador fornece feedback: +- Usar `str_replace` para fazer edições (nunca reimprimir todo o documento) +- Confirmar que as edições estão completas +- Se o utilizador editar o documento directamente e pedir para ler: notar mentalmente as alterações e tê-las em conta para futuras secções (revela preferências) + +**Continuar a iterar** até o utilizador ficar satisfeito com a secção. + +### Verificação de Qualidade + +Após 3 iterações consecutivas sem alterações substanciais, perguntar se algo pode ser removido sem perder informação importante. + +Quando a secção estiver concluída, confirmar que [NOME DA SECÇÃO] está completa. Perguntar se estão prontos para a próxima secção. + +**Repetir para todas as secções.** + +### Perto da Conclusão + +Ao aproximar da conclusão (80%+ das secções feitas), anunciar intenção de reler todo o documento e verificar: +- Fluxo e consistência entre secções +- Redundância ou contradições +- Qualquer coisa que pareça genérico ou filler +- Se cada frase tem peso + +Ler todo o documento e fornecer feedback. + +**Quando todas as secções estiverem redigidas e refinadas:** +Anunciar que todas as secções estão redigidas. Indicar intenção de rever o documento completo uma última vez. + +Rever para coerência geral, fluxo, completude. + +Fornecer sugestões finais. + +Perguntar se estão prontos para o teste de leitura, ou se querem refinar mais alguma coisa. + +--- + +## Fase 3: Teste de Leitura + +**Objectivo:** Testar o documento com um Claude sem contexto (sem contaminação) para verificar que funciona para leitores. + +**Instruções ao utilizador:** +Explicar que agora vai ser testado se o documento funciona para leitores. Isto detecta pontos cegos — coisas que fazem sentido para os autores mas podem confundir outros. + +### Abordagem de Teste + +**Se sub-agentes disponíveis (ex.: Claude Code):** + +Realizar o teste directamente sem envolvimento do utilizador. + +#### Passo 1: Prever Perguntas dos Leitores + +Anunciar intenção de prever que perguntas os leitores farão ao encontrar este documento. + +Gerar 5-10 perguntas que leitores realisticamente fariam. Para documentos Descomplicar, incluir perguntas que um cliente ou parceiro faria. + +#### Passo 2: Testar com Sub-Agente + +Anunciar que estas perguntas vão ser testadas com uma instância Claude sem contexto desta conversa. + +Para cada pergunta, invocar um sub-agente apenas com o conteúdo do documento e a pergunta. + +Resumir o que o Claude leitor acertou/errou para cada pergunta. + +#### Passo 3: Verificações Adicionais + +Anunciar que verificações adicionais vão ser realizadas. + +Invocar sub-agente para verificar ambiguidade, pressupostos falsos, contradições. + +Resumir quaisquer problemas encontrados. + +#### Passo 4: Reportar e Corrigir + +Se problemas encontrados: +Reportar que o Claude leitor teve dificuldades com questões específicas. + +Listar os problemas específicos. + +Indicar intenção de corrigir estas lacunas. + +Voltar ao refinamento para secções problemáticas. + +--- + +**Se sub-agentes não disponíveis:** + +O utilizador terá de fazer o teste manualmente. + +#### Passo 1: Prever Perguntas dos Leitores + +Perguntar que perguntas as pessoas farão ao encontrar este documento. O que escreveriam no Claude.ai? + +Gerar 5-10 perguntas que leitores realisticamente fariam. + +#### Passo 2: Configurar Teste + +Fornecer instruções de teste: +1. Abrir uma nova conversa Claude: https://claude.ai +2. Colar ou partilhar o conteúdo do documento +3. Fazer ao Claude leitor as perguntas geradas + +Para cada pergunta, instruir o Claude leitor a fornecer: +- A resposta +- Se algo foi ambíguo ou pouco claro +- Que conhecimento/contexto o documento assume como conhecido + +Verificar se o Claude leitor dá respostas correctas ou interpreta mal algo. + +#### Passo 3: Verificações Adicionais + +Também perguntar ao Claude leitor: +- "O que neste documento pode ser ambíguo ou pouco claro para leitores?" +- "Que conhecimento ou contexto este documento assume que os leitores já têm?" +- "Há contradições internas ou inconsistências?" + +#### Passo 4: Iterar com Base nos Resultados + +Perguntar o que o Claude leitor errou ou teve dificuldade. Indicar intenção de corrigir essas lacunas. + +Voltar ao refinamento para secções problemáticas. + +--- + +### Condição de Saída (Ambas as Abordagens) + +Quando o Claude leitor responde consistentemente às perguntas de forma correcta e não levanta novas lacunas ou ambiguidades, o documento está pronto. + +--- + +## Revisão Final + +Quando o teste de leitura passar: +Anunciar que o documento passou o teste de leitura. Antes de concluir: + +1. Recomendar uma leitura final pelo utilizador — eles são donos do documento e responsáveis pela qualidade +2. Sugerir verificação dupla de factos, links ou detalhes técnicos +3. Perguntar se atinge o impacto desejado + +Perguntar se querem mais uma revisão ou se o trabalho está concluído. + +**Se quiserem revisão final, fornecer. Caso contrário:** +Anunciar conclusão do documento. Fornecer dicas finais: +- Considerar gerar o documento final com /docx, /xlsx ou /pdf conforme o formato necessário +- Usar apêndices para fornecer profundidade sem inchar o documento principal +- Actualizar o documento à medida que feedback é recebido de leitores reais +- Se for proposta comercial, considerar criar estimate no Desk CRM via /crm + +--- + +## Integração com Ecossistema Descomplicar + +### Fontes de Contexto + +| Fonte | Quando usar | Como | +|-------|------------|------| +| /knowledge | Pesquisar conhecimento temático | NotebookLM, Supabase, docs locais | +| /crm | Dados de clientes e projectos | Desk CRM (contactos, historial, propostas) | +| Hub/90-Templates/ | Templates de documentos | Estruturas predefinidas | +| Hub/03-Propostas/ | Propostas anteriores | Referência de estilo e conteúdo | +| Hub/07-Clientes/ | Contexto de clientes | Notas, projectos, ficheiros | + +### Formatos de Saída + +Após concluir o documento: +- **Proposta comercial** → /docx ou /pdf para envio ao cliente +- **Spec de projecto** → Manter como .md no directório do projecto +- **SOP / Procedimento** → Mover para `Hub/06-Operacoes/Procedimentos/` como PROC-*.md +- **Relatório cliente** → /pdf para envio, guardar cópia em Hub/07-Clientes/ +- **Decisão técnica** → Guardar em Supabase via /knowledge e no Hub + +--- + +## Dicas para Orientação Eficaz + +**Tom:** +- Directo e procedimental +- Explicar brevemente o racional quando afecta o comportamento do utilizador +- Não tentar "vender" a abordagem — apenas executá-la + +**Lidar com Desvios:** +- Se o utilizador quiser saltar uma fase: Perguntar se querem saltar e escrever em formato livre +- Se o utilizador parecer frustrado: Reconhecer que está a demorar mais do que esperado. Sugerir formas de acelerar +- Dar sempre agência ao utilizador para ajustar o processo + +**Gestão de Contexto:** +- Ao longo de todo o processo, se faltar contexto sobre algo mencionado, perguntar proactivamente +- Não deixar lacunas acumular — resolvê-las à medida que surgem + +**Gestão de Ficheiros:** +- Usar `str_replace` para todas as edições +- Confirmar edições após cada alteração +- Nunca usar brainstorming em ficheiros — isso é conversa +- Documento de trabalho sempre em markdown até formato final + +**Qualidade sobre Velocidade:** +- Não apressar as fases +- Cada iteração deve trazer melhorias significativas +- O objectivo é um documento que funciona para leitores + +--- + +## Changelog + +### v1.0.0 (2026-03-06) +- Versão inicial adaptada de Anthropic doc-coauthoring +- Workflow de 3 fases: contexto, refinamento, teste de leitura +- Integração com /knowledge, /crm e templates Hub +- Tipos de documento Descomplicar: propostas, specs, relatórios, SOPs +- Sugestões de secções por tipo de documento +- Formatos de saída com /docx, /xlsx, /pdf +- Integração com ecossistema Descomplicar (Desk CRM, Hub, templates) + +--- + +**Versão**: 1.0.0 | **Data**: 2026-03-06 | **Autor**: 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ós cada erro corrigido.* diff --git a/gestao/skills/dual-review/SKILL.md b/gestao/skills/dual-review/SKILL.md index 671fd7a..fbed57e 100644 --- a/gestao/skills/dual-review/SKILL.md +++ b/gestao/skills/dual-review/SKILL.md @@ -2,7 +2,6 @@ name: dual-review description: Revisão dual-model de conteúdo publicável — artigos WordPress, propostas comerciais, relatórios de cliente. Um agente gera com contexto completo, outro revisa sem contexto partilhado. Usar antes de publicar ou enviar a cliente. context: fork -layer: wiki --- # /dual-review — Revisão Dual-Model diff --git a/gestao/skills/hub-compile/SKILL.md b/gestao/skills/hub-compile/SKILL.md index effc59a..adb5d7e 100644 --- a/gestao/skills/hub-compile/SKILL.md +++ b/gestao/skills/hub-compile/SKILL.md @@ -2,7 +2,6 @@ name: hub-compile description: Compilador do 00-Inbox do Hub Obsidian. Classifica ficheiros .md, gera resumos, sugere destino e backlinks, move com aprovação explícita do utilizador. Usar quando "hub-compile", "compilar inbox", "triagem inbox", "processar inbox", "classificar notas". context: fork -layer: wiki --- # /hub-compile v1.0 — Compilador do Hub Inbox @@ -150,4 +149,81 @@ Para cada ficheiro aprovado com acção `mover` ou `arquivar`: **Formato do path de destino:** - Worklogs: `/media/ealmeida/Dados/Hub/99-Arquivo/Worklogs/YYYY/MM/nome.md` -- Documentação pontual: `/media/ealmeida/Dados/Hub/99-Arquivo/Documentaca \ No newline at end of file +- Documentação pontual: `/media/ealmeida/Dados/Hub/99-Arquivo/Documentacao-Pontuais/nome.md` +- Knowledge-Base: `/media/ealmeida/Dados/Hub/06-Operacoes/Knowledge-Base/MDs/nome.md` + +--- + +## Passo 6 — Actualizar INDEX.md + +### INDEX.md do Inbox (00-Inbox/INDEX.md) + +Remover entradas dos ficheiros movidos. Se INDEX.md não tiver lista estruturada, adicionar nota de actualização no topo. + +### INDEX.md do Destino + +Para cada destino com movimentos: +1. Ler INDEX.md existente (se existir) +2. Adicionar entradas dos ficheiros movidos +3. Se INDEX.md não existir e destino tem >3 ficheiros → criar + +**Formato de entrada no INDEX.md:** + +```markdown +| `nome-ficheiro.md` | Tipo | YYYY-MM-DD | Descrição breve | +``` + +--- + +## Output Final + +```markdown +## Hub Compile — Concluído + +**Movidos:** N ficheiros +**Mantidos no Inbox:** M ficheiros +**Eliminados:** 0 (requer confirmação separada) + +### Movimentos Realizados + +- `worklog-2026-03-31.md` → 99-Arquivo/Worklogs/2026/03/ +- `prompt-modulo-moloni.md` → 99-Arquivo/Documentacao-Pontuais/ + +### Mantidos + +- `migracao-alurin-mini-pc.md` — migração activa +- `NovoPC.md` — planeamento em curso + +### INDEX.md Actualizados + +- 00-Inbox/INDEX.md ✓ +- 99-Arquivo/Worklogs/2026/03/INDEX.md ✓ +- 99-Arquivo/Documentacao-Pontuais/INDEX.md ✓ +``` + +--- + +## Regras Obrigatórias + +1. **NUNCA mover sem aprovação explícita** do utilizador +2. **Worklogs** vão sempre para `99-Arquivo/Worklogs/YYYY/MM/` +3. **Planeamento activo** e **migração em curso** ficam sempre no Inbox (`manter`) +4. **Prompts concluídos** vão para `99-Arquivo/Documentacao-Pontuais/` +5. **Notas técnicas com valor permanente** vão para `06-Operacoes/Knowledge-Base/MDs/` +6. **Eliminar** requer confirmação separada — nunca eliminar na aprovação em massa +7. **INDEX.md** deve ser actualizado em origem e destino após cada movimento +8. **Usar mcp__filesystem__*** para todas as operações de ficheiros + +--- + +## Anti-Patterns + +- **NUNCA** mover com `aprovar tudo` sem excluir os `manter` +- **NUNCA** criar destinos sem verificar se já existem +- **NUNCA** omitir actualização dos INDEX.md +- **NUNCA** classificar como `eliminar` sem justificação clara +- **NUNCA** confundir planeamento activo com documentação pontual + +--- + +*Skill v1.0 | 2026-04-07 | Descomplicar®* diff --git a/gestao/skills/hub-search/SKILL.md b/gestao/skills/hub-search/SKILL.md index fc01580..777415f 100644 --- a/gestao/skills/hub-search/SKILL.md +++ b/gestao/skills/hub-search/SKILL.md @@ -6,7 +6,6 @@ description: > Usar quando: (1) pesquisar conteúdo no Hub por termo ou conceito, (2) encontrar notas relacionadas via backlinks, (3) localizar PROCs/QR/docs antes de executar tarefas, (4) verificar se existe documentação antes de criar. -layer: wiki --- # /hub-search — Pesquisa no Hub (Layer 1 RAG) diff --git a/gestao/skills/imap-triage/SKILL.md b/gestao/skills/imap-triage/SKILL.md index 17296da..653f3ab 100644 --- a/gestao/skills/imap-triage/SKILL.md +++ b/gestao/skills/imap-triage/SKILL.md @@ -2,7 +2,6 @@ name: imap-triage description: Triagem automática de emails IMAP em 14 contas. Elimina spam, arquiva promocionais, identifica facturas, sinaliza prioritários. Deduplicação via Supabase. Usar quando "imap", "triagem email", "limpar emails", "email triage", "processar emails". disable-model-invocation: true -layer: wiki --- # /imap-triage v1.0 @@ -193,4 +192,57 @@ Action: skipped ``` - "Payment Confirmation" / "Payment Was Successfully Processed" -> apenas confirmacao - "Your subscription has been renewed" sem valor -> apenas notificacao -- \ No newline at end of file +- "Notificacao de transferencia" de bancos -> notificacao bancaria +- Marketing/changelog dos mesmos fornecedores -> promocional +- Subject "Welcome" / "Getting Started" -> onboarding +``` + +--- + +## Output Standalone + +Quando invocado directamente (sem /today): + +```markdown +## Triagem IMAP - DD-MM-YYYY + +**Total: X emails processados em Y contas** + +| Conta | Spam | Promo | Factura | Notif | Prio | Total | +|-------|------|-------|---------|-------|------|-------| + +### Facturas Detectadas (para /auto-expense) +- contabilidade: MEO (uid 164) - FT A/861215955 + +### Prioritarios +- emanuel: [Subject] de [Remetente] + +### Alertas Sistema +- [Alertas de seguranca, updates criticos] +``` + +--- + +## Anti-Patterns + +- NUNCA criar despesas directamente (delegar para /auto-expense) +- NUNCA processar >50 emails por conta (limitar) +- NUNCA eliminar emails de dominios protegidos +- SEMPRE registar no Supabase, mesmo se skipped +- SEMPRE usar imap_delete para contas sem pasta "Promotions" + +--- + +*Skill v1.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ós cada erro corrigido.* diff --git a/gestao/skills/index-update/SKILL.md b/gestao/skills/index-update/SKILL.md index f056dc0..a0588b3 100644 --- a/gestao/skills/index-update/SKILL.md +++ b/gestao/skills/index-update/SKILL.md @@ -2,7 +2,6 @@ name: index-update description: Actualiza INDEX.md de procedimentos após criar/modificar/arquivar PROC. Usar quando "actualizar index", "update INDEX.md", depois de criar procedimento, mover PROC, arquivar procedimento. Mantém estatísticas, navegação e data actualizadas. disable-model-invocation: true -layer: wiki --- # /index-update - Actualizador de INDEX.md @@ -213,4 +212,194 @@ Antes de salvar INDEX.md, verificar: ✅ Ordenação por código mantida ✅ Links relativos funcionam (./PROC-*.md) ✅ Sem linhas duplicadas -✅ Sem procedimentos órfãos (ficheiro existe mas não está no INDEX \ No newline at end of file +✅ Sem procedimentos órfãos (ficheiro existe mas não está no INDEX) +✅ Sem fantasmas (linha no INDEX mas ficheiro não existe) +✅ Data actualizada para hoje +✅ Formato tabela Markdown correcto +``` + +--- + +## Integração com /proc-creator + +`/proc-creator` chama `/index-update` automaticamente: + +``` +User: /proc-creator "MCP Session Recovery" +→ PROC-MCP-Session-Recovery.md criado +→ /index-update triggered automaticamente +→ D7-Tecnologia/INDEX.md actualizado (28 → 29) +→ INDEX.md principal actualizado (36 → 37) +→ Confirmação ao utilizador +``` + +--- + +## Modo Manual + +Quando usar manualmente: + +``` +User: Arquivei 3 procedimentos antigos do D7. Actualizar INDEX? +Assistant: /index-update + +1. Lendo D7-Tecnologia/INDEX.md... +2. Detectei que PROC-X, PROC-Y, PROC-Z não existem mais +3. Removendo linhas... +4. Actualizando contador: 28 → 25 +5. Actualizando INDEX principal: 36 → 33 +6. ✅ Ambos os INDEX.md actualizados +``` + +--- + +## Detecção Automática de Dessinc + +Quando `/index-update` é chamado sem contexto: + +``` +1. PARA CADA departamento: + - Ler INDEX.md + - Listar ficheiros PROC-*.md no directório + - Comparar + +2. DETECTAR problemas: + - Órfãos: ficheiro existe mas não está no INDEX + - Fantasmas: linha no INDEX mas ficheiro não existe + - Contadores errados: NUM no INDEX ≠ count real + +3. REPORTAR discrepâncias: + "D7-Tecnologia: 3 órfãos detectados" + "D3-Contabilidade: contador errado (diz 2, tem 3)" + +4. PERGUNTAR ao utilizador: + "Corrigir automaticamente? [Sim/Não]" + +5. SE Sim: + - Adicionar órfãos ao INDEX + - Remover fantasmas do INDEX + - Corrigir contadores + - Actualizar datas +``` + +--- + +## Exemplos de Uso + +### Exemplo 1: Após Criar PROC + +``` +User: /proc-creator criou PROC-WordPress-CLI.md +Assistant: (auto-triggered /index-update) + +✅ D7-Tecnologia/INDEX.md actualizado + - Adicionada linha: PROC-WordPress-CLI.md | WP-CLI-001 + - Contador: 28 → 29 + +✅ INDEX.md principal actualizado + - D7: 28 → 29 + - Total: 36 → 37 +``` + +### Exemplo 2: Correcção Manual + +``` +User: /index-update +Assistant: + +🔍 Verificando consistência... + +D7-Tecnologia: +- ⚠️ 2 órfãos detectados: + - PROC-MCP-Troubleshooting-Erro-471.md (não está no INDEX) + - PROC-MCP-Session-Recovery.md (não está no INDEX) +- ✅ Sem fantasmas + +D3-Contabilidade: +- ⚠️ Contador errado: INDEX diz 2, existem 3 ficheiros + +Corrigir automaticamente? [Sim] + +→ Adicionando órfãos... +→ Corrigindo contadores... +→ Actualizando datas... +✅ Todos os INDEX.md consistentes +``` + +### Exemplo 3: Após Arquivar + +``` +User: Arquivei PROC-Backup-Old-Method.md (obsoleto) +Assistant: /index-update D7-Tecnologia + +✅ Removido PROC-Backup-Old-Method.md do INDEX +✅ Contador: 29 → 28 +✅ INDEX principal: 37 → 36 +✅ Data actualizada +``` + +--- + +## Anti-Patterns + +**NUNCA:** +- ❌ Actualizar INDEX sem verificar ficheiro existe +- ❌ Esquecer de actualizar INDEX principal +- ❌ Deixar data desactualizada +- ❌ Quebrar ordenação por código +- ❌ Adicionar linha com link quebrado + +**SEMPRE:** +- ✅ Actualizar AMBOS os INDEX (dept + principal) +- ✅ Verificar ficheiro existe antes de adicionar +- ✅ Manter ordenação por código +- ✅ Actualizar contadores correctamente +- ✅ Actualizar data para hoje + +--- + +## Validação Pós-Actualização + +Checklist automática: + +``` +✅ Contadores matemáticos correctos +✅ Links relativos válidos +✅ Ordenação mantida +✅ Sem duplicados +✅ Sem órfãos detectados +✅ Sem fantasmas detectados +✅ Data = hoje +✅ Formato Markdown válido +``` + +--- + +## Scripts Auxiliares (Futuro) + +```bash +# Validar consistência INDEX.md +./scripts/validate-index.sh + +# Detectar órfãos e fantasmas +./scripts/detect-orphans.sh + +# Re-gerar INDEX.md do zero +./scripts/rebuild-index.sh [departamento] +``` + +--- + +*Skill v1.0.0 | 2026-02-13 | Plugin gestao | 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ós cada erro corrigido.* diff --git a/gestao/skills/knowledge/SKILL.md b/gestao/skills/knowledge/SKILL.md index d1c39a8..cc012bd 100644 --- a/gestao/skills/knowledge/SKILL.md +++ b/gestao/skills/knowledge/SKILL.md @@ -1,7 +1,6 @@ --- name: knowledge -description: Router de conhecimento unificado. Classifica pergunta por tipo e encaminha para fonte certa (Hub granular/NLM/Context7/CC memory/Mem0/Desk CRM/Git). v3.1.0 -layer: wiki +description: Router de conhecimento unificado. Classifica pergunta por tipo e encaminha para fonte certa (Hub granular/NLM/Context7/CC memory/Supabase/Desk CRM/Git). v3.1.0 --- # /knowledge — Router Unificado v3.1.0 @@ -9,7 +8,7 @@ layer: wiki > **Reescrita 13-04-2026:** v2.2.0 usava modelo Familia A/B com NLM restrito a "externo". > v3.0.0 classifica por tipo de pergunta (8 rotas), adiciona Hub granular > (QR/KB/APIs/Manuais/PROCs/Troubleshooting), reclassifica NLM como referencia -> tecnica primaria, e torna Mem0 complementar (nao alicerce). +> tecnica primaria, e torna Supabase complementar (nao alicerce). > Racional: `plans/atomic-fluttering-flame.md` ## Principio @@ -58,7 +57,7 @@ layer: wiki 3. **Hub Manuais** — `Grep` em `/media/ealmeida/Dados/Hub/06-Operacoes/Documentacao/Manuais/**/*.md` 4. **Context7** — `resolve-library-id` → `query-docs` (para frameworks/bibliotecas com docs oficiais) 5. **CC memory cross-projecto** — `Grep` em `~/.claude/projects/*/memory/*.md` -6. **Mem0** — `mcp__mem_search_memories(query)` [graceful se indisponivel] +6. **Supabase** — `search_memories(query, threshold=0.5, limit=5)` [graceful se indisponivel] **Prioridade por tipo de tema:** - Framework/biblioteca com docs oficiais (Next.js, React, Laravel...) → **KB local primeiro** + **Context7** + NLM @@ -89,4 +88,223 @@ layer: wiki | Video, producao, youtube | Producao de Video e Youtube | `058a896e-6c9a-4e51-ae7d-9adb2738bc5f` | | WooCommerce, loja, produtos | Documentacao WooCommerce | `bd06acff-4b9d-44aa-b3f7-60434bbd6b49` | -> Inventario completo 65 notebooks: `~/.claude/projects/-media-eal \ No newline at end of file +> Inventario completo 65 notebooks: `~/.claude/projects/-media-ealmeida-Dados-Hub/memory/notebooklm-inventory.md` + +**Hub KB: ficheiros locais densos (usar quando match directo):** + +| Keywords | Ficheiro KB | +|----------|-------------| +| next.js, app router, server components | `Next.js 14_15 App Router Deep Dive.md` | +| php, laravel | `PHP 8+ e Laravel 11_12_ Pesquisa Profunda.md` | +| core web vitals, ga4, performance | `Core Web Vitals, GA4, Performance Web.md` | +| n8n, automacao | `Base-Conhecimento-n8n.md` | +| perfex crm, modulos | `Base-Conhecimento-Perfex-CRM.md` | +| remotion, video codigo | `Base-Conhecimento-Remotion-Video.md` | +| ui, ux, design systems | `Base-Conhecimento-UI-UX-Design-Systems.md` | +| tipografia, cor, web design | `Base-Conhecimento-Web-Design-Tipografia-Cor.md` | +| youtube, video producao | `Base-Conhecimento-Video-YouTube.md` | +| openrouter, modelos ai | `OpenRouter-Matrix-v1.1.md` | +| postfix, email security | `Postfix Email Security Best Practices.md` | +| wcag, acessibilidade | `Relatório Acessibilidade Web WCAG 2.2.md` | +| gestao, operacoes, agencia | `Gestao-Operacoes-Agencias-Marketing-Tecnologia.md` | + +**Context7 para docs oficiais:** usar `resolve-library-id` → `query-docs` quando a pergunta e sobre uma biblioteca/framework com documentacao oficial actualizada (Next.js, React, Tailwind, Laravel, etc). Context7 tem docs mais frescos que NLM. + +### 3. API / implementacao (endpoint, payload, autenticacao) + +**Sinais:** "endpoint", "API de", "payload", "autenticacao", "integrar com" + +**Fontes (sequencial — Read directo do ficheiro):** + +| Keywords | Ficheiro em `Hub/06-Operacoes/Documentacao/APIs/` | +|----------|----------------------------------------------------| +| perfex, desk crm api | Perfex-CRM-API.md | +| cwp api, cwp endpoint | CWP-API.md | +| whatsms, sms api | WhatSMS-API.md + WhatSMS-Admin-API.md | +| paperclip api | Paperclip-API.md | +| dify api | Dify-API.md | +| bookstack api | BookStack-API.md | +| mcp desenvolvimento | MCP-Dev-Manual.md | + +Se API nao listada → NLM notebook relevante + Context7. + +### 4. Processo / procedimento (como fazemos X internamente) + +**Sinais:** "procedimento", "como fazemos", "PROC", "workflow interno", "passo-a-passo" + +**Fontes:** +1. `Grep` em `/media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/**/*.md` (38 PROCs) +2. `Grep` em `/media/ealmeida/Dados/Hub/06-Operacoes/Documentacao/Manuais/**/*.md` + +**Departamentos PROC:** + +| Tema | Pasta | +|------|-------| +| Comercial, CRM, catalogo | D1-Comercial/ | +| Suporte, tickets | D2-Suporte/ | +| Contabilidade, facturas | D3-Contabilidade/ | +| RH | D4-RH/ | +| Design | D5-Design/ | +| Marketing, conteudo | D6-Marketing/ | +| Tecnologia, MCP, Claude, infra | D7-Tecnologia/ | +| Multi-departamental | Cross-Departamental/ | + +### 5. Troubleshooting (erro, problema, nao funciona) + +**Sinais:** "erro", "nao funciona", "problema com", "fix para", "troubleshoot" + +**Fontes (paralelo):** +1. `Grep` em `/media/ealmeida/Dados/Hub/06-Operacoes/Documentacao/Troubleshooting/*.md` +2. CC memory cross-projecto — `Grep` em `~/.claude/projects/*/memory/*.md` +3. Supabase — `search_memories(query, threshold=0.5, limit=5)` [graceful] +4. NLM notebook relevante (contexto tecnico) + +### 6. Estado actual (quem, quando, quanto, aberto/fechado) + +**Sinais:** nome de cliente, "#" + numero, "tarefas abertas", "horas", "facturas", "tickets" + +**Fontes:** Directo ao **Desk CRM** via MCP: +- `get_tasks`, `get_projects`, `get_tickets`, `get_customers` +- `get_timesheets`, `get_invoices`, `get_estimates` + +**NLM e Hub NAO entram** — nao veem estado vivo. + +### 7. Decisao / historico (porque fizemos X, quando decidimos Y) + +**Sinais:** "decisao", "porque fizemos", "historico de", "quando decidimos", "ultima vez que" + +**Fontes (paralelo):** +1. **Supabase** — `search_memories(query, threshold=0.5, limit=8)` [graceful] +2. **CC memory cross-projecto** — `Grep` em `~/.claude/projects/*/memory/*.md` +3. **Desk CRM discussions** — `get_discussion_comments` (#31 worklogs, #32 reflexoes, #33 accoes) +4. **Git log** — `git log --oneline --grep="keyword"` nos repos relevantes + +### 8. Codigo / projecto (o que mudou, como esta o repo) + +**Sinais:** "changelog", "ultimo commit", "o que mudou em", "estado do repo" + +**Fontes:** +1. `Read` CHANGELOG.md do projecto +2. `git log` do repo +3. CC memory do projecto especifico + +--- + +## Classificador de pergunta (heuristica) + +| Sinal | Tipo | +|-------|------| +| ID, path, porta, comando concreto | **1. Facto rapido** | +| "como funciona", "como configurar", "melhores praticas" | **2. Referencia tecnica** | +| "endpoint", "API", "payload" | **3. API** | +| "procedimento", "PROC", "como fazemos internamente" | **4. Processo** | +| "erro", "nao funciona", "problema" | **5. Troubleshooting** | +| Cliente, tarefa #N, ticket, factura, horas | **6. Estado actual** | +| "decisao", "porque", "historico", "ultima vez" | **7. Decisao/historico** | +| "changelog", "commit", "repo" | **8. Codigo** | +| **Ambiguo** | **Perguntar ao utilizador** | + +--- + +## Formato de resposta + +```markdown +## [pergunta] + +**[Fonte 1]:** [excerto] _(origem especifica)_ +**[Fonte 2]:** [excerto] _(origem especifica)_ + +**Sintese:** [consolidacao em 2-3 frases citando as fontes mais fortes] +``` + +Origens possiveis: `QR:ficheiro`, `NLM:notebook`, `KB:ficheiro`, `API:ficheiro`, `PROC:codigo`, `Manual:ficheiro`, `Troubleshooting:ficheiro`, `memory/projecto:ficheiro`, `Supabase:id`, `Desk CRM:task #N`, `Git:commit` + +**Regra:** nunca responder sem citar fonte. Se 0 fontes, dizer explicitamente. + +--- + +## Comandos + +| Comando | Uso | +|---------|-----| +| `/knowledge [pergunta]` | Router automatico por tipo | +| `/kb [pergunta]` | Alias curto | +| `/kb-save [conteudo]` | Guardar na fonte adequada (ver abaixo) | +| `/kb-gaps` | Listar lacunas detectadas em Supabase | + +--- + +## Gravar conhecimento (/kb-save) + +| Tipo | Destino | Tool | +|------|---------|------| +| Decisao / solucao tecnica / workaround | Supabase | `save_memory` com tags `[tipo, dominio, projecto?, data]` | +| Feedback / regra estavel | CC memory | `Write` em `~/.claude/projects/*/memory/` | +| Procedimento operacional | Hub PROCs | `Write` PROC-*.md | +| Referencia rapida (ID, path) | Hub QR | `Edit` QR-*.md | +| Conhecimento externo | NotebookLM | `source_add` no notebook adequado | + +--- + +## Deteccao de lacunas + +Quando 0 hits uteis em todas as fontes consultadas para o tipo: + +```javascript +mcp__mem0__save_memory({ + content: `LACUNA: "${query}" — tipo ${tipo}, 0 hits`, + tags: ["lacuna-kb", tipo, dominio] +}); +``` + +Sugerir accao: criar PROC, actualizar QR, adicionar fonte a NLM, guardar em Supabase. + +--- + +## Regras operacionais + +1. **Classificar primeiro, consultar depois.** Nao despejar todas as fontes para todas as perguntas. +2. **Paralelismo obrigatorio** dentro de cada tipo quando ha multiplas fontes. +3. **Grep cross-projecto obrigatorio** para tipos 2, 5, 7 — `~/.claude/projects/*/memory/*.md`. +4. **Nunca responder sem citar fonte.** +5. **Max 2 notebooks NLM** por query (performance). +6. **Supabase sempre graceful** — se indisponivel ou 0 resultados, continuar com outras fontes. +7. **Estado presente = Desk CRM directo** — nunca NLM/Hub para tarefas/facturas/tickets. +8. **PT-PT sempre.** + +--- + +## Anti-patterns + +- Consultar NLM para "quantas tarefas abertas tem o projecto X" (estado vivo → Desk CRM) +- Fazer grep generico em `Hub/**/*.md` quando a pergunta e claramente sobre um QR especifico +- Consultar Supabase como unica fonte (usar como complemento, nao alicerce) +- Classificar "como funciona o nosso router /knowledge" como referencia externa (e interno → CC memory + Hub) +- Ignorar CC memory cross-projecto (harness so carrega cwd) +- Disparar 5 fontes para um facto rapido que esta num QR (sequencial, parar ao hit) + +--- + +## Referencias + +- `~/.claude/plans/atomic-fluttering-flame.md` — plano RAG-System completo +- `~/.claude/projects/-media-ealmeida-Dados-Hub/memory/feedback_knowledge-router-arquitectura.md` — decisao arquitectural +- `~/.claude/projects/-media-ealmeida-Dados-Hub/memory/notebooklm-inventory.md` — inventario 65 notebooks NLM + +--- + +## Healing log + +```jsonl +{"date":"2026-04-08","issue":"v2.0.0 tratava NotebookLM como fonte primaria para tudo","fix":"v2.1.0 router Familia A/B — NotebookLM so para externo","source":"user"} +{"date":"2026-04-08","issue":"v2.1.0 assumia FastMCP file-based (11 tools lightrag_*)","fix":"v2.1.1 restaurado LightRAG-HKU 17 tools","source":"user"} +{"date":"2026-04-13","issue":"LightRAG com 0 docs, servico sem utilidade","fix":"v2.2.0 removido LightRAG da Familia A","source":"user"} +{"date":"2026-04-08","issue":"memoria CC fragmentada por projecto","fix":"grep cross-projecto obrigatorio","source":"user"} +{"date":"2026-04-13","issue":"Supabase degradado (stats/paginacao/embeddings raw)","fix":"MCP reparado — stats, paginacao e sanitize embeddings corrigidos. 6 registos com credentials eliminados","source":"fase-2"} +{"date":"2026-04-13","issue":"v2.2.0 modelo A/B subestimava Hub e NLM para queries operacionais","fix":"v3.0.0 router por tipo (8 rotas), Hub granular (QR/KB/APIs/Manuais/PROCs/Troubleshooting), NLM referencia tecnica primaria, Supabase complementar","source":"plano RAG-System"} +{"date":"2026-04-13","issue":"v3.0.0 nao tinha routing para frameworks (Next.js foi ao notebook errado), KB local subutilizado","fix":"v3.1.0 prioridade por tipo de tema (KB local > Context7 > NLM para frameworks), 13 ficheiros KB mapeados, 4 notebooks NLM adicionados, Context7 como fonte para docs oficiais","source":"testes fase 5"} +``` + +--- + +**v3.1.0** | 13-04-2026 | KB local mapeado (13 ficheiros), Context7 para docs oficiais, prioridade por tipo de tema, 19 notebooks NLM diff --git a/gestao/skills/knowledge/config/sources.json.tmp b/gestao/skills/knowledge/config/sources.json.tmp new file mode 100644 index 0000000..e69de29 diff --git a/gestao/skills/knowledge/docs/workflow.md b/gestao/skills/knowledge/docs/workflow.md index 13862e2..1a0f446 100644 --- a/gestao/skills/knowledge/docs/workflow.md +++ b/gestao/skills/knowledge/docs/workflow.md @@ -110,7 +110,7 @@ Params: ### WikiJS ``` -MCP: mcp__wikijs__search_pages +Fonte: /knowledge (router Hub QR/PROC) + mcp__mem0__search_memories Params: - query: [termo] Filtrar por paths relevantes do routing @@ -118,7 +118,7 @@ Filtrar por paths relevantes do routing ### Supabase ``` -MCP: mcp__mem_search_memories +MCP: mcp__mem0__search_memories Params: - query: [termo] Filtrar por tags do routing diff --git a/gestao/skills/knowledge/references/routing-guide.md b/gestao/skills/knowledge/references/routing-guide.md index 54e372d..a86ab56 100644 --- a/gestao/skills/knowledge/references/routing-guide.md +++ b/gestao/skills/knowledge/references/routing-guide.md @@ -10,7 +10,7 @@ Dify KB removido em 06-03-2026. NotebookLM e a fonte primaria. 1. **Classificar tema** da query usando keywords 2. **Seleccionar 1-3 notebooks** por ordem de relevancia 3. **Query sequencial** ate score >70 -4. **Enriquecer** com Mem0/Context7/Local se necessario +4. **Enriquecer** com Supabase/Context7/Local se necessario 5. **Reportar lacunas** se score <50 --- @@ -180,7 +180,7 @@ const notebookRouting = { obsidian: [ "ebee9fe1-78fd-4f85-8938-f19f3ea32131" // Obsidian + Claude (117) ], - decisao: [], // Mem0 primeiro, depois Obsidian notebook + decisao: [], // Supabase primeiro, depois Obsidian notebook // --- Produtos e Clientes --- reonic: [ @@ -250,10 +250,10 @@ async function pesquisar(query) { } // 3. Enriquecer com outras fontes - const mem0 = await mcp__mem_search_memories({ - query + const supabase = await mcp__memory_supabase__search_memories({ + query, tags: temas }); - if (mem0.length > 0) resultados.push({ resultado: mem0, fonte: 'Mem0' }); + if (supabase.length > 0) resultados.push({ resultado: supabase, fonte: 'Supabase' }); // 4. Context7 para temas dev if (temas.some(t => ['programacao', 'claude', 'mcp_dev', 'wordpress'].includes(t))) { @@ -273,8 +273,9 @@ async function pesquisar(query) { // 5. Resultado if (resultados.length === 0) { // Lacuna detectada - await mcp__mem_save_memory({ - text: `LACUNA: Query "${query}" sem informacao. Temas: ${temas.join(', ')}` + await mcp__memory_supabase__save_memory({ + content: `LACUNA: Query "${query}" sem informacao.`, + metadata: { type: 'lacuna-kb', temas, query } }); return { lacuna: true, query, temas }; } @@ -292,7 +293,7 @@ async function pesquisar(query) { | Fonte | MCP | Quando Usar | |-------|-----|-------------| -| **Mem0** | mem0 | Decisoes, contexto, historico sessoes | +| **Mem0 (Tier 2)** | mem0 | Decisoes, contexto, historico sessoes | | **Context7** | context7 | Docs bibliotecas externas (npm, pip, etc.) | | **Docs Locais** | filesystem (Grep/Glob) | Codigo em /Dev/, docs em /Hub/ | diff --git a/gestao/skills/mindmap/SKILL.md b/gestao/skills/mindmap/SKILL.md index 10c1116..2ff17ca 100644 --- a/gestao/skills/mindmap/SKILL.md +++ b/gestao/skills/mindmap/SKILL.md @@ -2,7 +2,6 @@ name: mindmap description: Gera ficheiros .km (mindmap) compatíveis com DesktopNaotu/Kityminder. Cria mindmaps a partir de tópicos, planos, brainstorms ou qualquer estrutura hierárquica. Usar quando "mindmap", "mapa mental", "naotu", "criar mindmap", "brainstorm visual". disable-model-invocation: true -layer: wiki --- # Mindmap Generator - DesktopNaotu diff --git a/gestao/skills/monday-briefing/SKILL.md b/gestao/skills/monday-briefing/SKILL.md index 6a8be10..a25c627 100644 --- a/gestao/skills/monday-briefing/SKILL.md +++ b/gestao/skills/monday-briefing/SKILL.md @@ -2,7 +2,6 @@ name: monday-briefing description: Briefing semanal automatizado com 4 componentes — tendências de mercado, métricas chave, acção da semana e contra-argumentos. Usar quando "monday", "briefing segunda", "resumo semanal", "briefing semana", "monday briefing". context: fork -layer: wiki --- # /monday-briefing v1.0 @@ -171,4 +170,86 @@ Impacto potencial: [curto resumo] **Sobre as métricas (secção 2):** - [Contra-argumento]: A variação de [±Z%] pode ser [sazonalidade / evento pontual / dado incompleto] -- Atenção: [Métrica Y] está a [subir/descer] — \ No newline at end of file +- Atenção: [Métrica Y] está a [subir/descer] — verificar se é tendência real ou ruído + +**Sobre a acção (secção 3):** +- [Contra-argumento]: A acção proposta assume que [pressuposto] — validar antes de executar +- Risco principal: [O que pode correr mal e como mitigar] +- Alternativa mais simples: [Versão reduzida da acção com menor risco] + +--- + +*Próximo briefing: Segunda, {data_prox_segunda} 09:00* +*Para agendar: `/schedule "monday-briefing" cron:"0 9 * * 1"`* +``` + +--- + +## Envio Automático (opcional) + +``` +SE argumento "email": + mcp__google-workspace__gmail_send_email({ + to: "emanuelalmeidaa@gmail.com", + subject: "Monday Briefing — {periodo_atual}", + body: {output_markdown_acima}, + format: "html" + }) + +SE argumento "inbox" OU sem argumento: + Guardar em: /media/ealmeida/Dados/Hub/00-Inbox/monday-briefing-{YYYY-MM-DD}.md + Formato: frontmatter YAML + conteúdo markdown + +SE argumento "terminal": + Mostrar directamente no terminal (default) +``` + +--- + +## Como Agendar + +Para receber automaticamente todas as segundas às 9h: + +```bash +# Via skill /schedule: +/schedule "monday-briefing" cron:"0 9 * * 1" +``` + +--- + +## Fontes de Dados + +| Fonte | MCP / Ferramenta | Dados | +|-------|-----------------|-------| +| Desk CRM | `mcp__desk-crm-v3` | Tarefas, tickets, timesheets, leads, propostas | +| Moloni | `mcp__moloni-mcp` | Facturação semanal | +| Google Calendar | `mcp__google-workspace` | Agenda da semana | +| Tendências | `WebSearch` | Novidades mercado digital | +| Google Analytics | n8n BI workflow | Sessions, conversões (a configurar) | +| Google Search Console | GSC MCP (quando disponível) | Keywords, cliques orgânicos | + +> GA4 e GSC: quando MCPs dedicados estiverem configurados, adicionar ao Passo 2[A]. Ver `/n8n-webhook` para workflow BI existente. + +--- + +## Anti-Patterns + +- NUNCA bloquear o briefing por falta de dados GA4/GSC — usar "N/D" e continuar +- NUNCA inventar tendências — apenas WebSearch com fontes verificáveis +- NUNCA recomendar mais de 1 acção na secção 3 (Growth Hacker) +- SEMPRE usar mcp-time para calcular períodos (nunca assumir datas) +- SEMPRE incluir secção Reality Checker — é o que diferencia este briefing + +--- + +## Healing Log + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* + +--- + +*Skill v1.0.0 | 07-04-2026 | Descomplicar®* diff --git a/gestao/skills/notebooklm/SKILL.md b/gestao/skills/notebooklm/SKILL.md index 4f87ba4..ef18551 100644 --- a/gestao/skills/notebooklm/SKILL.md +++ b/gestao/skills/notebooklm/SKILL.md @@ -2,7 +2,6 @@ name: notebooklm description: Gestão programática completa do NotebookLM via MCP. Gerir notebooks, adicionar fontes, gerar artefactos (áudio, vídeo, mindmap, relatório, flashcards, quiz, infografia, apresentação), consultar via RAG, investigação autónoma. Usar quando "notebooklm", "notebook", "audio overview", "podcast", "adicionar fonte", "gerar artefacto". disable-model-invocation: true -layer: wiki --- # /notebooklm - Gestão Programática NotebookLM @@ -97,4 +96,311 @@ Motor RAG Gemini com geração de artefactos multimédia. 29 ferramentas MCP dis ### Clientes / Projectos (3) | Nome | ID | Fontes | -|------| \ No newline at end of file +|------|----|--------| +| **CarStuff** | `90f0bc77-b5e4-4ddd-a07c-013a1a30b247` | 25 | +| **Solar FV Engenharia** | `03d54e00-aefa-45dc-ba01-f3864a7c3112` | 5 | +| **OpenSolar Platform** | `0082bcaf-1e17-4b84-87cc-2256b1719b55` | 4 | + +--- + +## Comandos + +| Comando | Uso | +|---------|-----| +| `/notebooklm list` | Listar todos os notebooks | +| `/notebooklm query ` | Consulta RAG num notebook | +| `/notebooklm add ` | Adicionar fonte (url/file/text/drive) | +| `/notebooklm studio ` | Gerar artefacto | +| `/notebooklm research ` | Investigação autónoma web | +| `/notebooklm create ` | Criar novo notebook | + +--- + +## Studio — Artefactos + +| Tipo (`artifact_type`) | Parâmetros Chave | Output | Tempo | +|------------------------|-----------------|--------|-------| +| `audio` | `format`: deep_dive, brief, critique, debate | MP3 | 3-7 min | +| `video` | `format`: explainer, brief | MP4 | 5-12 min | +| `mind_map` | — | Markdown/JSON | <1 min | +| `report` | `report_format`: Briefing Doc, Study Guide, Blog Post | Markdown/Docs | 1-2 min | +| `flashcards` | `difficulty`: hard, easy | JSON/HTML | <1 min | +| `quiz` | `question_count`: Integer | JSON/HTML | <1 min | +| `infographic` | `orientation`: 1=Landscape, 2=Portrait | PNG/SVG | 2-4 min | +| `slide_deck` | `orientation`, `visual_style` (1-10), `language`, `length` | PDF | 2-5 min | +| `data_table` | — | CSV/JSON/Sheets | 1-2 min | + +### Workflow Geração de Artefacto + +``` +1. studio_create(notebook_id, artifact_type, ..., confirm=True) + → devolve artifact_id + +2. POLLING: studio_status(artifact_id) + → repetir cada 20s até status="complete" + +3a. download_artifact(artifact_id) → ficheiro local (MP3/MP4/JSON/MD) +3b. export_artifact(artifact_id) → Google Docs/Sheets +``` + +--- + +## Gestão de Fontes + +### Adicionar fonte + +```python +# URL +source_add(notebook_id, source_type="url", url="https://...", wait=True) + +# Ficheiro local (PDF, MD, TXT) +source_add(notebook_id, source_type="file", file_path="/caminho/absoluto", wait=True) + +# Texto directo +source_add(notebook_id, source_type="text", text="...", title="Título", wait=True) + +# Google Drive +source_add(notebook_id, source_type="drive", document_id="gdrive-id", wait=True) +``` + +**Regra crítica:** Usar sempre `wait=True`. Sem isso o NotebookLM reporta sucesso mas o conteúdo não está indexado. + +### Actualizar fontes Drive + +```python +source_sync_drive(notebook_id, confirm=True) +``` + +Para PDFs/URLs não Drive: `source_delete` + `source_add` da versão nova. + +--- + +## Consulta RAG (notebook_query) + +### Padrão Drill-Down para documentos extensos + +``` +Passo 1 — Topologia: + "Mapeia a estrutura deste documento, identifica os capítulos sobre [tema]." + +Passo 2 — Cirúrgico: + "Centra a análise em [secção específica]. Detalha [aspecto concreto]." + +Passo 3 — Síntese externa: + Claude agrega as respostas parciais no seu próprio contexto. +``` + +### Multi-notebook (sem suporte nativo) + +O NotebookLM não faz queries cross-notebook. Workflow: +``` +1. notebook_query(notebook_A, pergunta) +2. notebook_query(notebook_B, pergunta) +3. Claude sintetiza os dois resultados localmente +``` + +### Rate limiting + +~50 queries/dia em contas gratuitas. Contas Workspace: sem limite documentado. + +--- + +## Investigação Autónoma + +```python +# 1. Iniciar pesquisa +research_start( + notebook_id="uuid", + query="tendências telemedicina Portugal 2026", + mode="deep", # fast (~30s, 10 fontes) | deep (~5min, 40+ fontes) + source_type="web" # web | drive +) +# → devolve task_id + +# 2. Polling +research_status(task_id) # repetir até status="complete" + +# 3. Importar resultados +research_import(notebook_id, task_id) +``` + +**Atenção:** Iniciar nova pesquisa cancela qualquer pesquisa em curso no mesmo notebook. + +--- + +## Casos de Uso Descomplicar + +### Investigação técnica de plugin/tecnologia + +``` +1. Scraper → MDs em Hub/Manuais/ +2. source_add(files) → notebook_create ou existente +3. notebook_query drill-down → extracção de padrões +4. studio_create(mind_map) → exportar para Obsidian +5. studio_create(audio, deep_dive) → consumo em mobilidade +``` + +### Onboarding novo projecto + +``` +1. notebook_create("Cliente - NomeProjecto") +2. source_add(contratos PDF + requisitos WikiJS) +3. notebook_share_invite(emails equipa + cliente) +4. studio_create(report, "Briefing Doc") → resumo executivo +``` + +### Proposta comercial + +``` +1. notebook_query → extrair capacidades relevantes +2. studio_create(data_table) → export_artifact → Google Sheets comparativo +3. studio_create(slide_deck, orientation=1, visual_style=1, language="pt") → esqueleto apresentação +``` + +### Rotina /today + +``` +notebook_query(Gestão de Operações, "3 métricas críticas com desvios hoje") +→ studio_create(audio, brief) → MP3 para consumo rápido +``` + +### Questionários de validação + +``` +studio_create(quiz, question_count=15) → JSON +→ n8n lê JSON → cria tasks Desk CRM para engenheiros +``` + +--- + +## Gestão de Notebooks + +```python +# Listar +notebook_list() + +# Metadados + fontes +notebook_get(notebook_id) + +# Resumo IA com keywords +notebook_describe(notebook_id) + +# Criar +notebook_create(name="Nome do Notebook") + +# Partilha pública +notebook_share_public(notebook_id) + +# Partilha por convite +notebook_share_invite(notebook_id, email="user@domain.com") + +# Eliminar (irreversível) +notebook_delete(notebook_id, confirm=True) +``` + +--- + +## Integração n8n + +O NotebookLM não tem API REST pública. Comunicar via JSON-RPC para o servidor MCP local: + +``` +NOTEBOOKLM_MCP_TRANSPORT=http +NOTEBOOKLM_MCP_HOST=0.0.0.0 +NOTEBOOKLM_MCP_PORT=8000 +``` + +### Flows úteis + +**WikiJS → NotebookLM (ingestão dinâmica):** +``` +Webhook (publicação WikiJS) +→ HTTP Request: source_add(source_type="text", wait=True) +→ Notificação Slack: "Nova doc indexada no RAG" +``` + +**Relatório semanal de projecto:** +``` +Schedule (sexta 17h) +→ Desk CRM: extrair tasks semana +→ source_add(text) → studio_create(report, "Briefing Doc") +→ Polling studio_status +→ export_artifact → Google Docs +→ Link enviado para Slack do cliente +``` + +**Audio após actualização de manual:** +``` +Drive webhook +→ source_sync_drive +→ studio_create(audio, deep_dive) +→ Polling + download_artifact +→ Email com MP3 anexo +``` + +--- + +## Limitações + +| Limitação | Workaround | +|-----------|-----------| +| ~50 queries/dia (conta gratuita) | Usar conta Workspace; fallback Dify KB | +| Sem API REST oficial | JSON-RPC via servidor MCP local | +| Sem queries cross-notebook | Claude agrega respostas de múltiplos notebooks | +| Cookies expiram (2-4 semanas) | `refresh_auth()` automático; alertar se HTTP 401/499 | +| Slides com marca de água | Pós-processamento `clean-watermark.js` via n8n | +| Ficheiros estáticos imutáveis | `source_delete` + `source_add` para actualizar | +| `research_start` exclusivo | Só uma pesquisa activa por notebook de cada vez | +| Dados de treino Gemini | Workspace Enterprise: dados isentos de treino | + +--- + +## Autenticação + +```bash +# Verificar estado +nlm login status + +# Renovar tokens +mcp__notebooklm__refresh_auth() + +# Versão do servidor +mcp__notebooklm__server_info() +``` + +Auth guardada em: `~/.notebooklm-mcp-cli/profiles//auth.json` + +--- + +## Roadmap de Adopção + +**Fase 1 — Quick wins (<1 semana)** +- [ ] Conta Google Workspace dedicada a automações +- [ ] Servidor MCP em EasyPanel (projecto: descomplicar) +- [ ] Primeiro audio overview de manual técnico + +**Fase 2 — Integrações (1-4 semanas)** +- [ ] n8n: ingestão dinâmica WikiJS → NotebookLM +- [ ] n8n: relatório semanal /today automático +- [ ] Claude Code: queries drill-down nos notebooks existentes + +**Fase 3 — Escala (1-3 meses)** +- [ ] Notebook por cliente (criado automaticamente no Desk CRM) +- [ ] Quizzes de onboarding injectados em tarefas Desk CRM +- [ ] Research autónomo semanal: panorama competitivo por área + +--- + +**Versão**: 1.0.0 | **Data**: 24-02-2026 | **Autor**: 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ós cada erro corrigido.* diff --git a/gestao/skills/office-hours/SKILL.md b/gestao/skills/office-hours/SKILL.md index edde587..0a43720 100644 --- a/gestao/skills/office-hours/SKILL.md +++ b/gestao/skills/office-hours/SKILL.md @@ -4,7 +4,6 @@ description: > Persona YC que reframe problemas antes de escrever código. Desafia pressupostos, faz as perguntas difíceis que um investidor faria. Usar ANTES de qualquer implementação significativa. Baseado no gstack /office-hours. Eixo 2B. -layer: wiki --- # /office-hours — Consulta YC antes de Codar diff --git a/gestao/skills/onboarding/SKILL.md b/gestao/skills/onboarding/SKILL.md index ec07e4b..08e472f 100644 --- a/gestao/skills/onboarding/SKILL.md +++ b/gestao/skills/onboarding/SKILL.md @@ -5,7 +5,6 @@ description: "Checklist e automacao de onboarding de novo colaborador. Criacao d version: "1.0.0" created: 2026-04-07 tools: [mcp__desk-crm-v3__create_task, mcp__desk-crm-v3__add_task_checklist_item, mcp__google-workspace__gmail_send_email] -layer: wiki --- # Skill: /onboarding diff --git a/gestao/skills/proc-creator/SKILL.md b/gestao/skills/proc-creator/SKILL.md index 01885ef..6bc58eb 100644 --- a/gestao/skills/proc-creator/SKILL.md +++ b/gestao/skills/proc-creator/SKILL.md @@ -2,7 +2,6 @@ name: proc-creator description: Cria procedimentos seguindo formato Hub Descomplicar. Gera código automático [DEPT]-[TEMA]-[NUM], cria ficheiro na pasta departamental correcta, actualiza INDEX.md. Usar quando "criar procedimento", "novo PROC", "documentar processo", "PROC-*". disable-model-invocation: true -layer: wiki --- # /proc-creator - Criador de Procedimentos Hub @@ -236,4 +235,144 @@ tags: [categoria, tema, tecnologia] ## Actualização INDEX.md -Adicionar linha na tabela d \ No newline at end of file +Adicionar linha na tabela do departamento: + +```markdown +| [PROC-Titulo.md](./PROC-Titulo.md) | [Descrição breve] | [DEPT]-[TEMA]-[NUM] | +``` + +Actualizar estatísticas: +- Incrementar contador "X procedimentos" +- Actualizar data "Última actualização: YYYY-MM-DD" + +--- + +## Integração com Skills/Agents + +Após criar procedimento, informar utilizador: + +```markdown +**Próximos passos:** + +1. Preencher conteúdo do procedimento +2. Testar procedimento em cenário real +3. Actualizar status: draft → active +4. Adicionar referências em skills/agents relevantes: + +\`\`\`markdown +## Referências e Documentação + +**SEMPRE consultar:** +- [PROC-Titulo.md](file:///media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/[Dept]/PROC-Titulo.md) +\`\`\` +``` + +--- + +## Exemplos de Uso + +### Exemplo 1: Procedimento Técnico D7 + +``` +User: Criar procedimento para deployment EasyPanel +Assistant: /proc-creator + +Título: Deployment EasyPanel via API +Departamento: D7-Tecnologia +Tema: Infraestrutura (INF) +Descrição: Deploy automatizado de serviços no EasyPanel usando API oficial + +→ Código gerado: INF-EPL-001 +→ Ficheiro: PROC-Deployment-EasyPanel.md +→ Localização: D7-Tecnologia/ +→ INDEX.md actualizado +``` + +### Exemplo 2: Procedimento Cross-Departamental + +``` +User: Documentar processo de gestão de projectos +Assistant: /proc-creator + +Título: Sistema Gestão Projectos +Departamento: Cross-Departamental +Tema: Gestão Projectos (GPR) +Descrição: Metodologia híbrida Ágil/Waterfall + +→ Código gerado: XDP-GPR-002 (já existe 001) +→ Ficheiro: Sistema-Gestao-Projectos-v2.md +→ Localização: Cross-Departamental/ +→ INDEX.md actualizado +``` + +### Exemplo 3: Procedimento D2-Suporte (Gap) + +``` +User: Criar procedimento atendimento cliente +Assistant: /proc-creator + +Título: Atendimento Cliente +Departamento: D2-Suporte +Tema: Suporte (SUP) +Descrição: Workflow primeiro contacto, templates resposta, escalação + +→ Código gerado: SUP-ATC-001 (primeiro do D2!) +→ Ficheiro: PROC-Atendimento-Cliente.md +→ Localização: D2-Suporte/ +→ INDEX.md actualizado +→ NOTA: D2 tinha 0 procedimentos, agora tem 1 +``` + +--- + +## Anti-Patterns + +**NUNCA:** +- ❌ Criar procedimento sem perguntar departamento +- ❌ Inventar código sem verificar INDEX.md +- ❌ Esquecer de actualizar INDEX.md +- ❌ Usar status "active" para draft inicial +- ❌ Omitir frontmatter obrigatório +- ❌ Criar em localização errada +- ❌ Duplicar NUM existente no mesmo tema + +**SEMPRE:** +- ✅ Confirmar departamento com utilizador +- ✅ Ler INDEX.md para próximo NUM +- ✅ Actualizar INDEX.md após criação +- ✅ Usar status "draft" inicialmente +- ✅ Incluir todo frontmatter obrigatório +- ✅ Criar em pasta departamental correcta +- ✅ Verificar tema antes de atribuir NUM + +--- + +## Validação Pós-Criação + +Checklist automática: + +``` +✅ Ficheiro criado em pasta correcta +✅ Frontmatter completo e válido +✅ Código único e sequencial +✅ INDEX.md actualizado +✅ Template aplicado +✅ Path absoluto correcto +✅ Data actual em YYYY-MM-DD +``` + +--- + +*Skill v1.0.0 | 2026-02-13 | Plugin gestao | 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ós cada erro corrigido.* diff --git a/gestao/skills/qw/README.md b/gestao/skills/qw/README.md new file mode 100644 index 0000000..22c5afd --- /dev/null +++ b/gestao/skills/qw/README.md @@ -0,0 +1,88 @@ +# /qw — Quick Wrap-up + +Recapitulação rápida de sessão. Resumo + actualização de docs + memória mem0. + +## Uso Rápido + +```bash +/qw # Recapitulação completa +/qw --docs # Apenas actualizar docs +/qw --mem # Apenas guardar memória mem0 +``` + +## O Que Faz + +| Função | Tempo | Output | +|--------|-------|--------| +| **Resumo** | <30s | 3 bullets do trabalho realizado | +| **Docs** | <30s | Actualiza README/CHANGELOG | +| **Memória** | <30s | Cria entrada mem0 com protocolo Wayland v2 | + +## Exemplo Prático + +**Situação:** Acabaste de criar a skill `/qw` em 45 minutos. + +``` +/qw +``` + +**Output Automático:** +``` +✅ Quick Wrap-up — 2026-07-02 16:45 + +📝 RESUMO +• SKILL.md criada — skill /qw para recapitulação rápida de sesões +• Docs actualizados — plugin.json v1.5.0, CHANGELOG com entrada +• Memória guardada — mem0 Wayland v2 com tags skill,gestao + +📦 FICHEIROS ALTERADOS + + ~/.claude/plugins/.../gestao/skills/qw/SKILL.md + + ~/.claude/plugins/.../gestao/skills/qw/README.md + ~ ~/.claude/plugins/.../gestao/CHANGELOG.md + +💾 MEM0 + ID: mem0_xyz1234567890 + Entrada: "Skill /qw criada | propósito | recapitulação rápida sesões" + Tags: skill, gestao + Tier: global + +⏱️ Duração: 42s | Estado: OK ✓ +``` + +## Diferenças: /qw vs /worklog + +| Aspecto | `/qw` | `/worklog` | +|---------|-------|-----------| +| **Tempo** | <2 min | ~5-10 min | +| **Resumo** | 3 bullets max | Análise profunda | +| **Docs** | Básico (README) | Completo + higienização OKF | +| **Memória** | mem0 simple | Mem0 + insights profundos | +| **Uso** | Sesões curtas, tarefas isoladas | Fim de trabalho, reflexão | +| **Git commit** | Omitido | Automático se hub/.desk-project | + +## Configuração + +- **Execução:** Inline (nunca fork) +- **Staff ID:** 25 (Claude — ou o do utilizador) +- **MCP:** mem0 (gateway.descomplicar.pt) +- **Plugin:** gestao +- **Skill:** qw + +## Protocolo Mem0 + +Wayland v2 (Semantic P3): + +```json +{ + "subject": "Skill /qw criada", + "predicate": "propósito", + "object": "recapitulação rápida sesões", + "tags": ["skill", "gestao"], + "tier": "global", + "maxLength": 80 +} +``` + +--- + +**Versão:** 1.0 | **Data:** 2026-07-02 | **Autor:** Claude (staff_id 25) diff --git a/gestao/skills/qw/SKILL.md b/gestao/skills/qw/SKILL.md new file mode 100644 index 0000000..d4b9279 --- /dev/null +++ b/gestao/skills/qw/SKILL.md @@ -0,0 +1,134 @@ +--- +name: qw +description: "Recapitulação rápida de sessão — resumo conciso do trabalho feito, actualização de docs e memória mem0. Uso: /qw ao finalizar tarefa ou sessão curta. Complemento leve ao /worklog." +--- + +# /qw v1.0 — Quick Wrap-up (Recapitulação Rápida) + +**⚠️ EXECUÇÃO INLINE OBRIGATÓRIA — NUNCA FORK** + +Protocolo simples e rápido (máx 2 min) para fechar sesões curtas ou tarefas isoladas. Complemento ao `/worklog` (pesado). + +--- + +## Comandos + +| Comando | Função | +|---------|--------| +| `/qw` | Recapitulação rápida + mem0 | +| `/qw --docs` | Actualizar docs (README, CHANGELOG) | +| `/qw --mem` | Guardar memória mem0 apenas | + +--- + +## Protocolo Principal (/qw) + +``` +1. Obter hora actual (mcp__mcp-time__current_time) +2. RESUMIR sessão em máx 3 bullets: + - Ficheiro(s) modificado(s) + linha brevíssima do quê + - Problema resolvido / Tarefa finalizada + - Padrão/insight (se relevante) +3. ACTUALIZAR docs (escolher 1): + a. Se ficheiro novo: adicionar linha ao README (secção "Estrutura" ou similar) + b. Se ficheiro existente alterado: actualizar CHANGELOG (formato: - YYYY-MM-DD Descrição) + c. Se nenhum doc relevante: omitir +4. GUARDAR memória mem0: + - Tipo: semantic (P3) — facto conciso e reutilizável + - Tags: mínimo 2 (ex: "task", "bugfix" ou "feature", "integracao") + - Conteúdo: "O que foi feito + resultado" (máx 80 chars) + - tier: global se cross-projecto, project se específico +5. OUTPUT: + - Resumo legível + - Ficheiros afectados + - Link memória (se criada) +``` + +--- + +## Exemplo de Uso + +**Input:** +``` +/qw +``` + +**Output (gerado automático):** +``` +✅ Quick Wrap-up — 2026-07-02 16:45 + +📝 RESUMO +• qw/SKILL.md criada — skill recapitulação rápida +• docs atualizados — README.md com link nova skill +• memória guardada (mem0) — meta skill gestao/qw + +📦 FICHEIROS + - ~/.claude/plugins/.../gestao/skills/qw/SKILL.md (novo) + - ~/.claude/plugins/.../gestao/README.md (actualizado) + +💾 MEM0 + ID: mem0_xyz... + "Criada skill /qw para recapitulação sessões curtas" + Tags: skill, gestao + +--- +⏱️ Duração: 45s | Estado: OK +``` + +--- + +## Storage + +Memória mem0 (gateway.descomplicar.pt/v1/mem0/mcp): +- **Protocolos:** Wayland v2 (P5/P4/P3, tags, tier) +- **Limite:** máx 80 chars por entrada +- **Dedup:** pesquisar com `mcp__mem_search_memories` antes de gravar (IJFW foi descontinuado e removido — Mem0 é o único store canónico) +- **Tier:** `global` para skill/padrão cross-projecto, `project` para específico + +--- + +## Variantes + +### `/qw --docs` (Actualizar Docs) +Apenas actualiza README/CHANGELOG sem resumo: +``` +- Procura README ou CHANGELOG na pasta actual (até 2 níveis acima) +- Insere/actualiza entrada +- Omite memória e resumo +``` + +### `/qw --mem` (Memória Apenas) +Apenas guarda mem0, sem resumo: +``` +- Pede prompt: "Qual o insight para guardar?" +- Formata e guarda via mem0 MCP +- Output: ID memória apenas +``` + +--- + +## Integração com Plugin gestao + +Local: `~/.claude/plugins/marketplaces/descomplicar-plugins/gestao/skills/qw/` + +Ficheiros: +- `SKILL.md` — este ficheiro +- `prompts/` — templates de prompts (se necessário) + +Regra CLAUDE.md: Skills gestao executam INLINE (nunca fork). Sem subagentes. + +--- + +## Checklist Implementação + +- [x] SKILL.md criada +- [ ] Skill registada em plugin.json (gestao) +- [ ] Prompts adicionados (se necessário) +- [ ] Teste manual: `/qw` +- [ ] Teste com --docs flag +- [ ] Teste com --mem flag +- [ ] Validação mem0 (verificar entrada criada) + +--- + +**Versão:** 1.0 | **Data:** 2026-07-02 | **Plugin:** gestao | **Staff:** 25 (Claude) diff --git a/gestao/skills/qw/prompts/base.md b/gestao/skills/qw/prompts/base.md new file mode 100644 index 0000000..4cc13fd --- /dev/null +++ b/gestao/skills/qw/prompts/base.md @@ -0,0 +1,82 @@ +# Prompt Base — /qw Quick Wrap-up + +## Sistema + +Tu és a instância Claude Code, execução INLINE. Tarefa: gerar recapitulação rápida de sessão. + +**Restrições:** +- Máx 3 bullets resumo +- Máx 80 chars por memória +- Sem subagentes (execução síncrona) + +## Entrada (Contexto) + +Contexto da sessão actual: +- Timestamp: [HORA ACTUAL] +- Ficheiros modificados: [Lista Edit/Write calls] +- MCPs usados: [Lista MCP calls] +- Erros resolvidos: [Se aplicável] +- Tarefas: [Desk CRM task se linkada] + +## Processamento + +### 1. Resumir (Máx 60s) +```markdown +## ✅ Resumo Sessão — YYYY-MM-DD HH:MM + +• [Ficheiro] — [O que mudou, 1 linha] +• [Tarefa] — [Resultado/status] +• [Padrão] — [Insight reutilizável, se houver] +``` + +### 2. Actualizar Docs (Máx 30s) +``` +Se ficheiro NOVO: + README.md secção "Estrutura" → adicionar linha + +Se ficheiro ALTERADO: + CHANGELOG.md → linha em ## [Unreleased]: + - YYYY-MM-DD Descrição concisa +``` + +### 3. Memória mem0 (Máx 30s) +``` +- Protocolо Wayland v2 (P3 — fact) +- Sujeito | predicado | objecto +- Tags: mínimo 2 (task, feature, bugfix, integration, etc) +- Tier: global / project +- Exemplo: + "Skill /qw criada | propósito | recapitulação sessões curtas" +``` + +## Output Final + +``` +✅ Quick Wrap-up — [TIMESTAMP] + +📝 RESUMO +[3 bullets aqui] + +📦 FICHEIROS ALTERADOS +[Lista] + +💾 MEM0 +ID: [mem0_id] +Conteúdo: [entrada] + +⏱️ Duração: [segundos]s | Estado: OK +``` + +--- + +## Flags + +### `--docs` +Apenas actualizar docs (README, CHANGELOG). Omitir resumo. + +### `--mem` +Apenas guardar memória. Pedir prompt input: "Insight para guardar?" + +--- + +Versão: 1.0 | 2026-07-02 diff --git a/gestao/skills/qw/prompts/examples.md b/gestao/skills/qw/prompts/examples.md new file mode 100644 index 0000000..c26d5da --- /dev/null +++ b/gestao/skills/qw/prompts/examples.md @@ -0,0 +1,202 @@ +# Exemplos de Uso — /qw + +## Exemplo 1: Criar Ficheiro Novo + +**Contexto:** Acabaste de criar `novo-modulo.js` com 150 linhas. + +```bash +/qw +``` + +**Processamento automático:** +1. Detecta novo ficheiro: `novo-modulo.js` +2. Actualiza `README.md` secção "Estrutura" com: `- novo-modulo.js — módulo XYZ` +3. Cria memória mem0: + - Subject: "novo-modulo.js" + - Predicate: "criado para" + - Object: "funcionalidade XYZ" + - Tags: "feature", "javascript" + - Tier: "project" + +**Output:** +``` +✅ Quick Wrap-up — 2026-07-02 14:23 + +📝 RESUMO +• novo-modulo.js criado — 150 linhas, export default class XYZ +• README actualizado — secção Estrutura +• Memória guardada — mem0 (feature/javascript) + +📦 FICHEIROS + + novo-modulo.js + ~ README.md + +💾 MEM0 ID: mem0_abc123... + +⏱️ 38s | OK +``` + +--- + +## Exemplo 2: Bugfix + Docs + +**Contexto:** Corrigiste bug em `auth.js` linha 45 (return typo). + +```bash +/qw +``` + +**Processamento:** +1. Detecta ficheiro alterado: `auth.js` +2. Actualiza `CHANGELOG.md` em `## [Unreleased]`: + ``` + - 2026-07-02 [auth] Corrigido typo return em validação token + ``` +3. Memória mem0: + - Subject: "auth.js" + - Predicate: "bugfix" + - Object: "return typo validação token (linha 45)" + - Tags: "bugfix", "javascript" + +**Output:** +``` +✅ Quick Wrap-up — 2026-07-02 14:25 + +📝 RESUMO +• auth.js corrigido — typo return em validação token (linha 45) +• CHANGELOG actualizado — entrada [Unreleased] +• Memória guardada — mem0 (bugfix/javascript) + +📦 FICHEIROS + ~ auth.js + +💾 MEM0 ID: mem0_def456... + +⏱️ 22s | OK +``` + +--- + +## Exemplo 3: Usar Flag --docs + +**Contexto:** Já refiste 3 ficheiros mas esqueceste de actualizar README. + +```bash +/qw --docs +``` + +**Processamento:** +1. Detecta ficheiros alterados +2. Apenas actualiza README/CHANGELOG +3. Omite resumo e memória +4. Output minimalista + +**Output:** +``` +✅ Docs Updated — 2026-07-02 14:27 + +📦 FICHEIROS + ~ README.md + ~ CHANGELOG.md + +⏱️ 8s | OK +``` + +--- + +## Exemplo 4: Usar Flag --mem + +**Contexto:** Descobriste um padrão interessante durante a sessão. + +```bash +/qw --mem +``` + +**Processamento:** +1. Pede input: "Qual o insight para guardar?" +2. Utilizador responde: "Usar useCallback para memoização em loops React" +3. Formata e guarda em mem0 +4. Output: apenas ID memória + +**Output:** +``` +💾 MEM0 Saved + +ID: mem0_ghi789... +Entrada: "useCallback | memoização | loops React evita re-renders" +Tags: react, performance, padrão +Tier: global + +⏱️ 15s | OK +``` + +--- + +## Exemplo 5: Integração com Desk CRM + +**Contexto:** Estás a trabalhar na tarefa #2401 do Desk. + +```bash +/qw +``` + +**Processamento automático (se `.desk-project` detectado):** +1. Lê `.desk-project` → tarefa_id = 2401 +2. Gera resumo com link à tarefa +3. Memória mem0 inclui ref task_id + +**Output:** +``` +✅ Quick Wrap-up — 2026-07-02 14:30 + +📝 RESUMO +• Tarefa #2401 — implementação API endpoint /users +• Documentação atualizada — docs/api.md com endpoint spec +• Memória guardada — mem0 com ref task #2401 + +📦 FICHEIROS + + src/api/endpoints/users.js + ~ docs/api.md + +💾 MEM0 ID: mem0_jkl012... [task_id: 2401] + +⏱️ 35s | OK +``` + +--- + +## Exemplo 6: Nenhum Ficheiro Alterado + +**Contexto:** Tiveste uma sessão de investigação/leitura apenas (sem edições). + +```bash +/qw +``` + +**Processamento:** +1. Detecta: sem Edit/Write calls +2. Omite output (nada para registar) +3. Log silencioso: `[QW] Nada para registar — sessão leitura` + +**Output:** +``` +ℹ️ Quick Wrap-up + +Nenhum ficheiro alterado nesta sessão. Omitido. +``` + +--- + +## Checklist Implementação (Para Testar) + +- [ ] Criar novo ficheiro, rodar `/qw`, verificar README/CHANGELOG +- [ ] Editar ficheiro existente, rodar `/qw`, verificar CHANGELOG +- [ ] Testar `/qw --docs` (só docs) +- [ ] Testar `/qw --mem` (só memória, com input) +- [ ] Verificar mem0 entries criadas em gateway.descomplicar.pt +- [ ] Testar em projecto com `.desk-project` (task link) +- [ ] Testar sem alterações (nada para registar) + +--- + +**Versão:** 1.0 | 2026-07-02 diff --git a/gestao/skills/reflect/SKILL.md b/gestao/skills/reflect/SKILL.md index 715cc92..04bea72 100644 --- a/gestao/skills/reflect/SKILL.md +++ b/gestao/skills/reflect/SKILL.md @@ -1,7 +1,6 @@ --- name: reflect description: Alias de /worklog. Auto-reflexão e registo de trabalho unificado. /reflect = /worklog (mesmo resultado). /reflect view = ver últimos registos. /reflect deep = análise profunda com histórico → Discussão #32. /reflect week = revisão semanal → Discussão #32. Usar quando "reflect", "reflexão", "análise", "melhoria", "insight". -layer: wiki --- # /reflect - Alias de /worklog diff --git a/gestao/skills/report-5w2h/README.md b/gestao/skills/report-5w2h/README.md new file mode 100644 index 0000000..2c8e447 --- /dev/null +++ b/gestao/skills/report-5w2h/README.md @@ -0,0 +1,136 @@ +# /report — 5W2H + PDCA Report + +Estrutura formal de conclusão de tarefas/etapas com análise 5W2H + PDCA. + +## Uso Rápido + +```bash +/report # Report completo (interactivo) +/report --quick # Versão resumida (3 campos) +/report --auto # Auto-detectado de contexto +``` + +## O Que Faz + +| Função | Tempo | Output | +|--------|-------|--------| +| **5W2H** | <2 min | Tabela QUÊ/QUEM/QUANDO/ONDE/POR QUÊ/COMO/CUSTO | +| **PDCA** | <2 min | Ciclo Plan/Do/Check/Act | +| **Docs** | <1 min | README, CHANGELOG, PROC se relevante | +| **Memória** | <1 min | Entry mem0 Wayland v2 | +| **Desk** | <1 min | Comment em discussão #33 se .desk-project | + +## Exemplo + +```bash +/report +``` + +**Output:** +``` +# 5W2H Report — Criar skill /qw + +| Campo | Resposta | +|-------|----------| +| QUÊ | Skill /qw para recapitulação rápida sesões | +| QUEM | claude (staff_id 25) | +| QUANDO | 2026-07-02 16:00–16:45 (45 min) | +| ONDE | ~/.claude/plugins/.../gestao/skills/qw/ | +| POR QUÊ | Complemento /worklog para sesões curtas | +| COMO | Criação skill (SKILL.md + README + prompts) | +| CUSTO | Est: 30 min → Real: 45 min (+50% desvio) | + +## PDCA + +### PLAN +Objectivo: Skill recapitulação rápida de sesões curtas +Criteria: <2 min execução, mem0 integrado, docs actualizados +Scope: SKILL.md, README, 2 prompts + +### DO +• Criado SKILL.md com protocolo (v1.0) +• Criado README.md com guia + exemplos +• Criado prompts/base.md e examples.md (6 exemplos) +• Plugin gestao actualizado (v1.5.0) +• Desvio: Tempo +50% (escopo expandiu) + +### CHECK +✅ SKILL.md conforme template +✅ README com 3 flags +✅ Prompts documentados +✅ Plugin integrado +⚠️ Teste /qw ainda pendente + +### ACT +Próximo: Teste manual /qw +Validar mem0 entries criadas +Considerar symlink OpenCode +Documentar tempo real em CHANGELOG + +--- + +## MEM0 +ID: mem0_xyz123 +Entry: "Skill /qw criada | propósito | recapitulação rápida sesões" +Tags: skill, gestao, mem0, recapitulacao +Tier: global + +--- + +## DOCS UPDATED +✅ plugin.json (v1.4.0 → 1.5.0) +✅ CHANGELOG.md (entrada [1.5.0]) + +--- + +⏱️ Report: 2 min 15s | COMPLETO +``` + +## Integração CARL + +**Domínio:** TASK-COMPLETION-REPORT +**Triggers:** "concluído", "finalizado", "pronto", "terminado", "etapa completa" +**Auto-disparo:** Sim (sem confirmação necessária) + +## Estrutura 5W2H + +| Campo | Descrição | Exemplo | +|-------|-----------|---------| +| **QUÊ** | Deliverable/resultado | "Skill /qw criada" | +| **QUEM** | Executor (staff_id) | "claude (25)" | +| **QUANDO** | Timestamp início-fim | "16:00–16:45 (45 min)" | +| **ONDE** | Ficheiro/pasta/sistema | "~/.claude/plugins/.../gestao/" | +| **POR QUÊ** | Objectivo/motivação | "Complemento /worklog para sesões curtas" | +| **COMO** | Método/processo | "Criação skill com SKILL.md + README + prompts" | +| **CUSTO** | Tempo estimado vs real | "Est: 30 min → Real: 45 min (+50%)" | + +## Ciclo PDCA + +1. **PLAN** — Spec original, criteria de sucesso, scope +2. **DO** — Passos executados, decisões, desvios documentados +3. **CHECK** — Resultado vs criteria, gaps, testes +4. **ACT** — Ajustes necessários, próximas acções, melhorias + +## Flags + +### `--quick` +Report resumido — apenas 3 campos (QUÊ, COMO, RESULTADO). + +### `--auto` +Auto-detecta contexto: +- Git: commits e ficheiros alterados +- Desk: task_id e tempo loggado +- .desk-project: extrai dados de projecto +- Timer activo: usa duração real + +## Output + +- **Resumo visual:** Tabela 5W2H +- **Análise:** PDCA em markdown +- **Docs:** README/CHANGELOG/PROC actualizados +- **Memória:** Entry mem0 Wayland v2 criada +- **Desk:** Comment em #33 (se .desk-project) + +--- + +**Versão:** 1.0 | **Data:** 2026-07-02 | **Autor:** Claude (staff_id 25) diff --git a/gestao/skills/report-5w2h/SKILL.md b/gestao/skills/report-5w2h/SKILL.md new file mode 100644 index 0000000..9fed6e9 --- /dev/null +++ b/gestao/skills/report-5w2h/SKILL.md @@ -0,0 +1,236 @@ +--- +name: report +description: Report 5W2H+PDCA ao terminar tarefa/etapa — estrutura formal de conclusão com análise de resultados, documentação e memória. Integrado no domínio TASK-COMPLETION-REPORT do CARL. +--- + +# /report v1.0 — 5W2H + PDCA Report + +**⚠️ EXECUÇÃO INLINE OBRIGATÓRIA — NUNCA FORK** + +Protocolo formal ao terminar tarefa/etapa. Estrutura: 5W2H (QUÊ/QUEM/QUANDO/ONDE/POR QUÊ/COMO/CUSTO) + PDCA (Plan/Do/Check/Act). + +--- + +## Comandos + +| Comando | Função | +|---------|--------| +| `/report` | Report completo 5W2H+PDCA (interactivo) | +| `/report --quick` | Versão resumida (3 campos) | +| `/report --auto` | Auto-detectado de contexto (git, ficheiros, etc) | + +--- + +## Protocolo Principal (/report) + +``` +1. RECOLHER 5W2H (interactivo ou auto-detectado): + QUÊ → O que foi entregue/resultado (deliverable) + QUEM → Executor (staff_id 25 ou outro) + QUANDO → Timestamp início/fim + ONDE → Ficheiro/pasta/sistema/Desk task + POR QUÊ → Objectivo/motivação original + COMO → Método/processo aplicado + CUSTO → Tempo estimado vs. real (em minutos) + +2. RECOLHER PDCA (estruturado): + PLAN → Spec original, success criteria, scope + DO → Passos executados, decisões, desvios documentados + CHECK → Resultado vs. criteria, gaps detectados, testes + ACT → Ajustes necessários, próximas acções, melhorias + +3. DOCUMENTAR: + a. Se novo ficheiro/sistema → README secção "Estrutura" + b. Se processo → criar PROC-*.md em Hub/06-Operacoes/Procedimentos/ + c. CHANGELOG.md → linha em ## [Unreleased] com resumo + d. Se SEM docs relevantes → omitir + +4. GUARDAR MEM0 (Wayland v2): + - subject | predicate | object (máx 80 chars) + - tags: mínimo 2 (task, feature, bugfix, etc) + - tier: project ou global + - Dedup: pesquisar com mcp__mem_search_memories antes (IJFW descontinuado — Mem0 é o store canónico) + +5. GUARDAR EM DESK (se .desk-project detectado): + - Discussão #33 (Acções de Melhoria) + - Format:

5W2H Report — [tarefa/etapa]

...

+ - HTML estruturado com tabela 5W2H + PDCA + - staff_id: 25 + +6. OUTPUT: + - Resumo visual com tabela 5W2H + - PDCA análise em markdown + - Link memória/Desk se criado + - Timestamp execução +``` + +--- + +## Exemplo: Report Completo + +**Input:** +``` +/report +``` + +**Processamento (interactivo):** +``` +5W2H REPORT — Qual a tarefa/etapa? +> Criar skill /qw + +QUÊ (Deliverable)? +> Skill /qw com recapitulação rápida + mem0 + +QUEM (executor)? +> claude (staff_id 25) + +QUANDO (inicio/fim)? +> Auto-detectado: 16:00 - 16:45 (45 min) + +ONDE (ficheiro/sistema)? +> ~/.claude/plugins/.../gestao/skills/qw/ + +POR QUÊ (objectivo)? +> Complemento leve ao /worklog para sesões curtas + +COMO (método)? +> Criação skill (SKILL.md + README + prompts) + +CUSTO (estimado vs real)? +> Estimado: 30 min, Real: 45 min +``` + +**Output:** + +```markdown +# 5W2H Report — Criar skill /qw + +| Campo | Resposta | +|-------|----------| +| QUÊ | Skill /qw para recapitulação rápida | +| QUEM | claude (staff_id 25) | +| QUANDO | 2026-07-02 16:00–16:45 (45 min) | +| ONDE | ~/.claude/plugins/.../gestao/skills/qw/ | +| POR QUÊ | Complemento /worklog para sesões curtas | +| COMO | Criação skill (SKILL.md + README + prompts) | +| CUSTO | Est: 30 min → Real: 45 min (+50% desvio) | + +## PDCA + +### PLAN +- Objectivo: Skill recapitulação rápida +- Criteria: <2 min execução, mem0 integrado, docs actualizados +- Scope: SKILL.md, README, 2 prompts + +### DO +- Criado SKILL.md com protocolo (v1.0) +- Criado README.md com guia + exemplos +- Criado prompts/base.md e examples.md (6 exemplos) +- Plugin gestao actualizado (v1.5.0) +- Desvio: Tempo +50% (escopo expandiu com docs extras) + +### CHECK +- ✅ SKILL.md conforme template +- ✅ README com 3 flags +- ✅ Prompts documentados +- ✅ Plugin integrado +- ⚠️ Teste /qw ainda pendente (não validado) + +### ACT +- Próximo: Teste manual /qw +- Validar mem0 entries +- Considerar symlink OpenCode +- Documentar tempo real em CHANGELOG + +--- + +## MEM0 + +ID: mem0_xyz123 +Entry: "Skill /qw criada | propósito | recapitulação rápida sesões" +Tags: skill, gestao, mem0, recapitulacao +Tier: global + +--- + +## DOCS UPDATED + +✅ plugin.json (v1.4.0 → 1.5.0) +✅ CHANGELOG.md (entrada [1.5.0]) +✅ SKILL.md criado +✅ README.md criado + +--- + +⏱️ Report duração: 2 min 15s | Estado: COMPLETO +``` + +--- + +## Flags + +### `--quick` +Apenas 3 campos obrigatórios: +``` +QUÊ (deliverable)? +COMO (método)? +RESULTADO (sucesso)? +``` + +### `--auto` +Auto-detecta contexto: +- Git: commits, ficheiros alterados +- Desk: task_id, tempo loggado +- .desk-project: extrai dados +- Timestamp: agora vs. timer activo + +--- + +## Integração CARL + +Domínio: **TASK-COMPLETION-REPORT** +Triggers: "concluído", "finalizado", "pronto", "terminado", "etapa completa" +Auto-disparo: Sem confirmação (injecção automática) +Output: Desk #33 ou mem0 conforme contexto + +--- + +## Estrutura 5W2H Obrigatória + +| Sigla | Campo | Obrigatório | Max | +|-------|-------|-------------|-----| +| W | QUÊ (What) | Sim | 120 chars | +| W | QUEM (Who) | Sim | 50 chars | +| W | QUANDO (When) | Sim | timestamp | +| W | ONDE (Where) | Sim | path/sistema | +| W | POR QUÊ (Why) | Sim | 100 chars | +| H | COMO (How) | Sim | 150 chars | +| H | CUSTO (How much) | Sim | tempo (min) | + +--- + +## PDCA Obrigatória + +| Fase | Campo | Detalhe | +|------|-------|---------| +| **P** | PLAN | Spec original, criteria, scope | +| **D** | DO | Passos, decisões, desvios | +| **C** | CHECK | Resultado vs criteria, gaps | +| **A** | ACT | Ajustes, próximas acções | + +--- + +## Checklist Implementação + +- [x] SKILL.md criada +- [ ] Skill registada em plugin.json +- [ ] CARL domínio TASK-COMPLETION-REPORT activado +- [ ] Teste manual: `/report` +- [ ] Teste flag: `--quick` +- [ ] Teste flag: `--auto` +- [ ] Validar Desk #33 entry +- [ ] Validar mem0 entry + +--- + +**Versão:** 1.0 | **Data:** 2026-07-02 | **Plugin:** gestao | **Staff:** 25 (Claude) diff --git a/gestao/skills/report-templates/SKILL.md b/gestao/skills/report-templates/SKILL.md index a81292c..a2a07f5 100644 --- a/gestao/skills/report-templates/SKILL.md +++ b/gestao/skills/report-templates/SKILL.md @@ -1,7 +1,6 @@ --- name: report-templates description: Templates de comunicacao com clientes — updates mensais, status de projecto, relatorios de incidente e revisoes mensais. Usar quando "relatorio cliente", "report cliente", "update cliente", "status projecto", "incidente", "revisao mensal", "comunicar cliente", "resumo projecto", "enviar report", "preparar relatorio". -layer: wiki --- # /report-templates — Comunicacao com Clientes @@ -167,4 +166,32 @@ Gera revisao mensal completa e publica como comentario na tarefa Desk do cliente ## Anti-Patterns - **Nunca** gerar relatorio sem dados reais do Desk CRM -- **Nu \ No newline at end of file +- **Nunca** incluir valores financeiros estimados como factos +- **Nunca** enviar relatorio de incidente sem plano de accao definido +- **Nunca** usar tom informal em relatorios de incidente + +--- + +## Changelog + +### v1.0.0 (2026-03-10) +- Versao inicial +- 4 templates: client-update, project-status, incident-report, monthly-review +- Suporte HTML e Markdown +- Integracao com Desk CRM + +--- + +*Skill v1.0.0 | 2026-03-10 | 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ós cada erro corrigido.* diff --git a/gestao/skills/report/SKILL.md b/gestao/skills/report/SKILL.md index 1ad39cd..db4d372 100644 --- a/gestao/skills/report/SKILL.md +++ b/gestao/skills/report/SKILL.md @@ -2,7 +2,6 @@ name: report description: Relatórios agregados semanal, mensal e por projecto. Compila dados de múltiplas fontes CRM. Usar quando "report", "relatório", "semanal", "mensal", "resumo período". context: fork -layer: wiki --- # /report v1.0 - Relatórios Agregados diff --git a/gestao/skills/research-pipeline/SKILL.md b/gestao/skills/research-pipeline/SKILL.md index dfa53f9..e48d415 100644 --- a/gestao/skills/research-pipeline/SKILL.md +++ b/gestao/skills/research-pipeline/SKILL.md @@ -5,7 +5,6 @@ description: > Orquestra as camadas em sequência para pesquisas profundas. Usar quando /hub-search ou /knowledge isolados não são suficientes, quando o tema cruza conteúdo interno+externo, ou para research antes de executar tarefas complexas. -layer: wiki --- # /research-pipeline — Pipeline de Pesquisa em 2 Camadas diff --git a/gestao/skills/review-corrections/SKILL.md b/gestao/skills/review-corrections/SKILL.md index 7536adf..e405445 100644 --- a/gestao/skills/review-corrections/SKILL.md +++ b/gestao/skills/review-corrections/SKILL.md @@ -5,7 +5,6 @@ description: > de regras para CLAUDE.md. Lê ~/.claude-work/corrections.jsonl, agrupa por padrão, e propõe melhorias concretas. Usar semanalmente (via /schedule) ou quando há >5 correcções acumuladas. Faz parte do loop de auto-melhoria (Eixo 3, Stack Q2 2026). -layer: wiki --- # /review-corrections — Análise de Correcções e Auto-melhoria diff --git a/gestao/skills/spec-coauthor/SKILL.md b/gestao/skills/spec-coauthor/SKILL.md index 16021b5..35e8f73 100644 --- a/gestao/skills/spec-coauthor/SKILL.md +++ b/gestao/skills/spec-coauthor/SKILL.md @@ -1,7 +1,6 @@ --- name: spec-coauthor description: Co-autoria iterativa de documentos estruturados — SPECs de projecto, propostas comerciais e PROCs operacionais. Workflow 3 fases com brainstorming, curadoria e teste de leitura por sub-agente. Usar quando "spec", "proposta", "PROC", "documento", "co-autoria", "redigir", "estruturar documento", "escrever proposta". -layer: wiki --- # /spec-coauthor - Co-Autoria de Documentos Estruturados @@ -179,4 +178,175 @@ Para PROC operacional: 1. Objectivo e âmbito 2. Pré-requisitos 3. Passos detalhados -4. Checklis \ No newline at end of file +4. Checklist de execução +5. Troubleshooting +6. Métricas e validação +7. Referências cruzadas +``` + +### 2.4 Revisão global + +Após completar todas as secções: + +``` +Documento completo em rascunho. Revisão global: + +1. Fluxo lógico entre secções ✓/✗ +2. Consistência de terminologia ✓/✗ +3. Nível de detalhe adequado à audiência ✓/✗ +4. Sem lacunas de informação crítica ✓/✗ + +Ajustes antes do teste de leitura? (s/n) +``` + +--- + +## Fase 3: Teste de Leitura + +### 3.1 Sub-agente "leitor fresco" + +Invocar sub-agente via Agent tool **sem fornecer contexto da sessão actual**. O sub-agente recebe apenas o documento final e responde como leitor novo. + +**Instrução para o sub-agente:** + +``` +És um leitor que vê este documento pela primeira vez. +Não tens contexto adicional sobre o projecto ou empresa. +Lê o documento abaixo e responde: + +1. O que este documento comunica? (resumo em 2-3 frases) +2. Quem é a audiência alvo? +3. Que perguntas ficaram sem resposta? +4. Há algum ponto confuso ou contraditório? +5. O que mudarias na estrutura ou linguagem? + +DOCUMENTO: +[colar documento completo] +``` + +### 3.2 Análise das lacunas detectadas + +Apresentar ao utilizador o relatório do sub-agente: + +``` +**Relatório do leitor fresco:** + +Compreensão: [resumo do sub-agente] +Audiência identificada: [o sub-agente identificou correctamente?] + +Lacunas detectadas: +- [Lacuna 1] +- [Lacuna 2] + +Confusões detectadas: +- [Ponto X não está claro] + +Sugestões estruturais: +- [Sugestão A] +``` + +### 3.3 Correcção iterativa + +Para cada lacuna ou confusão, propor correcção: + +``` +Lacuna: "Não fica claro qual o prazo de entrega" +Proposta: Adicionar secção "Timeline" com datas concretas +→ Aprovar correcção? (s/n) +``` + +Repetir Fase 3 se correcções forem substanciais. + +--- + +## Integração com Desk CRM + +### Criar/actualizar tarefa associada + +Após finalizar o documento: + +``` +mcp__desk-crm-v3__create_task ou update_task: + - Nome: "SPEC/Proposta/PROC: [Título documento]" + - Descrição: Sumário do documento + - Projecto: [projecto associado] + - Status: Em revisão / Concluído +``` + +### Comentário HTML na tarefa + +```html +

Documento criado

+
    +
  • Tipo: [SPEC / Proposta / PROC]
    • +
  • Audiência: [quem vai ler]
    • +
  • Fases concluídas: Context Gathering → Refinamento → Teste de Leitura
    • +
+

Ficheiro: [path absoluto do documento]

+
+

Skill: /spec-coauthor | Data: YYYY-MM-DD

+``` + +--- + +## Onde Guardar o Documento + +| Tipo | Destino | +|------|---------| +| SPEC de projecto | `/media/ealmeida/Dados/Hub/05-Projectos/[projecto]/` | +| Proposta comercial | `/media/ealmeida/Dados/Hub/03-Propostas/` | +| PROC operacional | `/media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/[Dept]/` | +| Rascunho/inbox | `/media/ealmeida/Dados/Hub/00-Inbox/` | + +**Nomeação de ficheiros:** +- SPEC: `[Projecto]-SPEC.md` ou `[Projecto]-SPEC-v2.md` +- Proposta: `Proposta-[Cliente]-[Tema]-YYYY-MM-DD.md` +- PROC: `PROC-[Título].md` (via `/proc-creator` para código correcto) + +--- + +## Referências e Templates + +**Templates detalhados:** `references/templates.md` (neste directório) +- Template SPEC completo +- Template proposta comercial +- Template PROC operacional + +**Skills relacionadas:** +- `/proc-creator` — Criar PROCs com código departamental correcto e actualizar INDEX.md +- `/orcamento` — Gerar orçamentos e propostas com pricing +- `/knowledge` — Pesquisar contexto em NotebookLM / Hub antes de redigir + +--- + +## Anti-Patterns + +**Nunca:** +- Redigir documento completo de uma vez sem curadoria por secção +- Avançar para Fase 3 sem aprovação do rascunho completo +- Fornecer contexto da sessão ao sub-agente de teste +- Guardar documento sem tarefa Desk CRM associada +- Usar emojis ou maiúsculas desnecessárias no documento + +**Sempre:** +- Confirmar audiência antes de escolher linguagem e detalhe +- Gerar mínimo 5 opções por secção de brainstorming +- Aguardar curadoria do utilizador antes de rascunhar +- Corrigir lacunas detectadas pelo leitor fresco antes de fechar +- PT-PT estrito em todo o documento gerado + +--- + +*Skill v1.0.0 | 2026-03-10 | Plugin gestao | 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ós cada erro corrigido.* diff --git a/gestao/skills/task-state/SKILL.md b/gestao/skills/task-state/SKILL.md index 24f9bd5..665eee4 100644 --- a/gestao/skills/task-state/SKILL.md +++ b/gestao/skills/task-state/SKILL.md @@ -2,7 +2,6 @@ name: task-state description: Gestão de estado persistente de tarefas entre sessões. Cria, actualiza e lê .task-state.md para tarefas complexas. Usar quando tarefa tem >2 sessões, múltiplos ficheiros, ou risco de perder contexto por compaction. context: fork -layer: wiki --- # /task-state — Gestão de Estado de Tarefa diff --git a/gestao/skills/tasks-overview/SKILL.md b/gestao/skills/tasks-overview/SKILL.md index 6210998..e8e4585 100644 --- a/gestao/skills/tasks-overview/SKILL.md +++ b/gestao/skills/tasks-overview/SKILL.md @@ -1,7 +1,6 @@ --- name: tasks-overview description: Visão geral de tarefas pendentes, atrasadas e em curso do Desk CRM. Organiza por prioridade e projecto, sugere workflows relevantes. Usar quando "tarefas", "tasks", "pendentes", "overdue", "atrasadas", "o que temos para fazer". -layer: wiki --- # /tasks-overview v1.0 diff --git a/gestao/skills/time/SKILL.md b/gestao/skills/time/SKILL.md index 12bb271..39f973f 100644 --- a/gestao/skills/time/SKILL.md +++ b/gestao/skills/time/SKILL.md @@ -2,7 +2,6 @@ name: time description: Gestão de tempo integrada com Desk CRM. Alertas >4h, total semanal, integração worklog. Usar quando "time", "timer", "horas", "timesheet", "start", "stop", "tempo". disable-model-invocation: true -layer: wiki --- # /time v2.0 - Gestão de Tempo @@ -237,4 +236,29 @@ const ALERT_HOURS = 4; // Alertar após 4h ### v2.0.0 (2026-02-05) - Alerta se timer >4h - Mostrar total horas da semana no status -- Integração com /workl \ No newline at end of file +- Integração com /worklog ao parar +- Verificar estado Desk vs local +- Semana: Seg-Dom + +### v1.1.0 (2026-02-03) +- Workflows organizados +- MCP Tools corrigidos + +### v1.0.0 (2026-01-27) +- Versão inicial + +--- + +*Skill v2.0.0 | 2026-02-05 | 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ós cada erro corrigido.* diff --git a/gestao/skills/today/SETUP_MCPS.md b/gestao/skills/today/SETUP_MCPS.md index 97b07c7..717b1a6 100644 --- a/gestao/skills/today/SETUP_MCPS.md +++ b/gestao/skills/today/SETUP_MCPS.md @@ -2,7 +2,6 @@ title: Setup MCPs para /today date: 2025-01-21 status: activo -layer: wiki --- # Setup MCPs para /today @@ -100,7 +99,7 @@ cat .env # Verificar se credenciais estão preenchidas ``` -### Adicionar ao Claude settings.json +### Adicionar ao `~/.claude.json` (registo único de MCPs — regra 58) ```json { @@ -138,7 +137,7 @@ python -m workspace_mcp --test ``` ### 3. Adicionar ao Claude -Editar `~/.claude/settings.json` com configuração acima. +Editar `~/.claude.json` (`mcpServers`) com a configuração acima — NUNCA `~/.claude/settings.json` nem `.mcp.json` de plugins (regra 58). ### 4. Reiniciar Claude Code ```bash diff --git a/gestao/skills/today/SKILL.md b/gestao/skills/today/SKILL.md index f0555e4..677b6d9 100644 --- a/gestao/skills/today/SKILL.md +++ b/gestao/skills/today/SKILL.md @@ -1,29 +1,35 @@ --- name: today -description: Checkup diário - dashboard agregador que lê resultados dos agentes cron locais (desktop) e recolhe dados frescos via skills interactivas. Usar quando "checkup", "hoje", "today", "rotina", início de dia. +description: Checkup diário - dashboard agregador que lê resultados dos agentes systemd locais (desktop/hp) e recolhe dados frescos via skills interactivas. Usar quando "checkup", "hoje", "today", "rotina", início de dia. context: fork -layer: wiki --- -# /today v12.0 - Checkup Diario (Agregador) +# /today v12.1 - Checkup Diario (Agregador) -Le resultados dos agentes cron locais (desktop, crontab ealmeida) + invoca skills interactivas. Nao duplica trabalho automatizado. +Lê resultados dos agentes systemd locais (user timers, desktop/hp) + invoca skills interactivas. Não duplica trabalho automatizado. --- ## Arquitectura +> Migração: crontab (`claude_automations_dev`, extinto 20-04-2026) → Hermes cronjobs (05-05-2026, Task #2080) → **systemd user timers `stack-observer`** (actual, desde ~11-06-2026). Repo agentes: `git.descomplicar.pt/ealmeida/stack-observer` (código) + `~/.config/systemd/user/*.timer` (agendamento). + ``` -CRON (desktop local, crontab ealmeida) /today (interactivo, sob pedido) -├── imap-triage (4h) ├── Le logs locais do cron -├── auto-expense (4h +15min) ├── /daily-digest (dados frescos) -├── ticket-triage (4h +30min) ├── /tasks-overview (dados frescos) -├── aiktop-tasks (15min) ├── /cleanup-downloads (se necessario) -├── infra-check (diario 7h) ├── Specs/Sprints scan -├── wp-update (segunda 23h) ├── Rotinas especiais por dia -├── intelligence-* (researcher/scorer/ └── Dashboard + Obsidian + Mem0 -│ selector/publisher) -└── weekly-digest-podcast (quinta 20h) +SYSTEMD USER TIMERS (desktop/hp) /today (interactivo, sob pedido) +├── collector-gate-events (*/5min) ├── Lê estado systemd (list-timers + list-units --failed) +├── collector-hermes-jobs (*/5min) ├── /daily-digest (dados frescos CRM) +├── observer-ticket-queue (*/5min) ├── /tasks-overview (dados frescos Desk) +├── observer-tickets (diário 09:30) ├── /cleanup-downloads (se necessário) +├── observer-desk-alert (diário 09:00) ├── Specs/Sprints scan +├── update-omp / update-claude (periódico) ├── Rotinas especiais por dia +├── okf-confianca (semanal seg) └── Dashboard + Obsidian + Mem0 +├── verify-gates-registry (semanal seg) +└── stk-drift-check (semanal dom) + +Timers rclone (rclone-bisync, gdrive-sync — obsoletos: InSync é o único sync GDrive) e OKF secundários +(okf-health, okf-lint, okf-detect, okf-moc-sync, okf-validate) +existem mas ficam `disabled`/`inactive` por omissão — confirmar +estado antes de assumir que correm. ``` --- @@ -41,60 +47,50 @@ CRON (desktop local, crontab ealmeida) /today (interactivo, sob pedido) ``` 1. mcp__mcp-time__current_time -> data, dia da semana -2. mcp__mem_search_memories("today checkup YYYY-MM-DD") +2. mcp__mem0__search_memories("today checkup YYYY-MM-DD") -> Se ja existe hoje: perguntar se quer re-executar ``` -### Fase 1: Ler resultados dos agentes cron (silencioso) +### Fase 1: Ler estado dos agentes systemd (silencioso) ``` -3. Ler logs LOCAIS (Bash tail — sem SSH, tudo corre no desktop): +3. Ler estado systemd (Bash — sem SSH, tudo corre no desktop/hp): - Base: /media/ealmeida/Dados/Dev/claude_automations_dev/ + a) Próximas execuções + última corrida de cada timer activo: + systemctl --user list-timers --all --no-legend - a) IMAP (ultimo report): - tail -20 /media/ealmeida/Dados/Dev/claude_automations_dev/imap-triage/imap-triage.log - cat ~/.claude-work/today-imap-DD-MM-YYYY.json (se existir) + b) Unidades falhadas (qualquer serviço, não só os do stack-observer): + systemctl --user list-units --failed --no-legend --all - b) Ticket triage (ultimo log): - tail -30 /media/ealmeida/Dados/Dev/claude_automations_dev/ticket-triage/ticket-triage.log + c) Para cada falha encontrada em (b), obter a causa: + journalctl --user -u .service -n 20 --no-pager - c) Auto-expense (ultimo log): - tail -20 /media/ealmeida/Dados/Dev/claude_automations_dev/auto-expense/auto-expense.log + d) Confirmar se os timers de backup estão activos (regra 3-2-1): + # rclone-bisync/gdrive-sync devem estar DISABLED (InSync é o único sync GDrive) + systemctl --user is-enabled rclone-bisync.timer gdrive-sync.timer + systemctl --user is-active rclone-bisync.timer gdrive-sync.timer + -> Se disabled/inactive: ALERTA "Requer Atencao Urgente" (backup offsite em risco) - d) Infra check (ultimo log): - tail -30 /media/ealmeida/Dados/Dev/claude_automations_dev/infra-check/infra-check.log - - e) AikTop tasks (ultimo log): - tail -20 /media/ealmeida/Dados/Dev/claude_automations_dev/aiktop-tasks/aiktop-tasks.log - - f) SE segunda — wp-update (ultimo log): - tail -50 /media/ealmeida/Dados/Dev/claude_automations_dev/wp-update/wp-update.log - - g) Intelligence pipeline: - tail -30 /media/ealmeida/Dados/Dev/claude_automations_dev/daily-selector/daily-selector.log - tail -30 /media/ealmeida/Dados/Dev/claude_automations_dev/intelligence-publisher/intelligence-publisher.log - tail -20 /media/ealmeida/Dados/Dev/claude_automations_dev/intelligence-researcher/intelligence-researcher.log - tail -20 /media/ealmeida/Dados/Dev/claude_automations_dev/intelligence-scorer/intelligence-scorer.log - - h) HEARTBEAT WP — ultimo post em descomplicar.pt categoria 1188 (noticias): + e) HEARTBEAT WP — ultimo post em descomplicar.pt categoria 1188 (noticias): mcp__ssh-unified__ssh_execute(server="server", command="cd /home/ealmeida/public_html && wp post list --post_type=post --category=1188 --posts_per_page=1 --fields=ID,post_title,post_date --format=csv --allow-root 2>&1 | tail -2") + -> Se a ligação SSH falhar (auth/timeout), NÃO repetir a tentativa mais de uma vez + (risco de lockout CSF/LFD no servidor CWP) — reportar como alerta de acesso, + não como heartbeat em falta. -> Calcular idade do ultimo post -> Se >26h sem post novo: ALERTA "Requer Atencao Urgente" + contexto: - * Pipeline deveria publicar ate 5 noticias/dia (selector 06:30 + slots 09/11/13/15:30/17:30) - * Verificar logs daily-selector + publisher (passo g) - * Stock Supabase (base de dados própria do pipeline de notícias): scored>=7 count via curl REST - * Verificar se desktop teve downtime (uptime / journalctl) — agentes correm no desktop local + * Pipeline deveria publicar ate 5 noticias/dia + * Verificar journalctl dos timers relacionados (researcher/scorer/selector/publisher, se existirem) + * Verificar se desktop/hp tiveram downtime (uptime / journalctl -b) -4. DETECTAR PROBLEMAS nos logs: - - Cron nao correu (log desactualizado >8h) - - Exit codes != 0 - - Erros ou falhas nos logs - - HEARTBEAT WP >26h sem post novo em cat 1188 +4. DETECTAR PROBLEMAS: + - Timer com falha em list-units --failed + - Timer de backup/OKF crítico disabled/inactive quando deveria estar activo + - Exit codes != 0 nos journalctl consultados + - HEARTBEAT WP >26h sem post novo em cat 1188, ou SSH inacessível -> Adicionar a seccao "Requer Atencao Urgente" 4b. VERIFICAR FORNECEDORES AUTO-CRIADOS: - Ler ~/.claude-work/fornecedores-iva.json + Ler ~/.claude-work/fornecedores-iva.json (se existir) Filtrar entradas com "auto_proposto": true Para cada entrada extrair: nome, dominio (chave), politica, confianca, despesas_count -> Se existirem: adicionar secção "Fornecedores Auto-Criados" no dashboard (ver formato abaixo) @@ -105,23 +101,35 @@ CRON (desktop local, crontab ealmeida) /today (interactivo, sob pedido) ``` 5. Invocar /daily-digest -> Timer, tickets, facturas, leads, propostas, agenda + -> Requer MCP desk-crm-v3 (disabled por omissão, regra 57 CLAUDE.md) — + se desligado, reportar tickets/facturas/leads/propostas como indisponíveis + em vez de tentar contornar com desk-project-minimal (cobertura parcial: só tarefas). -> Output: dashboard markdown 6. Invocar /tasks-overview -> Tarefas overdue, pendentes, em curso, workflows sugeridos + -> desk-project-minimal cobre tarefas (get_overdue_tasks, get_tasks) sem depender do desk-crm-v3 -> Output: tarefas markdown 7. SE >10 ficheiros em ~/Transferencias: -> Invocar /cleanup-downloads + +7b. Bloco de segurança (P2-10, 10-08-2026): + python3 /media/ealmeida/Dados/Hub/04-Stack/02.04-Sistemas/71.Seguranca/tools/today-security-block.py + -> Lê relatorios/*.md já gerados (não corre scans novos — demoram minutos, usam APIs externas) + -> Score actual + delta vs leitura anterior por domínio, alerta se abaixo do SLA (90) ou mínimo (75) + -> Output: bloco markdown "## 🔒 Segurança" pronto a incluir no dashboard ``` ### Fase 2b: Sprint/Spec Activos (silencioso) ``` 8. Glob: /media/ealmeida/Dados/Dev/**/SPEC.md (profundidade max 3) - -> Para cada encontrado: Ler frontmatter (15 linhas) - -> Filtrar: status != "completed" - -> Extrair: titulo (linha # SPEC:), status, weight, scope done/total + -> Excluir placeholders genéricos: title "Spec"/"SPEC — " com status: draft + e sem secções de conteúdo além do frontmatter (gerados por template, docs/SPECS/SPEC.md) + -> Para cada SPEC.md real (conteúdo substantivo): ler frontmatter (grep ^status: mais rápido que ler 15 linhas por ficheiro) + -> Filtrar: status not in [completed, shipped, abandoned, rejected] + -> Extrair: titulo, status, data approved/updated, projecto Desk associado 9. Glob: /media/ealmeida/Dados/Dev/**/SPRINT.md -> Para cada encontrado: Ler frontmatter @@ -142,8 +150,8 @@ CRON (desktop local, crontab ealmeida) /today (interactivo, sob pedido) ### Fase 3: Output Final ``` -12. AGREGAR resultados de cron + skills: - - Logs do cron (Fase 1) +12. AGREGAR resultados de systemd + skills: + - Estado dos timers/serviços (Fase 1) - Dados frescos do /daily-digest e /tasks-overview (Fase 2) - Specs/Sprints (Fase 2b) @@ -153,9 +161,10 @@ CRON (desktop local, crontab ealmeida) /today (interactivo, sob pedido) Path: /media/ealmeida/Dados/Hub/00-Inbox/DD-MM-YYYY-checkup.md Conteudo: dashboard completo -15. GUARDAR em Mem0 (via MCP gateway): - mcp__mem_save_memory({ - text: "Checkup diario DD-MM-YYYY - X tickets, Y tarefas, Z urgentes, cron OK/FALHA" +15. GUARDAR em Mem0 (store canónico cross-agent, CLAUDE.md regra 28): + mcp__mem0__save_memory({ + text: "Checkup diario DD-MM-YYYY: X tarefas vencidas, Y em curso, Z urgentes, timers OK/FALHA", + metadata: {"type": "today-checkup", "date": "YYYY-MM-DD"} }) ``` @@ -169,7 +178,7 @@ CRON (desktop local, crontab ealmeida) /today (interactivo, sob pedido) --- ## Requer Atencao Urgente -[Alertas: cron falhado, erros infra, seguranca, notificacoes criticas] +[Alertas: timer/serviço falhado, backup offsite em risco, SSH inacessível, heartbeat WP em falta, notificacoes criticas] --- @@ -203,25 +212,30 @@ Nota: Promovidos automaticamente após 3 despesas. Confiança "baixa" = fallback --- ## Resumo do Dia -[Do /daily-digest: timer, tickets, facturas, tarefas, leads, agenda] +[Do /daily-digest: timer, tickets, facturas, tarefas, leads, agenda — ou "indisponível, desk-crm-v3 desligado" se aplicável] --- -## Agentes Cron (desktop local) +## 🔒 Segurança +[Output de today-security-block.py — score+delta por domínio, alertas abaixo do SLA/mínimo] -| Agente | Ultima execucao | Status | Resumo | -|--------|----------------|--------|--------| -| imap-triage | HH:MM | OK/FALHA | X contas, Y emails | -| auto-expense | HH:MM | OK/SKIP | Z despesas criadas | -| ticket-triage | HH:MM | OK/FALHA | W tickets processados | -| aiktop-tasks | HH:MM | OK/FALHA | N tarefas executadas | -| infra-check | HH:MM | OK/FALHA | X/4 MCPs operacionais | -| wp-update [se seg] | HH:MM | OK/FALHA | X/16 sites actualizados | +--- + +## Agentes Systemd (desktop/hp local) + +| Timer | Ultima execucao | Status | Resumo | +|-------|-----------------|--------|--------| +| collector-gate-events | HH:MM | OK/FALHA | — | +| collector-hermes-jobs | HH:MM | OK/FALHA | — | +| observer-ticket-queue | HH:MM | OK/FALHA | — | +| observer-tickets | HH:MM | OK/FALHA | — | +| observer-desk-alert | HH:MM | OK/FALHA | [journalctl summary se FALHA] | +| rclone-bisync / gdrive-sync | — | DISABLED (esperado) | [alerta se ACTIVO — InSync é o único sync GDrive] | --- ## Auto-Processamento (ultimas 24h) -[Resumo agregado: despesas criadas, tickets fechados, emails limpos] +[Resumo agregado: divergências detectadas pelo stack-observer, tickets criados, despesas criadas] ``` --- @@ -243,13 +257,14 @@ Filename: `DD-MM-YYYY-checkup.md` (Regra #45: formato DD-MM-YYYY) ## Anti-Patterns -- NUNCA invocar /ticket-triage, /imap-triage, /auto-expense, /infra-check, /wp-update (correm no cron) +- NUNCA invocar manualmente os componentes do stack-observer (correm por timer) - NUNCA mostrar output antes de terminar Fase 1 e 2 - NUNCA mostrar mais de 3 prioridades (PHDA) - NUNCA executar sem verificar data/hora primeiro -- SEMPRE ler logs do cron antes de mostrar dashboard -- SEMPRE alertar se algum agente cron nao correu nas ultimas 8h -- NUNCA usar `mem0` MCP para o checkup — deprecated para memória de agentes; usar `mem0` (`mcp__mem_*`) +- SEMPRE correr `list-timers` + `list-units --failed` antes de mostrar dashboard +- SEMPRE alertar se algum timer crítico (observer-desk-alert, observer-tickets, backup) falhou ou está inactivo +- NUNCA repetir uma tentativa SSH falhada ao host `server` mais de uma vez na mesma sessão (risco de lockout CSF/LFD) +- NUNCA contornar um MCP desligado (ex: desk-crm-v3) — reportar e remeter para `/mcp` (regra 57 CLAUDE.md) --- @@ -257,28 +272,21 @@ Filename: `DD-MM-YYYY-checkup.md` (Regra #45: formato DD-MM-YYYY) | Componente | Tipo | Responsabilidade | |-----------|------|-----------------| -| `imap-triage` | Cron desktop (*/4h) | Triagem IMAP 13 contas + dedup Supabase (BD própria do pipeline IMAP, não é memória de agente) | -| `auto-expense` | Cron desktop (15 */4h) | Criacao automatica de despesas | -| `ticket-triage` | Cron desktop (30 */4h) | Auto-process tickets (SPAM, facturas) | -| `aiktop-tasks` | Cron desktop (*/15min) | Executa tarefas AikTop do Desk CRM | -| `infra-check` | Cron desktop (07h) | Health check gateway + MCPs | -| `wp-update` | Cron desktop (seg 23h) | Actualizacoes WordPress 16 sites | -| `weekly-digest-podcast` | Cron desktop (quinta 20h) | Digest semanal para podcast | -| `improvement-evaluator-v2` | Cron Hermes (diário 07:00) | Lê worklogs/#33 → melhorias em BD; ticket semanal seg top 5 (job d398b5e2c3be) | -| `gitea-ci-cleaner` | Cron desktop (45 */4h) | Limpeza de runs CI Gitea | -| `daily-selector` | Cron desktop (06:30) | Selector ate 5 noticias/dia diversas → status=scheduled | -| `intelligence-publisher` | Cron desktop (5 slots 09/11/13/15:30/17:30) | Publica slots scheduled em descomplicar.pt | -| `intelligence-researcher` | Cron desktop (9/14/20) | Fetch 214 RSS → Supabase (BD própria do pipeline de notícias, não é memória de agente) | -| `intelligence-scorer` | Cron desktop (0/30 min) | Score OpenRouter gpt-oss-20b | -| `HEARTBEAT WP` | Check ao vivo | `wp post list cat=1188` → idade do ultimo post. Alerta se >26h | -| `/daily-digest` | Skill (interactivo) | Timer, tickets, facturas, leads, agenda | -| `/tasks-overview` | Skill (interactivo) | Tarefas pendentes/overdue + workflows | +| `collector-gate-events` | systemd timer (*/5min) | Recolhe gate_events do Espelho/observer | +| `collector-hermes-jobs` | systemd timer (*/5min) | Recolhe jobs Hermes | +| `observer-ticket-queue` | systemd timer (*/5min) | Processa fila de divergências (Node) | +| `observer-tickets` | systemd timer (diário 09:30) | Processador de fila de tickets → Desk CRM | +| `observer-desk-alert` | systemd timer (diário 09:00) | Auto-ticket para divergências detectadas | +| `rclone-bisync` / `gdrive-sync` | systemd timer | Obsoletos — devem ficar `disabled` (InSync é o único sync GDrive; offsite = rclone pontual LocalBackups→GDrive) | +| `okf-confianca` / `verify-gates-registry` / `stk-drift-check` | systemd timer (semanal) | Relatórios de qualidade/confiança OKF | +| `HEARTBEAT WP` | Check ao vivo | `wp post list cat=1188` via SSH → idade do ultimo post. Alerta se >26h ou SSH inacessível | +| `/daily-digest` | Skill (interactivo) | Timer, tickets, facturas, leads, agenda (requer desk-crm-v3) | +| `/tasks-overview` | Skill (interactivo) | Tarefas pendentes/overdue + workflows (desk-project-minimal) | | `/cleanup-downloads` | Skill (interactivo) | Limpeza pasta Transferencias | +| `today-security-block.py` | Script (leitura) | Score+delta de segurança por domínio, lê `71.Seguranca/relatorios/*.md` (não corre scans novos) | | `/spec` + `/sprint` | Scan local | Specs e sprints activos | -Repo agentes: `git.descomplicar.pt/ealmeida/claude_automations_dev` - - +Repo agentes: `git.descomplicar.pt/ealmeida/stack-observer` (código) — agendamento em `~/.config/systemd/user/*.timer`, não em crontab. --- @@ -294,8 +302,13 @@ Se encontrares um padrão relevante ao contexto actual, aplica o fix preventivam --- -*Skill v12.0.0 | 01-07-2026 | Descomplicar® — memória do checkup migrada de mem0 (deprecated) para Mem0 (mcp__mem_*)* - +*Skill v12.1.0 | 10-08-2026 | Descomplicar® — arquitectura actualizada de crontab/claude_automations_dev (extinto) para systemd user timers `stack-observer`; memory-supabase substituído por mem0; alerta de lockout SSH ao host `server`; bloco de segurança adicionado (P2-10, SPEC-Hardening-Seguranca.md)* ## Healing Log + +```jsonl +{"date":"2026-07-06","issue":"Fase 1 apontava para claude_automations_dev/{imap-triage,auto-expense,ticket-triage,aiktop-tasks,infra-check,wp-update} — todos arquivados em z_arquivo/ desde a migração para Hermes cronjobs (05-05) e depois systemd stack-observer (~11-06). Logs nunca existiam, secção 'Agentes Cron' sempre vazia.","fix":"Ler estado via systemctl --user list-timers/list-units --failed + journalctl, não tail de logs em paths fixos que mudam a cada migração de arquitectura.","source":"user"} +{"date":"2026-07-06","issue":"skill referenciava mcp__mem0 (desactivado) para Fase 0/3.","fix":"Usar mem0 (mcp__mem0__search_memories / save_memory), store canónico actual por CLAUDE.md regra 28.","source":"user"} +{"date":"2026-08-10","issue":"nao havia visibilidade de seguranca no checkup diario -- score so era visto ao correr /seguranca-check manualmente.","fix":"Adicionada Fase 2 passo 7b: today-security-block.py le relatorios/*.md ja gerados (sem correr scans novos) e mostra score+delta+alertas por dominio. Secao '## Segurança' no dashboard.","source":"agent"} +``` diff --git a/gestao/skills/today/prompts/execute.md b/gestao/skills/today/prompts/execute.md index e6410c8..7b6caf3 100644 --- a/gestao/skills/today/prompts/execute.md +++ b/gestao/skills/today/prompts/execute.md @@ -9,7 +9,7 @@ Executa o checkup diario lendo logs locais dos agentes + recolhe dados frescos. ``` mcp__mcp-time__current_time → data, dia da semana -mcp__mem_search_memories("today checkup YYYY-MM-DD") +mcp__mem0__search_memories("today checkup YYYY-MM-DD") Se ja existe hoje → perguntar se quer re-executar ``` @@ -83,9 +83,10 @@ Criar nota Obsidian: - Path: `/media/ealmeida/Dados/Hub/00-Inbox/DD-MM-YYYY-checkup.md` (formato DD-MM-YYYY) - Frontmatter: title, date, type: checkup, status: active -Guardar em Mem0: +Guardar em Supabase: ``` -mcp__mem_save_memory({ - text: "Checkup diario DD-MM-YYYY - X tickets, Y tarefas, cron OK/FALHA" +mcp__mem0__save_memory({ + content: "Checkup diario DD-MM-YYYY - X tickets, Y tarefas, cron OK/FALHA", + tags: ["today", "checkup", "DD-MM-YYYY"] }) ``` diff --git a/gestao/skills/today/templates/daily-report.md b/gestao/skills/today/templates/daily-report.md index 4b29928..b062c7d 100644 --- a/gestao/skills/today/templates/daily-report.md +++ b/gestao/skills/today/templates/daily-report.md @@ -4,7 +4,6 @@ date: {{DATE}} type: daily tags: [diario, checkup, {{WEEKDAY}}] aliases: ["{{DATE}}"] -layer: wiki --- # 📅 {{DATE}} - {{WEEKDAY}} diff --git a/gestao/skills/validate-component/SKILL.md b/gestao/skills/validate-component/SKILL.md index 918ac65..fe46955 100644 --- a/gestao/skills/validate-component/SKILL.md +++ b/gestao/skills/validate-component/SKILL.md @@ -1,7 +1,6 @@ --- name: validate-component description: Valida skills e agents para alinhamento com procedimentos Hub. Verifica se componente referencia procedimentos (não duplica) e segue padrão de referenciação. Usar quando "validar skill", "verificar agent", "audit component", antes de deploy. -layer: wiki --- # /validate-component - Validador de Componentes @@ -186,4 +185,193 @@ Audita skills e agents para garantir alinhamento com padrão de centralização | PROC | Departamento | Relevância | Status Link | |------|--------------|------------|-------------| | PROC-MCP-Desenvolvimento.md | D7 | Alta | ✅ Referenciado | -| PROC-WordPress-Hardening.md | D7 | Média | ❌ Nã \ No newline at end of file +| PROC-WordPress-Hardening.md | D7 | Média | ❌ Não referenciado | + +--- + +## Próximos Passos + +1. [ ] Corrigir issues críticas (se houver) +2. [ ] Aplicar recomendações P1 +3. [ ] Re-validar com /validate-component +4. [ ] Deploy quando score ≥7/10 +``` + +--- + +## Exemplos de Uso + +### Exemplo 1: Skill com Boa Referenciação + +``` +User: /validate-component /mcp-dev +Assistant: + +# Relatório Validação: mcp-dev + +**Score:** 9/10 ✅ + +## Status Geral +Excelente! Padrão ouro de referenciação. + +## Issues Detectadas +Nenhuma crítica. Pequena sugestão: expandir descrição PROC-MCP-Session-Recovery.md. + +## Boas Práticas +- Secção "Referências e Documentação" completa +- 5 links file:// para PROCs relevantes +- Instruções "SEMPRE consultar antes de..." +- Separação clara: comandos na skill, regras nos PROCs +``` + +### Exemplo 2: Agent com Procedimentos Embeddados + +``` +User: /validate-component wordpress-plugin-developer +Assistant: + +# Relatório Validação: wordpress-plugin-developer + +**Score:** 4/10 ❌ + +## Issues Críticas + +1. **Checklist WordPress Security (60 linhas embeddadas)** + - Localização: Linhas 234-294 + - Problema: Checklist completa hardening no system prompt + - Acção: Extrair para PROC-WordPress-Hardening.md (D7-Tecnologia) + +2. **Sem Secção Referências** + - System prompt não referencia nenhum PROC + - Deve adicionar links para PROC-WordPress-* relevantes + +## Recomendações P1 + +1. Criar PROC-WordPress-Hardening.md com checklist +2. Criar PROC-WordPress-CLI.md com comandos WP-CLI +3. Adicionar secção "Referências" no system prompt +4. Re-validar após refactoring +``` + +### Exemplo 3: Skill Nova Antes de Deploy + +``` +User: Criei /easypanel-deploy skill. Validar antes de commit? +Assistant: /validate-component easypanel-deploy + +# Relatório Validação: easypanel-deploy + +**Score:** 6/10 ⚠️ + +## Avisos + +1. **Workflow Deploy (40 linhas)** + - Localização: Secção "Deployment Workflow" + - Problema: Workflow passo-a-passo detalhado + - Sugestão: Considerar PROC-Deployment-EasyPanel.md (D7/INF) + - Alternativa: Manter se workflow é core da skill + +2. **API Reference Embeddada** + - 80 linhas de endpoints EasyPanel + - Sugestão: Mover para references/easypanel-api.md + +## Recomendações + +Score 6/10 é aceitável para deploy. Opcionalmente: +- Extrair API reference para ficheiro separado (progressive disclosure) +- Se workflow deploy for usado por outros componentes → PROC +``` + +--- + +## Integração CI/CD + +Para validação automática antes de commit: + +```bash +# .git/hooks/pre-commit +if [[ $(git diff --cached --name-only) =~ (skills|agents) ]]; then + echo "Validating modified components..." + claude-code /validate-component [path] +fi +``` + +--- + +## Critérios de Score + +### Score 9-10 (Excelente) +- Secção "Referências" completa e bem estruturada +- Todos os PROCs relevantes referenciados +- Zero procedimentos embeddados +- Separação clara comando vs regra + +### Score 7-8 (Bom) +- Secção "Referências" existe +- Maioria dos PROCs referenciados +- Pequenos procedimentos embeddados (<20 linhas) +- Maioria do conteúdo bem separado + +### Score 5-6 (Aceitável) +- Algumas referências, mas incompletas +- Procedimentos embeddados médios (20-50 linhas) +- Separação parcial +- Deploy OK mas melhorias recomendadas + +### Score 3-4 (Crítico) +- Sem secção "Referências" ou vazia +- Procedimentos longos embeddados (>50 linhas) +- Má separação comando vs regra +- Refactoring necessário antes deploy + +### Score 0-2 (Bloqueado) +- Zero referências a PROCs +- Procedimentos extensos embeddados (>100 linhas) +- Duplicação crítica de conteúdo +- Deploy BLOQUEADO até corrigir + +--- + +## Anti-Patterns + +**NUNCA:** +- ❌ Aprovar deploy com score <5/10 +- ❌ Ignorar issues críticas +- ❌ Validar sem ler componente completo +- ❌ Sugerir extrair conteúdo que é core da skill + +**SEMPRE:** +- ✅ Testar links file:// funcionam +- ✅ Verificar departamento correcto dos PROCs +- ✅ Distinguir "core skill" vs "procedimento duplicado" +- ✅ Dar exemplos concretos de refactoring + +--- + +## Referência: /mcp-dev (Padrão Ouro) + +Ver secção "Referências e Documentação" em: +`/home/ealmeida/.claude/plugins/.../mcp-dev/SKILL.md` + +**O que faz bem:** +- Secção dedicada no topo +- 5 links file:// para PROCs D7-Tecnologia +- Descrição breve de cada PROC +- Instrução clara "SEMPRE consultar antes de criar/modificar MCPs" +- Quick Reference sintética (não duplica PROC) + +--- + +*Skill v1.0.0 | 2026-02-13 | Plugin gestao | 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ós cada erro corrigido.* diff --git a/gestao/skills/worklog/SKILL.md b/gestao/skills/worklog/SKILL.md index d975c6b..0537aab 100644 --- a/gestao/skills/worklog/SKILL.md +++ b/gestao/skills/worklog/SKILL.md @@ -1,10 +1,9 @@ --- name: worklog -description: Registo de trabalho e reflexão unificado. Analisa sessão, regista trabalho, identifica padrões, sugere acções. /reflect é alias (mesmo resultado). Variantes: deep (análise profunda), week (revisão semanal). Usar quando "worklog", "reflect", "reflexão", "registar trabalho", "log", ao parar timer. -layer: wiki +description: "Registo de trabalho e reflexão unificado. Analisa sessão, regista trabalho, identifica padrões, sugere acções, higieniza documentação Hub. /reflect é alias (mesmo resultado). Variantes: deep (análise profunda), week (revisão semanal). Usar quando \"worklog\", \"reflect\", \"reflexão\", \"registar trabalho\", \"log\", ao parar timer." --- -# /worklog v4.1 - Registo de Trabalho + Reflexão +# /worklog v4.8.0 - Registo de Trabalho + Reflexão + Higienização **⚠️ EXECUÇÃO INLINE OBRIGATÓRIA — NUNCA FORK** @@ -14,8 +13,6 @@ Quando `/worklog` ou `/reflect` é invocado, o agente principal executa o protoc O histórico da conversa actual é a **fonte primária** do worklog. Só o agente principal o tem. Qualquer fork devolve "nothing to log" e falha silenciosamente o registo — anti-padrão verificado empiricamente em 2026-04-23. -Skill unificada: regista trabalho, analisa sessão, sugere acções, guarda memória. - **`/reflect` = alias de `/worklog`** (mesmo resultado). --- @@ -49,34 +46,12 @@ Skill unificada: regista trabalho, analisa sessão, sugere acções, guarda mem ``` 1. Obter hora via mcp__mcp-time__current_time 2. Verificar timer activo em ~/.claude-work/active-timer.json -3. ANALISAR sessão — FONTE PRIMÁRIA é o histórico conversacional actual do agente: - A) **Contexto conversa (OBRIGATÓRIO — FONTE PRIMÁRIA):** - O agente que executa esta skill tem, no seu próprio histórico, toda a informação que precisa. - Extrair directamente: - - Ficheiros modificados (procurar Edit/Write/MultiEdit nos tool_use da sessão) - - MCPs usados (procurar mcp__*__* tool calls) - - Erros encontrados e soluções aplicadas - - Padrões detectados, decisões arquitecturais - - Pedidos sucessivos do utilizador (sequência de mensagens user) - - Commits feitos (procurar `git commit` em tool_use) - - Subagentes dispatched (Agent tool calls) - - B) **Contexto externo (COMPLEMENTAR — SEMPRE recolher):** - - git diff --stat (últimas 3h): ficheiros alterados - - git log --oneline --since="3 hours ago": commits recentes - - SQLite Observabilidade (se disponível): `~/.claude-work/sessions.db` tabela sessions com project_slug+started_at+tool_calls da sessão actual - - find 00-Inbox/ -name "worklog-$(date +%Y-%m-%d)*" -newer - - Ficheiros modificados nas últimas 3h no working directory - - Tarefas Desk com comentários criados hoje (mcp__desk-crm-v3__get_task_comments filter staff_id=1 or 25) - - C) **Activity log do hook (FALLBACK — cross-session apenas):** - Usar só quando A) está genuinamente vazio (ex: /worklog invocado manualmente sem contexto activo). - - ls -lat ~/.claude-work/sessions/*.activity.log | head -5 - - Escolher activity.log MAIOR modificado nas últimas 2h (>5KB) - - Ler o .json correspondente para metadata - - REGRA: A) preenche o corpo do worklog. B) adiciona detalhes. C) só se A) vazio. - REGRA: Se A), B) e C) todos vazios após verificação rigorosa → NÃO gerar e reportar "nada novo para registar". +3. ANALISAR sessão: + - Ficheiros modificados (Edit/Write calls) + - MCPs usados + - Erros e soluções + - Padrões detectados + - Eficiência (tool calls vs resultado) 3b. VERIFICAR alinhamento com spec (se aplicavel): - Detectar ficheiros modificados na sessao - Procurar SPEC.md no directorio pai (ate 3 niveis) @@ -84,9 +59,7 @@ Skill unificada: regista trabalho, analisa sessão, sugere acções, guarda mem - SE ficheiro nao mapeia para scope: incluir SCOPE ALERT no worklog - SE sem SPEC.md: ignorar silenciosamente 4. VERIFICAR se há algo novo a documentar - - Se conversa vazia → recolher contexto externo (passo 3B) - - Se contexto externo tambem vazio → NÃO gerar - - NUNCA desistir sem verificar fontes externas primeiro + - Se sessão vazia/sem dados → NÃO gerar 5. Gerar comentário HTML (ver formato abaixo) 6. mcp__desk-crm-v3__add_discussion_comment({ discussion_id: 31, @@ -99,10 +72,330 @@ Skill unificada: regista trabalho, analisa sessão, sugere acções, guarda mem content: accoes_html, staff_id: 25 }) -7b. TRIGGER improvement-evaluator no desktop (localhost): - Bash: curl -s -X POST http://localhost:8095/trigger - (falha silenciosa OK — o systemd timer apanha em 30min) -8. SE insight valioso → mcp__mem_save_memory({ text: "[resumo do insight]" }) +7b. SUGESTÕES DE MELHORIA — avaliação autónoma (NÃO chamar nada): + As sugestões ficam registadas no passo 7 (Discussão #33). O Improvement Evaluator v2 (cronjob Hermes + no desktop, job d398b5e2c3be) lê os registos do worklog/#33 autonomamente e leva-os para a sua BD; + corre diariamente e gera ticket "Sugestões de Melhoria — Semana X" às segundas. + O /worklog NÃO dispara nem chama o evaluator — apenas regista. + (v1 HTTP :8095 http-trigger.py descontinuada/arquivada em 99-Arquivo/improvement-evaluator-v1-legado/. + Servidor "dev"/CT 102 abatido em 20-04-2026 — Regra #48; qualquer chamada ssh_execute(server:"dev") + falha sempre, não usar.) +8. SE insight valioso → save_memory Supabase 8b. GIT CHECKPOINT (automático se em projecto git): a. Verificar se existe `.desk-project` no directório actual (ou até 3 níveis acima) - b. Se sim: verificar se é repositório \ No newline at end of file + b. Se sim: verificar se é repositório git (`git rev-parse --git-dir`) + c. Se sim: verificar se há alterações pendentes (`git status --porcelain`) + d. Se há alterações: + - Gerar entrada CHANGELOG a partir da secção "Trabalho Realizado": + `- YYYY-MM-DD [tarefa #ID] Descrição concisa do trabalho feito` + Inserir em `## [Unreleased]` do CHANGELOG.md + - `git add -A` + - `git commit -m "worklog: [tarefa #ID] descrição da sessão"` + - `git push origin ` + - Registar resultado no output final + e. Se sem alterações: omitir (não mencionar) +9. HIGIENIZAÇÃO (obrigatório SE algum .md dentro do Hub foi criado/editado nesta sessão — PROC-Higienizacao-Documental.md, XDP-HIG-001): + a. CRIAR OKF: para cada .md novo que representa sistema/aplicação/processo real (não nota solta, + não template) — verificar se já existe ficha de entidade. Se não existe: criar 5W2H-PDCA agora, + não adiar. `bash 04-Stack/scripts/okf-detect-new.sh --hub --json /tmp/wl-detect.json` para listar + candidatos; `bash 04-Stack/scripts/okf-suggest-entity.sh ` para gerar proposta por ficheiro. + b. ACTUALIZAR REFERÊNCIAS: se alguma métrica/nome/link mudou nesta sessão, grep pelo valor antigo + nos documentos "vivos" (mapas de ecossistema, STK-Estado-Actual, fichas OKF relacionadas) e + propagar a correcção. Documentos históricos datados (changelogs antigos, snapshots rotulados + "auditado em DD-MM") NÃO se reescrevem. + c. ELIMINAR FICHEIROS DESNECESSÁRIOS: procurar `.bak`/`.tmp`/rascunhos/relatórios + `VALIDACAO-FASE-F-*.md` avulsos criados nesta sessão e remover antes do fecho. + d. ORGANIZAR E INDEXAR: directório novo criado nesta sessão tem `index.md`? Está referenciado no + MOC/índice do directório pai? Se não, corrigir agora. + e. Se algum dos 4 tópicos foi genuinamente ignorado (ex: nenhum .md tocado), omitir silenciosamente + esta secção do output. Se foi aplicável e ficou por fazer, reportar como bloqueio explícito — + nunca como "nota para depois". +10. Confirmar +``` + +**Output:** + +```markdown +Worklog registado! + +Tarefa: #1446 - Documentação Skills +Duração: 2h 15m +Discussão: #31 (Logs) +Acções: 2 sugeridas (#33) +Memória: Guardada / N/A +Git: commit abc1234 → push OK +Higienização: N/A (sem alterações no Hub) | OK (4/4 tópicos) | 2 pendências reportadas como bloqueio +``` + +--- + +## Formato Comentário HTML (Discussão #31) + +```html +

YYYY-MM-DD HH:MM - Título da Sessão

+ +

Projecto: Nome

+

Tarefa: #ID - Nome

+

Duração: ~XXh YYm

+

Resultado: Concluído | Parcial | Bloqueado

+ +

Trabalho Realizado

+
    +
  • Acção 1
    • +
  • Acção 2
    • +
+ +

Ficheiros Modificados

+
    +
  • path/file.ext - descrição
    • +
+ +

Problemas / Soluções

+
    +
  • Problema: Descrição +
    Solução: Como foi resolvido
    • +
+ +

Alertas de Scope

+
    +
  • SCOPE ALERT: path nao mapeado no SPEC
    • +
+ +

Padrões Detectados

+
    +
  • Padrão identificado e impacto
    • +
+ +

Acções Sugeridas

+

Detalhes na discussão #33

+
    +
  • [Tipo] Descrição breve
    • +
+ +

Próximos Passos

+
    +
  1. Tarefa pendente 1
    2. +
+``` + +--- + +## Formato Acções (Discussão #33) + +Cada acção num comentário separado: + +```html +

- [ ] [Tipo] Descrição da acção

+

Origem: Worklog YYYY-MM-DD HH:MM

+

Prioridade: P1/P2/P3

+

Contexto: Breve explicação

+``` + +**Tipos:** `[CLAUDE.md]`, `[Skill]`, `[MCP]`, `[Workflow]`, `[Bug]`, `[Feature]` + +--- + +## /worklog view + +``` +1. mcp__desk-crm-v3__get_project_discussions({ project_id: 65 }) +2. Filtrar discussão #31 +3. Mostrar últimos 5 comentários +``` + +--- + +## /reflect deep (Análise Profunda) + +Análise mais detalhada que o worklog normal. Publica em discussão **#32** (Reflexões). + +``` +1. Ler comentários recentes de #31 (worklogs) e #32 (reflexões) +2. Analisar padrões repetidos +3. Comparar eficiência com sessões anteriores +4. Verificar TaskForces utilizadas (ver Integração TaskForce) +5. Gerar comentário detalhado em #32 +6. Acções em #33 +7. Memória Supabase +``` + +--- + +## /reflect week (Revisão Semanal) + +Chamado automaticamente pelo `/today` às segundas-feiras. Publica em **#32**. + +``` +1. Ler comentários de #31 e #32 da semana +2. Agregar padrões e métricas +3. Gerar resumo semanal +4. Identificar melhorias prioritárias +5. FAXINA DE REPO (semanal — âmbito repo inteiro, complementa o Passo 9 diário que só vê a sessão): + a. LIXO → QUARENTENA (nunca rm directo — eliminação é T3): + - detectar por padrão mecânico: *.bak, *.tmp, *~, .xdp-*, VALIDACAO-FASE-F-*.md com >7 dias, + duplicados exactos por checksum (md5sum) + - mover para 99-Arquivo/quarentena/YYYY-WW/ preservando path relativo + - listar no relatório semanal (#32) para aprovação do Emanuel + - purga: só de quarentenas com >30 dias E semana aprovada — nunca na mesma semana + b. ÍNDICES vs REALIDADE: contagens/listas declaradas em index.md e MOCs vs `find` real + (check V-INDICE/N4 do APROFUNDAMENTO 01) — divergência → corrigir o índice, reportar no resumo + c. OKF SEMANAL: `bash 04-Stack/scripts/okf-detect-new.sh --hub` sobre a semana inteira + (apanha o que os Passos 9a diários deixaram escapar) + d. Output ganha secção "Faxina": N em quarentena / M índices corrigidos / K fichas OKF criadas +``` + +**Formato:** + +```html +

Semana YYYY-WNN - Revisão

+ +

Métricas

+ + + + +
Sessões registadasN
Reflexões geradasM
Padrões detectadosP
+ +

Padrões Frequentes

+
  1. Padrão A - Nx detectado
+ +

Melhorias Prioritárias

+
    +
  • [ ] [P1] Descrição
    • +
  • [ ] [P2] Descrição
    • +
+ +

Plano Esta Semana

+
    +
  • Implementar: X
    • +
  • Monitorar: Y
    • +
+``` + +--- + +## Integração /time + +Quando `/time stop` é executado: + +``` +1. Timer parado +2. Mostrar resumo (tarefa, duração) +3. Perguntar: "Criar worklog? [Sim/Não]" +4. Se sim → Gerar worklog com contexto do timer +``` + +--- + +## Auto-Save Memória + +| Tipo | Exemplo | Guardar? | +|------|---------|----------| +| Solução técnica nova | Fix para erro MCP | Sim | +| Configuração sistema | Novo MCP configurado | Sim | +| Workaround descoberto | Bypass para bug | Sim | +| Padrão novo | "X funciona melhor que Y" | Sim | +| Decisão arquitectural | Escolha de abordagem | Sim | +| Trabalho rotineiro | Updates, limpeza | Não | + +--- + +## Checklist de Reflexão + +Perguntas ao analisar sessão: + +- O sistema respondeu bem aos pedidos? +- Houve confusão ou mal-entendidos? +- Alguma tarefa repetitiva deveria ser skill? +- Faltou informação que deveria estar em memória? +- Alguma regra CLAUDE.md foi violada? +- Os MCPs funcionaram correctamente? +- **Context health:** CLAUDE.md global <200 linhas? MEMORY.md pessoal de agente: deprecated (Ref: DEV-CTX-001) + +--- + +## Auto-Alerts Data-Driven + +| Alerta | Threshold | Acção | +|--------|-----------|-------| +| Degradação performance | >15% vs baseline (7d) | Investigar causa | +| Error rate alto | >10% (30d) | Analisar erros | +| KB offline | 3 timeouts | Verificar MCP | + +**Formato alerta:** Inclui componente, tipo, threshold, valor actual, investigação e acções sugeridas. + +--- + +## Integração TaskForce (para /reflect deep) + +``` +1. LER ~/.claude/sdks/_registry.json +2. COMPARAR com skills/agents usados na sessão +3. SE match: adicionar secção "SDKs Utilizados" com tempo e baseline +``` + +--- + +## Auto-Trigger + +| Trigger | Acção | +|---------|-------| +| >10 tool calls | Gerar worklog background | +| Parar timer | Oferecer criar worklog | +| Mudança de projecto | Fechar sessão anterior | +| Mesmo erro 2+ vezes | Analisar causa | +| Segunda-feira via /today | Revisão semanal | + +--- + +## Anti-Patterns + +- **NUNCA** criar worklog sem dados de sessão +- **NUNCA** usar Markdown em comentários (usar HTML) +- **NUNCA** guardar memória para trabalho rotineiro +- **NUNCA** duplicar reflexão e worklog (são o mesmo) +- **NUNCA** fazer fork (Skill tool/Agent tool) para executar /worklog — perde o contexto conversacional que é a fonte primária. Anti-padrão verificado 2026-04-23. +- **NUNCA** omitir o Passo 9 (Higienização) quando a sessão tocou ficheiros do Hub — nem reportar "arrumado" sem correr os 4 tópicos. +- **NUNCA** chamar `ssh_execute(server: "dev")` ou qualquer referência ao servidor `dev`/CT 102 — abatido em 20-04-2026 (Regra #48), o alias já não existe em `~/.ssh/config`. +- **NUNCA** `rm` directo na faxina semanal — eliminação é T3 (irreversível): quarentena → aprovação → purga 30d. Um falso positivo com rm destrói trabalho; com quarentena custa um `mv`. + +--- + +## Changelog + +### v4.8.0 (2026-07-03) +- `/reflect week` ganha passo 5 (Faxina de Repo): quarentena de lixo por padrão mecânico (*.bak, *.tmp, *~, .xdp-*, VALIDACAO-* >7d, duplicados por checksum) em `99-Arquivo/quarentena/YYYY-WW/` com aprovação humana e purga a 30d; revisão índices vs disco (check V-INDICE/N4); okf-detect-new semanal. Complementa o Passo 9 diário (âmbito sessão) com âmbito repo. Racional: eliminação é T3 na matriz de tiers (SPEC Pipeline QT); diário=delta, semanal=estado. + +### v4.7.1 (2026-07-02) +- **Bug corrigido:** passo 7b chamava `mcp__ssh-unified__ssh_execute({ server: "dev", ... })` para disparar o improvement-evaluator — servidor `dev`/CT 102 foi abatido em 20-04-2026 (Regra #48), chamada falhava sempre (dead code). Substituído por texto informativo: o evaluator é 100% autónomo (cronjob Hermes no desktop), `/worklog` nunca dispara nada. +- Sincronizado conteúdo entre skill instalada (1.3.0), skill em cache (1.4.0) e fonte marketplace (que estava truncada a 107 linhas) — as três eram divergentes. + +### v4.7.0 (2026-07-02) +- Passo 9 (Higienização) novo: obrigatório sempre que a sessão tocou .md do Hub — 4 tópicos (criar OKF, actualizar referências, eliminar ficheiros desnecessários, organizar e indexar). Ver PROC-Higienizacao-Documental.md, XDP-HIG-001, regra CARL GLOBAL#19. +- Frontmatter corrigido: removido `context: fork` (bug — contradizia a regra "nunca fork" já documentada; causava perda de contexto conversacional em produção). Aviso inline reforçado no topo do ficheiro. +- Output final ganha linha "Higienização: ..." + +### v4.3.0 (2026-04-13) +- Git checkpoint integrado como passo 8b: detecta .desk-project + git, gera entrada CHANGELOG rica, commit + push automático no fim de cada worklog + +### v4.2.0 (2026-03-12) +- Integração improvement-evaluator: passo 7b trigger automático ao dev (POST :8095/trigger) — **descontinuado na v4.7.1** (ver acima) +- Acções publicadas em #33 são avaliadas imediatamente pelo agente cron no dev + +### v4.0.0 (2026-02-06) +- Fusão de /worklog e /reflect numa skill unificada +- /reflect torna-se alias de /worklog +- Discussão #31 recebe tudo (worklog + reflexão) +- Discussão #32 reservada para /reflect deep e /reflect week +- Checklist de reflexão integrado +- Auto-alerts data-driven integrados +- Integração TaskForce mantida para /reflect deep + +### v3.0.0 (2026-02-05) +- Integração completa com /time +- Auto-trigger ao parar timer +- Formato HTML alinhado com Regra #27 + +--- + +*Skill v4.8.0 | 2026-07-03 | Descomplicar®* diff --git a/infraestrutura/.claude-plugin/plugin.json b/infraestrutura/.claude-plugin/plugin.json index 259fd59..aa2e84a 100644 --- a/infraestrutura/.claude-plugin/plugin.json +++ b/infraestrutura/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "infraestrutura", "description": "Server management, Proxmox VE/PBS/Clustering, CWP administration, EasyPanel deployments, security audits, backups and MCP development. Backed by NotebookLM notebooks (Proxmox 150+ sources).", - "version": "1.2.0", + "version": "1.3.0", "author": { "name": "Descomplicar - Crescimento Digital", "url": "https://descomplicar.pt" diff --git a/infraestrutura/agents/backup-specialist.md b/infraestrutura/agents/backup-specialist.md index 0ae74bd..1da5cb6 100644 --- a/infraestrutura/agents/backup-specialist.md +++ b/infraestrutura/agents/backup-specialist.md @@ -7,6 +7,8 @@ model: sonnet tools: Read, Write, Bash, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - ssh-unified - desk-crm-v3 @@ -47,7 +49,6 @@ escalates_to: created: "2025-01-13" updated: "2026-02-04" author: "Descomplicar®" -layer: wiki --- # Backup Specialist Descomplicar @@ -178,4 +179,66 @@ mcp__notebooklm__notebook_query notebook_id:"f9a79b5a-649f-4443-afaf-7ff562b6c2e - **mcp-time** - Hora actual, conversão fusos horários - **puppeteer** - Browser automation -### All \ No newline at end of file +### All Available (32 total) +desk-crm-v3, moloni, context7, gitea, n8n, google-analytics, google-workspace, imap, outline-api, youtube-research, youtube-uploader, gsc, mem0, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, magic, vimeo, design-systems, replicate + +**Discovery:** Use ToolSearch to find specific tools. +**Example:** `ToolSearch("ssh upload")` finds SSH upload tools. +## Your Available Skills + +### Primary Skills (Your Domain) +✓ **/server-health** - Diagnóstico completo de servidor - CPU, RAM, MySQL, Web, SSL, Segurança. Usar qu + - Invoke: `/server-health` + +✓ **/wp-performance** - Auditoria de performance WordPress - cache, GZIP, imagens, plugins, base de dado + - Invoke: `/wp-performance` + +✓ **/wp-update** - Actualização e verificação de todos os sites WordPress do servidor CWP + - Invoke: `/wp-update` + +### Recommended for infra +- **/backup-strategies** - Estratégias de backup e recovery - RTO, RPO, disaster recove +- **/security-audit** - Auditoria de segurança e compliance - OWASP Top 10, GDPR, an +- **/archive** - Arquivamento automatico de ficheiros concluidos - move fiche +- **/delegate** - Delegar tarefas dev para outros chats Claude com workflow co + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /lead-approach, /orcamento, /saas, /content-marketing-pt, /remotion-video, /seo-content-optimization, /social-media, /video, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /crm-admin, /db-design, /elementor, /mcp-dev, /nextjs, /php-dev, /react-patterns, /woocommerce, /wp-dev, /second-brain-repo, /ads, /doc-sync, /marketing-strategy, /product, /skill-creator, /sop-creator, /calendar-manager, /interview, /time, /today, /research, /youtube, /seo-audit, /seo-report, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. +## Colaboração + +- **Reports to**: Security Compliance Specialist +- **Colabora com**: CWP Server Manager, Database Design Specialist, EasyPanel Specialist, Development Lead +- **Escalar para**: Security Compliance Specialist (políticas segurança), CWP Server Manager (recursos servidor) +## Your Team & Responsibilities + +You are part of **3 SDKs** (TaskForce teams): + +### TaskForce Claude Agents + +**Purpose:** NULL + +**Your responsibilities in this TaskForce:** +### TaskForce Gestão Administrativa e Financeira + +**Purpose:** NULL + +### TaskForce Infraestrutura + +**Purpose:** NULL + +**Collaboration:** +- Work with other agents in your TaskForce teams +- Share knowledge and context across team members +- Leverage team-specific skills and MCPs +- Contribute to team goals and deliverables + diff --git a/infraestrutura/agents/cwp-server-manager.md b/infraestrutura/agents/cwp-server-manager.md index 241b2d1..5c93e84 100644 --- a/infraestrutura/agents/cwp-server-manager.md +++ b/infraestrutura/agents/cwp-server-manager.md @@ -7,6 +7,8 @@ model: sonnet tools: Read, Write, Edit, Bash, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - ssh-unified - desk-crm-v3 @@ -53,7 +55,6 @@ escalates_to: created: "2025-01-13" updated: "2026-02-04" author: "Descomplicar®" -layer: wiki --- # CWP Server Manager Descomplicar @@ -140,4 +141,113 @@ Especialista em infraestrutura de servidores CWP, entregando ambientes de hostin 3. Instalar SSL automático 4. Deploy WordPress via SSH 5. `chown -R user:user /home/user/DOMINIO/` -6. Configurar permissões \ No newline at end of file +6. Configurar permissões (755 dirs, 644 files) +7. Testar site + +### Workflow 3: Security Hardening +1. Audit: firewall, malware scanner, access logs +2. Configurar CSF firewall rules +3. Activar malware scanner automático +4. Configurar fail2ban +5. Review SSH access (disable root login) +6. Backup automático configurado + +## MCPs Relevantes +- `ssh-unified`: Acesso aos servidores CWP +- `desk-crm-v3`: Documentar mudanças em projectos +- `mem0`: Histórico de configurações + +## Colaboracao + +- Reports to: EasyPanel Infrastructure Manager +- Colabora com: PHP Fullstack Engineer, WordPress Plugin Developer, Database Design Specialist, Security Compliance Specialist + +## Your Available MCPs + +### Primary MCPs (Your Domain) +✓ **desk-crm-v3** (business) + - Clientes, projectos, facturas, time tracking + - Usage: `mcp__desk-crm-v3__*` + +✓ **ssh-unified** (infra) + - SSH, SFTP, servidor management + - Usage: `mcp__ssh-unified__*` + +✓ **mem0** (system) + - Memória longo prazo + - Usage: `mcp__mem0__*` + +### Recommended for infra +- **cwp** - CentOS Web Panel +- **filesystem** - Ficheiros locais +- **lighthouse** - Performance audits +- **mcp-time** - Hora actual, conversão fusos horários +- **puppeteer** - Browser automation + +### All Available (32 total) +moloni, context7, gitea, n8n, google-analytics, google-workspace, imap, outline-api, youtube-research, youtube-uploader, gsc, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, magic, vimeo, design-systems, replicate + +**Discovery:** Use ToolSearch to find specific tools. +**Example:** `ToolSearch("ssh upload")` finds SSH upload tools. +## Your Available Skills + +### CWP Skills (Official Documentation Only) + +**Zero assumptions, zero hallucinations** - Todas baseadas em documentação oficial CWP. + +| Skill | Função | +|-------|--------| +| **/cwp-ssl** | SSL/AutoSSL com acme.sh nativo | +| **/cwp-accounts** | Gestão de contas via /scripts/cwp_api | +| **/cwp-backup** | Backups com /scripts/user_backup | +| **/cwp-security** | CSF firewall e segurança | +| **/cwp-email** | DKIM, SPF, mail queue | +| **/cwp-php** | PHP Switcher/Selector | +| **/cwp-webserver** | Apache/Nginx rebuild/restart | +| **/cwp-scripts** | Referência completa /scripts/ | + +### Primary Skills (Your Domain) +✓ **/server-health** - Diagnóstico completo de servidor + - Invoke: `/server-health` + +✓ **/wp-performance** - Auditoria de performance WordPress + - Invoke: `/wp-performance` + +✓ **/wp-update** - Actualização WordPress no servidor CWP + - Invoke: `/wp-update` + +### Recommended for infra +- **/backup-strategies** - Estratégias de backup e recovery +- **/security-audit** - Auditoria de segurança e compliance + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /lead-approach, /orcamento, /saas, /content-marketing-pt, /remotion-video, /seo-content-optimization, /social-media, /video, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /crm-admin, /db-design, /elementor, /mcp-dev, /nextjs, /php-dev, /react-patterns, /woocommerce, /wp-dev, /second-brain-repo, /ads, /doc-sync, /marketing-strategy, /product, /skill-creator, /sop-creator, /calendar-manager, /interview, /time, /today, /research, /youtube, /seo-audit, /seo-report, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. +## Your Team & Responsibilities + +You are part of **2 SDKs** (TaskForce teams): + +### TaskForce Claude Agents + +**Purpose:** NULL + +**Your responsibilities in this TaskForce:** +### TaskForce Infraestrutura + +**Purpose:** NULL + +**Collaboration:** +- Work with other agents in your TaskForce teams +- Share knowledge and context across team members +- Leverage team-specific skills and MCPs +- Contribute to team goals and deliverables + diff --git a/infraestrutura/agents/easypanel-specialist.md b/infraestrutura/agents/easypanel-specialist.md index 8aba483..b6367c2 100644 --- a/infraestrutura/agents/easypanel-specialist.md +++ b/infraestrutura/agents/easypanel-specialist.md @@ -9,6 +9,8 @@ model: sonnet tools: Read, Write, Edit, Bash, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - ssh-unified - desk-crm-v3 @@ -45,7 +47,6 @@ compliance: created: '2025-01-13' updated: '2026-02-04' author: Descomplicar® -layer: wiki --- # EasyPanel Specialist Descomplicar @@ -162,4 +163,56 @@ Especialista em deployment de aplicacoes, orquestracao de containers e gestao de - **puppeteer** - Browser automation ### All Available (32 total) -moloni, context7, gitea, n8n, google-analytics, google-workspace, imap, outline-api, youtube-research, youtube-uploader, wikijs, gsc, mem0, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, magic, vim \ No newline at end of file +moloni, context7, gitea, n8n, google-analytics, google-workspace, imap, outline-api, youtube-research, youtube-uploader, gsc, mem0, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, magic, vimeo, design-systems, replicate + +**Discovery:** Use ToolSearch to find specific tools. +**Example:** `ToolSearch("ssh upload")` finds SSH upload tools. +## Your Available Skills + +### Primary Skills (Your Domain) +✓ **/server-health** - Diagnóstico completo de servidor - CPU, RAM, MySQL, Web, SSL, Segurança. Usar qu + - Invoke: `/server-health` + +✓ **/wp-performance** - Auditoria de performance WordPress - cache, GZIP, imagens, plugins, base de dado + - Invoke: `/wp-performance` + +✓ **/wp-update** - Actualização e verificação de todos os sites WordPress do servidor CWP + - Invoke: `/wp-update` + +### Recommended for infra +- **/backup-strategies** - Estratégias de backup e recovery - RTO, RPO, disaster recove +- **/security-audit** - Auditoria de segurança e compliance - OWASP Top 10, GDPR, an +- **/archive** - Arquivamento automatico de ficheiros concluidos - move fiche +- **/delegate** - Delegar tarefas dev para outros chats Claude com workflow co + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /lead-approach, /orcamento, /saas, /content-marketing-pt, /remotion-video, /seo-content-optimization, /social-media, /video, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /crm-admin, /db-design, /elementor, /mcp-dev, /nextjs, /php-dev, /react-patterns, /woocommerce, /wp-dev, /second-brain-repo, /ads, /doc-sync, /marketing-strategy, /product, /skill-creator, /sop-creator, /calendar-manager, /interview, /time, /today, /research, /youtube, /seo-audit, /seo-report, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. +## Your Team & Responsibilities + +You are part of **2 SDKs** (TaskForce teams): + +### TaskForce Claude Agents + +**Purpose:** NULL + +**Your responsibilities in this TaskForce:** +### TaskForce Infraestrutura + +**Purpose:** NULL + +**Collaboration:** +- Work with other agents in your TaskForce teams +- Share knowledge and context across team members +- Leverage team-specific skills and MCPs +- Contribute to team goals and deliverables + diff --git a/infraestrutura/agents/infrastructure-orchestrator.md b/infraestrutura/agents/infrastructure-orchestrator.md index 8da24e9..ae79b84 100644 --- a/infraestrutura/agents/infrastructure-orchestrator.md +++ b/infraestrutura/agents/infrastructure-orchestrator.md @@ -6,6 +6,8 @@ model: sonnet tools: Read, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - ssh-unified - desk-crm-v3 @@ -17,7 +19,6 @@ allowed-mcps: desk-crm-v3, filesystem, mcp-time, gitea category: infra author: Descomplicar® version: 1.0.1 -layer: wiki --- # Infrastructure Orchestrator diff --git a/infraestrutura/agents/proxmox-specialist.md b/infraestrutura/agents/proxmox-specialist.md index dc63198..644da24 100644 --- a/infraestrutura/agents/proxmox-specialist.md +++ b/infraestrutura/agents/proxmox-specialist.md @@ -9,6 +9,8 @@ model: sonnet tools: Read, Write, Edit, Bash, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - ssh-unified - desk-crm-v3 @@ -48,7 +50,6 @@ compliance: created: '2026-02-14' updated: '2026-02-14' author: Descomplicar® -layer: wiki --- # Proxmox Specialist Descomplicar @@ -149,4 +150,297 @@ Especialista em Proxmox VE 8.x, PBS, Clustering e HA para Hetzner. Consulta Note |-------|--------|--------| | **/proxmox-setup** | Instalação node completa: installimage → ZFS → NAT networking | Pending | | **/pbs-config** | PBS setup: datastore → sync jobs → retention policies | Pending | -| **/vm-migration** | Migraç \ No newline at end of file +| **/vm-migration** | Migração workloads: CWP → Proxmox, EasyPanel → Proxmox | Pending | +| **/proxmox-cluster** | Cluster formation: 2 nodes → Corosync → Quorum | Pending | +| **/proxmox-ha** | HA Manager: resource groups → fencing → live migration | Pending | + +**Workflow completo:** +``` +/proxmox-setup → /pbs-config → /vm-migration + ↓ + /proxmox-cluster → /proxmox-ha +``` + +## Workflows + +### Workflow 1: Setup Node Proxmox em Hetzner + +**Pre-requisites:** +- Servidor dedicado Hetzner contractado +- Rescue mode activo + +**Steps:** +1. **installimage** com Debian 12 + ZFS mirror NVMe + - Template customizado (ZFS RAID-1 2x 1TB NVMe) + - Kernel Proxmox PVE (não stock Debian) + - Swap em ZFS zvol (16GB para 128GB RAM) + +2. **Proxmox VE 8.x installation** + ```bash + apt update && apt install proxmox-ve + ``` + +3. **ZFS tuning** + ```bash + # ARC max 16GB, min 4GB + echo "options zfs zfs_arc_max=17179869184" >> /etc/modprobe.d/zfs.conf + echo "options zfs zfs_arc_min=4294967296" >> /etc/modprobe.d/zfs.conf + update-initramfs -u + ``` + +4. **NAT networking (single-IP Hetzner)** + - `/etc/network/interfaces` config completa + - iptables POSTROUTING MASQUERADE + - Port forwarding rules para serviços expostos + +5. **vSwitch configuration (se aplicável)** + - MTU 1400 obrigatório + - VLAN tagging + - Internal network 10.0.0.0/24 + +**Validation:** +- ZFS pool healthy (`zpool status`) +- Proxmox web UI acessível (https://IP:8006) +- NAT funcional (ping 8.8.8.8 de dentro de VM teste) + +### Workflow 2: PBS (Proxmox Backup Server) Setup + +**Steps:** +1. **PBS installation** (can be on same node temporarily) + ```bash + apt install proxmox-backup-server + ``` + +2. **Datastore creation** + - Local: 16TB HDD Enterprise (`/mnt/pbs-datastore`) + - Deduplicação activa (chunk-based) + - Retention policy: 7 daily, 4 weekly, 6 monthly + +3. **Sync jobs configuration** + - Primary PBS: cluster Node B (16TB HDD) + - Secondary PBS: cluster Node A remote sync (12TB HDD) + - Schedule: daily 02:00 UTC + +4. **Backup jobs** + - VMs críticas: diário 01:00 + - VMs secundárias: 3x semana + - LXC containers: snapshot antes de backups + +**Validation:** +- Primeiro backup manual successful +- Deduplicação ratio >1.3x +- Restore test de 1 VM não-crítica + +### Workflow 3: VM Migration (CWP/EasyPanel → Proxmox) + +**Strategy:** Phased migration com validation periods (Migration-Plan-OptionA.md) + +**Phase 1: EasyPanel Migration (Week 1-2)** +1. Backup EasyPanel containers em easy.descomplicar.pt +2. Criar VM Proxmox para Docker host +3. Migrar containers batch (5-10 de cada vez) +4. Validar health endpoints + DNS +5. Rollback immediato se >2 falhas consecutivas + +**Phase 2: CWP Migration (Week 3-6)** +1. **7 dias safety net:** server.descomplicar.pt intacto +2. Criar VM AlmaLinux 8 para CWP +3. Migrar contas CWP batch (rsync + mysql dump) +4. Validar sites (content, DB, email) +5. DNS cutover gradual (TTL 300s) +6. Rollback disponível durante 7 dias + +**Phase 3: Cluster Formation (Week 7-8)** +1. Preparar server.descomplicar.pt como Node A +2. `pvecm create cluster-descomplicar` +3. `pvecm add ` em Node B +4. Validar quorum (2 votes) +5. Configurar HA groups +6. Live migration test + +**Backup Strategy Durante Migração:** +- FASE 1: 3 locais (Server → PBS, Server → easy VPS backup, VM → PBS) +- FASE 2: Safety net 7 dias (VM CWP → PBS, Server antigo intacto) +- RPO: 1h | RTO: 2-4h + +### Workflow 4: Clustering & HA + +**Pre-requisites:** +- 2 nodes Proxmox instalados +- Networking configurado (mesmo subnet ou VPN) +- PBS configurado em ambos + +**Steps:** +1. **Cluster creation** (em Node B) + ```bash + pvecm create cluster-descomplicar + ``` + +2. **Node join** (em Node A) + ```bash + pvecm add + ``` + +3. **Quorum validation** + ```bash + pvecm status # Expected votes: 2 + ``` + +4. **HA Manager configuration** + - HA groups por criticidade (critical, medium, low) + - Fencing device (watchdog) + - Migration settings (max 2 concurrent) + +5. **Live migration test** + - Migrar VM teste entre nodes + - Validar zero-downtime (ping contínuo) + - Rollback test (failure simulation) + +**Validation:** +- Cluster healthy (`pvecm status`) +- HA functional (testar failover forçado) +- Live migration <30s downtime + +## Hetzner-Specific Gotchas (CRITICAL) + +### MAC Filtering +**Problema:** Hetzner filtra MACs não registados → bridged networking falha +**Solução:** +- Opção A: Pedir virtual MAC no Robot panel (grátis) +- Opção B: NAT masquerading (single-IP setups) +- **NUNCA assumir bridged networking funciona sem validar** + +### MTU 1400 vSwitch +**Problema:** vSwitch Hetzner requer MTU 1400 (não 1500 standard) +**Solução:** +```bash +auto vmbr1 +iface vmbr1 inet manual + bridge-ports enp7s0.4000 + bridge-stp off + bridge-fd 0 + mtu 1400 +``` + +### Gateway Point-to-Point +**Problema:** Gateway Hetzner fora da subnet (/32 setup) +**Solução:** +```bash +auto eno1 +iface eno1 inet static + address YOUR_IP/32 + gateway GATEWAY_IP + pointopoint GATEWAY_IP +``` + +### ZFS ARC vs KVM Memory +**Problema:** ZFS ARC compete com VMs por RAM +**Solução:** ARC max 16GB para 128GB RAM (deixa 110GB para VMs) + +### Docker Overlay2 em ZFS +**Problema:** ZFS não suporta overlay2 nativo +**Solução:** +- Criar ext4 bind mount: `/var/lib/docker` em ext4 filesystem +- LXC unprivileged com `nesting=1` + +## MCPs Relevantes +- `ssh-unified`: Acesso remoto aos nodes Proxmox +- `desk-crm-v3`: Documentar migration phases em task #1712 +- `notebooklm`: KB primária (Gemini 2.5 RAG, 150+ fontes) +- `mem0`: Guardar gotchas descobertos durante migration +- `filesystem`: Ler/escrever configs e scripts locais +- `gitea`: Version control de Terraform configs + +## Colaboração +- Reports to: Infrastructure Manager +- Colabora com: System administrators, DevOps specialists, Backup specialists +- Escalate: Problemas de hardware Hetzner, suporte Proxmox Enterprise + +## Your Available MCPs + +### Primary MCPs (Your Domain) +✓ **desk-crm-v3** (business) + - Documentar migration progress em task #1712 + - Usage: `mcp__desk-crm-v3__*` + +✓ **ssh-unified** (infra) + - SSH para nodes Proxmox (cluster.descomplicar.pt, server.descomplicar.pt) + - Usage: `mcp__ssh-unified__*` + +✓ **notebooklm** (knowledge primária) + - 150+ fontes Proxmox research consolidadas + - Usage: `mcp__notebooklm__notebook_query` + +✓ **mem0** (knowledge persistence) + - Guardar gotchas técnicos descobertos + - Usage: `mcp__mem0__*` + +### Recommended for Proxmox +- **filesystem** - Configs locais, Terraform files +- **gitea** - Version control de infrastructure code +- **mcp-time** - Scheduling de backups e sync jobs + +### All Available (32 total) +moloni, context7, n8n, google-analytics, google-workspace, imap, outline-api, youtube-research, youtube-uploader, gsc, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, magic, vimeo, design-systems, replicate, cwp, lighthouse, puppeteer + +**Discovery:** Use ToolSearch to find specific tools. +**Example:** `ToolSearch("ssh execute")` finds SSH execution tools. +## Your Available Skills + +### Primary Skills (Your Domain) +✓ **/proxmox-setup** - Instalação node Proxmox: installimage → ZFS → NAT networking (PENDING) + - Invoke: `/proxmox-setup` + +✓ **/pbs-config** - PBS configuration: datastore → sync jobs → retention (PENDING) + - Invoke: `/pbs-config` + +✓ **/vm-migration** - Migração workloads: CWP/EasyPanel → Proxmox (PENDING) + - Invoke: `/vm-migration` + +### Recommended for Proxmox +- **/backup-strategies** - Estratégias backup 3-2-1, RTO/RPO, disaster recovery +- **/security-audit** - Auditoria segurança (firewall, SSH hardening, updates) +- **/server-health** - Diagnóstico servidor (CPU, RAM, disk, services) + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua +- **/worklog** - Registo trabalho com migration phases tracking +- **/_core** - Sacred Rules, Excellence Standards +- **/knowledge** - Unified KB search (NotebookLM → Hub) +- **/desk** - Integração .desk-project (task #1712, project #65) + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /lead-approach, /orcamento, /saas, /content-marketing-pt, /remotion-video, /seo-content-optimization, /social-media, /video, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /crm-admin, /db-design, /elementor, /mcp-dev, /nextjs, /php-dev, /react-patterns, /woocommerce, /wp-dev, /second-brain-repo, /ads, /doc-sync, /marketing-strategy, /product, /skill-creator, /sop-creator, /calendar-manager, /interview, /time, /today, /research, /youtube, /seo-audit, /seo-report, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. +## Hardware Context (Current Mission) + +### New Server (cluster.descomplicar.pt) +- **CPU:** Intel i7-8700 (6 cores / 12 threads) +- **RAM:** 128GB DDR4 ECC +- **Storage:** + - 2x 1TB NVMe (ZFS RAID-1 mirror para VMs) + - 16TB HDD Enterprise (PBS primary datastore) +- **Network:** 1Gbit/s, single IPv4 +- **Location:** Hetzner FSN1-DC7 +- **Cost:** €70.70/month + +### Current Infrastructure (To Migrate) +- **server.descomplicar.pt** - Dedicated, CWP, CentOS 7 (EOL), 39 vhosts +- **easy.descomplicar.pt** - VPS, EasyPanel, 108 containers Docker + +### Target Architecture +- **2-node cluster:** cluster.descomplicar.pt (Node B) + server.descomplicar.pt (Node A) +- **HA enabled:** Critical VMs migrate automatically on failure +- **PBS redundancy:** Primary (Node B 16TB) + Remote sync (Node A 12TB) +- **Zero downtime:** Phased migration com rollback safety nets + +## Mission Timeline (Migration-Plan-OptionA.md) + +- **Week 1-2:** Setup Node B + PBS + EasyPanel migration +- **Week 3-6:** CWP migration com 7 dias validation window +- **Week 7-8:** Cluster formation + HA + cleanup legacy + +**Status:** Research phase | Awaiting hardware delivery +**Task:** #1712 (Desk CRM) | **Project:** #65 (Cluster Descomplicar) diff --git a/infraestrutura/agents/security-compliance-specialist.md b/infraestrutura/agents/security-compliance-specialist.md index 609ec2d..e8183c1 100644 --- a/infraestrutura/agents/security-compliance-specialist.md +++ b/infraestrutura/agents/security-compliance-specialist.md @@ -11,6 +11,8 @@ model: opus tools: Read, Write, Edit, Bash, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - ssh-unified - desk-crm-v3 @@ -39,7 +41,6 @@ compliance: created: '2025-01-13' updated: '2026-02-04' author: Descomplicar® -layer: wiki --- # Security Compliance Specialist Descomplicar @@ -137,7 +138,64 @@ Especialista em ciberseguranca e compliance responsavel por auditar sistemas, im - **puppeteer** - Browser automation ### All Available (32 total) -moloni, context7, gitea, n8n, google-analytics, google-workspace, imap, outline-api, youtube-research, youtube-uploader, wikijs, gsc, mem0, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, magic, vimeo, design-systems, replicate +moloni, context7, gitea, n8n, google-analytics, google-workspace, imap, outline-api, youtube-research, youtube-uploader, gsc, mem0, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, elevenlabs, magic, vimeo, design-systems, replicate **Discovery:** Use ToolSearch to find specific tools. -**Example:** `ToolSear \ No newline at end of file +**Example:** `ToolSearch("ssh upload")` finds SSH upload tools. +## Your Available Skills + +### Primary Skills (Your Domain) +✓ **/server-health** - Diagnóstico completo de servidor - CPU, RAM, MySQL, Web, SSL, Segurança. Usar qu + - Invoke: `/server-health` + +✓ **/wp-performance** - Auditoria de performance WordPress - cache, GZIP, imagens, plugins, base de dado + - Invoke: `/wp-performance` + +✓ **/wp-update** - Actualização e verificação de todos os sites WordPress do servidor CWP + - Invoke: `/wp-update` + +### Recommended for infra +- **/backup-strategies** - Estratégias de backup e recovery - RTO, RPO, disaster recove +- **/security-audit** - Auditoria de segurança e compliance - OWASP Top 10, GDPR, an +- **/archive** - Arquivamento automatico de ficheiros concluidos - move fiche +- **/delegate** - Delegar tarefas dev para outros chats Claude com workflow co + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /lead-approach, /orcamento, /saas, /content-marketing-pt, /remotion-video, /seo-content-optimization, /social-media, /video, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /crm-admin, /db-design, /elementor, /mcp-dev, /nextjs, /php-dev, /react-patterns, /woocommerce, /wp-dev, /second-brain-repo, /ads, /doc-sync, /marketing-strategy, /product, /skill-creator, /sop-creator, /calendar-manager, /interview, /time, /today, /research, /youtube, /seo-audit, /seo-report, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. +## Your Team & Responsibilities + +You are part of **4 SDKs** (TaskForce teams): + +### TaskForce Claude Agents + +**Purpose:** NULL + +**Your responsibilities in this TaskForce:** +### TaskForce Infraestrutura + +**Purpose:** NULL + +### TaskForce SaaS + +**Purpose:** NULL + +### TaskForce Segurança e Autenticação + +**Purpose:** NULL + +**Collaboration:** +- Work with other agents in your TaskForce teams +- Share knowledge and context across team members +- Leverage team-specific skills and MCPs +- Contribute to team goals and deliverables + diff --git a/infraestrutura/skills/authentik/SKILL.md b/infraestrutura/skills/authentik/SKILL.md index ca7e01a..5b17455 100644 --- a/infraestrutura/skills/authentik/SKILL.md +++ b/infraestrutura/skills/authentik/SKILL.md @@ -2,7 +2,6 @@ name: authentik description: Gestão do Authentik SSO via API v3 — utilizadores, grupos, aplicações, providers, flows e eventos em auth.descomplicar.pt. disable-model-invocation: true -layer: wiki --- # /authentik - Gestao Authentik via API v3 @@ -161,4 +160,71 @@ Para POST/PUT/PATCH, adicionar `-X {METHOD} -d '{JSON}'`. ## Paginacao -Todos os endpoints de lista sup \ No newline at end of file +Todos os endpoints de lista suportam: +- `?page=N` - pagina (default: 1) +- `?page_size=N` - itens por pagina (default: 20, max: depende) +- `?ordering=field` - ordenacao (prefixo `-` para descendente) +- `?search=query` - pesquisa texto livre + +Resposta paginada: +```json +{ + "pagination": {"next": 2, "previous": 0, "count": 50, "current": 1, "total_pages": 3}, + "results": [...] +} +``` + +## Aplicacoes Actuais + +| App | Slug | URL | +|-----|------|-----| +| Dashboard Descomplicar | dashboard-descomplicar | https://dash.descomplicar.pt | +| MCP Gateway | mcp-gateway | https://gateway.descomplicar.pt | + +## Exemplos Praticos + +### Listar todos os users +```bash +curl -sk "https://auth.descomplicar.pt/api/v3/core/users/" \ + -H "Authorization: Bearer Sa4Zofsdm7UoMXrHRAZ4sIsvNIqCtEQ3uCZrsDg7kx3wDCKQqI0frlFuoUVS" +``` + +### Criar user +```bash +curl -sk -X POST "https://auth.descomplicar.pt/api/v3/core/users/" \ + -H "Authorization: Bearer Sa4Zofsdm7UoMXrHRAZ4sIsvNIqCtEQ3uCZrsDg7kx3wDCKQqI0frlFuoUVS" \ + -H "Content-Type: application/json" \ + -d '{"username": "joao.silva", "name": "Joao Silva", "email": "joao@empresa.pt", "is_active": true}' +``` + +### Ver login events ultimas 24h +```bash +curl -sk "https://auth.descomplicar.pt/api/v3/events/events/?action=login&ordering=-created" \ + -H "Authorization: Bearer Sa4Zofsdm7UoMXrHRAZ4sIsvNIqCtEQ3uCZrsDg7kx3wDCKQqI0frlFuoUVS" +``` + +### Health check sistema +```bash +curl -sk "https://auth.descomplicar.pt/api/v3/admin/system/" \ + -H "Authorization: Bearer Sa4Zofsdm7UoMXrHRAZ4sIsvNIqCtEQ3uCZrsDg7kx3wDCKQqI0frlFuoUVS" +``` + +## Regras + +1. SEMPRE confirmar com utilizador antes de criar/apagar users +2. NUNCA apagar users admin (akadmin) +3. Pesquisar duplicados antes de criar users (como CRM) +4. Passwords devem ter minimo 12 caracteres +5. Verificar groups existentes antes de associar + +--- + +## 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/infraestrutura/skills/backup-strategies/SKILL.md b/infraestrutura/skills/backup-strategies/SKILL.md index 3da176c..d08ba66 100644 --- a/infraestrutura/skills/backup-strategies/SKILL.md +++ b/infraestrutura/skills/backup-strategies/SKILL.md @@ -1,7 +1,6 @@ --- name: backup-strategies description: Planeamento e implementacao de estrategias de backup -- bases de dados, ficheiros e configuracoes com RPO/RTO e regra 3-2-1. -layer: wiki --- # /backup-strategies - Backup e Disaster Recovery @@ -81,7 +80,7 @@ Inclui: - Backup contas e configuracoes CWP - Rotacao GFS (Grandfather-Father-Son) - Cron schedule completo -- Cloud sync com rclone +- Backup offsite via rclone pontual (LocalBackups→GDrive) — NUNCA rclone mount/bisync em pastas de trabalho - Script teste de restore - Runbook disaster recovery @@ -103,7 +102,7 @@ Ver schedule completo em `references/scripts.md` (seccao Cron Schedule). ### Passo 5: Configurar cloud sync -Configurar rclone para sync automatico. Ver detalhes em `references/scripts.md`. +Offsite via rclone **pontual** LocalBackups→GDrive (ver `references/scripts.md`). NUNCA rclone mount/bisync em pastas de trabalho — InSync é o único sync GDrive activo. ### Passo 6: Testar restore (mensal obrigatorio) @@ -159,7 +158,41 @@ Ver runbook completo passo-a-passo em `references/scripts.md` (seccao Runbook Di - [ ] Scripts de backup criados - [ ] Cron jobs configurados - [ ] Rotacao automatica activa -- [ ] Cloud sync activo (rclone) +- [ ] Backup offsite via rclone pontual (LocalBackups→GDrive) verificado ### Seguranca -- [ ] Encriptacao em backups se \ No newline at end of file +- [ ] Encriptacao em backups sensiveis +- [ ] Permissoes correctas (600/700) +- [ ] Passwords em .my.cnf +- [ ] Offsite com autenticacao 2FA + +### Monitorizacao +- [ ] Logs de backup centralizados +- [ ] Alertas de falha (email/Slack) +- [ ] Relatorio semanal automatico + +### Validacao +- [ ] Primeiro restore teste executado +- [ ] RTO medido (tempo real) +- [ ] RPO validado (dados perdidos) +- [ ] Runbook ajustado conforme teste + +--- + +## Ficheiros de referencia + +| Ficheiro | Conteudo | +|----------|----------| +| [references/scripts.md](references/scripts.md) | Scripts MySQL/PostgreSQL/WordPress/CWP, rotacao GFS, cron, rclone, teste restore, runbook DR | + +--- + +## 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/infraestrutura/skills/backup-strategies/references/scripts.md b/infraestrutura/skills/backup-strategies/references/scripts.md index 0de0380..af00efc 100644 --- a/infraestrutura/skills/backup-strategies/references/scripts.md +++ b/infraestrutura/skills/backup-strategies/references/scripts.md @@ -210,7 +210,9 @@ du -sh "$BACKUP_DIR"/* --- -## Cloud Sync com rclone +## Backup offsite com rclone (só LocalBackups→GDrive) + +> **Nota:** rclone mount/bisync de pastas de trabalho está DESACTIVADO — InSync é o único sync GDrive. rclone serve apenas para espelhar `Externo/LocalBackups` para GDrive offsite (pontual ou cron dedicado de backups). ```bash # Instalar rclone diff --git a/infraestrutura/skills/cwp/SKILL.md b/infraestrutura/skills/cwp/SKILL.md index 86bcd19..75fd89f 100644 --- a/infraestrutura/skills/cwp/SKILL.md +++ b/infraestrutura/skills/cwp/SKILL.md @@ -1,12 +1,11 @@ --- name: cwp -description: Meta-skill CWP (CentOS Web Panel, servidor 176.9.3.158) cobrindo gestão de contas, backups, email/Postfix/DKIM, PHP Switcher/Selector, segurança CSF/LFD, SSL/acme.sh, webservers Apache/Nginx e referência completa dos scripts oficiais. Triggers — cwp, centos web panel, cwp_api, /scripts/, csf, lfd, acme, autossl, postfix, dkim, php selector, php switcher, varnish, httpd, nginx cwp, user_backup, whoowns, list_users, hostname ssl, mail queue, fix_perms. -layer: wiki +description: Meta-skill CWP (CentOS Web Panel, servidor server.descomplicar.pt) cobrindo gestão de contas, backups, email/Postfix/DKIM, PHP Switcher/Selector, segurança CSF/LFD, SSL/acme.sh, webservers Apache/Nginx e referência completa dos scripts oficiais. Triggers — cwp, centos web panel, cwp_api, /scripts/, csf, lfd, acme, autossl, postfix, dkim, php selector, php switcher, varnish, httpd, nginx cwp, user_backup, whoowns, list_users, hostname ssl, mail queue, fix_perms. --- # /cwp - Meta-skill CWP (CentOS Web Panel) -Skill unificada para o servidor **CWP Principal `176.9.3.158`** (MCP `ssh-unified`, user `root`). Substitui as antigas cwp-accounts, cwp-backup, cwp-email, cwp-php, cwp-scripts, cwp-security, cwp-ssl, cwp-webserver. +Skill unificada para o servidor **CWP Principal `server.descomplicar.pt`** (MCP `ssh-unified`, user `root`). Substitui as antigas cwp-accounts, cwp-backup, cwp-email, cwp-php, cwp-scripts, cwp-security, cwp-ssl, cwp-webserver. **REGRA #38 — ZERO INVENÇÃO:** NUNCA improvisar comandos. Verificar estado actual ANTES de alterar. Pesquisar wiki CWP se necessário. Usar APENAS scripts oficiais (`/scripts/*` e `/scripts/cwp_api`). Se não souber: PERGUNTAR. @@ -16,10 +15,10 @@ Skill unificada para o servidor **CWP Principal `176.9.3.158`** (MCP `ssh-unifie > **Antes de QUALQUER alteração em CWP (SSL, email/Postfix/Dovecot, nginx/Apache, CSF, PHP), correr este checklist. Padrão recorrente de edições manuais desnecessárias = causa de incidentes repetidos (#3992).** -1. **CONSULTAR PRIMEIRO** (Regra 53 — LLM Wiki obrigatório): +1. **CONSULTAR PRIMEIRO** (PROCs Hub + skills /cwp-* — regra CWP Zero Invenção): - `PROC-CWP-SSL.md` (D7 Infraestrutura) — para SSL/certificados. - `PROC-Email-Antispam-CWP.md` (D7 Infraestrutura) — para email/Postfix/DKIM/antispam. - - NotebookLM CWP `0ded7bd6-69b3-4c76-b327-452396bf7ea7` + `~/wiki/` se o caso não estiver nos PROCs. + - NotebookLM CWP `0ded7bd6-69b3-4c76-b327-452396bf7ea7` + `/knowledge` (router Hub QR/PROC) + `mcp__mem0__search_memories` se o caso não estiver nos PROCs. 2. **VERIFICAR ESTADO ACTUAL** (read-only) antes de tocar — ver secção relevante abaixo (ex.: `openssl s_client` para SSL, `postqueue -p` para email). 3. **SCRIPT NATIVO, NUNCA EDIÇÃO MANUAL.** Se existe `/scripts/*` para a tarefa, usar esse. Editar Postfix/Dovecot/vhosts/certs à mão é anti-pattern (sobrescrito em updates + causa-raiz de drift). - **SSL de email partido → `sh /scripts/mail_rebuild_sni_certs`** (NÃO editar `main.cf`/`master.cf` manualmente). @@ -103,4 +102,403 @@ curl -sI http://DOMINIO | head -5 ``` ### Anti-patterns -Remover sem backup | editar ficheiros manualmente | esquecer \ No newline at end of file +Remover sem backup | editar ficheiros manualmente | esquecer fix_perms após SSH | suspender sem avisar cliente. + +--- + +## 2. Backups + +### Comando principal +```bash +sh /scripts/user_backup USERNAME # backup completo: ficheiros, BD, emails, configs +``` + +Localização padrão: `/backup/`. Cron: `/usr/local/cwpsrv/htdocs/resources/admin/include/cron_backup.php`. + +### Workflow +```bash +df -h /backup # 1. espaço +sh /scripts/whoowns DOMINIO # 2. identificar +du -sh /home/USERNAME/ # 3. tamanho conta +sh /scripts/user_backup USERNAME # 4. backup +ls -lh /backup/ | grep USERNAME # 5. verificar +tar -tzf /backup/FILE.tar.gz > /dev/null && echo OK || echo CORRUPTO # 6. integridade +``` + +### Restauro manual (GUI restore não é fiável segundo doc) +```bash +mkdir /tmp/restore_test +tar -xzf /backup/FILE.tar.gz -C /tmp/restore_test +# copiar manualmente para localização correcta +chown -R USERNAME:USERNAME /home/USERNAME/public_html/ +rm -rf /tmp/restore_test +``` + +### Boas práticas +Backup antes de operações destrutivas | manter cópias remotas (GDrive/S3) | testar restauro periodicamente | limpar >30 dias | nunca confiar só em locais. + +--- + +## 3. Email (Postfix, DKIM, Mail Queue) + +### Scripts oficiais +| Script | Função | +|--------|--------| +| `/scripts/install_cbpolicyd` | Instalar limites emails/hora | +| `/scripts/check_postqueue` | Verificar mail queue | +| `/scripts/mail_queue_stats` | Estatísticas queue | +| `/scripts/mail_roundcube_update` | Update RoundCube | +| `/scripts/mail_vmail_import` | Importar contas /var/vmail | +| `/scripts/mail_rebuild_sni_certs` | Rebuild certificados mail | + +### DKIM/SPF +1. CWP.admin -> Postfix Manager -> rebuild com DKIM&SPF activos. +2. DKIM Manager -> adicionar key por domínio. +3. Testar: enviar para `check-auth@verifier.port25.com` (deve responder "DKIM check: pass"). +4. DKIM 2048-bit: dividir TXT record ao meio, ambas partes em quotes. + +### Mail queue +```bash +sh /scripts/check_postqueue +sh /scripts/mail_queue_stats +postqueue -p # ver +postqueue -f # flush +postcat -q QUEUE_ID # ver mensagem +postsuper -d ALL # CUIDADO: limpa tudo +``` + +### Policyd +```bash +sh /scripts/install_cbpolicyd +/scripts/cwp_api account update_policyd_all +``` + +### Após SSL: rebuild certs mail +```bash +sh /scripts/mail_rebuild_sni_certs +``` + +### Anti-spam +- rDNS: só configurável pelo provider de hosting. +- Blacklists: https://mxtoolbox.com/blacklists.aspx. +- DMARC recomendado. + +### Validação +```bash +echo "Test" | mail -s "Subject" dest@example.com +tail -100 /var/log/maillog +``` + +### Anti-patterns +Limpar queue sem ver | ignorar blacklists | DKIM sem testar | editar postfix directamente. + +--- + +## 4. PHP (Switcher / Selector / FPM) + +3 ferramentas: **PHP Switcher** (versão default), **PHP Selector** (por pasta), **PHP-FPM Selector**. + +Versões suportadas (Selector): 4.4, 5.2-5.6, 7.0-7.4, 8.0, 8.1. + +### Paths +| Path | Descrição | +|------|-----------| +| `/usr/local/cwpsrv/htdocs/resources/conf/el7/php_switcher/` | Configs CentOS 7 | +| `/usr/local/cwpsrv/htdocs/resources/conf/el8/php_switcher/` | Configs CentOS 8 | +| `/var/log/php-rebuild.log` | Log compilação | + +### Comandos +```bash +php -v +php -i | grep -E 'memory_limit|upload_max|post_max|max_execution' +php -i | grep -E 'opcache.enable|opcache.memory_consumption' +ps aux | grep php-fpm | wc -l +sh /scripts/phpfpm_rebuild_user_conf +tail -f /var/log/php-rebuild.log # monitorizar instalação versão PHP +``` + +### Desactivar funções perigosas +```bash +echo "disable_functions = exec, system, popen, proc_open, shell_exec, passthru, show_source" \ + > /usr/local/php/php.d/disabled_function.ini +``` +(cada versão PHP tem path próprio) + +### Flags compilação +Editar `/usr/local/cwpsrv/htdocs/resources/conf/el7/php_switcher/7.0.ini`: +```ini +[nome-unico] +default=0 +option="--enable-opcao" +``` +**Aviso doc:** "CWP update will overwrite these files" — documentar para reaplicar. + +### Anti-patterns +Editar .ini sem documentar | compilar PHP manualmente | ignorar php-rebuild.log. + +--- + +## 5. Segurança (CSF / LFD) + +### Paths +`/etc/csf/csf.conf` | `/etc/csf/csf.pignore` | `/var/log/lfd.log` + +### Controlo firewall +| Comando | Descrição | +|---------|-----------| +| `csf -e` | Activar | +| `csf -x` | Desactivar | +| `csf -r` | Restart iptables | +| `csf -ra` | Restart completo (iptables + LFD) | +| `service lfd restart` | Restart só LFD | + +### IPs +| Comando | Descrição | +|---------|-----------| +| `csf -g IP` | Verificar bloqueio e razão | +| `csf -d IP` | Bloquear permanente | +| `csf -td IP 86400` | Bloquear temp (segundos) | +| `csf -dr IP` | Desbloquear | +| `csf -a IP` | Whitelist permanente | +| `csf -a 192.168.0.0/24` | Whitelist range | +| `csf -ta IP 86400` | Whitelist temp | +| `csf -tf` | Limpar bloqueios temp | +| `csf -df` | Limpar bloqueios permanentes | + +```bash +grep "IP" /var/log/lfd.log +``` + +### Configuração portas +`/etc/csf/csf.conf` -> `TCP_IN`, `TCP_OUT`, `UDP_IN`, `UDP_OUT`. Após alterar: `csf -r`. + +### Ignorar país +``` +CC_IGNORE = "PT" +``` + +### Scripts segurança +```bash +sh /scripts/cwp_bruteforce_protection +sh /scripts/security_is_my_server_hacked # verifica sinais de hack +sh /scripts/cwpsecure_update_rules +``` + +### Hardening documentado +- **SSH port:** alterar `/etc/ssh/sshd_config` -> actualizar `csf.conf` TCP_IN -> `service sshd restart`. +- **tmpfs:** `/etc/fstab` -> `tmpfs /dev/shm tmpfs defaults,nodev,nosuid,noexec 0 0`. +- **Kernel panic:** `/etc/sysctl.conf` -> `vm.panic_on_oom=1`, `kernel.panic=10`, `sysctl -p`. +- **MySQL:** `[mysqld] max_user_connections=45`, `service mysql restart`. + +### Validação +```bash +csf -l | head -20 +csf -g IP +service lfd status +``` + +### Anti-patterns +Bloquear sem `csf -g` | desactivar firewall | editar iptables directamente | ignorar logs LFD. + +--- + +## 6. SSL (acme.sh nativo CWP) + +### Paths oficiais +| Path | Descrição | +|------|-----------| +| `/root/.acme.sh/cwp_certs/` | Certificados CWP | +| `/root/.acme.sh/acme.sh.log` | Log acme.sh | +| `/var/log/cwp/autossl.log` | Log AutoSSL | +| `/usr/local/apache/autossl_tmp/` | **Webroot validação** (única pasta válida) | +| `/etc/pki/tls/certs/` | Certs Nginx | +| `/etc/pki/tls/private/` | Chaves Nginx | + +### Scripts +```bash +sh /scripts/install_acme # reinstalar acme.sh +sh /scripts/autossl_reload +sh /scripts/generate_hostname_ssl +sh /scripts/hostname_ssl_restart_services +``` + +### Comandos chave +```bash +ls /root/.acme.sh/cwp_certs/ +grep "Le_NextRenewTimeStr" /root/.acme.sh/cwp_certs/www.DOMINIO_ecc/www.DOMINIO.conf + +# FORÇAR renovação (oficial) +/root/.acme.sh/acme.sh --renew -d DOMINIO --force --home /root/.acme.sh/cwp_certs + +# Verificar produção +echo | openssl s_client -connect DOMINIO:443 2>/dev/null | openssl x509 -noout -dates + +tail -100 /root/.acme.sh/acme.sh.log | grep DOMINIO +tail -100 /var/log/cwp/autossl.log +``` + +Cron renovação CWP: `23 2 * * *` (diário 02:23). `crontab -l | grep -i acme`. + +### Workflow listar todos +```bash +for d in $(ls /root/.acme.sh/cwp_certs/); do + echo "=== $d ===" + grep -E 'Le_NextRenewTimeStr|Le_Alt' /root/.acme.sh/cwp_certs/$d/*.conf 2>/dev/null | head -3 +done +``` + +### Troubleshooting documentado +- **Muitos subdomínios em Le_Alt** (mail/ftp/cpanel): qualquer falha bloqueia tudo. **Solução:** editar `.conf` e reduzir `Le_Alt` ao domínio principal. +- **Webroot incorrecto:** Nginx CWP serve validação de pasta GLOBAL `/usr/local/apache/autossl_tmp/`. NUNCA usar `/home/user/.../.well-known/`. + +### Thresholds +| Expira | Acção | +|--------|-------| +| >30d | OK | +| 15-30d | Monitorizar | +| <15d | Crítico — renovar | +| Expirado | Forçar renovação | + +### Anti-patterns +**Usar certbot** (conflito com acme.sh nativo) | incluir mail/ftp/cpanel em `Le_Alt` | hooks manuais (sobrescritos em update) | editar certs em `/etc/pki/`. + +--- + +## 7. WebServers (Apache / Nginx / Varnish) + +### API webservers +```bash +/scripts/cwp_api webservers rebuild_all +/scripts/cwp_api webservers rebuild_user USERNAME +/scripts/cwp_api webservers restart +/scripts/cwp_api webservers reload +``` + +### Scripts +```bash +sh /scripts/restart_httpd +sh /scripts/cwpsrv_rebuild_user_conf +sh /scripts/varnish_clear_cache +sh /scripts/apache_mpm_calculator +``` + +### Verificações +```bash +systemctl status httpd --no-pager | head -15 +systemctl status nginx --no-pager | head -15 +httpd -t # SEMPRE testar antes de restart +nginx -t +httpd -S 2>&1 | grep -E 'port|namevhost' | head -20 +``` + +### Restart vs Reload +| Operação | Quando | +|----------|--------| +| Reload | Alterações pequenas, sem downtime | +| Restart | Alterações grandes, módulos | + +### Workflow rebuild completo +```bash +/scripts/cwp_api webservers rebuild_all +/scripts/cwp_api webservers restart +``` + +### Validação +```bash +systemctl is-active httpd nginx +curl -sI localhost | head -5 +curl -sI http://DOMINIO | head -5 +tail -20 /var/log/httpd/error_log +tail -20 /var/log/nginx/error.log +``` + +### Anti-patterns (críticos) +Inventar comandos (PHP desactivado, site offline) | restart sem `httpd -t` | editar vhosts manualmente (sobrescritos) | ignorar erros teste | restart em vez de reload | alterar sysctl sem pesquisar | `kill -9` em processos CWP. + +--- + +## 8. Scripts oficiais CWP — referência completa + +Forma de execução: `sh /scripts/NOME` ou `/scripts/NOME`. + +### Sistema CWP +| Script | Descrição | +|--------|-----------| +| `cwp_version` | Ver versão CWP | +| `update_cwp` | Actualizar CWP | +| `restart_cwpsrv` / `reload_cwpsrv` | Restart/reload painel | +| `cwp_monitor` | Verificar load | +| `cwp_set_memory_limit` | Alterar memory limit | +| `add_alert` | Adicionar alerta | + +### Utilizadores +`list_users`, `list_domains`, `list_subdomains`, `whoowns DOMINIO`, `user_backup USERNAME`, `ulimit_user_check`, `cwpsrv_rebuild_user_conf`. + +### SSL +`install_acme`, `autossl_reload`, `autossl_fix_tmp_path`, `autossl_generate_apache_conf`, `generate_hostname_ssl`, `hostname_ssl_restart_services`. + +### MySQL +`upgrade_mysql`, `mysql_pwd_reset`, `mysql_fix_myisam_tables`, `mysql_phpmyadmin_update`, `mysql_set_max_connections`, `mysql_show_max_connections`, `checkdb`. + +### Email +`install_cbpolicyd`, `check_postqueue`, `mail_queue_stats`, `mail_roundcube_update`, `mail_vmail_import`, `mail_rebuild_sni_certs`. + +### WebServers +`restart_httpd`, `apache_mpm_calculator`, `varnish_clear_cache`. + +### PHP +`phpfpm_rebuild_user_conf`, `php_big_file_upload`, `update_ioncube`, `cron_fix_openbasedir`, `dso_handler_remove`. + +### Segurança +`cwp_bruteforce_protection`, `security_is_my_server_hacked`, `cwpsecure_update_rules`. + +### FTP +`reinstall_pure-ftpd`, `install_pure-ftpd_tls`. + +### DNS +`dns_sync_slave2`. + +### Aplicações +`install_imagick`, `install_maldet`, `install_net2ftp`, `install_terminal`, `install_supportKey`, `softaculous_fix_update`. + +### Antivírus +`freshclam`, `reinstall_clamd_amavisd`, `clamd_fix_100_cpu_usage`. + +### API +`install_api`, `check_api`. + +### Outros +`chroot_add`/`chroot_remove`, `bandwidth_run`, `disk_check`, `cgroups_blkio`, `net_show_connections`, `open_basedir-suphp`, `image_rebuild_server_config`, `cpanel_addhandlers`, `el8_stream_convert_to_cwp_stable`. + +### Top 10 mais usados +1. `user_backup USERNAME` +2. `whoowns DOMINIO` +3. `list_users` +4. `security_is_my_server_hacked` +5. `mysql_pwd_reset` +6. `restart_httpd` +7. `check_postqueue` +8. `cwp_version` +9. `update_cwp` +10. `varnish_clear_cache` + +### API unificada — outras secções + +**Apps:** +```bash +/scripts/cwp_api apps install_softaculous +/scripts/cwp_api apps remove_softaculous +/scripts/cwp_api apps install_sitepad +/scripts/cwp_api apps remove_sitepad +``` + +--- + +**Versão:** 2.0.0 (consolidação 8->1, 07-04-2026) | **Autor:** Descomplicar® +**Fonte:** wiki.centos-webpanel.com, docs.control-webpanel.com + +## Healing Log + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` diff --git a/infraestrutura/skills/easypanel-api/SKILL.md b/infraestrutura/skills/easypanel-api/SKILL.md index c3325db..ebc1a86 100644 --- a/infraestrutura/skills/easypanel-api/SKILL.md +++ b/infraestrutura/skills/easypanel-api/SKILL.md @@ -1,7 +1,6 @@ --- name: easypanel-api description: Referência completa da API tRPC oficial do EasyPanel — todos os endpoints para projectos, serviços, deploy e configurações. -layer: wiki --- # /easypanel-api - API Oficial EasyPanel @@ -136,4 +135,220 @@ Os dominios NAO sao geridos por `services.app.*` mas sim pelo namespace `domains ```bash # Listar dominios INPUT='{"json":{"projectName":"descomplicar"}}' -ENCODED=$(python3 -c "import urllib.parse; print(urllib.par \ No newline at end of file +ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$INPUT'))") +curl -s "http://localhost:3000/api/trpc/domains.listDomains?input=$ENCODED" \ + -H "Authorization: Bearer $TOKEN" + +# Criar dominio para servico +curl -s -X POST "http://localhost:3000/api/trpc/domains.createDomain" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"json":{ + "id":"meu-dominio-id", + "https":true, + "host":"app.descomplicar.pt", + "path":"/", + "middlewares":[], + "certificateResolver":"letsencrypt", + "wildcard":false, + "destinationType":"service", + "serviceDestination":{ + "protocol":"http", + "port":3000, + "path":"/", + "projectName":"descomplicar", + "serviceName":"meu-servico" + } + }}' +``` + +**Nota:** O `id` pode ser qualquer string unica (cuid ou slug). O `certificateResolver` deve ser `"letsencrypt"` para HTTPS com certificado automatico, ou `""` para dominios internos. + +--- + +## Monitor API + +```bash +# Stats do sistema +curl -s "http://localhost:3000/api/trpc/monitor.getSystemStats" \ + -H "Authorization: Bearer $TOKEN" + +# Stats de serviço (URL encode necessário) +# input: {"json":{"projectName":"descomplicar","serviceName":"api"}} +curl -s "http://localhost:3000/api/trpc/monitor.getServiceStats?input=..." \ + -H "Authorization: Bearer $TOKEN" + +# Stats Docker tasks +curl -s "http://localhost:3000/api/trpc/monitor.getDockerTaskStats" \ + -H "Authorization: Bearer $TOKEN" +``` + +--- + +## Logs API + +```bash +# Logs de serviço (tail=100) +# input: {"json":{"projectName":"descomplicar","serviceName":"api","tail":100}} +curl -s "http://localhost:3000/api/trpc/logs.getServiceLogs?input=..." \ + -H "Authorization: Bearer $TOKEN" +``` + +--- + +## Settings API + +| Endpoint | Tipo | Descrição | +|----------|------|-----------| +| `settings.getServerIp` | GET | IP do servidor | +| `settings.getPanelDomain` | GET | Domínio do painel | +| `settings.setPanelDomain` | POST | Definir domínio (`domain`) | +| `settings.getLetsEncryptEmail` | GET | Email Let's Encrypt | +| `settings.setLetsEncryptEmail` | POST | Definir email (`email`) | +| `settings.restartTraefik` | POST | Reiniciar Traefik | +| `settings.restartEasypanel` | POST | Reiniciar EasyPanel | +| `settings.pruneDockerImages` | POST | Limpar imagens Docker | + +--- + +## URL Encoding para GET + +```bash +INPUT='{"json":{"projectName":"descomplicar","serviceName":"api"}}' +ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$INPUT'))") +curl -s "http://localhost:3000/api/trpc/services.app.inspectService?input=$ENCODED" \ + -H "Authorization: Bearer $TOKEN" +``` + +--- + +## Wrapper Script + +Criar `/usr/local/bin/easypanel-api`: + +```bash +#!/bin/bash +TOKEN=$(cat /etc/easypanel/.api-token) +BASE="http://localhost:3000/api/trpc" + +if [ -z "$2" ]; then + curl -s "$BASE/$1" -H "Authorization: Bearer $TOKEN" +else + curl -s -X POST "$BASE/$1" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d "$2" +fi +``` + +Uso: `easypanel-api projects.listProjects` + +--- + +## Checklist de Uso + +- [ ] SSH para servidor `easy` +- [ ] `TOKEN=$(cat /etc/easypanel/.api-token)` +- [ ] Testar: `curl -s ".../projects.listProjects" -H "Authorization: Bearer $TOKEN"` +- [ ] Usar endpoints conforme documentado +- [ ] Validar resposta em `result.data.json` + +--- + +## Limitações de Mounts + +O EasyPanel usa Docker Swarm internamente. Isto impõe limitações nos mounts que diferem do Docker standalone. + +### Tipos de mount suportados + +| Tipo | API `type` | Comportamento | Limitações | +|------|-----------|---------------|------------| +| **Volume mount** | `volume` | Volume gerido pelo Docker Swarm | Funciona bem. Dados persistem no nó. Sem acesso directo ao filesystem do host | +| **Bind mount** | `bind` | Monta directório do host no container | **Limitado no Swarm** — só funciona se o serviço estiver fixo a um nó específico | +| **File mount** | `file` | Monta ficheiro individual (config) | Funciona. Ideal para ficheiros de configuração | + +### Limitações críticas + +1. **Bind mounts no Swarm** — O Docker Swarm não garante que o container corra sempre no mesmo nó. Um bind mount (`type: "bind"`) aponta para um path no host, mas se o container migrar para outro nó, esse path pode não existir. O EasyPanel mitiga isto parcialmente por correr num único nó, mas a limitação arquitectural mantém-se. + +2. **Sem suporte nativo a NFS/CIFS** — O EasyPanel nao suporta drivers de volume remotos (NFS, CIFS, etc.) directamente via API. Para volumes partilhados, e necessario criar o volume Docker manualmente com o driver adequado e depois referencia-lo. + +3. **Permissões** — Volumes criados via API pertencem a `root:root` por defeito. Containers que correm com utilizador não-root podem ter problemas de permissões. Workaround: usar `command` no `updateAdvanced` para corrigir permissões no arranque. + +4. **Substituicao total** — Mounts sao geridos via UI do EasyPanel. O endpoint `updateMounts` NAO foi encontrado na versao instalada. Configurar mounts directamente na interface web. + +### Workarounds conhecidos + +```bash +# 1. Obter mounts actuais antes de adicionar novo +INSPECT=$(curl -s "http://localhost:3000/api/trpc/services.app.inspectService?input=..." \ + -H "Authorization: Bearer $TOKEN") +# Extrair mounts existentes do JSON e adicionar o novo + +# 2. Volume com permissões corrigidas — usar initCommand +curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateAdvanced" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"json":{ + "projectName":"descomplicar", + "serviceName":"minha-api", + "deploy":{ + "command":"chown -R 1000:1000 /app/data && node dist/index.js" + } + }}' + +# 3. Volume Docker manual com driver NFS (fora da API) +docker volume create --driver local \ + --opt type=nfs \ + --opt o=addr=192.168.1.10,rw \ + --opt device=:/export/data \ + vol-nfs-data +# Depois referenciar na API: +# {"type":"volume","name":"vol-nfs-data","mountPath":"/app/data"} +``` + +### Recomendações + +- **Preferir `volume`** sobre `bind` — mais portável e compatível com Swarm +- **Usar `file`** para configs individuais (nginx.conf, .env, etc.) +- **Inspeccionar antes de actualizar** — a API substitui a lista inteira de mounts +- **Documentar volumes manuais** — volumes criados fora da API não aparecem no painel EasyPanel até serem referenciados por um serviço + +--- + +## Seguranca + +**ATENCAO:** `services.app.inspectService` retorna TODAS as variaveis de ambiente em texto limpo, incluindo passwords, tokens API e credenciais de base de dados. Nunca incluir output bruto de `inspectService` em reports, logs ou comentarios. Sanitizar sempre antes de mostrar ao utilizador. + +Campos sensiveis tipicos no `env`: `DB_PASS`, `API_TOKEN`, `SERVER_PASS`, `GATEWAY_PASS`, `EASYPANEL_API_TOKEN`. + +## Anti-Patterns + +| Anti-Pattern | Risco | Alternativa | +|--------------|-------|-------------| +| Expor API externamente | Seguranca critica | Usar apenas via SSH localhost | +| Hardcode token | Leak de credenciais | Usar `/etc/easypanel/.api-token` | +| Nao validar response | Erros silenciosos | Verificar `result.data.json` | +| POST sem `Content-Type` | Request falha | Sempre incluir header | +| Mostrar output de inspectService | Expoe passwords em texto limpo | Sanitizar env vars | + +--- + +## Ficheiros de Referência + +| Ficheiro | Conteúdo | +|----------|----------| +| [references/services-api.md](references/services-api.md) | Endpoints de servicos com curl completo (create, inspect, deploy, stop/start/restart, destroy) | +| [references/service-config-api.md](references/service-config-api.md) | Endpoints de configuracao (source, env, resources, build, deploy, domains, backup BD) | + +--- + +## 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/infraestrutura/skills/easypanel-cicd/SKILL.md b/infraestrutura/skills/easypanel-cicd/SKILL.md index d77dad4..3bc06b2 100644 --- a/infraestrutura/skills/easypanel-cicd/SKILL.md +++ b/infraestrutura/skills/easypanel-cicd/SKILL.md @@ -1,7 +1,6 @@ --- name: easypanel-cicd description: Configuracao de CI/CD com Gitea Actions para auto-deploy no EasyPanel via webhook — setup de workflows, secrets e validacao. -layer: wiki --- # /easypanel-cicd - CI/CD Gitea Actions para EasyPanel @@ -65,7 +64,7 @@ curl -s "http://localhost:3000/api/trpc/services.app.inspectService?input=$ENCOD | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['result']['data']['json']['deploymentUrl'])" ``` -**Formato da URL:** `http://178.63.18.51:3000/api/deploy/` +**Formato da URL:** `https://easy.descomplicar.pt:3000/api/deploy/` **Nota:** O token e unico por servico e nao expira. Nao confundir com o API token geral. @@ -77,7 +76,7 @@ mcp__gitea__upsert_repo_action_secret({ owner: "ealmeida", repo: "REPO_NAME", secretname: "EASYPANEL_DEPLOY_URL", - body: { data: "http://178.63.18.51:3000/api/deploy/" } + body: { data: "https://easy.descomplicar.pt:3000/api/deploy/" } }) ``` @@ -181,4 +180,180 @@ jobs: sleep 15 done echo "Health check failed after 5 attempts" - e \ No newline at end of file + exit 1 +``` + +#### Template Python + +```yaml +name: CI/CD Pipeline (Python) + +on: + push: + branches: [main] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + - run: pip install -r requirements.txt + - run: python -m pytest --if-present + + deploy: + needs: test + runs-on: ubuntu-latest + if: github.ref == 'refs/heads/main' + steps: + - name: Trigger EasyPanel Deploy + run: | + curl -sf -X POST "${{ secrets.EASYPANEL_DEPLOY_URL }}" || exit 1 +``` + +### 4. Commit e push + +```bash +git add .gitea/workflows/deploy.yml +git commit -m "ci: add Gitea Actions deploy pipeline" +git push origin main +``` + +### 5. Validar pipeline + +```bash +# Via MCP Gitea — verificar runs +mcp__gitea__list_repo_action_runs({ + owner: "ealmeida", + repo: "REPO_NAME", + limit: 5 +}) +``` + +Ou verificar logs: +```bash +mcp__gitea__list_repo_action_run_jobs({ + owner: "ealmeida", + repo: "REPO_NAME", + run_id: RUN_ID +}) +``` + +--- + +## Diagnostico (--diagnose) + +### Pipeline nao dispara + +1. Verificar se o ficheiro esta em `.gitea/workflows/` (nao `.github/workflows/`) +2. Verificar se o branch e `main` (ou o configurado no `on.push.branches`) +3. Verificar se os runners estao activos: + ```bash + docker service ls | grep gitea-runner + # Esperado: 3/3 replicas + ``` + +### Webhook falha (HTTP != 200) + +1. Verificar se o `deploymentUrl` esta correcto (servico pode ter sido recriado) +2. Verificar se o EasyPanel esta acessivel internamente: + ```bash + curl -s http://localhost:3000/api/trpc/projects.listProjects -H "Authorization: Bearer $TOKEN" + ``` +3. Verificar se o token do servico nao mudou (re-obter via inspectService) + +### Build falha no EasyPanel + +1. Verificar Dockerfile: + ```bash + /easypanel-validate + ``` +2. Verificar logs do build: + ```bash + /easypanel-troubleshoot SERVICE_NAME + ``` + +### Testes falham no runner + +1. Verificar logs do job: + ```bash + mcp__gitea__get_repo_action_job_log_preview({ + owner: "ealmeida", + repo: "REPO_NAME", + job_id: JOB_ID + }) + ``` +2. Verificar se dependencias estao no `package.json`/`requirements.txt` +3. Verificar se env vars de teste estao configuradas + +--- + +## Servicos com CI/CD activo (inventario) + +Para listar todos os servicos com source git (candidatos a CI/CD): + +```bash +TOKEN=$(cat /etc/easypanel/.api-token) +curl -s "http://localhost:3000/api/trpc/projects.listProjectsAndServices" \ + -H "Authorization: Bearer $TOKEN" \ + | python3 -c " +import sys,json +d=json.load(sys.stdin)['result']['data']['json'] +for s in d.get('services',[]): + src=s.get('source',{}) or {} + if src.get('type')=='git' and s.get('type')=='app': + repo=src.get('repo','').split('@')[-1] if '@' in src.get('repo','') else src.get('repo','') + print(f\"{s['projectName']}/{s['name']} | repo={repo} | ref={src.get('ref','?')}\") +" +``` + +--- + +## Checklist de execucao + +- [ ] Identificar servico EasyPanel alvo (projectName + serviceName) +- [ ] Obter deploymentUrl via inspectService (SSH ao servidor easy) +- [ ] Criar secret EASYPANEL_DEPLOY_URL no repo Gitea (via MCP) +- [ ] Criar secret DEPLOY_DOMAIN no repo Gitea (opcional, para health check) +- [ ] Criar `.gitea/workflows/deploy.yml` com template adequado +- [ ] Commit e push do workflow +- [ ] Verificar que o primeiro run dispara (list_repo_action_runs) +- [ ] Verificar que o deploy completa no EasyPanel +- [ ] Health check do servico apos deploy + +--- + +## MCPs necessarios + +- `ssh-unified` — Acesso ao servidor easy para obter deploymentUrl +- `gitea` — Criar secrets e verificar action runs + +--- + +## Skills relacionadas + +| Skill | Quando usar | +|-------|-------------| +| `/easypanel-deploy` | Deploy manual com validacao completa | +| `/easypanel-validate` | Validar projecto antes de configurar CI/CD | +| `/easypanel-init` | Scaffold novo projecto (ja inclui workflow template) | +| `/easypanel-troubleshoot` | Diagnosticar deploy falhado | +| `/easypanel-api` | Referencia API tRPC | + +--- + +*Skill v1.0.0 | 24-03-2026 | Descomplicar(r)* + +--- + +## 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/infraestrutura/skills/easypanel-deploy/SKILL.md b/infraestrutura/skills/easypanel-deploy/SKILL.md index 478a7b4..9d2227c 100644 --- a/infraestrutura/skills/easypanel-deploy/SKILL.md +++ b/infraestrutura/skills/easypanel-deploy/SKILL.md @@ -2,7 +2,6 @@ name: easypanel-deploy description: Deploy completo e automatizado para EasyPanel com validação integrada, monitoring e safety net (auto-rollback) via API oficial. disable-model-invocation: true -layer: wiki --- # EasyPanel Deploy @@ -230,4 +229,197 @@ docker stats --no-stream [00:20] ✅ Local build [00:25] ✅ Git push [01:55] ✅ EasyPanel build started -[03:42] \ No newline at end of file +[03:42] ✅ Container started +[03:50] ❌ Health check 1/5: 502 Bad Gateway +[04:00] ❌ Health check 2/5: 502 Bad Gateway +[04:10] ❌ Health check 3/5: 502 Bad Gateway +[04:20] ❌ HEALTH CHECK FAILED (3/5 retries) + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +🔴 ERROR DETAILS +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Issue: Health endpoint not responding (502) +Likely cause: Port mismatch or app crash + +Logs (last 20 lines): + > Error: listen EADDRINUSE: address already in use :::8080 + > at Server.setupListenHandle [as _listen2] + +Root cause detected: App listening on port 8080, Traefik expects 3000 + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +🔄 AUTO-ROLLBACK +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +[04:25] ⏪ Rolling back to previous version (commit: 7d3a1f2) +[04:30] ✅ Rollback complete +[04:35] ✅ Health check: 200 OK (service restored) + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +🛠️ RECOMMENDED FIXES +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +1. Update Dockerfile EXPOSE: Change 8080 → 3000 + OR +2. Update docker-compose.yml Traefik label: + traefik.http.services.X.loadbalancer.server.port=8080 + +3. Test fix locally: docker build && docker run +4. Commit fix + redeploy: /easypanel-deploy + +🔍 Troubleshooting: + /easypanel-troubleshoot +``` + +## Auto-Rollback Logic + +**Trigger Conditions:** +- Health check fails 3/5 times +- Container crashes dentro de 60s +- Metrics críticos (CPU > 95%, Memory OOM) + +**Rollback Actions:** +1. Identificar último commit estável (health OK) +2. `git revert` ou `git checkout` +3. Force push para trigger redeploy +4. Aguardar health check OK +5. Report success/fail + +## Flags + +### --skip-tests + +```bash +/easypanel-deploy --skip-tests +``` + +**Quando usar:** +- CI/CD já executou tests +- Tests demoram muito (>5min) +- Deploy de hotfix urgente + +### --force + +```bash +/easypanel-deploy --force +``` + +**Quando usar:** +- Ignorar validation warnings +- Deploy apesar de score < 7/10 +- Override safety checks + +**⚠️ ATENÇÃO:** Usar apenas se souber o que está a fazer. + +## Integration com CI/CD + +O deploy automatico via Gitea Actions usa o webhook do EasyPanel (nao esta skill directamente). +Cada servico tem um `deploymentUrl` unico (visivel em `inspectService`). + +```yaml +# .gitea/workflows/deploy.yml +steps: + - name: Trigger EasyPanel Deploy + run: | + curl -s -X POST "${{ secrets.EASYPANEL_DEPLOY_URL }}" + # EASYPANEL_DEPLOY_URL = http://IP:3000/api/deploy/ +``` + +Ver skill `/easypanel-cicd` para configuracao completa de CI/CD com Gitea Actions. + +## API Endpoints Usados + +Ver skill `/easypanel-api` para documentação completa. + +| Acção | Endpoint | Verificado | +|-------|----------|:----------:| +| Deploy serviço | `POST services.app.deployService` | Sim | +| Estado serviço | `GET services.app.inspectService` | Sim | +| Parar serviço | `POST services.app.stopService` | Sim | +| Iniciar serviço | `POST services.app.startService` | Sim | +| Reiniciar serviço | `POST services.app.restartService` | Sim | +| Logs serviço | `GET logs.getServiceLogs` | Sim | + +**Endpoints que NAO existem:** `redeployService` — usar `deployService` para re-deploy. + +## MCPs Necessários + +- ✅ `ssh-unified` - Acesso ao servidor para executar comandos API +- ✅ `gitea` - Git operations e push + +## Tools Necessários + +```bash +# Git +git status +git add . +git commit +git push + +# Docker +docker build +docker stats + +# Curl +curl -f https://domain/health +``` + +## Metrics Tracking + +Após deploy, gravar métricas: + +```sql +INSERT INTO tblskill_metrics ( + skill_name, duration_ms, success, + build_time_ms, image_size_mb, deploy_time_ms, + health_check_status, cpu_avg, ram_mb +) VALUES ( + '/easypanel-deploy', DURATION, SUCCESS, + BUILD_TIME, IMAGE_SIZE, DEPLOY_TIME, + 'ok', CPU, RAM +); +``` + +## Checklist Execução + +- [ ] Executar /easypanel-validate +- [ ] Check score >= 7/10 +- [ ] Run tests (se não --skip-tests) +- [ ] Build local test +- [ ] Verificar uncommitted changes +- [ ] Push to Gitea +- [ ] Monitor build EasyPanel +- [ ] Health check (5 retries) +- [ ] Validate metrics (CPU, RAM) +- [ ] Report success ou trigger rollback +- [ ] Log metrics + +--- + +**Versão:** 1.0.0 | **Autor:** Descomplicar® | **Data:** 2026-02-04 + +## Metadata (Desk CRM Task #65) + +``` +Tarefa: SKL: /easypanel-deploy - Automated Deploy + Validation +Milestone: 294 (Skills Claude Code) +Tags: skill(79), stackworkflow(75), claude-code(81), activo(116) +Responsáveis: Emanuel(1), AikTop(25) +Status: 4 (Em progresso) → 5 (Concluído) +``` + +--- + +**/** @author Descomplicar® | @link descomplicar.pt | @copyright 2026 **/ +--- + +## 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/infraestrutura/skills/easypanel-init/SKILL.md b/infraestrutura/skills/easypanel-init/SKILL.md index 6211d2b..ca41dab 100644 --- a/infraestrutura/skills/easypanel-init/SKILL.md +++ b/infraestrutura/skills/easypanel-init/SKILL.md @@ -2,7 +2,6 @@ name: easypanel-init description: Inicialização de projectos EasyPanel com configuração adequada via API oficial — scaffold automático para Node.js, PHP ou sites estáticos. disable-model-invocation: true -layer: wiki --- # EasyPanel Init @@ -245,4 +244,252 @@ git commit -m "chore: initial project setup via /easypanel-init" ### 4. Criar Projecto no EasyPanel via API ```bash -# Obte \ No newline at end of file +# Obter token +TOKEN=$(cat /etc/easypanel/.api-token) + +# Criar projecto +curl -s -X POST "http://localhost:3000/api/trpc/projects.createProject" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"json":{"name":"PROJECT_NAME"}}' + +# Criar serviço app +curl -s -X POST "http://localhost:3000/api/trpc/services.app.createService" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"json":{"projectName":"PROJECT_NAME","serviceName":"app"}}' + +# Configurar dominio (namespace domains.*, NAO services.app.*) +curl -s -X POST "http://localhost:3000/api/trpc/domains.createDomain" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"json":{ + "id":"PROJECT_NAME-app", + "https":true, + "host":"DOMAIN", + "path":"/", + "middlewares":[], + "certificateResolver":"letsencrypt", + "wildcard":false, + "destinationType":"service", + "serviceDestination":{ + "protocol":"http", + "port":3000, + "path":"/", + "projectName":"PROJECT_NAME", + "serviceName":"app" + } + }}' + +# Configurar Git source (params RAIZ, NAO dentro de source) +# Para repos Gitea privados, incluir token no URL +curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateSourceGit" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"json":{ + "projectName":"PROJECT_NAME", + "serviceName":"app", + "repo":"https://ealmeida:GITEA_TOKEN@git.descomplicar.pt/ealmeida/REPO", + "ref":"main", + "path":"/" + }}' +``` + +### 5. Push to Gitea (opcional) + +```bash +# Criar repo via MCP Gitea +mcp__gitea__create_repo({ + name: PROJECT_NAME, + private: false, + auto_init: false +}) + +# Add remote and push +git remote add origin https://git.descomplicar.pt/ORG/PROJECT_NAME.git +git push -u origin main +``` + +### 6. Output Summary + +``` +✅ Project scaffolded: PROJECT_NAME + +📁 Structure created: + - Dockerfile (multi-stage, 3 layers, ~80MB final image) + - docker-compose.yml (Traefik configured for DOMAIN) + - Health endpoint: src/routes/health.ts + - CI/CD: .gitea/workflows/deploy.yml + - README.md (deploy guide + troubleshooting) + +🔧 Configuration: + - Domain: DOMAIN + - Port: 3000 + - Node.js: 22-alpine + - Health check: GET /health + +📦 Next Steps: + 1. cd PROJECT_NAME + 2. npm install + 3. cp .env.example .env.local && edit .env.local + 4. npm run dev (test locally) + 5. git push origin main (trigger deploy) + +📚 Documentation: + - README.md: Quick start + - Checklist: Use /easypanel-validate before deploy + +🚀 EasyPanel Setup: + 1. Create service → Custom (Docker Compose) + 2. Connect repository: git.descomplicar.pt/ORG/PROJECT_NAME + 3. Set environment variables (copy from .env.example) + 4. Create webhook (for CI/CD) + 5. Deploy + +⏱️ Estimated setup time: 5min (vs 30min manual) +``` + +## Database Support (--db) + +### PostgreSQL + +Adiciona ao docker-compose.yml: + +```yaml +services: + db: + image: postgres:16-alpine + restart: unless-stopped + environment: + POSTGRES_DB: ${DB_NAME} + POSTGRES_USER: ${DB_USER} + POSTGRES_PASSWORD: ${DB_PASSWORD} + volumes: + - postgres_data:/var/lib/postgresql/data + networks: + - traefik + +volumes: + postgres_data: +``` + +Adiciona a .env.example: +``` +DATABASE_URL=postgresql://${DB_USER}:${DB_PASSWORD}@db:5432/${DB_NAME} +``` + +### MySQL + +Similar ao PostgreSQL, usando `mysql:8-alpine`. + +## Type Support (--type) + +### nodejs (default) +- Node.js 22-alpine +- TypeScript + ESM +- tsx para dev +- Express boilerplate + +### python (futuro) +- Python 3.12-alpine +- FastAPI boilerplate +- poetry para dependencies +- uvicorn para server + +### go (futuro) +- Go 1.21-alpine +- Gin ou Echo boilerplate +- Multi-stage build (builder + runtime) +- Binário estático + +## API Endpoints Usados + +Ver skill `/easypanel-api` para documentação completa. + +| Acção | Endpoint | Verificado | +|-------|----------|:----------:| +| Criar projecto | `POST projects.createProject` | Sim | +| Criar serviço | `POST services.app.createService` | Sim | +| Configurar dominio | `POST domains.createDomain` | Sim | +| Configurar Git source | `POST services.app.updateSourceGit` | Sim | +| Configurar GitHub source | `POST services.app.updateSourceGithub` | Sim | +| Deploy inicial | `POST services.app.deployService` | Sim | + +**Endpoints que NAO existem:** `saveDomains`, `saveGithubSource` — usar `domains.createDomain` e `updateSourceGit`/`updateSourceGithub`. + +## Validation + +Após scaffold, executar automaticamente: +```bash +/easypanel-validate +``` + +Se score < 9/10, reportar issues. + +## Templates Base + +Usar templates de: +`/media/ealmeida/Dados/Dev/Docs/EasyPanel-Deploy-Research/` + +- TEMPLATE_Dockerfile_NodeJS_MultiStage +- TEMPLATE_docker-compose.yml +- TEMPLATE_gitea-workflow-deploy.yml +- TEMPLATE_health-endpoint.ts + +## Customização + +User pode customizar após scaffold: +- Port (default 3000) +- Node version (default 22) +- Package manager (npm, pnpm, yarn) +- Framework (Express, Fastify, Koa) + +## Checklist Execução + +- [ ] Verificar nome projecto válido (lowercase, no spaces) +- [ ] Verificar domain válido (DNS format) +- [ ] Criar estrutura pastas +- [ ] Gerar Dockerfile multi-stage +- [ ] Gerar docker-compose.yml com Traefik labels +- [ ] Criar health endpoint +- [ ] Gerar .dockerignore +- [ ] Gerar .gitignore +- [ ] Gerar .env.example +- [ ] Criar package.json com scripts +- [ ] Gerar tsconfig.json (se TS) +- [ ] Criar CI/CD workflow +- [ ] Gerar README.md +- [ ] Git init +- [ ] Git commit inicial +- [ ] Executar /easypanel-validate +- [ ] Output summary com next steps + +--- + +**Versão:** 1.0.0 | **Autor:** Descomplicar® | **Data:** 2026-02-04 + +## Metadata (Desk CRM Task #65) + +``` +Tarefa: SKL: /easypanel-init - Scaffold EasyPanel Project +Milestone: 294 (Skills Claude Code) +Tags: skill(79), stackworkflow(75), claude-code(81), activo(116) +Responsáveis: Emanuel(1), AikTop(25) +Status: 4 (Em progresso) → 5 (Concluído) +``` + +--- + +**/** @author Descomplicar® | @link descomplicar.pt | @copyright 2026 **/ + +--- + +## 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/infraestrutura/skills/easypanel-monitor/SKILL.md b/infraestrutura/skills/easypanel-monitor/SKILL.md index 6a0506d..7f70046 100644 --- a/infraestrutura/skills/easypanel-monitor/SKILL.md +++ b/infraestrutura/skills/easypanel-monitor/SKILL.md @@ -1,7 +1,6 @@ --- name: easypanel-monitor description: Monitorizacao de servicos EasyPanel -- estado de todos os servicos Docker, uso de recursos, disco e logs de erros com tabela resumo OK/DOWN/WARN. -layer: wiki --- # /easypanel-monitor - Monitorizacao EasyPanel @@ -201,4 +200,150 @@ docker service ls -q | xargs -I {} docker service ps {} --format "{{.Name}} {{.C | / | 45G | 55G | 45% | OK | | /var/lib/docker | 30G | 70G | 30% | OK | -Docker system: X imagens, Y containers, Z volumes ( \ No newline at end of file +Docker system: X imagens, Y containers, Z volumes (total: XGB) + +### Alertas + +**CRITICAL:** +- descomplicar_db: 0/1 replicas - servico DOWN + Logs: `[erro relevante dos logs]` + +**WARN:** +- descomplicar_redis: CPU a 85% (threshold 70%) + +### Accoes recomendadas + +1. [URGENTE] Investigar descomplicar_db: `/easypanel-troubleshoot db` +2. [IMPORTANTE] Monitorizar descomplicar_redis - CPU elevado +3. [MELHORIA] Limpar imagens Docker nao utilizadas: `docker system prune` +``` + +--- + +## Modo quick + +Apenas passo 1 e 2. Output resumido: + +```markdown +## EasyPanel Quick Check - [DATA] + +| Servico | Estado | +|---------|--------| +| descomplicar_api | OK | +| descomplicar_n8n | OK | +| descomplicar_db | DOWN | + +**X/Y OK** | Z alertas +``` + +--- + +## Modo servico especifico + +Para `/easypanel-monitor `: + +```bash +# Estado +docker service inspect --pretty + +# Tarefas (historico) +docker service ps + +# Logs (ultimas 50 linhas) +docker service logs --tail 50 --no-trunc 2>&1 + +# Stats do container +docker stats --no-stream --filter "name=" +``` + +--- + +## Integracao com API EasyPanel + +A API e o metodo **preferido** (ver `/easypanel-api`). Os comandos Docker sao fallback. + +```bash +TOKEN=$(cat /etc/easypanel/.api-token) + +# Stats do sistema (CPU, RAM, Disco — ver estrutura no Passo 3) +curl -s "http://localhost:3000/api/trpc/monitor.getSystemStats" \ + -H "Authorization: Bearer $TOKEN" + +# Stats Docker tasks (actual/desired replicas por servico) +# Resposta: {"serviceName": {"actual": 1, "desired": 1}, ...} +curl -s "http://localhost:3000/api/trpc/monitor.getDockerTaskStats" \ + -H "Authorization: Bearer $TOKEN" + +# Projectos e servicos +curl -s "http://localhost:3000/api/trpc/projects.listProjectsAndServices" \ + -H "Authorization: Bearer $TOKEN" +``` + +**Nota de seguranca:** `inspectService` expoe variaveis de ambiente em texto limpo (incluindo passwords e tokens). Nunca incluir output bruto de `inspectService` em reports — sanitizar sempre. + +--- + +## MCPs necessarios + +- `ssh-unified` - Acesso ao servidor easy (obrigatorio) +- `mcp-time` - Data/hora para o report (obrigatorio) +- `desk-crm-v3` - Comentar resultado em tarefa (opcional) + +--- + +## Anti-patterns + +| Anti-pattern | Problema | Solucao | +|--------------|----------|---------| +| Ignorar servicos DOWN | Problemas acumulam | Sempre investigar com /easypanel-troubleshoot | +| Nao verificar disco | Disco cheio causa crash geral | Incluir df -h sempre | +| docker stats sem --no-stream | Bloqueia terminal | Sempre usar --no-stream | +| Ignorar tarefas falhadas | Crash loops nao detectados | Verificar desired-state=shutdown | +| Nao limpar imagens | Disco enche | docker system prune periodico | + +--- + +## Checklist de execucao + +- [ ] Conectar via SSH ao servidor easy +- [ ] docker service ls (estado de todos os servicos) +- [ ] Identificar servicos DOWN (0/N replicas) +- [ ] docker stats --no-stream (recursos) +- [ ] df -h (espaco em disco) +- [ ] docker system df (uso Docker) +- [ ] Logs de servicos com problemas (--tail 10) +- [ ] Tarefas falhadas (docker service ps --filter) +- [ ] Classificar cada servico: OK / WARN / DOWN +- [ ] Gerar tabela resumo +- [ ] Listar accoes recomendadas priorizadas +- [ ] Report formatado (Markdown) + +--- + +## Skills relacionadas + +| Skill | Quando usar | +|-------|-------------| +| `/easypanel-troubleshoot` | Diagnostico aprofundado de servico com problema | +| `/easypanel-rollback` | Reverter deploy falhado | +| `/easypanel-deploy` | Deploy de novo servico ou actualizacao | +| `/easypanel-validate` | Validacao pos-deploy | +| `/easypanel-api` | Referencia API tRPC | +| `/server-health` | Health check do servidor CWP (nao EasyPanel) | + +--- + +*Skill v1.1.0 | 24-03-2026 | Descomplicar(r) | Fix: estrutura real monitor.getSystemStats (nested memInfo/cpuInfo/diskInfo)* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +{"date":"2026-08-22","issue":"Varios servicos nao relacionados a quebrar e reiniciar em simultaneo, ciclicamente — NAO e bug de app; e stall de compactacao de memoria do kernel (kcompactd0, vm.compaction_proactiveness) sob pressao do host Proxmox sem folga, que faz o containerd perder shims em massa e o Swarm reagendar tudo. Detectar com: journalctl -u containerd | grep 'shim disconnected' | cut -c1-16 | sort | uniq -c (rajadas na mesma janela de 1min) + journalctl -k | grep -iE 'rcu|soft lockup'. Confirmar se e evento de HOST (nao so do easy) comparando pvesh rrddata das outras VMs no mesmo minuto antes de investigar servico a servico. Ver INC-032. Nota: ssh-unified MCP esta permanentemente proibido — usar ssh nativo/bash.","fix":"sysctl vm.compaction_proactiveness=0 + vm.swappiness=10 (persistir em /etc/sysctl.d/); aplicar cgroup memory limit a todo o container sem tecto (docker update --memory ao vivo nao exige restart).","source":"auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/easypanel-rollback/SKILL.md b/infraestrutura/skills/easypanel-rollback/SKILL.md index 1f46dcd..41583eb 100644 --- a/infraestrutura/skills/easypanel-rollback/SKILL.md +++ b/infraestrutura/skills/easypanel-rollback/SKILL.md @@ -2,7 +2,6 @@ name: easypanel-rollback description: Rollback seguro de deployments EasyPanel para versões anteriores estáveis via API oficial. disable-model-invocation: true -layer: wiki --- # EasyPanel Rollback @@ -246,4 +245,225 @@ Confirm? [Y/n]: y [00:10] ✅ Push to Gitea [01:45] ✅ EasyPanel redeploy started [03:20] ✅ Container started -[03:28] ✅ Health \ No newline at end of file +[03:28] ✅ Health check: 200 OK +[03:30] ✅ Metrics validated (CPU: 11%, RAM: 42MB) + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +✅ ROLLBACK COMPLETE +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Total time: 3m 30s +Service restored: https://dashboard.descomplicar.pt +Health: ✅ 200 OK + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +🛠️ NEXT STEPS +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +1. Investigate root cause of v1.3.0 failure + → /easypanel-troubleshoot dashboard-api + +2. Fix issues locally + → Update Dockerfile EXPOSE port + +3. Test fix locally + → docker build + docker run + test + +4. Redeploy + → /easypanel-deploy + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📝 ROLLBACK LOGGED +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Desk CRM Task #1502: Comment added +Gitea: Rollback commit pushed (4e8a9c3) +``` + +## Output Format (Failed) + +``` +❌ ROLLBACK FAILED + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +⏱️ TIMELINE +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +[00:00] ✅ Git revert +[00:05] ✅ Push to Gitea +[01:45] ✅ Build started +[03:20] ✅ Container started +[03:28] ❌ Health check: 500 Internal Server Error + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +🔴 ERROR +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Target version v1.2.5 also failing after rollback +Possible causes: +- Database schema incompatibility +- Environment variable missing +- External dependency changed + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +🚨 MANUAL INTERVENTION REQUIRED +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +1. Check logs: /easypanel-troubleshoot dashboard-api +2. Verify database migrations +3. Check environment variables +4. Consider rollback to v1.2.4 (older stable) +``` + +## Flags + +### --auto + +Selecção automática da "last known good version": +- Versão anterior com health OK +- Sem confirmação interactiva +- Deploy imediato + +**Uso em automation:** +```bash +# Triggered by monitoring alert +if [[ $(curl -s -o /dev/null -w "%{http_code}" https://domain/health) != "200" ]]; then + /easypanel-rollback dashboard-api --auto +fi +``` + +### --to-version + +Especificar versão alvo exacta: +```bash +/easypanel-rollback dashboard-api --to-version v1.2.3 +``` + +**Validações:** +- Versão existe? (git tag) +- Versão não é actual +- Versão é anterior (não futura) + +## Version Metadata Tracking + +**Stored in:** `.easypanel/deploy-history.json` + +```json +{ + "versions": [ + { + "tag": "v1.2.5", + "commit": "7d3a1f2", + "timestamp": "2026-02-04T10:30:00Z", + "health_status": "ok", + "health_checks": 1523, + "health_failures": 3, + "uptime_percentage": 99.8, + "deploy_duration_ms": 180000, + "image_size_mb": 82, + "rollback_safe": true + } + ] +} +``` + +## Integration com /easypanel-deploy + +Quando `/easypanel-deploy` detecta falha, chama automaticamente: +```bash +/easypanel-rollback --auto +``` + +## API Endpoints Usados + +Ver skill `/easypanel-api` para documentação completa. + +| Acção | Endpoint | Verificado | +|-------|----------|:----------:| +| Inspeccionar serviço | `GET services.app.inspectService` | Sim | +| Deploy (redeploy) | `POST services.app.deployService` | Sim | +| Obter logs | `GET logs.getServiceLogs` | Sim | + +**Endpoints que NAO existem:** `redeployService`, `getServiceLogs` (logs estao em `logs.*`, nao `services.app.*`). + +## MCPs Necessários + +- ✅ `gitea` - Git operations e tags +- ✅ `ssh-unified` - Acesso ao servidor para API +- ✅ `desk-crm-v3` - Log rollback em comentário tarefa + +## Tools Necessários + +```bash +# Git +git log +git tag +git revert +git checkout +git push --force (com cuidado!) + +# Docker +docker service ps +docker logs + +# Curl +curl -f https://domain/health +``` + +## Safety Checks + +1. **Backup actual state** antes de rollback +2. **Validate target version** existe +3. **Check database migrations** compatibility +4. **Confirm with user** (excepto --auto) +5. **Monitor rollback** até health OK + +## Checklist Execução + +- [ ] List recent versions (git log + tags) +- [ ] Fetch deploy history metadata +- [ ] Select target version (interactive/auto/specific) +- [ ] Show rollback plan + diff +- [ ] Confirm with user (se não --auto) +- [ ] Backup actual state +- [ ] Perform git revert ou checkout +- [ ] Commit rollback +- [ ] Push to Gitea +- [ ] Monitor redeploy (5min timeout) +- [ ] Health check (5 retries) +- [ ] Validate logs (no errors) +- [ ] Validate metrics (CPU, RAM) +- [ ] Report success ou fail +- [ ] Log rollback em Desk CRM + +--- + +**Versão:** 1.0.0 | **Autor:** Descomplicar® | **Data:** 2026-02-04 + +## Metadata (Desk CRM Task #65) + +``` +Tarefa: SKL: /easypanel-rollback - Automated Rollback +Milestone: 294 (Skills Claude Code) +Tags: skill(79), stackworkflow(75), claude-code(81), activo(116) +Responsáveis: Emanuel(1), AikTop(25) +Status: 4 (Em progresso) → 5 (Concluído) +``` + +--- + +**/** @author Descomplicar® | @link descomplicar.pt | @copyright 2026 **/ + +--- + +--- + +## 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/infraestrutura/skills/easypanel-troubleshoot/SKILL.md b/infraestrutura/skills/easypanel-troubleshoot/SKILL.md index 75e34b7..d1f197a 100644 --- a/infraestrutura/skills/easypanel-troubleshoot/SKILL.md +++ b/infraestrutura/skills/easypanel-troubleshoot/SKILL.md @@ -1,7 +1,6 @@ --- name: easypanel-troubleshoot description: Diagnóstico automático de problemas de deploy no EasyPanel — análise de logs de containers, health endpoints, routing Traefik e recursos para identificar causas raiz. -layer: wiki --- # EasyPanel Troubleshoot @@ -132,6 +131,12 @@ Fix: Add variable to EasyPanel environment ``` Pattern: Restart count > 3 in 10min Fix: Check logs for root cause + +Se VÁRIOS serviços não relacionados reiniciarem na MESMA janela (~1min): +NÃO é bug de app individual. Ver INC-032 — provável stall de compactação +de memória do kernel (host sem folga) a derrubar containerd em massa. +Confirmar: journalctl -u containerd | grep "shim disconnected" | +cut -c1-16 | sort | uniq -c (rajadas na mesma janela = confirma). ``` ### Database Connection @@ -202,4 +207,96 @@ CPU: X% ## API Endpoints Usados -Ver skill `/easypanel-api` para documentação completa \ No newline at end of file +Ver skill `/easypanel-api` para documentação completa. + +| Acção | Endpoint | Verificado | +|-------|----------|:----------:| +| Estado serviço | `GET services.app.inspectService` | Sim | +| Logs serviço | `GET logs.getServiceLogs` | Sim | +| Listar projectos | `GET projects.listProjects` | Sim | +| Stats sistema | `GET monitor.getSystemStats` | Sim | +| Stats Docker | `GET monitor.getDockerTaskStats` | Sim | + +**Endpoints que NAO existem:** `services.app.getServiceLogs` (usar `logs.getServiceLogs`), `monitor.getStats` (usar `monitor.getSystemStats`). + +## MCPs Necessários + +- ⚠️ `ssh-unified` está PERMANENTEMENTE PROIBIDO (regra global) — usar `ssh`/`bash` nativo para acesso ao servidor + +## Tools Necessários + +```bash +# Via SSH +docker ps +docker logs --tail 100 +docker inspect +curl https:///health +``` + +## Checklist Execução + +- [ ] Conectar via SSH ao servidor EasyPanel +- [ ] Obter status do container (docker ps) +- [ ] Fetch logs (últimas 100 linhas) +- [ ] Parse errors automático (patterns conhecidos) +- [ ] Check health endpoint (curl) +- [ ] Verificar Traefik labels (docker inspect) +- [ ] Detectar port mismatch +- [ ] Verificar env vars (se possível) +- [ ] Gerar report estruturado +- [ ] Recomendar fixes priorizados + +## Error Messages Database + +### Common Patterns + +| Pattern | Root Cause | Fix | +|---------|------------|-----| +| `EADDRINUSE :::PORT` | Port já em uso | Matar processo ou usar porta diferente | +| `Cannot find module 'X'` | Dependency missing | npm install no build | +| `ECONNREFUSED` | Database/service down | Verificar network/DATABASE_URL | +| `502 Bad Gateway` | App crash ou port mismatch | Check logs + ports | +| `MODULE_NOT_FOUND` | Build incorrecto | Verificar Dockerfile COPY | +| `OOM killed` | Memória insuficiente | Aumentar limite RAM | + +## Security + +- NUNCA expor credenciais nos logs +- Sanitizar env vars em output +- Limitar acesso SSH apenas ao necessário + +## Performance + +- Limitar logs a 100 linhas (evitar overflow) +- Cache de patterns conhecidos +- Timeout de 30s em curl health checks + +--- + +**Versão:** 1.0.0 | **Autor:** Descomplicar® | **Data:** 2026-02-04 + +## Metadata (Desk CRM Task #65) + +``` +Tarefa: SKL: /easypanel-troubleshoot - Automated Diagnostics +Milestone: 294 (Skills Claude Code) +Tags: skill(79), stackworkflow(75), claude-code(81), activo(116) +Responsáveis: Emanuel(1), AikTop(25) +Status: 4 (Em progresso) → 5 (Concluído) +``` + +--- + +**/** @author Descomplicar® | @link descomplicar.pt | @copyright 2026 **/ +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +{"date":"2026-08-22","issue":"Padrao de 'varios servicos a quebrar e reiniciar sucessivamente' foi confundido inicialmente com bugs de app individuais. Causa real era host-level: stall de compactacao de memoria do kernel (kcompactd0) sob pressao do host Proxmox sem folga, derrubando o containerd em massa e disparando reagendamento simultaneo de dezenas de servicos Swarm nao relacionados. 76/90 containers no easy corriam sem qualquer cgroup memory limit, o que agravou o impacto (um processo sem tecto, surrealdb, chegou a 24-30GB e disparou OOM). Ver INC-032 para diagnostico completo e comandos.","fix":"Antes de investigar servico a servico: correlacionar timestamps de 'Failed'/'Shutdown' entre servicos via docker service ps; se simultaneos, investigar journalctl -k (rcu/soft lockup) e journalctl -u containerd (shim disconnected) no host antes de assumir bug de app. Aplicar cgroup memory limit a qualquer container sem tecto.","source":"auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/easypanel-validate/SKILL.md b/infraestrutura/skills/easypanel-validate/SKILL.md index 8e574dc..fd93d62 100644 --- a/infraestrutura/skills/easypanel-validate/SKILL.md +++ b/infraestrutura/skills/easypanel-validate/SKILL.md @@ -1,7 +1,6 @@ --- name: easypanel-validate description: Validação pré-deploy de projectos EasyPanel com health checks, verificação de serviços e auto-fix opcional via API oficial. -layer: wiki --- # EasyPanel Validate @@ -220,4 +219,135 @@ curl -s "http://localhost:3000/api/trpc/monitor.getSystemStats" \ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✅ READY TO DEPLOY (score >= 7/10) -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ \ No newline at end of file +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Next: /easypanel-deploy or git push origin main +``` + +## Score Interpretation + +| Score | Status | Action | +|-------|--------|--------| +| 9-10 | EXCELLENT | Deploy com confiança | +| 7-8 | GOOD | Deploy OK, resolver warnings depois | +| 5-6 | FAIR | Resolver critical issues antes de deploy | +| 0-4 | POOR | BLOCKER - Não deploy até corrigir | + +## Strict Mode (--strict) + +Se `--strict`: +- Warnings são tratados como CRITICAL +- Score mínimo para pass: 9/10 +- Exit code 1 se score < 9 + +Uso em CI/CD: +```yaml +- name: Validate + run: /easypanel-validate --strict +``` + +## Auto-Fix Capabilities + +| Issue | Auto-Fix? | Action | +|-------|-----------|--------| +| .dockerignore missing | ✅ Yes | Create from template | +| .gitignore incomplete | ✅ Yes | Append missing entries | +| docker-compose restart policy | ✅ Yes | Add unless-stopped | +| Health endpoint missing | ✅ Yes | Create template file | +| Dockerfile npm install | ✅ Yes | Replace with npm ci | +| Multi-stage missing | ❌ No | Recommend only | +| Port mismatch | ❌ No | Report only | + +## API Endpoints Usados + +Ver skill `/easypanel-api` para documentação completa. + +| Acção | Endpoint | Verificado | +|-------|----------|:----------:| +| Inspeccionar serviço | `GET services.app.inspectService` | Sim | +| Stats sistema | `GET monitor.getSystemStats` | Sim | +| Listar projectos | `GET projects.listProjects` | Sim | +| IP servidor | `GET settings.getServerIp` | Sim | + +**Endpoints que NAO existem:** `monitor.getStats` (usar `monitor.getSystemStats`), `settings.getSystemInfo` (usar `settings.getServerIp`). + +## Tools Necessários + +```bash +# Docker para build test +docker build --no-cache -t test . + +# hadolint para Dockerfile lint (opcional) +hadolint Dockerfile +``` + +## Integration com CI/CD + +```yaml +# .gitea/workflows/deploy.yml +steps: + - name: Validate + run: /easypanel-validate --strict + + - name: Deploy + if: success() + run: /easypanel-deploy +``` + +## Checklist Execução + +- [ ] Verificar Dockerfile existe +- [ ] Lint Dockerfile (hadolint ou manual) +- [ ] Check .dockerignore +- [ ] Validar docker-compose.yml +- [ ] Verificar package.json (se Node.js) +- [ ] Check health endpoint +- [ ] Validar .gitignore +- [ ] Check .env.example +- [ ] Verificar CI/CD config +- [ ] Test local build (docker build) +- [ ] Calcular score +- [ ] Apply auto-fixes (se --fix) +- [ ] Gerar report + +## Templates Disponíveis + +Usar templates de: +`/media/ealmeida/Dados/Dev/Docs/EasyPanel-Deploy-Research/` + +- TEMPLATE_Dockerfile_NodeJS_MultiStage +- TEMPLATE_docker-compose.yml +- TEMPLATE_gitea-workflow-deploy.yml +- TEMPLATE_health-endpoint.ts + +--- + +**Versão:** 1.0.0 | **Autor:** Descomplicar® | **Data:** 2026-02-04 + +## Metadata (Desk CRM Task #65) + +``` +Tarefa: SKL: /easypanel-validate - Pre-deploy Validation +Milestone: 294 (Skills Claude Code) +Tags: skill(79), stackworkflow(75), claude-code(81), activo(116) +Responsáveis: Emanuel(1), AikTop(25) +Status: 4 (Em progresso) → 5 (Concluído) +``` + +--- + +**/** @author Descomplicar® | @link descomplicar.pt | @copyright 2026 **/ + +--- + +--- + +## 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/infraestrutura/skills/gateway-check/SKILL.md b/infraestrutura/skills/gateway-check/SKILL.md index 0dbe624..c261767 100644 --- a/infraestrutura/skills/gateway-check/SKILL.md +++ b/infraestrutura/skills/gateway-check/SKILL.md @@ -2,7 +2,6 @@ name: gateway-check description: Gestao completa dos MCPs no gateway.descomplicar.pt — health check, restart, troubleshoot, mapa de portas, adicionar MCPs. Usar quando MCP falha, health check, ou gestao gateway. context: fork -layer: wiki --- # /gateway-check v2.0 @@ -25,7 +24,7 @@ Gestao e health check dos MCPs no servidor gateway (VM 103, gateway.descomplicar --- -## Mapa de MCPs (30 services — actualizado 28-03-2026) +## Mapa de MCPs (34 services — actualizado 10-08-2026) ### pm2 (Node.js — /opt/mcp-gateway/) @@ -36,9 +35,9 @@ Gestao e health check dos MCPs no servidor gateway (VM 103, gateway.descomplicar | 2 | mcp-wikijs | 3152 | /v1/wikijs/mcp | P3 | | 5 | mcp-moloni | 3158 | /v1/moloni/mcp | P2 | | 6 | mcp-youtube-research | 3157 | /v1/youtube-research/mcp | P3 | -| 7 | mcp-youtube | 3187 | /v1/youtube/mcp | P3 | +| 3 | mcp-paperclip | 3168 | /v1/paperclip/mcp | P3 | -### systemd (24 services) +### systemd (27 services) | Service | Porta | nginx path | Tipo | Prioridade | |---------|-------|------------|------|------------| @@ -65,9 +64,20 @@ Gestao e health check dos MCPs no servidor gateway (VM 103, gateway.descomplicar | presenton-mcp | 3182 | /v1/presenton/mcp | supergateway | P3 | | cwp-mcp | 3183 | /v1/cwp/mcp | supergateway | P3 | | design-engine-mcp | 3184 | /v1/design-engine/mcp | supergateway | P3 | +| mcp-youtube-router | 3198 | /v1/youtube/mcp | Python/Starlette | P3 | +| mcp-youtube | 3187 | (nenhuma — upstream interno) | Python/FastMCP | P3 | +| mcp-youtube-desc | 3199 | (nenhuma — upstream interno) | Python/FastMCP | P3 | +| ssh-unified | 3192 | /v1/ssh-unified/mcp | Python/FastMCP | P3 | +| slides-mcp | 3201 | /v1/slides-mcp/mcp | Python/FastMCP | P3 | +| easypanel-mcp | 3206 | /v1/easypanel/mcp | fastmcp-proxy (Node stdio wrapped) | P2 | +| infisical-mcp | 3207 | /v1/infisical/mcp | fastmcp-proxy (Node stdio wrapped) | P2 | **Prioridades:** P1=critico (bloqueia trabalho) | P2=importante (degrada workflow) | P3=util -**Proxima porta livre:** 3188 +**Proxima porta livre:** 3208. **Verificar sempre** — este mapa +ficou desactualizado antes (30-07-2026, porta 3188 já ocupada) e voltou a ficar (08-08-2026, +`/opt/mcp-gateway/port-map.json` tinha 3198 marcado como mcp-easypanel quando na verdade é +mcp-youtube-router; corrigido, easypanel real ficou em 3206): +`ss -tlnH` cruzado com `grep -oE "127.0.0.1:3[0-9]{3}" /etc/nginx/sites-enabled/mcp-gateway`. --- @@ -120,4 +130,112 @@ systemctl restart .service pm2 logs --lines 30 --nostream # systemd -journalctl -u .ser \ No newline at end of file +journalctl -u .service --since "1h ago" --no-pager | tail -30 +``` + +### Testar endpoint especifico + +```bash +# Internamente no gateway +curl -s http://127.0.0.1:/mcp -X POST \ + -H "Content-Type: application/json" \ + -H "Accept: application/json, text/event-stream" \ + -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}' + +# Externamente +curl -s https://gateway.descomplicar.pt/v1//mcp -X POST \ + -H "Content-Type: application/json" \ + -H "Accept: application/json, text/event-stream" \ + -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}' +``` + +--- + +## Troubleshooting + +### MCP DOWN + +1. Verificar service: `systemctl status ` ou `pm2 show ` +2. Ver logs: `journalctl -u --since "1h ago" --no-pager | tail -30` +3. Se supergateway: verificar preload `catch-errors.mjs` (ver abaixo) +4. Tentar restart: `systemctl restart ` +5. Re-verificar porta: `ss -tln | grep :` + +### Supergateway crash (bug conhecido) + +- **Erro:** `No connection established for request ID: 0` +- **Fix:** preload script em `/opt/mcp-gateway/supergateway-catch-errors.mjs` +- **Activacao:** `Environment="NODE_OPTIONS=--import /opt/mcp-gateway/supergateway-catch-errors.mjs"` no unit file +- **15 services patchados:** todos os supergateway na tabela acima +- **Ao adicionar novo supergateway:** OBRIGATORIO adicionar esta linha ao unit file + +### FastMCP Python + nginx (DNS rebinding) + +FastMCP 1.26+ bloqueia Host headers externos. No nginx: +```nginx +proxy_set_header Host "127.0.0.1:"; # CORRECTO +# proxy_set_header Host $host; # ERRADO — FastMCP bloqueia +``` +**Detectar:** Se MCP retorna `Invalid Host header` via HTTPS mas funciona em `curl localhost` -> e este problema. + +### 403 Forbidden + +IP nao esta na whitelist nginx. Verificar: `curl -4 ifconfig.me` +IP autorizado: `188.251.199.30`. Actualizar em `/etc/nginx/sites-enabled/` se mudou. + +### RAM total > 2GB + +1. Identificar top consumers: `ps aux --sort=-%mem | head -20 | grep -E 'node|python|supergateway'` +2. Processos orphan: `ps aux | grep -c supergateway` +3. Se orphans > 24: `pkill -f supergateway` e restart escalonado + +--- + +## Adicionar novo MCP ao gateway + +1. Instalar em `/opt/mcp-gateway//` (Node) ou `/opt/mcp-/` (Python) +2. Porta: proxima livre (actualmente **3188**) +3. Criar unit file systemd (se supergateway: incluir preload catch-errors) +4. Criar bloco nginx (se FastMCP Python: Host header fix obrigatorio) +5. `systemctl daemon-reload && systemctl enable --now .service` +6. `nginx -t && systemctl reload nginx` +7. Testar internamente e externamente (ver comandos curl acima) +8. Adicionar a `~/.claude.json`: `{"type":"http","url":"https://gateway.descomplicar.pt/v1//mcp"}` +9. Actualizar esta skill (mapa de portas + proxima porta livre) +10. Actualizar memory `mcp-gateway.md` + +--- + +## Anti-Patterns + +- **Nunca** restart massivo sem verificar primeiro +- **Nunca** ignorar MCP P1 em estado DOWN +- **Nunca** confundir gateway (VM 103) com dev/server/easy +- **Sempre** reportar estado mesmo que tudo OK +- **Sempre** testar endpoint apos restart +- **Sempre** actualizar mapa de portas ao adicionar/remover MCPs +- **Nunca** guardar backups do nginx dentro de `sites-enabled/` — o include e por + wildcard, o backup passa a ser carregado e `nginx -t` falha com `duplicate log_format`, + quebrando *todo* o gateway. Backups vao para `/root/`. +- **Nunca** confiar no "proxima porta livre" deste ficheiro sem cruzar `ss -tlnH` com as + portas roteadas no nginx. +- **Contar** ~40s de arranque nos MCPs Python/FastMCP no gateway (import lento, I/O de + disco). Um probe imediato apos `systemctl start` da falso negativo — aguardar o bind. + +--- + +*Skill v2.0.0 | 28-03-2026 | Descomplicar* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"2026-07-30","issue":"Backup do nginx criado em sites-enabled/ -> duplicate log_format mcp_audit -> nginx -t falhou para todo o gateway","fix":"Backups para /root/. Verificar com nginx -t apos remover.","source":"auto"} +{"date":"2026-07-30","issue":"Skill anunciava 3188 como proxima porta livre; estava ocupada -> deploy abortou","fix":"Cruzar ss -tlnH com grep 127.0.0.1:3XXX no nginx antes de escolher porta","source":"auto"} +{"date":"2026-07-30","issue":"Probe tools/list imediatamente apos systemctl start deu falso negativo (FastMCP demora ~40s a bindar)","fix":"Poll da porta com timeout antes do probe HTTP","source":"auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/infra-check/SKILL.md b/infraestrutura/skills/infra-check/SKILL.md index cc85ebd..8264a46 100644 --- a/infraestrutura/skills/infra-check/SKILL.md +++ b/infraestrutura/skills/infra-check/SKILL.md @@ -2,7 +2,6 @@ name: infra-check description: Health check de MCPs e auditoria de despesas — sábado check completo 9 MCPs + auditoria despesas, domingo check resumido top 5 + despesas sem PDF. context: fork -layer: wiki --- # /infra-check v1.0 diff --git a/infraestrutura/skills/mcp-dev/SKILL.md b/infraestrutura/skills/mcp-dev/SKILL.md index 4c3d104..75494ea 100644 --- a/infraestrutura/skills/mcp-dev/SKILL.md +++ b/infraestrutura/skills/mcp-dev/SKILL.md @@ -1,13 +1,32 @@ --- name: mcp-dev -description: Desenvolvimento e teste de servidores MCP — criação, configuração e gestão de MCPs customizados seguindo os padrões Descomplicar com transporte StreamableHTTP. -layer: wiki +description: Desenvolvimento e teste de servidores MCP — criação, configuração e gestão de MCPs customizados. SDK TypeScript v2 (@modelcontextprotocol/server) e transporte HTTP são obrigatórios, sem excepção silenciosa. --- # /mcp-dev - Desenvolvimento de MCPs Skill para criação, configuração e gestão de servidores MCP customizados. + +## Regra de Ouro — obrigatória, sem excepção silenciosa + +Todo MCP próprio da Descomplicar — novo, existente, ou sob edição estrutural — tem de cumprir isto. A regra aplica-se ao código que nós escrevemos; ver §Política para MCPs de terceiros mais abaixo. Um MCP que falhe qualquer ponto abaixo está fora de conformidade e tem de ser migrado (não "deixado como está" por funcionar). + +1. **SDK oficial v2** ([ts.sdk.modelcontextprotocol.io/v2](https://ts.sdk.modelcontextprotocol.io/v2/)) — pacotes `@modelcontextprotocol/server` (+ `@modelcontextprotocol/client` só em testes/evaluations). **`@modelcontextprotocol/sdk` (v1) está descontinuado nesta casa** — nunca instalar, nunca copiar código de um MCP antigo que o use sem migrar primeiro. API de alto nível `McpServer` + `registerTool`/`registerResource`/`registerPrompt` — a API de baixo nível `Server` + `setRequestHandler(Schema, …)` está **proibida** (reintroduz classes de bugs que o v2 elimina por desenho, incluindo o anti-padrão de capabilities manuais que causava o erro 471). +2. **Transporte HTTP obrigatório** — `createMcpHandler` (Streamable HTTP), tipicamente montado com `@modelcontextprotocol/express` + `@modelcontextprotocol/node`. `stdio` (`serveStdio`) só é aceitável quando o host tem de lançar o processo directamente e não existe gateway — nesse caso documentar a excepção no README do MCP com a razão concreta, e usar sempre `serveStdio` do SDK v2 (nunca `StdioServerTransport` manual). +3. **Node.js 20+, ESM (`"type": "module"`), `zod/v4` (peer `^4.2.0`)** — nunca `zod` v3, nunca `require()`. +4. **Nunca construir comandos shell/SQL por interpolação de string** quando o MCP faz ponte para SSH/CLI externos (ex.: WP-CLI). Dados do utilizador passam sempre por STDIN (texto ou base64), nunca concatenados num comando `ssh ... "..."`. Ver `references/best-practices.md` §Segurança — regra escrita depois de uma injecção de comandos real ter sido encontrada e corrigida em produção (`mcp-kivicare`, 19-08-2026, ver Healing Log no fim deste ficheiro). + +Se qualquer um destes 4 pontos não puder ser cumprido, **parar e perguntar** antes de prosseguir — não decidir sozinho por uma alternativa mais rápida. + +**⚠️ Armadilha — pacote v2 ≠ API v2.** Importar `@modelcontextprotocol/server` não garante conformidade: um MCP só está conforme se usar a API de alto nível `McpServer` + `registerTool`. Se o código (mesmo importando o pacote v2) chamar `setRequestHandler` ou instanciar `Server`, está a usar a API de baixo nível proibida — é não-conforme. Verificação: `grep -oE 'setRequestHandler|McpServer\(|registerTool' dist/*.js | sort | uniq -c` — deve mostrar `McpServer` + `registerTool` e **zero** `setRequestHandler`. Caso real: `mcp-desk-project-minimal` (26-08-2026) importava só o pacote v2 mas usava `setRequestHandler` — não-conforme apesar do pacote certo. + +## Política para MCPs de terceiros e migração de existentes + +**MCPs de terceiros** (pacotes npm/uvx que apenas instalamos e corremos — ex.: `deepl`, `lighthouse`, `notebooklm`, `puppeteer`, `echarts`, `pixabay`, `authentik`, `spaceship`, `replicate`, `context7`, `gitea-mcp`): a Regra de Ouro **não lhes aplica** — não controlamos o código deles e não os podemos migrar (só dar fork ou substituir). Correm como estão, em v1. Só substituir se uma alternativa v2/nativa (ex.: Python FastMCP) fizer sentido para os mais usados — decisão por caso, não política global. + +**MCPs próprios já existentes em v1** (ex.: `desk-crm-v3`, `moloni`, `mem0`, `wikijs`, `cwp`, `reonic`, `imap-enterprise`, `youtube-research`, `carl-mcp`, `mcp-wayland`, `gestix-mcp` stdio): estão fora de conformidade e devem ser migrados para v2. Antes de cada migração em produção: **fazer snapshot do código e dist actual** (git commit ou cópia) para rollback rápido se o build v2 partir algo. Migrar é mudança de API, não bump de versão — é trabalho por servidor, não automatizável em massa. + ## Contexto NotebookLM Consultar ANTES de executar: @@ -24,7 +43,7 @@ mcp__notebooklm__notebook_query({ - [PROC-MCP-Troubleshooting-Erro-471.md](file:///media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D7-Tecnologia/MCP/PROC-MCP-Troubleshooting-Erro-471.md) - [PROC-MCP-Google-Auth.md](file:///media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D7-Tecnologia/MCP/PROC-MCP-Google-Auth.md) -> **Regra #48:** Novos MCPs são desenvolvidos no **container dev** (`server:"dev"`, path `/root/Dev/`). Após validação, mover para `/home/ealmeida/mcp-servers/` em produção. +> **Regra #48:** Novos MCPs são desenvolvidos **localmente no desktop** em `/media/ealmeida/Dados/Dev/` (CT 102 extinto em 20-04-2026). Após validação, mover para `~/mcp-servers/` em produção. --- @@ -49,7 +68,7 @@ mcp__notebooklm__notebook_query({ 1. Consultar NotebookLM (notebook acima) 2. Verificar MCPs existentes — evitar duplicação 3. Identificar ferramentas necessárias e nomear segundo padrão -4. Definir transporte: HTTP (recomendado) ou stdio +4. Transporte: **HTTP obrigatório** (Streamable HTTP via SDK v2, `createMcpHandler`). stdio só com justificação escrita explícita — ver secção Transportes. 5. Criar spike/PoC se tecnologia desconhecida **Nomenclatura de tools:** `{serviço}_{acção}_{recurso}` em snake_case, máx. 40 caracteres. @@ -64,31 +83,28 @@ getCustomerNotes (camelCase), get_customer_notes_with_all_billing_details (>40 c ### Fase 2: Implementation -1. Scaffold no container dev: `/root/Dev//` -2. Implementar tools com **annotations obrigatórias** e validação Zod -3. Definir capabilities completas (tools + resources + prompts) +1. Scaffold local no desktop: `/media/ealmeida/Dados/Dev//` +2. Implementar tools com **annotations obrigatórias** e validação Zod (`z.object(...)` de `zod/v4`) +3. `McpServer` deriva capabilities automaticamente de `registerTool`/`registerResource`/`registerPrompt` — nunca declarar capabilities à mão (isso é API de baixo nível v1, proibida) 4. Responses em **dual format**: Markdown (text) + JSON (structuredContent) 5. Erros **accionáveis**: causa + próximos passos -**Annotations obrigatórias em cada tool:** +**Annotations obrigatórias em cada tool** — vão directo na config de `registerTool` (sem passo de inferência separado no v2): ```typescript -annotations: { - readOnlyHint: true, // não modifica estado - destructiveHint: false, // não é destrutiva - idempotentHint: true, // mesmo resultado em chamadas repetidas - openWorldHint: false, // opera em sistema fechado (interno) -} -``` - -Usar `inferAnnotations()` do SDK para inferência automática: -```typescript -import { inferAnnotations } from '@modelcontextprotocol/sdk/server/utils.js'; -const annotated = inferAnnotations(tool); -``` - -**Capabilities — sempre completas (anti-erro 471):** -```typescript -capabilities: { tools: {}, resources: {}, prompts: {} } +server.registerTool( + 'get_customer', + { + description: 'Obtém dados de um cliente pelo ID', + inputSchema: z.object({ customer_id: z.number().int().positive() }), + annotations: { + readOnlyHint: true, // não modifica estado + destructiveHint: false, // não é destrutiva + idempotentHint: true, // mesmo resultado em chamadas repetidas + openWorldHint: false, // opera em sistema fechado (interno) + }, + }, + async ({ customer_id }) => { /* ... */ } +); ``` **Dual format de resposta:** @@ -120,13 +136,15 @@ return { 2. `pnpm audit` — sem vulnerabilidades críticas 3. Validar limites de nomes de tools (máx. 40 chars) 4. Testar build: `npm run build` -5. Testar manualmente: `echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node dist/index.js` +5. Testar manualmente via HTTP: `curl -s -X POST http://127.0.0.1:32XX/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'` 6. Documentar decisões em ADR se necessário **Grep de validação rápida:** ```bash grep -rn '`.*\${.*}`' src/ | grep -i 'select\|insert\|update\|delete' grep -rn 'Math.random' src/ +# Comandos shell/ssh interpolados (ver Regra de Ouro §4) — qualquer resultado exige revisão manual +grep -rn 'exec(\|execSync(\|spawn(.*sh\b' src/ | grep -i '\${' ``` ### Fase 4: Evaluations @@ -144,4 +162,160 @@ Criar e executar testes estruturados antes do deploy. | 5 | Operações destrutivas apagam correctamente? | Delete em recurso existente | | 6 | Tools read-only não alteram estado? | Get + verificar estado antes/depois | | 7 | Paginação funciona com listas grandes? | 1000+ registos, página 2 | -| 8 | Auth invá \ No newline at end of file +| 8 | Auth inválida é rejeitada graciosamente? | API key removida | +| 9 | structuredContent é consistente com text? | Comparar campos nos dois formatos | +| 10 | Performance < 5s em p95? | 10 chamadas consecutivas | + +**Executar:** +```bash +npm run eval # evaluations +npm run eval:ci # build + evaluations (para CI/CD) +``` + +--- + +## Estrutura de Projecto + +``` +/media/ealmeida/Dados/Dev/mcp-/ # Desenvolvimento (local, desktop) +├── package.json +├── tsconfig.json +├── src/ +│ ├── server.ts # Factory McpServer + registerTool (partilhado) +│ ├── http.ts # Entry point HTTP (createMcpHandler + Express) — obrigatório +│ └── stdio.ts # Entry point stdio (serveStdio) — só se excepção justificada +├── eval/ +│ └── run-evals.ts # Evaluations automáticas (Client + StreamableHTTPClientTransport in-process) +├── .env.example +├── README.md +└── .gitignore + +/home/ealmeida/mcp-servers/mcp-/ # Produção +``` + +--- + +## Configuração + +**~/.claude.json (HTTP — obrigatório):** +```json +{ + "mcpServers": { + "": { "type": "http", "url": "http://127.0.0.1:32XX/mcp" } + } +} +``` + +**~/.claude.json (stdio — apenas excepção documentada):** +```json +{ + "mcpServers": { + "": { "command": "node", "args": ["/home/ealmeida/mcp-servers//dist/stdio.js"] } + } +} +``` + +--- + +## Transportes + +| Transporte | Estado | Quando usar | +|------------|--------|-------------| +| Streamable HTTP (SDK v2) | **Obrigatório** | Todos os MCPs novos — acesso remoto, gateway, múltiplos clientes | +| stdio (SDK v2, `serveStdio`) | Excepção documentada | Só quando o host lança o processo directamente e não há gateway. Justificar no README do MCP. | +| SSE | Deprecated | Retrocompatibilidade apenas — nunca usar em MCP novo | + +--- + +## MCPs Existentes (Referência) + +| MCP | Path | Tools | Transporte | +|-----|------|-------|------------| +| desk-crm-v3 | ~/mcp-servers/desk-crm-v3/ | 150+ | SSE :3100 | +| mem0 | gateway.descomplicar.pt/v1/mem0/mcp (remoto) | 5 | HTTP | +| google-workspace | (npm package) | 42 | stdio | +| filesystem | (npm package) | 8 | stdio | + +--- + +## Referências + +| Ficheiro | Conteúdo | +|----------|----------| +| `references/best-practices.md` | Nomenclatura, annotations, segurança (incl. anti-injecção de comandos shell), SQL Perfex | +| `references/evaluation-guide.md` | Guia completo de evaluations, script automatizado (Client v2 in-process) | +| `references/templates.md` | Templates TypeScript v2 prontos (server factory, HTTP obrigatório, stdio excepcional, systemd) | + +**Agente especializado:** `mcp-protocol-developer` — desenvolvimento complexo, debug, optimização. + +--- + +### v3.0.1 (2026-08-26) +- **Esclarecida a armadilha "pacote v2 ≠ API v2"** — importar `@modelcontextprotocol/server` não basta; um MCP só está conforme com `McpServer` + `registerTool`, nunca `setRequestHandler`/`Server`. Motivo: `mcp-desk-project-minimal` importava o pacote v2 mas usava a API de baixo nível proibida. Incluído comando de verificação rápida. +- **Política de migração explícita** — a Regra de Ouro aplica-se a todos os MCPs próprios (novos, existentes, edição estrutural); existentes em v1 devem ser migrados, com snapshot para rollback antes de tocar produção. MCPs de terceiros (npm/uvx) ficam fora do âmbito — não os controlamos, não os migramos. + +### v3.0.0 (2026-08-19) +- **SDK TypeScript v2 obrigatório** (`@modelcontextprotocol/server`, ver [ts.sdk.modelcontextprotocol.io/v2](https://ts.sdk.modelcontextprotocol.io/v2/)) — `@modelcontextprotocol/sdk` v1 descontinuado nesta casa. +- **Transporte HTTP obrigatório**; stdio passa a excepção documentada (antes era "válido" sem restrição). +- API de baixo nível `Server` + `setRequestHandler(Schema, …)` proibida — só `McpServer` + `registerTool`/`registerResource`/`registerPrompt`. +- Capabilities manuais removidas do fluxo (v2 deriva automaticamente) — a secção "anti-erro 471" do v1 já não se aplica ao padrão obrigatório. +- `inferAnnotations()` removido (não existe em v2) — annotations sempre inline na config de `registerTool`. +- Nova secção "Regra de Ouro" no topo do ficheiro, com 4 obrigações sem excepção silenciosa. +- `references/best-practices.md` §Segurança recebeu regra de anti-injecção de comandos shell (bridge SSH/CLI), motivada por incidente real corrigido em `mcp-kivicare` (19-08-2026, 8 bugs, incl. injecção de comandos crítica). +- Templates (`references/templates.md`) reescritos para a API v2 (`createMcpHandler`, `createMcpExpressApp`, `serveStdio`). + +### v2.0.0 (2026-03-10) +- Refactorização: SKILL.md de 1163 para <500 linhas (progressive disclosure) +- **Fase 4: Evaluations** adicionada ao workflow (padrão mcp-builder Anthropic) +- Nomenclatura tools: `{serviço}_{acção}_{recurso}` snake_case documentada +- Annotations obrigatórias (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) +- `inferAnnotations()` mencionado como padrão automático +- Dual format de resposta (JSON + Markdown) documentado +- Erros accionáveis com causa + próximos passos +- Extracto para `references/`: best-practices, evaluation-guide, templates + +### v1.3.0 (2026-01-31) +- HTTP StreamableHTTP como padrão oficial +- SSE marcado como deprecated +- Checklist de segurança (audit 164 tools) + +### v1.2.0 (2026-01-27) +- Template SSE com http nativo +- systemd service template + +### v1.0.0 (2026-01-27) +- Versão inicial + +--- + +## Quando NÃO Usar + +- Para tarefas fora do domínio de desenvolvimento MCP +- Quando outra skill mais específica está disponível +- Para operações simples que não requerem MCP + +## Protocolo + +1. Consultar NotebookLM e PROCs relevantes +2. Executar as 4 fases: Research -> Implementation -> Review -> Evaluations +3. Validar resultados antes de concluir +4. Reportar status e próximos passos + +--- + +*Skill v3.0.1 | Descomplicar® | 2026-08-26* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +{"date":"2026-08-19","issue":"mcp-kivicare: runRawSqlQuery interpolava a query directamente num comando `ssh ... wp db query \"...\"` — injecção de comandos shell explorável","fix":"query sempre por STDIN (`wp db query < stdin`), nunca interpolada no comando remoto","source":"auto"} +{"date":"2026-08-19","issue":"mcp-kivicare: hooks nativos do KiviCare (kc_appointment_status_update) disparados com um inteiro em vez do objecto do modelo — TypeError fatal num listener nativo, registo órfão em produção","fix":"recarregar o modelo (ex.: KCAppointment::find($id)) antes de disparar qualquer hook nativo; ler a assinatura real do hook no código-fonte do sistema alvo antes de o chamar","source":"auto"} +{"date":"2026-08-19","issue":"mcp-kivicare: basic_data do paciente gravado como array PHP em vez do JSON que o sistema nativo espera (json_encode com JSON_UNESCAPED_UNICODE) — corrompia a leitura no admin nativo","fix":"replicar exactamente o formato de serialização do sistema nativo (grep ao código-fonte real), nunca assumir a partir da forma dos dados em memória","source":"auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/mcp-dev/references/best-practices.md b/infraestrutura/skills/mcp-dev/references/best-practices.md index d8d58f3..827d366 100644 --- a/infraestrutura/skills/mcp-dev/references/best-practices.md +++ b/infraestrutura/skills/mcp-dev/references/best-practices.md @@ -65,38 +65,27 @@ Cada tool deve declarar as suas annotations para orientar o modelo: | `idempotentHint` | boolean | Resultado idêntico em múltiplas chamadas | | `openWorldHint` | boolean | Interage com sistemas externos/web | -**Inferência automática com `inferAnnotations()`:** - -```typescript -import { inferAnnotations } from '@modelcontextprotocol/sdk/server/utils.js'; - -// Inferir automaticamente a partir do nome e descrição da tool -const annotated = inferAnnotations(tool); -``` +**v2 não tem `inferAnnotations()`** (era só v1) — declarar sempre `annotations` inline na config de `registerTool`, como no exemplo acima. Nunca inventar um passo de inferência que o SDK actual não tem. --- -## Capabilities Obrigatórias (Regra de Ouro) +## Capabilities — derivadas automaticamente (nunca declarar à mão) + +`McpServer` (SDK v2) deriva `capabilities` de `registerTool`/`registerResource`/`registerPrompt` automaticamente — **não existe** `capabilities: {...}` nem `setRequestHandler(...)` na API de alto nível obrigatória. ```typescript -// ERRADO: capabilities incompletas -> erro 471 -capabilities: { tools: {} } +// ERRADO — API de baixo nível v1, proibida nesta casa +import { Server } from '@modelcontextprotocol/sdk/server/index.js'; +const server = new Server({...}, { capabilities: { tools: {} } }); // causava erro 471 em v1 +server.setRequestHandler(ListToolsRequestSchema, async () => ({...})); -// CORRECTO: sempre declarar as três, mesmo vazias -capabilities: { - tools: {}, - resources: {}, - prompts: {} -} +// CORRECTO — API de alto nível v2, a única aceite +import { McpServer } from '@modelcontextprotocol/server'; +const server = new McpServer({ name: 'mcp-', version: '1.0.0' }); +server.registerTool('get_customer', { description: '...', inputSchema: z.object({...}) }, async (args) => {...}); ``` -**Handlers mínimos obrigatórios:** -```typescript -server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [...] })); -server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: [] })); -server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: [] })); -server.setRequestHandler(CallToolRequestSchema, async (req) => { ... }); -``` +O erro 471 (capabilities incompletas) era uma armadilha da API de baixo nível v1 — deixa de poder acontecer ao usar `McpServer`/`registerTool` do v2. Se algum código ainda usa `Server` + `setRequestHandler(Schema, ...)`, é sinal de que está a reintroduzir o v1 — migrar antes de continuar (ver `SKILL.md` §Regra de Ouro). --- @@ -148,7 +137,7 @@ return { ## Validação com Zod ```typescript -import { z } from 'zod'; +import * as z from 'zod/v4'; const GetCustomerSchema = z.object({ customer_id: z.number().int().positive(), @@ -156,42 +145,40 @@ const GetCustomerSchema = z.object({ date_from: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(), }); -// No handler -const validated = GetCustomerSchema.parse(args); -// Zod lança ZodError automaticamente se inválido +server.registerTool( + 'get_customer', + { description: 'Obtém dados de um cliente', inputSchema: GetCustomerSchema }, + async ({ customer_id, include_invoices, date_from }) => { + // O SDK v2 já validou e rejeitou argumentos inválidos antes de este handler correr — + // nunca chamar `.parse()`/`.safeParse()` outra vez aqui, é redundante e esconde a + // mensagem de erro accionável que o SDK já produziu. + // ... lógica aqui + }, +); ``` --- ## Error Handling -```typescript -server.setRequestHandler(CallToolRequestSchema, async (request) => { - const { name, arguments: args } = request.params; +No v2, um handler que atira (`throw`) é convertido automaticamente num resultado `isError: true` — não existe `setRequestHandler(CallToolRequestSchema, ...)` para envolver manualmente (isso é API de baixo nível v1). Ver [errors.md](https://ts.sdk.modelcontextprotocol.io/v2/servers/errors.md) para o detalhe completo (`ProtocolError` para resources/prompts, subclasses tipadas). - try { - const result = await handleTool(name, args); - return result; - } catch (error) { - if (error instanceof z.ZodError) { +```typescript +server.registerTool( + 'get_customer', + { description: 'Obtém dados de um cliente pelo ID', inputSchema: z.object({ customer_id: z.number() }) }, + async ({ customer_id }) => { + const customer = await db.getCustomer(customer_id); + if (!customer) { + // Devolver isError explicitamente dá controlo total sobre o `content` return { - content: [{ - type: 'text', - text: `Parâmetros inválidos:\n${error.errors.map(e => ` - ${e.path.join('.')}: ${e.message}`).join('\n')}` - }], - isError: true + content: [{ type: 'text', text: `Cliente ${customer_id} não encontrado. Verificar: 1) ID existe na BD 2) Permissões de acesso` }], + isError: true, }; } - - return { - content: [{ - type: 'text', - text: `Erro: ${error instanceof Error ? error.message : String(error)}` - }], - isError: true - }; - } -}); + return { content: [{ type: 'text', text: `Cliente: ${customer.name}` }], structuredContent: customer }; + }, +); ``` --- @@ -199,7 +186,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => { ## Logging ```typescript -// SEMPRE usar console.error (não console.log — interfere com stdio) +// SEMPRE usar console.error (não console.log — interfere com o framing stdio quando o +// MCP corre em modo stdio excepcional; em HTTP não framing-crítico mas mantém-se a +// convenção para consistência entre os dois entry points) console.error(`[MCP:${toolName}] Início — params: ${JSON.stringify(args)}`); console.error(`[MCP:${toolName}] Concluído em ${duration}ms`); ``` @@ -210,12 +199,14 @@ console.error(`[MCP:${toolName}] Concluído em ${duration}ms`); - [ ] SQL injection: inputs validados antes de entrar em queries? - [ ] Interpolação directa em SQL proibida sem validação +- [ ] **Comandos shell/SSH: nunca interpolar dados do utilizador num comando (`ssh ... "$var"`, `exec(\`cmd ${var}\`)`); dados sempre por STDIN (texto ou base64)** — regra escrita depois de uma injecção de comandos real corrigida em produção (`mcp-kivicare`, 19-08-2026) - [ ] Transacções em operações multi-query relacionadas - [ ] Recursos (pool.connect) têm `finally` com release - [ ] Cleanup (ROLLBACK) tem try-catch próprio - [ ] `crypto.randomBytes()` em vez de `Math.random()` - [ ] Secrets em variáveis de ambiente, nunca hardcoded - [ ] `pnpm audit` sem vulnerabilidades críticas +- [ ] Se o MCP faz ponte para um sistema nativo (WP-CLI, API externa, …): o formato exacto de escrita (ex.: JSON vs PHP serialize, hooks disparados com objecto vs escalar) foi confirmado por leitura do código-fonte real do sistema alvo, nunca assumido **Grep de validação:** ```bash @@ -227,6 +218,9 @@ grep -rn 'Math.random' src/ # connect() sem finally grep -rn '\.connect()' src/ + +# Comandos shell/ssh interpolados — qualquer resultado exige revisão manual +grep -rn 'exec(\|execSync(\|spawn(.*sh\b' src/ | grep -i '\${' ``` --- @@ -257,9 +251,9 @@ tblleads, tblleads_sources, tblstaff, tbltaskstimers, tblexpenses | Transporte | Estado | Uso | |------------|--------|-----| -| StreamableHTTP | Recomendado | Novos MCPs, acesso remoto | -| stdio | Válido | Claude Code local, scripts | -| SSE | Deprecated | Retrocompatibilidade apenas | +| Streamable HTTP (SDK v2) | **Obrigatório** | Todos os MCPs novos — acesso remoto, gateway | +| stdio (SDK v2, `serveStdio`) | Excepção documentada | Só quando o host lança o processo directamente e não há gateway — justificar no README | +| SSE | Deprecated | Retrocompatibilidade apenas — nunca em MCP novo | **Portas HTTP reservadas (3200+):** @@ -284,4 +278,4 @@ tblleads, tblleads_sources, tblstaff, tbltaskstimers, tblexpenses --- -*best-practices.md v2.0 | 2026-03-10* +*best-practices.md v3.0 | 2026-08-19* diff --git a/infraestrutura/skills/mcp-dev/references/evaluation-guide.md b/infraestrutura/skills/mcp-dev/references/evaluation-guide.md index f91ad34..462f805 100644 --- a/infraestrutura/skills/mcp-dev/references/evaluation-guide.md +++ b/infraestrutura/skills/mcp-dev/references/evaluation-guide.md @@ -130,12 +130,15 @@ npx @modelcontextprotocol/inspector # Testar cada tool manualmente ``` -### Método Automatizado (Script TypeScript) +### Método Automatizado (Script TypeScript, SDK v2 — in-process, sem porta/socket) + +`handler.fetch` do `createMcpHandler` serve pedidos em processo — o transporte de teste nunca liga de facto ao URL, por isso não há porta a reservar nem servidor a arrancar/parar à volta de cada corrida. Ver [testing.md](https://ts.sdk.modelcontextprotocol.io/v2/testing.md). ```typescript // eval/run-evals.ts -import { Client } from '@modelcontextprotocol/sdk/client/index.js'; -import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'; +import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client'; +import { createMcpHandler } from '@modelcontextprotocol/server'; +import { createServer } from '../src/server.js'; // a mesma factory usada em src/http.ts interface EvalResult { id: string; @@ -160,7 +163,6 @@ async function runEval( const result = await client.callTool({ name: toolName, arguments: input }); const duration = Date.now() - start; - // Verificar assertions if (assertions.notError && result.isError) { return { id: toolName, passed: false, duration, error: 'Esperava sucesso, recebeu erro' }; } @@ -170,7 +172,7 @@ async function runEval( } if (assertions.containsFields) { - const text = result.content[0]?.text || ''; + const text = (result.content?.[0] as { text?: string })?.text || ''; for (const field of assertions.containsFields) { if (!text.includes(field)) { return { id: toolName, passed: false, duration, error: `Campo "${field}" não encontrado` }; @@ -191,12 +193,12 @@ async function runEval( // Executar todas as evaluations async function main() { - const transport = new StdioClientTransport({ - command: 'node', - args: ['dist/index.js'] + const handler = createMcpHandler(createServer); + const transport = new StreamableHTTPClientTransport(new URL('http://test.local/mcp'), { + fetch: (url, init) => handler.fetch(new Request(url, init)), }); - const client = new Client({ name: 'eval-client', version: '1.0.0' }); + const client = new Client({ name: 'eval-client', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' } }); await client.connect(transport); const results: EvalResult[] = []; @@ -226,6 +228,7 @@ async function main() { }); await client.close(); + await handler.close(); process.exit(passed === total ? 0 : 1); } @@ -277,4 +280,4 @@ jobs: --- -*evaluation-guide.md v1.0 | 2026-03-10* +*evaluation-guide.md v2.0 | 2026-08-19* diff --git a/infraestrutura/skills/mcp-dev/references/templates.md b/infraestrutura/skills/mcp-dev/references/templates.md index b5ed8f2..473eda5 100644 --- a/infraestrutura/skills/mcp-dev/references/templates.md +++ b/infraestrutura/skills/mcp-dev/references/templates.md @@ -1,6 +1,8 @@ -# MCP Templates - Scaffolding TypeScript +# MCP Templates - Scaffolding TypeScript (SDK v2, HTTP obrigatório) > Templates de código prontos a usar. Substituir `` pelo nome real do MCP. +> SDK oficial: [ts.sdk.modelcontextprotocol.io/v2](https://ts.sdk.modelcontextprotocol.io/v2/). +> **Transporte HTTP é obrigatório** — o template stdio no fim deste ficheiro só se aplica a uma excepção documentada (ver `SKILL.md` §Regra de Ouro). --- @@ -11,29 +13,34 @@ "name": "mcp-", "version": "1.0.0", "type": "module", - "main": "dist/index.js", + "main": "dist/http.js", "scripts": { "build": "tsc", - "start": "node dist/index.js", - "start:http": "node dist/index-http.js", - "dev": "tsx src/index.ts", - "dev:http": "tsx src/index-http.ts", + "start": "node dist/http.js", + "dev": "tsx src/http.ts", "eval": "tsx eval/run-evals.ts", "eval:ci": "npm run build && npm run eval", "reload:http": "npm run build && systemctl --user restart mcp- && sleep 2 && curl -s http://127.0.0.1:32XX/health" }, "dependencies": { - "@modelcontextprotocol/sdk": "^1.0.0", - "zod": "^3.22.0" + "@modelcontextprotocol/server": "^2.0.0", + "@modelcontextprotocol/express": "^2.0.0", + "@modelcontextprotocol/node": "^2.0.0", + "express": "^4.19.0", + "zod": "^4.2.0" }, "devDependencies": { + "@modelcontextprotocol/client": "^2.0.0", "@types/node": "^20.0.0", - "typescript": "^5.0.0", - "tsx": "^4.0.0" + "@types/express": "^4.17.0", + "typescript": "^5.7.0", + "tsx": "^4.19.0" } } ``` +Node.js **20+** obrigatório. `type: module` — o SDK v2 é ESM-only na sua API pública (ainda que publique um build CJS de compatibilidade). + --- ## tsconfig.json @@ -42,8 +49,8 @@ { "compilerOptions": { "target": "ES2022", - "module": "ESNext", - "moduleResolution": "bundler", + "module": "NodeNext", + "moduleResolution": "NodeNext", "outDir": "./dist", "rootDir": "./src", "strict": true, @@ -58,244 +65,100 @@ --- -## src/index.ts (stdio — padrão local) +## src/server.ts — factory partilhada (única fonte da definição de tools) + +A `McpServer` do v2 deriva capabilities automaticamente de `registerTool`/`registerResource`/`registerPrompt` — nunca declarar `capabilities: {...}` à mão (isso é a API de baixo nível v1, proibida). ```typescript -#!/usr/bin/env node /** - * MCP + * MCP — factory partilhada por HTTP e (excepcionalmente) stdio. * @author Descomplicar® | @link descomplicar.pt | @copyright 2026 */ -import { Server } from '@modelcontextprotocol/sdk/server/index.js'; -import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; -import { - CallToolRequestSchema, - ListToolsRequestSchema, - ListResourcesRequestSchema, - ListPromptsRequestSchema, -} from '@modelcontextprotocol/sdk/types.js'; -import { z } from 'zod'; +import { McpServer } from '@modelcontextprotocol/server'; +import * as z from 'zod/v4'; -// --- Schemas de validação --- -const ExampleSchema = z.object({ - param: z.string().min(1, 'param é obrigatório'), -}); +export function createServer(): McpServer { + const server = new McpServer({ name: 'mcp-', version: '1.0.0' }); -// --- Definição de tools --- -const allTools = [ - { - name: 'example_get_item', // {serviço}_{acção}_{recurso} - description: 'Obtém um item pelo ID', - annotations: { - readOnlyHint: true, - destructiveHint: false, - idempotentHint: true, - openWorldHint: false, - }, - inputSchema: { - type: 'object' as const, - properties: { - param: { type: 'string', description: 'ID do item' }, + server.registerTool( + 'example_get_item', // {serviço}_{acção}_{recurso}, snake_case, <=40 chars + { + description: 'Obtém um item pelo ID', + inputSchema: z.object({ + param: z.string().min(1).describe('ID do item'), + }), + outputSchema: z.object({ + id: z.string(), + status: z.string(), + }), + annotations: { + readOnlyHint: true, + destructiveHint: false, + idempotentHint: true, + openWorldHint: false, }, - required: ['param'], }, - handler: async (args: unknown) => { - const { param } = ExampleSchema.parse(args); - // ... lógica aqui + async ({ param }) => { + // ... lógica aqui — nunca interpolar `param` num comando shell/SQL; + // se este tool fizer ponte SSH/CLI, ver best-practices.md §Segurança. return { - content: [{ type: 'text' as const, text: `Item: ${param}` }], + content: [{ type: 'text', text: `Item: ${param}` }], structuredContent: { id: param, status: 'found' }, }; }, - }, -]; + ); -// --- Servidor --- -const server = new Server( - { name: 'mcp-', version: '1.0.0' }, - { capabilities: { tools: {}, resources: {}, prompts: {} } } -); - -server.setRequestHandler(ListToolsRequestSchema, async () => ({ - tools: allTools.map(t => ({ - name: t.name, - description: t.description, - annotations: t.annotations, - inputSchema: t.inputSchema, - })), -})); - -server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: [] })); -server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: [] })); - -server.setRequestHandler(CallToolRequestSchema, async (request) => { - const { name, arguments: args } = request.params; - const tool = allTools.find(t => t.name === name); - - if (!tool) { - return { - content: [{ type: 'text', text: `Tool desconhecida: ${name}` }], - isError: true, - }; - } - - try { - return await tool.handler(args); - } catch (error) { - if (error instanceof z.ZodError) { - return { - content: [{ - type: 'text', - text: `Parâmetros inválidos:\n${error.errors.map(e => ` - ${e.path.join('.')}: ${e.message}`).join('\n')}`, - }], - isError: true, - }; - } - return { - content: [{ - type: 'text', - text: `Erro em ${name}: ${error instanceof Error ? error.message : String(error)}`, - }], - isError: true, - }; - } -}); - -async function main() { - const transport = new StdioServerTransport(); - await server.connect(transport); - console.error('MCP running on stdio'); + return server; } - -main().catch(console.error); ``` --- -## src/index-http.ts (StreamableHTTP — padrão remoto) +## src/http.ts — entry point HTTP (obrigatório) ```typescript -#!/usr/bin/env node /** - * MCP - HTTP Server Mode + * MCP — HTTP Server (Streamable HTTP) * @author Descomplicar® | @link descomplicar.pt | @copyright 2026 */ -import { Server } from '@modelcontextprotocol/sdk/server/index.js'; -import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'; -import { - ListToolsRequestSchema, - CallToolRequestSchema, - ListResourcesRequestSchema, - ListPromptsRequestSchema, -} from '@modelcontextprotocol/sdk/types.js'; -import * as http from 'http'; -import { URL } from 'url'; -import { randomUUID } from 'crypto'; +import { createMcpExpressApp } from '@modelcontextprotocol/express'; +import { toNodeHandler } from '@modelcontextprotocol/node'; +import { createMcpHandler } from '@modelcontextprotocol/server'; +import { createServer } from './server.js'; -const PORT = parseInt(process.env.MCP_HTTP_PORT || '3200', 10); +const PORT = parseInt(process.env.MCP_HTTP_PORT || '32XX', 10); const HOST = process.env.MCP_HTTP_HOST || '127.0.0.1'; -const STATEFUL = process.env.MCP_STATEFUL !== 'false'; -const sessions = new Map(); +const handler = createMcpHandler(createServer); +const node = toNodeHandler(handler); -// Importar allTools do mesmo local que stdio -import { allTools } from './tools/index.js'; +// createMcpExpressApp já valida Host/Origin contra DNS rebinding no bind 127.0.0.1 +const app = createMcpExpressApp(); -function createMcpServer(): Server { - const server = new Server( - { name: 'mcp-', version: '1.0.0' }, - { capabilities: { tools: {}, resources: {}, prompts: {} } } - ); +app.all('/mcp', (req, res) => void node(req, res, req.body)); - server.setRequestHandler(ListToolsRequestSchema, async () => ({ - tools: allTools.map(t => ({ - name: t.name, - description: t.description, - annotations: t.annotations, - inputSchema: t.inputSchema, - })), - })); +app.get('/health', (_req, res) => { + res.json({ status: 'ok', name: 'mcp-', version: '1.0.0' }); +}); - server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: [] })); - server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: [] })); +const httpServer = app.listen(PORT, HOST, () => { + console.log(`MCP HTTP v1.0.0`); + console.log(` Endpoint: http://${HOST}:${PORT}/mcp`); + console.log(` Health: http://${HOST}:${PORT}/health`); +}); - server.setRequestHandler(CallToolRequestSchema, async (request) => { - const { name, arguments: args } = request.params; - const tool = allTools.find(t => t.name === name); - if (!tool) { - return { content: [{ type: 'text', text: `Tool desconhecida: ${name}` }], isError: true }; - } - try { - return await tool.handler(args); - } catch (error) { - return { - content: [{ type: 'text', text: `Erro: ${error instanceof Error ? error.message : String(error)}` }], - isError: true, - }; - } - }); - - return server; +async function shutdown(): Promise { + await handler.close(); + httpServer.close(() => process.exit(0)); } - -async function main() { - const httpServer = http.createServer(async (req, res) => { - res.setHeader('Access-Control-Allow-Origin', '*'); - res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS'); - res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Mcp-Session-Id'); - - if (req.method === 'OPTIONS') { res.writeHead(200); res.end(); return; } - - const url = new URL(req.url || '/', `http://${HOST}:${PORT}`); - - if (url.pathname === '/health') { - res.writeHead(200, { 'Content-Type': 'application/json' }); - res.end(JSON.stringify({ status: 'ok', version: '1.0.0', sessions: sessions.size, tools: allTools.length })); - return; - } - - if (url.pathname === '/mcp') { - try { - const transport = new StreamableHTTPServerTransport({ - sessionIdGenerator: STATEFUL ? () => randomUUID() : undefined, - }); - const srv = createMcpServer(); - if (STATEFUL && transport.sessionId) { - sessions.set(transport.sessionId, { transport }); - transport.onclose = () => { if (transport.sessionId) sessions.delete(transport.sessionId); }; - } - await srv.connect(transport); - await transport.handleRequest(req, res); - } catch (error) { - if (!res.headersSent) { - res.writeHead(500, { 'Content-Type': 'application/json' }); - res.end(JSON.stringify({ error: 'Internal server error' })); - } - } - return; - } - - res.writeHead(404, { 'Content-Type': 'application/json' }); - res.end(JSON.stringify({ error: 'Not found' })); - }); - - httpServer.listen(PORT, HOST, () => { - console.log(`MCP HTTP v1.0.0`); - console.log(` Endpoint: http://${HOST}:${PORT}/mcp`); - console.log(` Health: http://${HOST}:${PORT}/health`); - console.log(` Mode: ${STATEFUL ? 'Stateful' : 'Stateless'}`); - }); - - const shutdown = () => httpServer.close(() => process.exit(0)); - process.on('SIGINT', shutdown); - process.on('SIGTERM', shutdown); -} - -main().catch(console.error); +process.on('SIGINT', shutdown); +process.on('SIGTERM', shutdown); ``` +Binding a `0.0.0.0` (exposição fora de localhost) exige passar `allowedHosts` a `createMcpExpressApp({ host: '0.0.0.0', allowedHosts: [...] })` — nunca desligar a validação de Host/Origin. + --- ## ~/.config/systemd/user/mcp-.service @@ -308,7 +171,7 @@ After=network.target [Service] Type=simple WorkingDirectory=/home/ealmeida/mcp-servers/mcp- -ExecStart=/home/ealmeida/.nvm/versions/node/v22.18.0/bin/node dist/index-http.js +ExecStart=/home/ealmeida/.nvm/versions/node/v22.18.0/bin/node dist/http.js Restart=on-failure RestartSec=5 Environment=NODE_ENV=production @@ -323,7 +186,7 @@ WantedBy=default.target --- -## Configuração ~/.claude.json +## Configuração ~/.claude.json (HTTP — obrigatório) ```json { @@ -338,4 +201,40 @@ WantedBy=default.target --- -*templates.md v1.0 | 2026-03-10* +## src/stdio.ts — apenas para excepção documentada + +Usar **só** quando o host tem de lançar o processo directamente e não existe gateway (justificar no README do MCP). Mesma factory `createServer()` de `src/server.ts` — nunca duplicar a definição de tools. + +```typescript +/** + * MCP — stdio (EXCEPÇÃO — ver README §Transporte para a justificação) + * @author Descomplicar® | @link descomplicar.pt | @copyright 2026 + */ + +import { serveStdio } from '@modelcontextprotocol/server/stdio'; +import { createServer } from './server.js'; + +void serveStdio(createServer); +console.error('MCP running on stdio'); +``` + +::: warning +stdout é o canal do protocolo — logar sempre com `console.error`; um único `console.log` corrompe o stream JSON-RPC. +::: + +Configuração `~/.claude.json` correspondente: + +```json +{ + "mcpServers": { + "": { + "command": "node", + "args": ["/home/ealmeida/mcp-servers//dist/stdio.js"] + } + } +} +``` + +--- + +*templates.md v2.0 | 2026-08-19* diff --git a/infraestrutura/skills/pbs-config/SKILL.md b/infraestrutura/skills/pbs-config/SKILL.md index 3c4baec..f843cdc 100644 --- a/infraestrutura/skills/pbs-config/SKILL.md +++ b/infraestrutura/skills/pbs-config/SKILL.md @@ -1,7 +1,6 @@ --- name: pbs-config description: Configuracao do Proxmox Backup Server (PBS) -- criacao de datastores, politicas de retencao, sync jobs e remote targets para estrategia 3-2-1. -layer: wiki --- # PBS Config diff --git a/infraestrutura/skills/proxmox-cluster/SKILL.md b/infraestrutura/skills/proxmox-cluster/SKILL.md index 6d952ad..cc91174 100644 --- a/infraestrutura/skills/proxmox-cluster/SKILL.md +++ b/infraestrutura/skills/proxmox-cluster/SKILL.md @@ -2,7 +2,6 @@ name: proxmox-cluster description: Formação de cluster Proxmox com 2+ nodes — configuração de Corosync, Quorum e preparação para High Availability. disable-model-invocation: true -layer: wiki --- # Proxmox Cluster @@ -238,4 +237,264 @@ pvecm status cat /etc/pve/corosync.conf # Deve usar IP management (não vSwitch) -# bindnetaddr: +``` + +**5.2 Testar Latência Entre Nodes** +```bash +# De Node A → Node B +ping -c 100 | tail -5 + +# Expected: <5ms latency (mesma datacenter) +# CRITICAL: >10ms pode causar issues cluster +``` + +**5.3 Configurar Cluster Network Redundancy (Opcional)** +```bash +# Se múltiplas networks disponíveis: +pvecm update-ring -interface + +# Adicionar 2º ring (redundância) +# Requer 2 NICs ou VLANs separadas +``` + +### Fase 6: Firewall Cluster + +**6.1 Portas Necessárias (abrir entre nodes)** +```bash +# Corosync: +UDP 5404-5405 + +# PVE cluster: +TCP 22 (SSH) +TCP 8006 (Web UI) +TCP 3128 (SPICE proxy) +TCP 85 (pvedaemon) + +# Verificar firewall permite +iptables -L -n -v | grep 5404 +``` + +**6.2 Firewall Proxmox (Web UI)** +```bash +# Datacenter → Firewall → Options +# Enable firewall: NO (inicialmente, configurar depois) + +# Se enable: +# - Adicionar rules para cluster communication +# - Testar conectividade antes de aplicar +``` + +### Fase 7: Validation Tests + +**7.1 Cluster Status** +```bash +# Ambos nodes: +pvecm status + +# Expected: +# Quorum: Active +# Nodes: 2 +# Total votes: 2 +# Node online: 2 +``` + +**7.2 Criar VM Teste** +```bash +# Node A: Criar VM 999 +qm create 999 --name cluster-test --memory 512 --cores 1 + +# Node B: Verificar VM aparece +qm list | grep 999 + +# Deve aparecer em ambos (shared /etc/pve/) +``` + +**7.3 Migrar VM Entre Nodes (Offline)** +```bash +# Migração offline (sem shared storage) +qm migrate 999 + +# Aguardar transfer completo +# Verificar VM migrou +``` + +**7.4 Simular Falha Node (CUIDADO)** +```bash +# Em ambiente teste: +# Shutdown Node B +systemctl stop pve-cluster corosync + +# Node A deve continuar funcional +# Mas quorum perdido (2-node limitation) + +# Reactivar Node B +systemctl start corosync pve-cluster + +# Quorum restaura automaticamente +``` + +## Output Summary + +``` +✅ Cluster Proxmox formado: descomplicar + +🖥️ Nodes: + - Node A: server.descomplicar.pt (138.201.X.X) + - Node B: cluster.descomplicar.pt (138.201.X.X) + - Total: 2 nodes + +🗳️ Quorum: + - Expected votes: 2 + - Active votes: 2 + - Status: Active ✓ + +📁 Shared Config: + - /etc/pve/ replicated + - VMs visible em ambos nodes + - Storage config synced + +💾 Storage: + - Local: ZFS rpool em cada node + - Backup: PBS shared (pbs-main) + - [Futuro] Shared storage: Ceph ou NFS + +🔄 Migration: + - Offline migration: Enabled ✓ + - Live migration: Enabled (sem shared storage = slow) + - HA: Ready (configurar com /proxmox-ha) + +⚠️ Limitations (2-node cluster): + - Perder 1 node = perder quorum + - Solução: QDevice ou 3º node + - HA com fencing crítico + +📋 Next Steps: + 1. Configurar HA groups (/proxmox-ha) + 2. Configurar fencing devices + 3. Testar failover automático + 4. Migrar VMs production para cluster + 5. Monitorizar cluster health + +⏱️ Formation time: ~15min +``` + +## 2-Node Cluster Considerations + +### Quorum Issue +**Problema:** Perder 1 node = perder quorum (cluster read-only) + +**Mitigações:** +1. **QDevice externo** (3º vote em VPS leve) +2. **expected_votes override** (emergência - perigoso) +3. **Adicionar 3º node** (ideal) + +### Fencing CRITICAL +**Problema:** Split-brain (ambos nodes pensam que são primários) + +**Solução:** Fencing obrigatório para HA +- STONITH (Shoot The Other Node In The Head) +- Power fencing via IPMI/iLO +- Network fencing (menos confiável) + +### No Shared Storage +**Implicações:** +- Live migration mais lenta (copia disk) +- HA requer storage replication ou aceita downtime +- VMs ficam "pinned" ao node onde disk existe + +**Alternativas:** +- Ceph (mínimo 3 nodes) +- NFS share externo +- ZFS replication (pvesr) + +## Troubleshooting + +### Node join fails +```bash +# Verificar conectividade +ping +ssh root@ + +# Verificar versões matching +pveversion + +# Verificar /etc/hosts +cat /etc/hosts +# Deve ter entrada para ambos nodes + +# Logs +journalctl -u pve-cluster -f +journalctl -u corosync -f +``` + +### Quorum lost +```bash +# Verificar status +pvecm status + +# Nodes online mas quorum lost: +# - Verificar time sync (ntpd/chrony) +# - Verificar network latency +# - Restart corosync + +systemctl restart corosync pve-cluster +``` + +### Split-brain +```bash +# CRITICAL: Ambos nodes pensam que são primários + +# Identificar: +pvecm status # Em ambos nodes, status diferente + +# Resolver: +# 1. Shutdown 1 node completamente +# 2. Fix networking/corosync no node online +# 3. Rejoin node shutdown +``` + +## References + +- **NotebookLM:** 276ccdde-6b95-42a3-ad96-4e64d64c8d52 +- **Proxmox Cluster Docs:** https://pve.proxmox.com/pve-docs/chapter-pvecm.html +- **Corosync:** https://corosync.github.io/corosync/ + +--- + +**Versão:** 1.0.0 | **Autor:** Descomplicar® | **Data:** 2026-02-14 + +--- + +## Contexto NotebookLM + +ANTES de executar, consultar notebooks para contexto especializado: + +| Notebook | ID | Consultar quando | +|----------|-----|-----------------| +| Proxmox | 276ccdde-6b95-42a3-ad96-4e64d64c8d52 | Sempre | + +``` +mcp__notebooklm__notebook_query({ + notebook_id: "276ccdde-6b95-42a3-ad96-4e64d64c8d52", + query: "" +}) +``` + +Integrar insights do NotebookLM nas recomendações e decisões. + +--- + +**/** @author Descomplicar® | @copyright 2026 **/ + +--- + +## 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/infraestrutura/skills/proxmox-ha/SKILL.md b/infraestrutura/skills/proxmox-ha/SKILL.md index 4fddb1c..d7dc767 100644 --- a/infraestrutura/skills/proxmox-ha/SKILL.md +++ b/infraestrutura/skills/proxmox-ha/SKILL.md @@ -1,7 +1,6 @@ --- name: proxmox-ha description: Configuracao de High Availability em cluster Proxmox -- HA Manager, fencing devices (STONITH) e failover automatico para VMs criticas. -layer: wiki --- # Proxmox HA diff --git a/infraestrutura/skills/proxmox-setup/SKILL.md b/infraestrutura/skills/proxmox-setup/SKILL.md index 06587f8..b5564a7 100644 --- a/infraestrutura/skills/proxmox-setup/SKILL.md +++ b/infraestrutura/skills/proxmox-setup/SKILL.md @@ -1,7 +1,6 @@ --- name: proxmox-setup description: Instalacao completa de Proxmox VE 8.x em Hetzner -- installimage, ZFS RAID-1, NAT networking single-IP e vSwitch com optimizacoes. -layer: wiki --- # Proxmox Setup diff --git a/infraestrutura/skills/security-audit/SKILL.md b/infraestrutura/skills/security-audit/SKILL.md index c1ca9e9..e3f20c3 100644 --- a/infraestrutura/skills/security-audit/SKILL.md +++ b/infraestrutura/skills/security-audit/SKILL.md @@ -1,7 +1,6 @@ --- name: security-audit description: Auditoria de seguranca para aplicacoes web e servidores -- identificacao de vulnerabilidades, verificacao OWASP/GDPR e recomendacoes de hardening. -layer: wiki --- # /security-audit - Security Compliance Specialist @@ -28,7 +27,7 @@ Auditoria de seguranca seguindo padroes OWASP Top 10, GDPR e best practices Desc ```javascript // Antes de qualquer audit, consultar historico -await mcp__mem_search_memories({ +await mcp__mem0__search_memories({ query: "security vulnerabilidade [sistema/projecto]", limit: 5 }); diff --git a/infraestrutura/skills/security-check/SKILL.md b/infraestrutura/skills/security-check/SKILL.md index db7ec7a..dfb0d74 100644 --- a/infraestrutura/skills/security-check/SKILL.md +++ b/infraestrutura/skills/security-check/SKILL.md @@ -2,7 +2,6 @@ name: security-check description: Auditoria de seguranca de infraestrutura — certificados SSL, portas abertas, actualizacoes pendentes, backups recentes, CSF/firewall e email security. Score por servidor. context: fork -layer: wiki --- # /security-check v1.0 (infraestrutura) @@ -19,8 +18,8 @@ Auditoria de seguranca dos servidores Descomplicar. Verifica SSL, portas, actual | Alias | Host | IP | SO | Firewall | Gestor SSL | |-------|------|----|----|----------|------------| -| server | server.descomplicar.pt | 176.9.3.158 | CentOS (CWP) | CSF v15 | acme.sh | -| easy | qibspu.easypanel.host | 178.63.18.51 | Ubuntu 24.04 | — | EasyPanel/Traefik | +| server | server.descomplicar.pt | 5.9.90.105 | CentOS (CWP) | CSF v15 | acme.sh | +| easy | easy.descomplicar.pt | 5.9.90.70 | Ubuntu 24.04 | — | EasyPanel/Traefik | | gateway | gateway.descomplicar.pt | — | — | — | nginx/acme | --- @@ -158,4 +157,176 @@ echo "=== LFD Status ===" systemctl is-active lfd echo "=== Ataques Recentes (24h) ===" -grep "$(date \ No newline at end of file +grep "$(date +%b\ %d)" /var/log/lfd.log 2>/dev/null | grep -c "blocked" +``` + +**Thresholds:** +- **OK:** CSF activo, LFD activo, <50 bloqueios/dia +- **WARN:** >50 bloqueios/dia (possivel ataque) +- **CRITICAL:** CSF/LFD inactivo + +### Check 6: Email Security (server) + +```bash +# mcp__ssh-unified__ssh_execute(server="server") + +# Executar script de verificacao (criado 12-03-2026) +bash /root/scripts/email-security-check.sh 2>&1 | tail -20 +echo "Exit code: $?" +# Exit 0 = OK, Exit 1 = erros detectados +``` + +**Verifica:** Postfix header/body checks, content_filter (amavis), ClamAV, SpamAssassin, DMARC p=reject, Sieve anti-backscatter. + +--- + +## Execucao Pratica + +Agrupar comandos para minimizar chamadas SSH (3 chamadas total). + +**Chamada 1 — server (SSL + portas + firewall):** +```bash +echo "=== SSL CERTS ===" && for dir in /root/.acme.sh/cwp_certs/*_ecc; do domain=$(basename "$dir" | sed 's/_ecc$//'); cert="$dir/${domain}.cer"; if [ -f "$cert" ]; then expiry=$(openssl x509 -enddate -noout -in "$cert" 2>/dev/null | cut -d= -f2); days=$(( ($(date -d "$expiry" +%s) - $(date +%s)) / 86400 )); if [ "$days" -lt 15 ]; then echo "CRITICAL ${days}d $domain"; elif [ "$days" -lt 30 ]; then echo "WARN ${days}d $domain"; else echo "OK ${days}d $domain"; fi; fi; done | sort && echo "=== PORTAS ===" && ss -tlnp | awk 'NR>1 {print $4}' | sed 's/.*://' | sort -n | uniq -c | sort -rn && echo "=== CSF ===" && csf -v && systemctl is-active lfd && wc -l /etc/csf/csf.deny && echo "Bloqueios hoje:" && grep "$(date +%b\ %d)" /var/log/lfd.log 2>/dev/null | grep -c "blocked" +``` + +**Chamada 2 — server (backups + updates + email sec):** +```bash +echo "=== BACKUPS ===" && echo "MySQL daily:" && find /home/backup/mysql/daily/ -name "*.sql.gz" -mtime -2 2>/dev/null | wc -l && echo "Monthly:" && ls -lt /home/backup/monthly/ 2>/dev/null | head -3 && echo "=== UPDATES ===" && dnf check-update --quiet 2>/dev/null | grep -v "^$" | wc -l && dnf updateinfo list security 2>/dev/null | tail -5 && echo "=== EMAIL SEC ===" && bash /root/scripts/email-security-check.sh 2>&1 | tail -15 && echo "Exit: $?" +``` + +**Chamada 3 — easy (updates + portas):** +```bash +echo "=== UPDATES ===" && apt list --upgradable 2>/dev/null | grep -v "^Listing" | wc -l && apt list --upgradable 2>/dev/null | grep -v "^Listing" | head -10 && echo "=== PORTAS ===" && ss -tlnp | grep LISTEN | wc -l && echo "=== DOCKER ===" && docker ps --format '{{.Names}}: {{.Status}}' 2>/dev/null | grep -i unhealthy && echo "=== DISCO ===" && df -h / /gordito 2>/dev/null +``` + +--- + +## Output + +```markdown +## Security Check — [data via mcp-time] + +### Resumo + +| Servidor | SSL | Portas | Updates | Backups | Firewall | Email | Score | +|----------|-----|--------|---------|---------|----------|-------|-------| +| server | OK/WARN/CRIT | OK/WARN | OK/WARN/CRIT | OK/WARN/CRIT | OK/WARN/CRIT | OK/WARN | X/6 | +| easy | n/a | OK/WARN | OK/WARN/CRIT | n/a | n/a | n/a | X/2 | + +**Score global:** X/8 checks OK + +### SSL Certificados ([N] dominios verificados) + +| Estado | Dominio | Expira em | Data | +|--------|---------|-----------|------| +| CRITICAL | example.pt | Xd | YYYY-MM-DD | +| WARN | example2.pt | Xd | YYYY-MM-DD | + +[Se todos OK: "Todos os N certificados validos (minimo Xd)"] + +### Portas Inesperadas +| Porta | Processo | Accao Sugerida | +|-------|----------|----------------| +| XXXX | processo | Investigar / Fechar | + +[Se nenhuma: "Todas as portas dentro do esperado"] + +### Actualizacoes Pendentes +- **server (CentOS):** N packages (M security) +- **easy (Ubuntu):** N packages + +### Backups +- MySQL daily: N BDs com backup <48h [OK/WARN/CRIT] +- Monthly: ultimo em DD-MM-YYYY [OK/WARN/CRIT] + +### Firewall CSF +- CSF: vXX [activo/inactivo] +- LFD: [activo/inactivo] +- IPs bloqueados: N permanentes +- Bloqueios hoje: N + +### Email Security +- [resultado do script email-security-check.sh] + +### Accoes Recomendadas +1. [CRITICAL] Accao imediata +2. [WARN] Accao recomendada +3. [INFO] Melhorias opcionais +``` + +--- + +## Scoring + +| Score | Significado | +|-------|-------------| +| 8/8 | Excelente — tudo operacional | +| 6-7/8 | Bom — warnings menores | +| 4-5/8 | Atencao — accoes necessarias | +| <4/8 | Critico — accao imediata | + +**Calculo:** 1 ponto por cada check OK. WARN conta 0.5. CRITICAL conta 0. + +--- + +## Troubleshooting + +``` +SSL CRITICAL (<15d): + 1. SSH server: /root/.acme.sh/acme.sh --renew -d DOMAIN --ecc + 2. Copiar para /etc/pki/tls/: /scripts/autossl_install_certs + 3. Reload nginx: /scripts/cwp_api webservers restart + 4. Verificar Cloudflare DNS-only (proxied impede Let's Encrypt) + Ref: cwp-ssl-autorenew-fix.md + +CSF/LFD inactivo: + 1. csf -e (activar) + 2. service lfd start + 3. Verificar /etc/csf/csf.conf (TESTING = "0") + +Backup MySQL >72h: + 1. Verificar cron: crontab -l | grep backup + 2. Verificar espaco: df -h /home/backup/ + 3. Verificar logs: /var/log/cron | grep backup + +Muitos bloqueios CSF (>100/dia): + 1. Analisar origens: awk '{print $2}' /etc/csf/csf.deny | sort | uniq -c | sort -rn | head + 2. Se mesmo IP range: bloquear CIDR + 3. Se paises especificos: CC_DENY em csf.conf +``` + +--- + +## Integracao + +- **/today** pode invocar `/security-check quick` como parte do checkup diario +- **/infra-check** (cron) ja faz verificacao basica; `/security-check` e mais profundo e interactivo +- **/server-health** cobre metricas de performance; `/security-check` foca-se em seguranca +- **/cwp-security** foca-se em operacoes CSF; `/security-check` e auditoria abrangente +- Resultado pode ser publicado na discussao #31 (Logs) do projecto #65 + +--- + +## Anti-Patterns + +- **Nunca** desactivar CSF para "resolver" problemas de acesso +- **Nunca** ignorar certificado CRITICAL (<15d) — pode expirar antes do proximo check +- **Nunca** actualizar kernel sem janela de manutencao planeada +- **Sempre** verificar email-security apos alteracoes em Postfix/AMaViS +- **Sempre** incluir timestamp via mcp-time no output + +--- + +*Skill v1.0.0 | 12-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ós cada erro corrigido.* diff --git a/infraestrutura/skills/server-health/SKILL.md b/infraestrutura/skills/server-health/SKILL.md index 31c5aa7..f4ba111 100644 --- a/infraestrutura/skills/server-health/SKILL.md +++ b/infraestrutura/skills/server-health/SKILL.md @@ -1,7 +1,6 @@ --- name: server-health description: Diagnostico completo de servidor -- monitorizacao de recursos, estado de servicos e identificacao de problemas de performance. -layer: wiki --- # /server-health - Diagnostico Completo de Servidor @@ -35,7 +34,7 @@ mcp__notebooklm__notebook_query({ | Servidor | IP | MCP | User | |----------|-----|-----|------| -| **CWP Principal** | 176.9.3.158 | ssh-unified | root | +| **CWP Principal** | server.descomplicar.pt | ssh-unified | root | ```javascript mcp__ssh-unified__ssh_execute({ diff --git a/infraestrutura/skills/vm-migration/SKILL.md b/infraestrutura/skills/vm-migration/SKILL.md index 51154c5..2be198e 100644 --- a/infraestrutura/skills/vm-migration/SKILL.md +++ b/infraestrutura/skills/vm-migration/SKILL.md @@ -1,7 +1,6 @@ --- name: vm-migration description: Migracao zero-downtime de workloads CWP e EasyPanel para VMs Proxmox com safety nets e rollback procedures. -layer: wiki --- # VM Migration diff --git a/marketing/.claude-plugin/plugin.json b/marketing/.claude-plugin/plugin.json index 4f17dfa..0d4739e 100644 --- a/marketing/.claude-plugin/plugin.json +++ b/marketing/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "marketing", "description": "Digital marketing strategy, SEO, content marketing, social media, ads, copywriting, video and YouTube. Backed by NotebookLM notebooks.", - "version": "1.0.0", + "version": "2.1.0", "author": { "name": "Descomplicar - Crescimento Digital", "url": "https://descomplicar.pt" diff --git a/marketing/CHANGELOG.md b/marketing/CHANGELOG.md index bf3e7b4..09e3840 100644 --- a/marketing/CHANGELOG.md +++ b/marketing/CHANGELOG.md @@ -1,5 +1,9 @@ # CHANGELOG — marketing +## 2.1.0 — 2026-10-17 +### Removido +- Skill `brand-strategy`: fundida em `crm-ops:estrategia-marca` (uma só skill de estratégia de marca, alinhada com a SPEC v2.0). + ## 0.1.0 — 2026-06-30 ### Adicionado - Estrutura padrão (PROC-DEV-STANDARD) diff --git a/marketing/agents/content-manager.md b/marketing/agents/content-manager.md index 59c6382..241b530 100644 --- a/marketing/agents/content-manager.md +++ b/marketing/agents/content-manager.md @@ -11,6 +11,8 @@ model: sonnet tools: Read, Write, Edit, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 - google-workspace @@ -24,7 +26,6 @@ skills: - video - youtube desk_task: 1494 -layer: wiki --- # Content Manager Descomplicar @@ -161,4 +162,97 @@ Você é um gestor de conteúdo experiente responsável por: ### NotebookLM (Primario - usar PRIMEIRO) ``` -mcp__notebooklm__notebook_query noteb \ No newline at end of file +mcp__notebooklm__notebook_query notebook_id:"76647e0f-3ae2-4c00-a0a8-f457aebf5655" query:"estrategia editorial calendario" +mcp__notebooklm__notebook_query notebook_id:"7b8fec17-d34f-4e3f-a8c6-8231e51f6323" query:"brand voice storytelling" +``` + +## Your Available MCPs + +### Recommended for content +- **youtube-research** - Pesquisa e análise YouTube +- **youtube-uploader** - Upload vídeos YouTube +- **elevenlabs** - Text-to-speech, voice cloning, audio transcription +- **vimeo** - Video management - upload, metadata, transcripts, analytics +- **outline-api** - Outline documentation +- **google-workspace** - Email, calendário, docs, drive +- **replicate** - AI models - imagem, vídeo, áudio, LLMs + +### All Available (32 total) +desk-crm-v3, moloni, context7, gitea, n8n, cwp, filesystem, ssh-unified, google-analytics, imap, gsc, lighthouse, mcp-time, mem0, puppeteer, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, magic, design-systems + +**Discovery:** Use ToolSearch to find specific tools. +**Example:** `ToolSearch("ssh upload")` finds SSH upload tools. +## Your Available Skills + +### Primary Skills (Your Domain) +✓ **/content-marketing-pt** - Criação de conteúdo marketing em Português Europeu. Tom de voz, copywriting, est + - Invoke: `/content-marketing-pt` + +✓ **/video** - Criar vídeos programáticos com Remotion e React. Gera intros, promos, social med + - Invoke: `/video` + +✓ **/youtube** - Extrair transcrições e metadados do YouTube + Estratégia crescimento canal. Supo + - Invoke: `/youtube` + +### Recommended for content +- **/social-media** - Gestão e estratégia de redes sociais - Instagram, LinkedIn, +- **/remotion-video** - Create and edit Remotion videos with domain-specific knowled +- **/seo-content-optimization** - Optimização SEO técnico e conteúdo - meta tags, structured d +- **/research** - Pesquisa profunda e análise competitiva - SWOT, Porter's Fiv + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /lead-approach, /orcamento, /saas, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /crm-admin, /db-design, /elementor, /mcp-dev, /nextjs, /php-dev, /react-patterns, /woocommerce, /wp-dev, /backup-strategies, /security-audit, /server-health, /wp-performance, /wp-update, /second-brain-repo, /ads, /doc-sync, /marketing-strategy, /product, /skill-creator, /sop-creator, /calendar-manager, /delegate, /interview, /time, /today, /seo-audit, /seo-report, /archive, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. +## Colaboração + +- **Reports to**: Marketing Planning Expert +- **Colabora com**: Copywriter, SEO Specialist, Social Media Manager, UI Designer, Video Production Specialist +- **Escalar para**: Marketing Planning Expert (estratégia), SEO Specialist (optimização técnica) +## Your Team & Responsibilities + +You are part of **7 SDKs** (TaskForce teams): + +### TaskForce Claude Agents + +**Purpose:** NULL + +**Your responsibilities in this TaskForce:** +### TaskForce Conteúdo + +**Purpose:** NULL + +### TaskForce Deep Research + +**Purpose:** NULL + +### TaskForce Marketing Estratégico + +**Purpose:** NULL + +### TaskForce Redes Sociais + +**Purpose:** NULL + +### TaskForce SEO + +**Purpose:** NULL + +### TaskForce YouTube + +**Purpose:** NULL + +**Collaboration:** +- Work with other agents in your TaskForce teams +- Share knowledge and context across team members +- Leverage team-specific skills and MCPs +- Contribute to team goals and deliverables + diff --git a/marketing/agents/copywriter.md b/marketing/agents/copywriter.md index cd90d49..c1481cc 100644 --- a/marketing/agents/copywriter.md +++ b/marketing/agents/copywriter.md @@ -7,6 +7,8 @@ model: sonnet tools: Read, Write, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 recommended_mcps: @@ -45,7 +47,6 @@ escalates_to: created: "2025-01-13" updated: "2026-02-04" author: "Descomplicar®" -layer: wiki --- # Copywriter Descomplicar @@ -180,4 +181,129 @@ A: Vantagem prática B: Benefício emocional ("para ti") ``` -## Brand Voice Descomplicar \ No newline at end of file +## Brand Voice Descomplicar® + +- **Claro**: Sem jargão, directo ao ponto +- **Humano**: Conversa natural, não corporativo +- **Confiante**: Sabemos o que fazemos (não arrogante) +- **Acessível**: Estamos aqui para ajudar +- **Accionável**: Sempre com próximo passo claro + +**Evitar:** +- Buzzwords vazios ("sinergias", "disruptivo") +- Superlativos exagerados ("melhor do mundo") +- Promessas irrealistas +- Tom condescendente + +## Knowledge Sources (Consultar SEMPRE) + +### NotebookLM (Primario - usar PRIMEIRO) + +``` +mcp__notebooklm__notebook_query notebook_id:"7b8fec17-d34f-4e3f-a8c6-8231e51f6323" query:"persuasao conversao AIDA PAS" +mcp__notebooklm__notebook_query notebook_id:"76647e0f-3ae2-4c00-a0a8-f457aebf5655" query:"storytelling brand" +mcp__notebooklm__notebook_query notebook_id:"9053d0e8-dd39-460b-b5ea-e67af3e9a675" query:"brand voice tom comunicacao" +``` + +## Your Available MCPs + +### Recommended for content +- **youtube-research** - Pesquisa e análise YouTube +- **youtube-uploader** - Upload vídeos YouTube +- **elevenlabs** - Text-to-speech, voice cloning, audio transcription +- **vimeo** - Video management - upload, metadata, transcripts, analytics +- **outline-api** - Outline documentation +- **google-workspace** - Email, calendário, docs, drive +- **replicate** - AI models - imagem, vídeo, áudio, LLMs + +### All Available (32 total) +desk-crm-v3, moloni, context7, gitea, n8n, cwp, filesystem, ssh-unified, google-analytics, imap, gsc, lighthouse, mcp-time, mem0, puppeteer, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, magic, design-systems + +**Discovery:** Use ToolSearch to find specific tools. +**Example:** `ToolSearch("ssh upload")` finds SSH upload tools. +## Your Available Skills + +### Primary Skills (Your Domain) +✓ **/content-marketing-pt** - Criação de conteúdo marketing em Português Europeu. Tom de voz, copywriting, est + - Invoke: `/content-marketing-pt` + +✓ **/video** - Criar vídeos programáticos com Remotion e React. Gera intros, promos, social med + - Invoke: `/video` + +✓ **/youtube** - Extrair transcrições e metadados do YouTube + Estratégia crescimento canal. Supo + - Invoke: `/youtube` + +### Recommended for content +- **/social-media** - Gestão e estratégia de redes sociais - Instagram, LinkedIn, +- **/remotion-video** - Create and edit Remotion videos with domain-specific knowled +- **/seo-content-optimization** - Optimização SEO técnico e conteúdo - meta tags, structured d +- **/research** - Pesquisa profunda e análise competitiva - SWOT, Porter's Fiv + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /lead-approach, /orcamento, /saas, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /crm-admin, /db-design, /elementor, /mcp-dev, /nextjs, /php-dev, /react-patterns, /woocommerce, /wp-dev, /backup-strategies, /security-audit, /server-health, /wp-performance, /wp-update, /second-brain-repo, /ads, /doc-sync, /marketing-strategy, /product, /skill-creator, /sop-creator, /calendar-manager, /delegate, /interview, /time, /today, /seo-audit, /seo-report, /archive, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. +## Colaboração + +- **Reports to**: Content Manager +- **Colabora com**: SEO Specialist, Social Media Manager, UI Designer, Marketing Planning Expert +- **Escalar para**: Content Manager (estratégia conteúdo), SEO Specialist (optimização técnica) +## Your Team & Responsibilities + +You are part of **10 SDKs** (TaskForce teams): + +### TaskForce Ad Manager + +**Purpose:** NULL + +### TaskForce Claude Agents + +**Purpose:** NULL + +**Your responsibilities in this TaskForce:** +### TaskForce Conteúdo + +**Purpose:** NULL + +### TaskForce Copywriting + +**Purpose:** NULL + +### TaskForce E-commerce + +**Purpose:** NULL + +### TaskForce Elementor + +**Purpose:** NULL + +### TaskForce Marketing Estratégico + +**Purpose:** NULL + +### TaskForce Redes Sociais + +**Purpose:** NULL + +### TaskForce Vendas + +**Purpose:** NULL + +### TaskForce YouTube + +**Purpose:** NULL + +**Collaboration:** +- Work with other agents in your TaskForce teams +- Share knowledge and context across team members +- Leverage team-specific skills and MCPs +- Contribute to team goals and deliverables + diff --git a/marketing/agents/marketing-planning-expert.md b/marketing/agents/marketing-planning-expert.md index e00f6ff..7db8ab3 100644 --- a/marketing/agents/marketing-planning-expert.md +++ b/marketing/agents/marketing-planning-expert.md @@ -18,10 +18,12 @@ user_invocable: true tier: 1 # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 # Business operations - google-workspace # Analytics, Ads, Docs - - mem0 # Long-term memory + - mem0 # Memória longo prazo (Tier 2) via Mem0 recommended_mcps: - google-analytics # GA4 analytics - youtube-research # YouTube research @@ -84,7 +86,6 @@ collaborations: created: 2026-02-04 last_updated: 2026-02-04 quality_score: 85 -layer: wiki --- # Marketing Planning Expert Descomplicar @@ -148,4 +149,8 @@ Especialista em estrategia de marketing digital, desenvolvimento de campanhas e ### Workflow 3: Growth Hacking Experiment 1. Identificar bottleneck no funil -2. Hipótese de growth (ex \ No newline at end of file +2. Hipótese de growth (ex: referral program) +3. MVP rápido (2 semanas max) +4. Metrics tracking (antes/durante/depois) +5. Validar ou invalidar hipótese +6. Scale se funciona, pivotar se falha diff --git a/marketing/agents/ppc-specialist.md b/marketing/agents/ppc-specialist.md index e1c1bd8..b3454c5 100644 --- a/marketing/agents/ppc-specialist.md +++ b/marketing/agents/ppc-specialist.md @@ -10,6 +10,8 @@ model: sonnet tools: Read, Write, Edit, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 - google-analytics @@ -37,7 +39,6 @@ compliance: created: '2025-01-13' updated: '2026-02-04' author: Descomplicar® -layer: wiki --- # PPC Specialist Descomplicar @@ -127,17 +128,45 @@ mcp__notebooklm__notebook_query notebook_id:"76647e0f-3ae2-4c00-a0a8-f457aebf565 - **pexels** - Pesquisa imagens stock de alta qualidade - **tavily** - AI-powered search API - web search optimizado para LLMs - **** - Knowledge base AI -- **mem0** - Memória longo prazo +- **mem0** - Mem0 (Tier 2, `mcp__mem0__*`) + IJFW (Tier 1, automático via hooks) - **elevenlabs** - Text-to-speech, voice cloning, audio transcription - **vimeo** - Video management - upload, metadata, transcripts, analytics - **replicate** - AI models - imagem, vídeo, áudio, LLMs ### All Available (32 total) -moloni, context7, gitea, n8n, cwp, filesystem, ssh-unified, imap, outline-api, wikijs, gsc, lighthouse, mcp-time, puppeteer, mcp-mermaid, mcp-echarts, powerpoint, penpot, magic, design-systems +moloni, context7, gitea, n8n, cwp, filesystem, ssh-unified, imap, outline-api, gsc, lighthouse, mcp-time, puppeteer, mcp-mermaid, mcp-echarts, powerpoint, penpot, magic, design-systems **Discovery:** Use ToolSearch to find specific tools. **Example:** `ToolSearch("ssh upload")` finds SSH upload tools. ## Your Available Skills ### Primary Skills (Your Domain) -✓ **/lead-approach** - Abordagem estratégica de leads - análise, estratégia e primeiro contacto. Usar q \ No newline at end of file +✓ **/lead-approach** - Abordagem estratégica de leads - análise, estratégia e primeiro contacto. Usar q + - Invoke: `/lead-approach` + +✓ **/marketing-strategy** - Estratégia de marketing digital integrada - análise mercado, posicionamento, mix + - Invoke: `/marketing-strategy` + +✓ **/ads** - Gestão de campanhas de publicidade paga (PPC) - Google Ads, Meta Ads, LinkedIn A + - Invoke: `/ads` + +### Recommended for marketing +- **/social-media** - Gestão e estratégia de redes sociais - Instagram, LinkedIn, +- **/content-marketing-pt** - Criação de conteúdo marketing em Português Europeu. Tom de v +- **/seo-content-optimization** - Optimização SEO técnico e conteúdo - meta tags, structured d +- **/youtube** - Extrair transcrições e metadados do YouTube + Estratégia cre +- **/research** - Pesquisa profunda e análise competitiva - SWOT, Porter's Fiv + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /orcamento, /saas, /remotion-video, /video, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /crm-admin, /db-design, /elementor, /mcp-dev, /nextjs, /php-dev, /react-patterns, /woocommerce, /wp-dev, /backup-strategies, /security-audit, /server-health, /wp-performance, /wp-update, /second-brain-repo, /doc-sync, /product, /skill-creator, /sop-creator, /calendar-manager, /delegate, /interview, /time, /today, /seo-audit, /seo-report, /archive, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. + diff --git a/marketing/agents/seo-specialist.md b/marketing/agents/seo-specialist.md index 5ea0697..2cc9bd6 100644 --- a/marketing/agents/seo-specialist.md +++ b/marketing/agents/seo-specialist.md @@ -5,43 +5,43 @@ description: > Use for SEO strategy, keyword research, technical SEO audits, on-page optimization, Core Web Vitals, rankings monitoring, link building, SERP analysis, or when user mentions "SEO", "keywords", "rankings", "tráfego orgânico", "SERP", "technical SEO", "link building", "Google", "optimização", "indexação". author: Descomplicar® Crescimento Digital -version: 2.0.0 +version: 3.0.0 category: business model: sonnet tools: Read, Glob, Grep, ToolSearch # Dependencies +# OpenSEO é o motor único de SEO. O stack antigo (gsc, lighthouse, Ahrefs, +# SEO Tools API) está desligado ou não existe — não o invocar. primary_mcps: - - gsc - - google-analytics - - desk-crm-v3 + - openseo recommended_mcps: - - lighthouse + - chrome-devtools + - google-workspace - context7 -allowed-mcps: ssh-unified, google-workspace, gsc, lighthouse, google-analytics, tavily +allowed-mcps: openseo, chrome-devtools, google-workspace, context7 skills: - _core - seo-audit - seo-report - seo-content-optimization desk_task: 1516 -layer: wiki --- # SEO Specialist Descomplicar -Especialista em optimizacao para motores de busca, focado em crescimento de trafego organico atraves de SEO tecnico, optimizacao de conteudo e estrategias de link building. +Especialista em optimização para motores de busca, focado em crescimento de tráfego orgânico através de SEO técnico, optimização de conteúdo e estratégias de link building. ## Responsabilidades -- Conduzir pesquisa de keywords e analise competitiva -- Optimizar elementos on-page (titulos, meta descriptions, headers) -- Melhorar SEO tecnico (velocidade, crawlability, indexacao, Core Web Vitals) -- Desenvolver estrategias de link building e autoridade de dominio -- Monitorizar rankings e reportar metricas de trafego organico +- Conduzir pesquisa de keywords e análise competitiva +- Optimizar elementos on-page (títulos, meta descriptions, headers) +- Melhorar SEO técnico (velocidade, crawlability, indexação, Core Web Vitals) +- Desenvolver estratégias de link building e autoridade de domínio +- Monitorizar rankings e reportar métricas de tráfego orgânico ## Knowledge Sources (Consultar SEMPRE) -### NotebookLM (Primario - usar PRIMEIRO) +### NotebookLM (Primário — usar PRIMEIRO) ``` mcp__notebooklm__notebook_query notebook_id:"76647e0f-3ae2-4c00-a0a8-f457aebf5655" query:"keywords rankings optimizacao SERP" @@ -50,13 +50,13 @@ mcp__notebooklm__notebook_query notebook_id:"76647e0f-3ae2-4c00-a0a8-f457aebf565 ## System Prompt ### Papel -Especialista SEO responsavel por aumentar trafego organico atraves de optimizacao tecnica, keyword research e estrategias de link building alinhadas com algoritmos 2026. +Especialista SEO responsável por aumentar tráfego orgânico através de optimização técnica, keyword research e estratégias de link building alinhadas com algoritmos 2026. -### Regras Obrigatorias -1. SEMPRE priorizar Core Web Vitals (LCP, FID, CLS) +### Regras Obrigatórias +1. SEMPRE priorizar Core Web Vitals (LCP < 2,5s, INP < 200ms, CLS < 0,1 — o INP substituiu o FID) 2. NUNCA usar black-hat SEO (keyword stuffing, PBNs, cloaking) -3. Keyword research baseado em search intent, nao volume -4. E-E-A-T obrigatorio (Experience, Expertise, Authority, Trust) +3. Keyword research baseado em search intent, não volume +4. E-E-A-T obrigatório (Experience, Expertise, Authority, Trust) 5. Mobile-first indexing (testar sempre em mobile) 6. Structured data (Schema.org) para rich snippets @@ -68,63 +68,129 @@ Especialista SEO responsavel por aumentar trafego organico atraves de optimizaca ## Workflows ### Workflow 1: Keyword Research -1. Seed keywords: Brainstorm com cliente, analise concorrentes -2. Expansion: Google Keyword Planner, Ahrefs, SEMrush -3. Intent mapping: Informacional, navegacional, transaccional -4. Difficulty: Avaliar competicao (DA de top 10) -5. Priorization: Quick wins (low difficulty, medium volume) -6. Mapping: Atribuir keywords a paginas/conteudos +1. **Search Console primeiro** (grátis): `get_search_console_performance` — o que já posiciona +2. Striking distance: filtrar pos 4-20 com impressões ≥ 25 (o GSC não filtra por posição) +3. Hidratar: `get_keyword_metrics` — até 700 keywords/chamada, volume + KD + intenção +4. Expandir (só se necessário): `research_keywords`, 1-5 seeds +5. Priorizar: quick wins (KD baixo, volume médio, intenção comercial) +6. Mapear keywords a páginas; guardar com `save_keywords` ### Workflow 2: Technical SEO Audit -1. Crawl: Screaming Frog, Google Search Console -2. Core Web Vitals: PageSpeed Insights, Lighthouse -3. Indexation: Sitemap, robots.txt, canonicals, redirects -4. Structure: URL structure, internal linking, breadcrumbs -5. Mobile: Responsive design, tap targets, viewport -6. Schema: Structured data validation (Google Rich Results Test) +1. GSC por página: conta quantas páginas têm procura real +2. `run_site_audit` com **maxPages ≥ páginas do GSC + 25%** (o default 50 cega a auditoria) +3. `get_audit_status` em poll até "completed"; depois `get_audit_issues` por severidade +4. Priorizar issues pelas páginas com impressões — nunca por contagem bruta +5. Core Web Vitals das páginas que importam: `chrome-devtools → performance_start_trace` +6. Indexação: `inspect_urls` (até 10 URLs) ### Workflow 3: On-Page Optimization 1. Title tag: Keyword + brand, <60 chars 2. Meta description: CTR-focused, <160 chars 3. Headers: H1 (1x), H2/H3 hierarchy com keywords 4. Content: E-E-A-T, >1000 words para pillar content -5. Images: Alt text descritivo, compressao, lazy loading -6. Internal links: Link para conteudo relacionado +5. Images: Alt text descritivo, compressão, lazy loading +6. Internal links: Link para conteúdo relacionado ## MCPs Relevantes -- ssh-unified: Optimizacoes tecnicas em servidores WP -- google-workspace: GSC data, relatorios em Sheets +- **openseo**: motor único — crawl, Search Console, keywords, SERP, backlinks +- **chrome-devtools**: Core Web Vitals e Lighthouse por página +- **google-workspace**: exportar relatórios para Docs/Sheets -## Metricas Chave +## Métricas Chave - **Organic Traffic**: Visitantes de search engines -- **Rankings**: Posicoes keywords alvo (top 3 = sucesso) +- **Rankings**: Posições das keywords alvo (top 3 = sucesso) - **CTR**: Click-through rate em SERPs -- **Core Web Vitals**: LCP <2.5s, FID <100ms, CLS <0.1 -- **Backlinks**: Numero e qualidade (DA dos sites) +- **Core Web Vitals**: LCP < 2,5s, INP < 200ms, CLS < 0,1 +- **Backlinks**: Número e qualidade (DA dos sites) -## Colaboracao +## Colaboração - Reports to: Digital Marketing Manager - Colabora com: Content Manager, Copywriter, Web Designer, WordPress Developer ## Your Available MCPs ### Primary MCPs (Your Domain) -✓ **ssh-unified** (infra) - - SSH, SFTP, servidor management - - Usage: `mcp__ssh-unified__*` +✓ **openseo** (motor SEO) + - Crawl e issues, Search Console, keywords, SERP, backlinks, rank tracking + - Ferramentas grátis primeiro; pagas só depois de esgotar as grátis + - Mercado PT obrigatório: `locationCode: 2620`, `languageCode: "pt"` -✓ **google-workspace** (integration) - - Email, calendário, docs, drive - - Usage: `mcp__google-workspace__*` +✓ **chrome-devtools** (performance) + - `lighthouse_audit`, `performance_start_trace` — CWV reais por página ### Recommended for seo -- **gsc** - Google Search Console -- **lighthouse** - Performance audits -- **google-analytics** - Google Analytics 4 -- **tavily** - AI-powered search API - web search optimizado para LLMs +- **google-workspace** — Exportar relatórios (Docs, Sheets) +- **context7** — Documentação de bibliotecas e frameworks -### All Available (32 total) -desk-crm-v3, moloni, context7, gitea, n8n, cwp, filesystem, imap, outline-api, youtube-research, youtube-uploader, wikijs, mcp-time, mem0, puppeteer, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, elevenlabs, magic, vimeo, design-systems, replicate +### Desligados — NÃO invocar +`gsc`, `lighthouse`, `google-analytics` estão em disabledServers. `Ahrefs` e a +`SEO Tools API` (localhost:3000) não existem. Se precisares de um deles, pedir +activação via `/mcp` — nunca contornar com bash/curl. **Discovery:** Use ToolSearch to find specific tools. **Example:** `ToolSearch("ssh upload")` finds SSH upload tools. +## Your Available Skills + +### Primary Skills (Your Domain) +✓ **/seo-audit** - Auditoria SEO completa com dados reais via OpenSEO (crawl, GSC, SERP, backlinks) + - Invoke: `/seo-audit` + +✓ **/seo-report** - Relatório SEO para cliente com OpenSEO, exportado para Google Docs + - Invoke: `/seo-report` + +### Recommended for seo +- **/seo-content-optimization** - Optimização SEO técnico e conteúdo - meta tags, structured d +- **/wp-performance** - Auditoria de performance WordPress - cache, GZIP, imagens, p +- **/server-health** - Diagnóstico completo de servidor - CPU, RAM, MySQL, Web, SSL + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /lead-approach, /orcamento, /saas, /content-marketing-pt, /remotion-video, /social-media, /video, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /crm-admin, /db-design, /elementor, /mcp-dev, /nextjs, /php-dev, /react-patterns, /woocommerce, /wp-dev, /backup-strategies, /security-audit, /wp-update, /second-brain-repo, /ads, /doc-sync, /marketing-strategy, /product, /skill-creator, /sop-creator, /calendar-manager, /delegate, /interview, /time, /today, /research, /youtube, /archive, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. +## Your Team & Responsibilities + +You are part of **7 SDKs** (TaskForce teams): + +### TaskForce Claude Agents + +**Purpose:** NULL + +**Your responsibilities in this TaskForce:** +### TaskForce Conteúdo + +**Purpose:** NULL + +### TaskForce E-commerce + +**Purpose:** NULL + +### TaskForce Marketing Estratégico + +**Purpose:** NULL + +### TaskForce SEO + +**Purpose:** NULL + +### TaskForce WooCommerce + +**Purpose:** NULL + +### TaskForce YouTube + +**Purpose:** NULL + +**Collaboration:** +- Work with other agents in your TaskForce teams +- Share knowledge and context across team members +- Leverage team-specific skills and MCPs +- Contribute to team goals and deliverables + diff --git a/marketing/agents/social-media-manager.md b/marketing/agents/social-media-manager.md index 847c28f..da237f5 100644 --- a/marketing/agents/social-media-manager.md +++ b/marketing/agents/social-media-manager.md @@ -11,6 +11,8 @@ model: sonnet tools: Read, Write, Edit, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 - google-workspace @@ -26,7 +28,6 @@ skills: - marketing-strategy - ads desk_task: 1520 -layer: wiki --- # Social Media Manager Descomplicar @@ -126,4 +127,47 @@ mcp__notebooklm__notebook_query notebook_id:"081ca512-8279-4850-b2b9-dff09026748 - **youtube-uploader** - Upload vídeos YouTube - **pixabay** - Pesquisa imagens e vídeos stock gratuitos - **pexels** - Pesquisa imagens stock de alta qualidade -- **tavily** - AI-powered search API - web search optimi \ No newline at end of file +- **tavily** - AI-powered search API - web search optimizado para LLMs +- **** - Knowledge base AI +- **mem0** - Mem0 (Tier 2, `mcp__mem0__*`) + IJFW (Tier 1, automático via hooks) +- **elevenlabs** - Text-to-speech, voice cloning, audio transcription +- **vimeo** - Video management - upload, metadata, transcripts, analytics +- **replicate** - AI models - imagem, vídeo, áudio, LLMs + +### All Available (32 total) +moloni, context7, gitea, n8n, cwp, filesystem, ssh-unified, imap, outline-api, gsc, lighthouse, mcp-time, puppeteer, mcp-mermaid, mcp-echarts, powerpoint, penpot, magic, design-systems + +**Discovery:** Use ToolSearch to find specific tools. +**Example:** `ToolSearch("ssh upload")` finds SSH upload tools. +## Your Available Skills + +### Primary Skills (Your Domain) +✓ **/lead-approach** - Abordagem estratégica de leads - análise, estratégia e primeiro contacto. Usar q + - Invoke: `/lead-approach` + +✓ **/marketing-strategy** - Estratégia de marketing digital integrada - análise mercado, posicionamento, mix + - Invoke: `/marketing-strategy` + +✓ **/ads** - Gestão de campanhas de publicidade paga (PPC) - Google Ads, Meta Ads, LinkedIn A + - Invoke: `/ads` + +### Recommended for marketing +- **/social-media** - Gestão e estratégia de redes sociais - Instagram, LinkedIn, +- **/content-marketing-pt** - Criação de conteúdo marketing em Português Europeu. Tom de v +- **/seo-content-optimization** - Optimização SEO técnico e conteúdo - meta tags, structured d +- **/youtube** - Extrair transcrições e metadados do YouTube + Estratégia cre +- **/research** - Pesquisa profunda e análise competitiva - SWOT, Porter's Fiv + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /orcamento, /saas, /remotion-video, /video, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /crm-admin, /db-design, /elementor, /mcp-dev, /nextjs, /php-dev, /react-patterns, /woocommerce, /wp-dev, /backup-strategies, /security-audit, /server-health, /wp-performance, /wp-update, /second-brain-repo, /doc-sync, /product, /skill-creator, /sop-creator, /calendar-manager, /delegate, /interview, /time, /today, /seo-audit, /seo-report, /archive, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. + diff --git a/marketing/agents/video-production-specialist.md b/marketing/agents/video-production-specialist.md index ecd6ab8..ff6f705 100644 --- a/marketing/agents/video-production-specialist.md +++ b/marketing/agents/video-production-specialist.md @@ -10,6 +10,8 @@ model: sonnet tools: Read, Write, Edit, Bash, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 - filesystem @@ -41,7 +43,6 @@ compliance: created: '2025-01-13' updated: '2026-02-04' author: Descomplicar® -layer: wiki --- # Video Production Specialist Descomplicar @@ -139,11 +140,38 @@ mcp__notebooklm__notebook_query notebook_id:"081ca512-8279-4850-b2b9-dff09026748 - **replicate** - AI models - imagem, vídeo, áudio, LLMs ### All Available (32 total) -desk-crm-v3, moloni, context7, gitea, n8n, cwp, filesystem, ssh-unified, google-analytics, imap, wikijs, gsc, lighthouse, mcp-time, mem0, puppeteer, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, magic, design-systems +desk-crm-v3, moloni, context7, gitea, n8n, cwp, filesystem, ssh-unified, google-analytics, imap, gsc, lighthouse, mcp-time, mem0, puppeteer, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, magic, design-systems **Discovery:** Use ToolSearch to find specific tools. **Example:** `ToolSearch("ssh upload")` finds SSH upload tools. ## Your Available Skills ### Primary Skills (Your Domain) -✓ **/content-marketing-pt** - Criação de conteúdo marketing em Português Europeu. Tom de voz, copy \ No newline at end of file +✓ **/content-marketing-pt** - Criação de conteúdo marketing em Português Europeu. Tom de voz, copywriting, est + - Invoke: `/content-marketing-pt` + +✓ **/video** - Criar vídeos programáticos com Remotion e React. Gera intros, promos, social med + - Invoke: `/video` + +✓ **/youtube** - Extrair transcrições e metadados do YouTube + Estratégia crescimento canal. Supo + - Invoke: `/youtube` + +### Recommended for content +- **/social-media** - Gestão e estratégia de redes sociais - Instagram, LinkedIn, +- **/remotion-video** - Create and edit Remotion videos with domain-specific knowled +- **/seo-content-optimization** - Optimização SEO técnico e conteúdo - meta tags, structured d +- **/research** - Pesquisa profunda e análise competitiva - SWOT, Porter's Fiv + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /lead-approach, /orcamento, /saas, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /crm-admin, /db-design, /elementor, /mcp-dev, /nextjs, /php-dev, /react-patterns, /woocommerce, /wp-dev, /backup-strategies, /security-audit, /server-health, /wp-performance, /wp-update, /second-brain-repo, /ads, /doc-sync, /marketing-strategy, /product, /skill-creator, /sop-creator, /calendar-manager, /delegate, /interview, /time, /today, /seo-audit, /seo-report, /archive, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. + diff --git a/marketing/agents/youtube-specialist.md b/marketing/agents/youtube-specialist.md index d9ca547..44b565c 100644 --- a/marketing/agents/youtube-specialist.md +++ b/marketing/agents/youtube-specialist.md @@ -10,6 +10,8 @@ model: sonnet tools: Read, Write, Edit, Glob, Grep, ToolSearch # Dependencies +# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube +# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. primary_mcps: - desk-crm-v3 - youtube-research @@ -38,7 +40,6 @@ compliance: created: '2025-01-13' updated: '2026-02-04' author: Descomplicar® -layer: wiki --- # YouTube Specialist Descomplicar @@ -148,4 +149,44 @@ mcp__notebooklm__notebook_query notebook_id:"081ca512-8279-4850-b2b9-dff09026748 ### Recommended for content - **youtube-uploader** - Upload vídeos YouTube -- **elevenlabs** - Text-to-speech, voice cloning, audio transcription \ No newline at end of file +- **elevenlabs** - Text-to-speech, voice cloning, audio transcription +- **vimeo** - Video management - upload, metadata, transcripts, analytics +- **outline-api** - Outline documentation +- **replicate** - AI models - imagem, vídeo, áudio, LLMs + +### All Available (32 total) +desk-crm-v3, moloni, context7, gitea, n8n, cwp, filesystem, ssh-unified, google-analytics, imap, gsc, lighthouse, mcp-time, mem0, puppeteer, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, tavily, magic, design-systems + +**Discovery:** Use ToolSearch to find specific tools. +**Example:** `ToolSearch("ssh upload")` finds SSH upload tools. +## Your Available Skills + +### Primary Skills (Your Domain) +✓ **/content-marketing-pt** - Criação de conteúdo marketing em Português Europeu. Tom de voz, copywriting, est + - Invoke: `/content-marketing-pt` + +✓ **/video** - Criar vídeos programáticos com Remotion e React. Gera intros, promos, social med + - Invoke: `/video` + +✓ **/youtube** - Extrair transcrições e metadados do YouTube + Estratégia crescimento canal. Supo + - Invoke: `/youtube` + +### Recommended for content +- **/social-media** - Gestão e estratégia de redes sociais - Instagram, LinkedIn, +- **/remotion-video** - Create and edit Remotion videos with domain-specific knowled +- **/seo-content-optimization** - Optimização SEO técnico e conteúdo - meta tags, structured d +- **/research** - Pesquisa profunda e análise competitiva - SWOT, Porter's Fiv + +### Core Skills (All Agents) +- **/reflect** - Auto-reflexão e melhoria contínua do sistema. Analisa sessõe +- **/worklog** - Registo automático de trabalho - tarefas, problemas, soluçõe +- **/_core** - Padrões fundamentais Descomplicar® - Sacred Rules, Excellenc +- **/knowledge** - Gestão unificada de conhecimento - pesquisa inteligente com +- **/desk** - Integração com Desk CRM via ficheiro .desk-project. Auto-det + +### All Available (53 total) +/billing-check, /crm-ops, /ecommerce, /lead-approach, /orcamento, /saas, /ui-ux-pro-max-repo, /brand-voice-generator, /frontend-design, /pptx-generator, /ui-ux-pro-max, /crm-admin, /db-design, /elementor, /mcp-dev, /nextjs, /php-dev, /react-patterns, /woocommerce, /wp-dev, /backup-strategies, /security-audit, /server-health, /wp-performance, /wp-update, /second-brain-repo, /ads, /doc-sync, /marketing-strategy, /product, /skill-creator, /sop-creator, /calendar-manager, /delegate, /interview, /time, /today, /seo-audit, /seo-report, /archive, /metrics, /sdk + +**Discovery:** Use the Skill tool to invoke skills. +**Example:** `Skill("skill-name")` invokes the skill. + diff --git a/marketing/skills/ads/SKILL.md b/marketing/skills/ads/SKILL.md index f2c0275..7446eaf 100644 --- a/marketing/skills/ads/SKILL.md +++ b/marketing/skills/ads/SKILL.md @@ -1,7 +1,6 @@ --- name: ads description: Criação e gestão de campanhas Google Ads para o mercado português. Campanhas segmentadas com pesquisa de palavras-chave e copy de anúncios. -layer: wiki --- # /ads @@ -180,4 +179,306 @@ Campanha: [Produto] - [Objectivo] - Meta └── ... ``` --- \ No newline at end of file +--- + +## 💰 Orçamento e Bidding 2026 + +### Orçamento Inicial Recomendado + +| Objectivo | Orçamento Mínimo | Fase | +|-----------|------------------|------| +| **Teste (Learning)** | €500-€1.000/mês | Primeiras 2-4 semanas | +| **Escala** | €2.000-€5.000/mês | Após encontrar winners | +| **Performance** | €5.000+/mês | Optimização contínua | + +### Alocação Orçamento (Regra 70/20/10) + +``` +70% → Proven campaigns (ROAS > 3x, consistente) +20% → Scaling winners (aumentar budget top performers) +10% → Testing new (audiências, criativos, keywords) +``` + +### Estratégias Bidding Google Ads 2026 + +| Estratégia | Uso | Quando Usar | +|------------|-----|-------------| +| **Maximize Conversions** | Obter max conversões dentro do budget | Início (learning) | +| **Target CPA** | Manter custo por conversão fixo | Após 30+ conversões/mês | +| **Target ROAS** | Maximizar receita | E-commerce, tracking revenue | +| **Maximize Clicks** | Tráfego (não conversões) | Awareness, tráfego blog | +| **Target Impression Share** | Aparecer em posições específicas | Branding, concorrência | + +**Recomendação 2026:** Smart Bidding (Target CPA/ROAS) > Manual CPC. Machine learning é superior. + +--- + +## 📊 Métricas Chave + +### Performance Metrics + +| Métrica | Fórmula | Benchmark Google | Benchmark Meta | +|---------|---------|------------------|----------------| +| **CTR** | Clicks / Impressions | Search: 3-5%, Display: 0.5% | Feed: 1-3%, Stories: 0.5-1.5% | +| **CPC** | Cost / Clicks | €0.50-€3.00 (search) | €0.20-€1.50 | +| **CPM** | Cost / 1000 Impressions | €5-€15 | €5-€15 | +| **CPA** | Cost / Conversions | Depende produto (€10-€100) | €5-€50 | +| **ROAS** | Revenue / Ad Spend | > 3x bom, > 5x excelente | > 3x bom | +| **CVR** | Conversions / Clicks | 2-5% | 1-4% | + +### Métricas por Funil + +| Fase Funil | Métrica Primária | Target | +|------------|------------------|--------| +| **Awareness (ToFu)** | CPM, Reach | CPM < €10 | +| **Consideration (MoFu)** | CTR, CPC | CTR > 2% | +| **Conversion (BoFu)** | CPA, ROAS | CPA < €50, ROAS > 3x | +| **Retention** | LTV/CAC | LTV/CAC > 3x | + +--- + +## 🎯 Optimização Contínua + +### Google Ads Search + +```markdown +**Semanal:** +- [ ] Adicionar negative keywords (search terms report) +- [ ] Pausar ads com CTR < 2% +- [ ] Aumentar bids keywords top performers +- [ ] Testar novos ad copy (2 variações) + +**Mensal:** +- [ ] Analisar Quality Score (target > 7/10) +- [ ] Optimizar landing pages (velocidade, relevância) +- [ ] Adicionar extensões novas (seasonal) +- [ ] Review conversions por dispositivo (mobile vs desktop) + +**Trimestral:** +- [ ] Reestruturar campanhas underperforming +- [ ] Testar novos match types +- [ ] Expandir para Display/YouTube se ROAS Search > 4x +``` + +### Meta Ads + +```markdown +**Diário (primeiros 7 dias learning):** +- [ ] Verificar spending (não pausar durante learning) +- [ ] Monitorizar CPA (não optimizar antes 50 conversões) + +**Semanal:** +- [ ] Duplicar ad sets winning (escalar) +- [ ] Pausar ads CTR < 1% ou CPA > 2x target +- [ ] Testar 2-3 novos criativos +- [ ] Refresh audiências (adicionar lookalikes) + +**Mensal:** +- [ ] Analisar Breakdown (age, gender, placement) +- [ ] Optimizar landing page (mobile-first) +- [ ] Criar custom audience novos converters +- [ ] Testar novos formatos (Reels, Carousel) +``` + +--- + +## 🎨 Criativos que Convertem + +### Google Search Ads (RSAs) + +```markdown +**Headlines (15 slots):** + +Slot 1-3 (SEMPRE aparecem): Keyword + Benefício +"Painéis Solares Portugal | Poupança 60%" +"Instalação Solar | Desde 4.500€" +"Energia Solar | 0€ Investimento Inicial" + +Slot 4-8: Diferenciadores + USPs +"Certificado DGEG | Garantia 25 Anos" +"Financiamento 120 Meses | Aprovação 24h" + +Slot 9-12: CTAs + Urgência +"Pedir Orçamento Gratuito" +"Instalar em 30 Dias" + +Slot 13-15: Social Proof +"500+ Instalações Portugal" +"Avaliação 4.9★ Google" + +**Descriptions (4 slots):** +- Benefício principal + CTA (80 chars) +- USPs bullets (80 chars) +- Objecções + garantia (80 chars) +- Urgência + CTA (80 chars) +``` + +### Meta Ads (Imagem/Vídeo) + +```markdown +**Estrutura Criativo:** + +1. **Visual (80% sucesso)** + - Imagem/vídeo alta qualidade + - Rosto humano (aumenta CTR 30%) + - Cores contrastantes (destaca em feed) + - Texto on-image < 20% (regra deprecada mas boa prática) + +2. **Primary Text (Hook)** + Primeira linha CRÍTICA (preview mostra 125 chars) + "Empresas portuguesas estão a poupar €5K/ano em electricidade." + +3. **Headline** + Benefício claro (40 chars) + "Poupa 60% Conta Luz | Orçamento Grátis" + +4. **Description** (Opcional) + Reforço benefício (30 chars) + "Instalação em 30 dias" + +5. **CTA Button** + - "Saber Mais" (ToFu) + - "Pedir Orçamento" (BoFu) + - "Enviar Mensagem" (Leads) +``` + +### Vídeo Ads (YouTube/Meta) + +```markdown +**Primeiros 3 Segundos:** +Hook visual + texto +"PARA. Estás a desperdiçar dinheiro." + +**3-10 Segundos:** +Problema + agitação +"Conta luz aumentou 40% em 2025. Sem solução?" + +**10-25 Segundos:** +Solução + benefício +"Painéis solares eliminam 95% da conta. Assim:" + +**25-30 Segundos:** +CTA + urgência +"Orçamento gratuito. Só hoje: Instalação 0€. Link descrição." + +**Duração Ideal:** +- Bumper (6s): Awareness +- In-stream skippable (15-30s): Conversão +- Meta Reels (15-30s): Engagement + conversão +``` + +--- + +## ✅ Checklist Pré-Lançamento + +### Google Ads + +- [ ] Pixel instalado e testado (conversões a registar) +- [ ] Negative keywords lista (min 50) +- [ ] Landing page optimizada (load < 3s, mobile-first) +- [ ] UTMs configurados (tracking correcto) +- [ ] Conversion tracking validado (test conversion) +- [ ] Extensions todas configuradas (min 4 sitelinks) +- [ ] Orçamento definido (min €20/dia Search PT) +- [ ] Bidding strategy escolhida (Smart Bidding se > 30 conv/mês histórico) +- [ ] Ad copy 3 variações por ad group +- [ ] Campanhas Brand separadas (proteger marca) + +### Meta Ads + +- [ ] Pixel instalado (events: ViewContent, AddToCart, Purchase) +- [ ] Conversions API configurada (CAPI - bypass iOS 14) +- [ ] Domínio verificado (Meta Business Manager) +- [ ] Criativos aprovados (3-5 por ad set) +- [ ] Copy variações (2-3 per criativo) +- [ ] Audiências criadas (Custom, Lookalike) +- [ ] Landing page optimizada (mobile 80% tráfego) +- [ ] Orçamento definido (min €10/dia, €20/dia recomendado) +- [ ] Placement strategy (Advantage+ ou manual sem Audience Network) + +--- + +## 📚 Datasets Dify (Consultar SEMPRE) + +| Dataset | ID | Prioridade | Uso | +|---------|----|-----------:|-----| +| **Marketing Digital** | `c1ec779f-4cb1-4ecf-ba11-6b39b93d4e24` | 1 | Estratégia ads, métricas | +| **Marketing Redes Sociais** | `66117552-348f-455d-9aca-2da722567693` | 2 | Meta Ads, criativos | +| **Neil Patel** | `6ff761b3-a054-435c-8fc3-a6e6c3a0afaf` | 3 | PPC strategies | + +### Como Consultar + +```javascript +// Optimização Google Ads +mcp__notebooklm__notebook_query, mcp__dify-kb__dify_kb_retrieve_segments({ + dataset_id: "c1ec779f-4cb1-4ecf-ba11-6b39b93d4e24", + query: "google ads optimization ROAS CPA bidding 2026" +}) + +// Meta Ads criativos +mcp__dify-kb__dify_kb_retrieve_segments({ + dataset_id: "66117552-348f-455d-9aca-2da722567693", + query: "facebook ads creative testing CTR conversion" +}) + +// PPC strategies +mcp__dify-kb__dify_kb_retrieve_segments({ + dataset_id: "6ff761b3-a054-435c-8fc3-a6e6c3a0afaf", + query: "ppc campaigns keywords optimization" +}) +``` + +--- + +## 🎯 Agente Complementar +- `ppc-specialist` (agente especializado) + +--- + +**Versão:** 2.0.0 | **Autor:** Descomplicar® | **Data:** 2026-02-03 +**Standards:** Smart Bidding 2026, Advantage+ Audiences, ROAS > 3x + +--- + + +## Quando NÃO Usar + +- Para tarefas fora do domínio de especialização desta skill +- Quando outra skill mais específica está disponível +- Para operações que requerem confirmação manual do utilizador + + +## Protocolo + +1. Analisar requisitos da tarefa +2. Verificar disponibilidade de ferramentas necessárias +3. Executar operações de forma incremental +4. Validar resultados antes de concluir +5. Reportar status e próximos passos + + +## Exemplos + +### Exemplo 1: Uso Básico +``` +Input: [descrição da tarefa] +Output: [resultado esperado] +``` + +### Exemplo 2: Uso Avançado +``` +Input: [caso complexo] +Output: [resultado detalhado] +``` + +--- + +## 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/marketing/skills/brand-voice-generator b/marketing/skills/brand-voice-generator new file mode 120000 index 0000000..b22694d --- /dev/null +++ b/marketing/skills/brand-voice-generator @@ -0,0 +1 @@ +/home/ealmeida/.claude/skills/second-brain-repo/.claude/skills/brand-voice-generator \ No newline at end of file diff --git a/marketing/skills/content-marketing-pt/SKILL.md b/marketing/skills/content-marketing-pt/SKILL.md index 9cbd2ea..2e705e0 100644 --- a/marketing/skills/content-marketing-pt/SKILL.md +++ b/marketing/skills/content-marketing-pt/SKILL.md @@ -1,7 +1,6 @@ --- name: content-marketing-pt description: Criacao de conteudo de marketing profissional em portugues europeu com standards actuais. -layer: wiki --- # Content Marketing PT-PT @@ -144,4 +143,110 @@ Anatomia: [Verbo Accao] + [Beneficio Imediato] + [Reducao Friccao] | **LinkedIn** | 150-300 chars | Profissional, insights | 3-5 | | **Instagram** | 100-150 chars | Inspiracional, visual | 10-15 | | **Facebook** | 40-80 chars | Conversacional | 1-3 | -| **Twitter/X** \ No newline at end of file +| **Twitter/X** | 100-280 chars | Directo, opinioes | 1-2 | + +--- + +## Checklist Pre-Publicacao + +### Tecnico (SEO) +- [ ] Portugues europeu validado (zero brasileirismos) +- [ ] Keyword principal no titulo (primeiros 60 chars) +- [ ] Meta description optimizada (150-160 chars) +- [ ] Headings hierarquicos (H1 unica, H2-H6 logicos) +- [ ] Alt text descritivo em todas as imagens +- [ ] Internal links (3-5 relevantes) +- [ ] External links autoritativos (1-3, DR > 40) + +### Conteudo (Qualidade) +- [ ] Headlines com beneficio claro +- [ ] Paragrafos curtos (< 4 linhas) +- [ ] Listas para informacao complexa +- [ ] Exemplos praticos / casos reais +- [ ] Dados/estatisticas (com fontes) +- [ ] FAQ section (min 3 perguntas) + +### Conversao (CTA) +- [ ] CTA especifico e accionavel +- [ ] Beneficio imediato claro +- [ ] Reducao friccao (sem cartao, gratuito, etc.) + +### E-E-A-T (Trust) +- [ ] Autor identificado (nome + foto) +- [ ] Bio autor (credenciais + experiencia) +- [ ] Data publicacao + ultima actualizacao +- [ ] Fontes citadas (links externos) + +--- + +## References (conteudo detalhado) + +| Ficheiro | Conteudo | +|----------|----------| +| `references/vocabulario-br-pt.md` | Tabela completa de conversao BR -> PT-PT | +| `references/templates-conteudo.md` | Templates artigo blog, email promocional, landing page | +| `references/copywriting-patterns.md` | Headlines, CTAs, storytelling, persuasao etica, CRO | + +--- + +## Anti-Patterns + +- Usar brasileirismos em conteudo PT-PT +- CTAs vagos como "Clique aqui" ou "Submeter" +- Paragrafos longos (> 4 linhas) em conteudo web +- Ignorar E-E-A-T (sem autor, sem datas, sem fontes) +- Headlines sem beneficio claro ou keyword +- Excesso de anglicismos quando existe equivalente PT + +--- + +**Versao**: 2.1.0 | **Autor**: Descomplicar + +--- + +## Media Bank (D7-MB-001) + +**Quando consultar:** antes de sugerir ou inserir imagens de suporte em artigos, ebooks, whitepapers ou landing pages. Reutilizar matéria-prima local é preferível a geração IA ou stock externo. + +**Workflow tentativa-primeiro:** + +1. Pesquisar via MCP `media-bank`: + ``` + mcp__media-bank__search_media( + query="", + type="image", + tema="", + orientation="landscape", + min_quality=7, + min_width=1200, + exclude_used_in_last_days=30, + limit=5 + ) + ``` +2. Avaliar candidatos por `description_en` + `quality_score`. +3. Se ≥1 adequado → usar `path_local`; derivar `alt` text a partir de `description_en` traduzido para PT-PT. +4. Se nenhum → fallback para geração IA. +5. Marcar uso: `mcp__media-bank__mark_used(asset_id, {type:"content-piece", ref:"", date:""})`. + +**Fallback REST** (se MCP indisponível): +```bash +SK=$(grep SERVICE_KEY /media/ealmeida/Dados/Hub/05-Projectos/Banco-Imagens-Videos/scripts/.env | cut -d= -f2) +curl -s "https://mem.descomplicar.pt/rest/v1/media_bank_assets?type=eq.image&orientation=eq.landscape&quality_score=gte.7&deleted_at=is.null&order=quality_score.desc&limit=5" \ + -H "apikey: $SK" -H "Authorization: Bearer $SK" +``` + +**Regra inviolável:** matéria-prima local. Usar como input para composição — NUNCA inserir o ficheiro raw directamente em publicação pública sem edição/contextualização. + +Ver `Hub/06-Operacoes/Procedimentos/D7-Tecnologia/MCP/PROC-Media-Bank.md` (D7-MB-001) para detalhes. + +--- + +## 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/marketing/skills/lead-approach/SKILL.md b/marketing/skills/lead-approach/SKILL.md index 9ca0f2e..9ed7e67 100644 --- a/marketing/skills/lead-approach/SKILL.md +++ b/marketing/skills/lead-approach/SKILL.md @@ -1,7 +1,6 @@ --- name: lead-approach description: Abordagem estratégica de leads com análise completa, estratégia de proposta e primeiro contacto. Lança agentes especializados em paralelo, consulta datasets Dify, cria proposta e actualiza CRM. -layer: wiki --- # Skill /lead-approach - Abordagem Estratégica de Leads @@ -203,4 +202,124 @@ mcp__desk-crm-v3__update_lead({ |---------|----|-----------| | Marketing Digital | `c1ec779f-4cb1-4ecf-ba11-6b39b93d4e24` | Estratégias, funil, leads | | Vendas | `a7ba6005-517c-41ab-ac5e-da1c1a1c62ef` | Técnicas fecho, objecções | -| Serviços Descomplicar | `bd65f36e-6004-4584-b478-129b2c21b4d2` \ No newline at end of file +| Serviços Descomplicar | `bd65f36e-6004-4584-b478-129b2c21b4d2` | Pacotes, preços | +| Websites | `c8489151-de94-42b2-8cee-c0b961cfac6d` | Funcionalidades | + +## Agentes Utilizados + +| Agente | Função | +|--------|--------| +| `marketing-planning-expert` | Estratégia, pacotes, diferenciação | +| `sales-manager` | Abordagem, templates, follow-up | + +## Outputs + +1. **Documento proposta** em `01-Projectos/Profissional/` +2. **Lead actualizado** no CRM com dados completos +3. **Template email** pronto a enviar +4. **Estratégia follow-up** documentada + +## Exemplos de Uso + +### Lead de abandono de formulário +``` +User: /lead-approach 215 +→ Busca lead #215 +→ Encontra ticket associado +→ Extrai dados do formulário +→ Lança agentes em paralelo +→ Cria proposta + estratégia abordagem +→ Documento: PRJ-EmpresaX-Proposta.md +→ Lead actualizado no CRM +``` + +### Exemplo 2: Lead por nome +``` +User: /lead-approach "Century 21" +→ Pesquisa leads com "Century 21" +→ Encontra match +→ Executa workflow completo +→ Consulta datasets Dify +→ Gera estratégia completa +``` + +### Exemplo 3: Interactivo +``` +User: /lead-approach +→ Pergunta: "Qual o lead? (ID ou nome empresa)" +→ Utilizador responde: "João Silva - TechStart" +→ Executa workflow +→ Agentes em paralelo (marketing + sales) +→ Resultado: documento + CRM actualizado +``` + +## Checklist de Execução + +- [ ] Lead identificado no CRM +- [ ] Dados completos extraídos +- [ ] Ticket associado verificado +- [ ] Empresa pesquisada (web, redes) +- [ ] Agente marketing lançado +- [ ] Agente sales lançado +- [ ] Datasets Dify consultados +- [ ] Documento proposta criado +- [ ] Lead actualizado no CRM +- [ ] Template email pronto + +## Referências + +- `03-Recursos/Procedimentos/PROC-CRM-Operacoes.md` +- `/media/ealmeida/Dados/GDrive/Cloud/Docs/Produtos_Servicos/tabela-geral.csv` +- Skill `/orcamento` para preços oficiais + +--- + +**Versão:** 1.0.0 | **Data:** 2026-01-28 + +--- + +## Instrumentação Automática + +Esta skill grava métricas automaticamente para análise PDCA. + +### Baseline + +| Métrica | Valor | +|---------|-------| +| Tempo baseline | 25 min | +| Tempo target | 12 min | +| Melhoria esperada | -52% | + +### Query para Gravar (executar no final) + +```sql +INSERT INTO tblskill_agent_metrics ( + type, name, duration_ms, status, staff_id, + kb_consulted, kb_cache_hit, tool_calls, project_id +) VALUES ( + 'skill', '/lead-approach', {DURACAO_MS}, '{STATUS}', 25, + {KB_CONSULTADO}, {CACHE_HIT}, {TOOL_CALLS}, {PROJECT_ID} +); +``` + +### Ver Métricas + +```bash +/metrics /lead-approach +``` + +--- + +**Versão**: 1.1.0 | **Data**: 2026-02-03 | **Instrumentação**: Activa + +--- + +## 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/marketing/skills/marketing-strategy/SKILL.md b/marketing/skills/marketing-strategy/SKILL.md index 5a9ec26..cbdc356 100644 --- a/marketing/skills/marketing-strategy/SKILL.md +++ b/marketing/skills/marketing-strategy/SKILL.md @@ -1,7 +1,6 @@ --- name: marketing-strategy description: Desenvolvimento de estrategia de marketing para PMEs portuguesas. Cria planos completos com mix de canais e alocacao de orcamento. -layer: wiki --- # /marketing-strategy diff --git a/marketing/skills/seo-audit/SKILL.md b/marketing/skills/seo-audit/SKILL.md index 5dc4ff9..3dd0f1a 100644 --- a/marketing/skills/seo-audit/SKILL.md +++ b/marketing/skills/seo-audit/SKILL.md @@ -1,175 +1,208 @@ --- name: seo-audit -description: Auditoria SEO completa com recomendacoes de optimizacao. Analisa SEO tecnico, conteudo, backlinks e desempenho. -layer: wiki +description: Auditoria SEO completa com dados reais via OpenSEO (crawl, Search Console, SERP, backlinks, keywords). Analisa SEO técnico, conteúdo, autoridade e desempenho, e prioriza por retorno. Usar quando "auditoria SEO", "audit", "analisar site", "Core Web Vitals", "Search Console", "striking distance", "porque não tenho tráfego". --- -# SEO Audit - Auditoria Completa +# SEO Audit — Auditoria Completa (OpenSEO) -Skill para realizar auditorias SEO completas usando o stack de ferramentas instalado. Best practices 2026. +Auditoria SEO com dados reais. **Motor único: OpenSEO** (`seo.descomplicar.pt`), que substituiu o stack antigo (SEO Tools API + Ahrefs + GSC MCP + Lighthouse MCP) — ver `references/ferramentas-api.md` para a tabela de migração. --- -## Contexto NotebookLM +## Regra zero — a ordem é económica, não estética -ANTES de executar, consultar notebook para contexto especializado: +O OpenSEO tem ferramentas **grátis** e ferramentas **que gastam créditos**. Executar pela ordem errada gasta dinheiro a produzir conclusões que as ferramentas grátis já davam. -| Notebook | ID | Consultar quando | -|----------|-----|-----------------| -| Marketing Digital PT | `4c595973` | Sempre | +| Fase | Ferramentas | Custo | Porquê nesta ordem | +|---|---|---|---| +| 1 | `get_search_console_performance`, `inspect_urls` | **grátis** | Dados de primeira mão. Diz o que já posiciona e quais páginas importam | +| 2 | `run_site_audit`, `get_audit_issues`, `get_audit_pages` | **grátis** | Estado técnico. O dimensionamento do crawl depende da fase 1 | +| 3 | `get_keyword_metrics` | pago (lote) | Hidrata até 700 keywords conhecidas de uma vez — a melhor relação valor/crédito | +| 4 | `get_ranked_keywords`, `get_domain_overview`, `get_backlinks_overview` | pago | Contexto competitivo | +| 5 | `get_serp_results`, `find_serp_competitors` | pago (~30-60/keyword) | Só nas keywords que sobreviveram à filtragem | -``` -mcp__notebooklm__notebook_query({ - notebook_id: "4c595973-ba10-420a-a3bf-e4389e424ad3", - query: "" -}) -``` - -**Procedimento relacionado:** `PROC-DMARC-Email-Entregabilidade.md` -- consultar quando a auditoria envolve email deliverability. +**Nunca começar pela fase 3 ou acima.** As fases 1-2 resolvem a maioria das auditorias sem gastar um crédito. --- -## Quando Usar +## Pré-voo obrigatório (3 verificações, 30 segundos) -- Auditar um site completo (tecnico + conteudo + performance) -- Verificar Core Web Vitals e ranking factors -- Analisar backlinks e autoridade de dominio -- Obter dados reais do Google Search Console -- Identificar oportunidades de optimizacao -- Comparar com concorrencia +``` +1. openseo → whoami → confirma ligação, org, modo +2. openseo → list_projects → obtém projectId E o mercado do projecto +3. confirmar mercado → PT = locationCode 2620, languageCode "pt" +``` + +**GATE — mercado.** Se o projecto estiver em `2840/en` (EUA/inglês, que é o default) e o cliente for português, **todas** as chamadas pagas devolvem dados do mercado errado. Ou se corrige o mercado do projecto, ou se passa `locationCode`/`languageCode` explicitamente em **cada** chamada. Um esquecimento = créditos gastos em lixo. + +> `locationCode: 2620` = Portugal — confirmado empiricamente (SERP devolve domínios `.pt`). Não inventar códigos: se houver dúvida, correr uma query de teste e validar pelos resultados. --- -## Google Updates 2026 +## Fase 1 — Search Console primeiro (grátis, é o mapa) -### Core Algorithm Updates +``` +openseo → get_search_console_performance + dimensions: ["query"] dateRange: "last_3_months" rowLimit: 1000 +openseo → get_search_console_performance + dimensions: ["page"] dateRange: "last_3_months" rowLimit: 1000 +``` -| Update | Data | Impacto | -|--------|------|---------| -| **Helpful Content Q1** | Jan 2026 | Penaliza conteudo AI de baixa qualidade | -| **Core Web Vitals 3.0** | Mar 2026 | INP substitui FID, thresholds mais rigorosos | -| **E-E-A-T Focus** | Q1-Q2 | Experiencia pratica obrigatoria | -| **Mobile-First Index** | Universal | 100% dos sites | +Paginar com `startRow` enquanto o cabeçalho disser `more available`. -### Novos Ranking Factors 2026 +### As três armadilhas do GSC -1. **INP (Interaction to Next Paint)** -- Bom: < 200ms | Medio: 200-500ms | Mau: > 500ms -2. **E-E-A-T** -- Autor identificado com bio, credenciais verificaveis, experiencia real -3. **Page Experience Signals** -- HTTPS obrigatorio, intrusive interstitials penalizados +**1. Vista por query ≠ vista por página.** O GSC anonimiza queries raras, por isso os totais por query são sempre **muito menores** que os totais por página. A vista por **página** é a real; usar essa para números globais. + +**2. O GSC não filtra por posição.** `striking distance` tem de ser filtrado do lado do cliente, depois de puxar as linhas. + +**3. Há lixo nas queries.** Colagens de relatórios do Google Ads, operadores `site:`, strings com mojibake. Filtrar antes de contar, ou as métricas mentem. + +```python +def is_noise(k): + return ('ativado' in k and 'correspond' in k) or k.startswith('-site:') \ + or k.startswith('=') or len(k) > 90 or '0,00' in k +``` + +### O que extrair + +| Métrica | Cálculo | Leitura | +|---|---|---| +| CTR global | cliques ÷ impressões (vista por página) | < 1% = problema de captação, não de ranking | +| Distribuição por posição | buckets 1-3 / 4-10 / 11-20 / 21-50 / 51+ | Impressões concentradas em 21+ = visibilidade inútil | +| Branded vs não-branded | queries com o nome da marca vs resto | Se só a marca converte, o SEO não está a trabalhar | +| **Striking distance** | pos 4-20 **e** impressões ≥ 25 | **É aqui que está o retorno** | +| Desperdício | pos > 40 **e** impressões ≥ 300 | Páginas com procura real enterradas | + +### O sinal mais accionável de todos + +**Posição 4-10 com CTR perto de 0%.** Não é problema de ranking — o site está na primeira página. É o **título e a meta description** a não convencerem. Cruzar esta lista com os issues `missing-meta-description` e `title-too-long` da fase 2: a intersecção é a lista de trabalho, por ordem. --- -## Workflow de Auditoria Completa - -### Passo 1: Analise Tecnica Basica (3 min) +## Fase 2 — Auditoria técnica (grátis) ``` -1. SEO Tools API -> /seo-audit -> Meta tags, headings, estrutura HTML -2. SEO Tools API -> /page-speed-analyzer -> Velocidade, sugestoes -3. Lighthouse -> run_audit -> Performance, SEO, Accessibility scores +openseo → run_site_audit + url: "" maxPages: runLighthouse: true +openseo → get_audit_status (poll até "completed") +openseo → get_audit_issues (severity: critical → warning → info) ``` -**Checklist Critico:** -- [ ] Meta title (50-60 chars) -- [ ] Meta description (150-160 chars) -- [ ] H1 unico com keyword -- [ ] Canonical URL definido -- [ ] Robots.txt acessivel -- [ ] Sitemap.xml presente -- [ ] HTTPS activo -- [ ] Mobile-friendly +### GATE — `maxPages` (o erro que cega a auditoria) -### Passo 2: Core Web Vitals (2 min) +**`maxPages` tem default 50.** Um site de 600 páginas auditado com o default devolve um relatório limpo e falso: descreve 8% do site e omite exactamente o hub de conteúdo que gera o tráfego. + +**Regra:** `maxPages` ≥ número de páginas com impressões no GSC (fase 1), com folga de ~25%. Por isso é que a fase 1 vem primeiro — é ela que dimensiona o crawl. + +> Caso real (descomplicar.pt, 07-2026): auditoria com default 50 → 25 URLs únicos, 92 issues, **zero críticos**, nenhuma das 119 páginas `/guia-*`. Relançada com `maxPages: 600` → **1337 issues, 9 críticos**. O relatório "limpo" descrevia 4% do site. + +### Prioridade dos issues + +| Severidade | Tipos | Acção | +|---|---|---| +| **critical** | `broken-internal-link`, `blocked-page`, `server-error`, `broken-page` | Corrigir já — sangram autoridade e crawl budget | +| **warning** | `missing-h1`, `missing-meta-description`, `duplicate-content`, `multiple-h1`, `duplicate-title` | Priorizar pelas páginas com impressões (fase 1) | +| **info** | `title-too-long`, `noindex-page`, `slow-response`, `heading-order-skip` | Lote; só vale a pena onde há procura | + +**Nunca tratar a lista de issues por ordem de contagem.** 300 metas em falta em páginas sem impressões valem menos que 6 em páginas na posição 8. A fase 1 é que ordena a fase 2. + +### Limitação conhecida — issues sem URL + +`get_audit_issues` e `get_audit_pages` devolvem **apenas contagens agregadas** através da bridge MCP. As linhas por URL vivem em `structuredContent.issues`, que a bridge não entrega; `get_audit_pages` trunca a listagem em ~25 linhas independentemente do `limit`. + +**Contorno:** o campo `details.mcpMeta.url` da resposta traz o link do relatório na UI. Entregar esse link ao humano para os URLs concretos: +``` +https://seo.descomplicar.pt/p//audit?auditId= +``` +Declarar esta limitação no relatório — não fingir que se verificaram URLs que não se viram. + +### Core Web Vitals por página + +`run_site_audit` com `runLighthouse: true` corre Lighthouse numa amostra (até 20 páginas). Para uma página específica, usar `chrome-devtools`: ``` -1. Lighthouse -> get_core_web_vitals -> LCP, INP, CLS (mobile + desktop) -2. Lighthouse -> compare_mobile_desktop -> Identificar gaps -3. Lighthouse -> get_lcp_opportunities -> Sugestoes optimizacao +chrome-devtools → lighthouse_audit (SEO, acessibilidade, best practices) +chrome-devtools → performance_start_trace (LCP, INP, CLS reais) ``` -**Thresholds 2026:** +**Thresholds 2026:** LCP < 2,5s · **INP** < 200ms · CLS < 0,1 +(INP substituiu o FID — se algum documento ainda disser FID, está desactualizado.) -| Metrica | Bom | Necessita Melhoria | Mau | -|---------|-----|-------------------|-----| -| **LCP** | < 2.5s | 2.5-4s | > 4s | -| **INP** | < 200ms | 200-500ms | > 500ms | -| **CLS** | < 0.1 | 0.1-0.25 | > 0.25 | +--- -### Passo 3: Analise de Conteudo (3 min) +## Fase 3 — Hidratar keywords (pago, lote) ``` -1. SEO Tools API -> /content-optimization -> On-page SEO, keyword density -2. SEO Tools API -> /internal-linking -> Estrutura links internos -3. SEO Ahrefs -> keyword_generator -> Keywords relacionadas, volume, KD +openseo → get_keyword_metrics + keywords: [] + locationCode: 2620 languageCode: "pt" ``` -**Checklist E-E-A-T:** -- [ ] Autor identificado com bio -- [ ] Credenciais verificaveis -- [ ] Data publicacao/actualizacao -- [ ] Fontes citadas (links externos autoritativos) -- [ ] Experiencia real demonstrada +Até **700 keywords numa só chamada** — volume, dificuldade (KD), intenção, CPC, tendência. É a forma barata de priorizar. Só depois disto se decide onde vale a pena competir. -### Passo 4: Backlinks e Autoridade (2 min) +Guardar o que sobreviver: `openseo → save_keywords` (grátis, idempotente). + +--- + +## Fase 4 — Contexto competitivo (pago) ``` -1. SEO Tools API -> /backlink-checker -> Backlinks basicos, DR/UR -2. SEO Ahrefs -> get_backlinks_list -> Lista detalhada (DR, anchor text) -3. SEO Ahrefs -> get_traffic -> Trafego estimado mensal -``` - -**Metricas Autoridade:** -- **DR (Domain Rating)**: 0-100 (forca backlink profile) -- **UR (URL Rating)**: 0-100 (forca pagina especifica) -- **Backlinks**: Quantidade + qualidade (DR > 30) -- **Referring Domains**: Numero de dominios unicos - -### Passo 5: Dados Reais GSC (3 min) - -``` -1. GSC -> get_search_analytics -> Queries, impressoes, CTR real (ultimos 90 dias) -2. GSC -> check_indexing_issues -> Problemas de indexacao -3. GSC -> get_sitemaps -> Status sitemaps submetidos -``` - -**Metricas GSC a Analisar:** -- **Impressoes vs Cliques**: CTR medio > 2% -- **Posicao media**: Top 3 para keywords principais -- **Cobertura**: % paginas indexadas vs submetidas -- **Mobile Usability**: Erros especificos mobile - -### Passo 6: Concorrencia (opcional, 2 min) - -``` -SEO Tools API -> /competitor-analysis -> Comparar com 2-3 concorrentes -- Keywords gap -- Backlinks gap -- Content gap +openseo → get_domain_overview (tráfego orgânico estimado, nº keywords, backlinks) +openseo → get_ranked_keywords (onde o domínio posiciona, por mercado) +openseo → get_backlinks_overview (~50 créditos por domínio) +openseo → get_backlinks_profile (linhas detalhadas: anchors, dofollow, spam) ``` --- -## Propriedades GSC Disponiveis +## Fase 5 — SERP (pago, por último) ``` -sc-domain:descomplicar.pt -https://emanuelalmeida.pt/ -https://carstuff.pt/ -https://solarfvengenharia.com/ -https://aquisevende.pt/ -https://alojadamaria.com/ -https://e-commerce.descomplicar.pt/ +openseo → get_serp_results (1-10 keywords por chamada, ~30-60 créditos cada) +openseo → find_serp_competitors (quem compete num conjunto de keywords) ``` +Ler a SERP como **estrutura**, não como lista: se o top-10 estiver cheio de directórios e artigos "melhores X", a intenção é comparativa e uma homepage não entra — é preciso uma página de comparação. Se estiver cheio de homepages de concorrentes, é disputa de marca. + +Local/Maps: `get_local_serp_results`, `search_local_businesses`, `get_google_business_questions`. + --- -## Notas Importantes +## Custos — o que sabemos e o que não sabemos -### Requisitos -- **SEO Tools API** deve estar a correr: `~/mcp-servers/seo-tools-api/start.sh` -- **GSC** requer autenticacao OAuth na primeira utilizacao -- **GA** requer ADC credentials configuradas +`whoami` **não expõe saldo de créditos** em modo self-hosted (verificado antes e depois de uma chamada paga: output idêntico). Os `~30-60 créditos/keyword` são a **estimativa do schema**, não uma medição. -### Limitacoes -- Ahrefs API tem rate limiting (100 req/day free tier) -- GSC data maxi \ No newline at end of file +**Consequência prática:** não há medidor no OpenSEO. O contador real vive na conta DataForSEO. Para lotes grandes, confirmar saldo aí primeiro. Nunca reportar custo consumido como facto — reportar como estimativa. + +--- + +## Anti-patterns + +- **Correr `run_site_audit` com o `maxPages` por omissão.** Produz relatórios limpos e falsos. +- **Começar por ferramentas pagas.** O GSC é grátis e responde a metade das perguntas. +- Usar totais por query como totais do site (o GSC anonimiza — usar a vista por página). +- Priorizar issues por contagem em vez de por impressões da página afectada. +- Correr chamadas pagas sem confirmar o mercado do projecto. +- Apresentar contagens de issues como se fossem URLs verificados. +- Auditar sem dados reais ou simular métricas. +- Recomendações sem prioridade (crítico/importante/melhoria) e sem esforço estimado. + +--- + +## References + +| Ficheiro | Conteúdo | +|---|---| +| `references/ferramentas-api.md` | Inventário OpenSEO completo + tabela de migração do stack antigo | +| `references/template-relatorio-auditoria.md` | Template do relatório com todas as secções e tabelas | + +--- + +**Versão:** 3.0.0 | **Autor:** Descomplicar® | **Motor:** OpenSEO + +## Healing Log + +```jsonl +{"date":"2026-07-30","issue":"Skill dependia de SEO Tools API (localhost:3000), Ahrefs MCP, GSC MCP e Lighthouse MCP — todos inexistentes ou desligados. Nenhum dos 6 passos era executável.","fix":"Reescrita completa sobre OpenSEO, com ordem por custo, gates de mercado e maxPages.","source":"auto"} +``` diff --git a/marketing/skills/seo-audit/references/ferramentas-api.md b/marketing/skills/seo-audit/references/ferramentas-api.md index 9252cc7..14af24f 100644 --- a/marketing/skills/seo-audit/references/ferramentas-api.md +++ b/marketing/skills/seo-audit/references/ferramentas-api.md @@ -1,75 +1,113 @@ -# Ferramentas e APIs - SEO Audit +# Ferramentas SEO — OpenSEO -## 1. SEO Tools API (http://localhost:3000) +Motor único do SEO Descomplicar®. Substituiu integralmente o stack anterior. +UI: `https://seo.descomplicar.pt` · Projecto default: `1e5ad4d6-a285-4fd3-9633-339abef4b6af` -```bash -# Auditoria basica -curl "http://localhost:3000/seo-audit?url=URL" +--- -# Velocidade PageSpeed Insights style -curl "http://localhost:3000/page-speed-analyzer?url=URL" +## 1. Migração — o que morreu e o que o substitui -# Backlinks + DR/UR -curl "http://localhost:3000/backlink-checker?url=URL" +O stack antigo desta skill (v2.1.0) apontava para quatro dependências. **Nenhuma está operacional** (verificado 30-07-2026): -# Rankings para keywords -curl "http://localhost:3000/rank-checker?url=URL&keywords=keyword1,keyword2" +| Dependência antiga | Estado real | Substituto OpenSEO | +|---|---|---| +| **SEO Tools API** `localhost:3000` | `~/mcp-servers/seo-tools-api/` **não existe em disco** | ver tabela abaixo | +| **Ahrefs MCP** | nunca esteve em nenhuma config MCP | `get_backlinks_*`, `get_domain_overview`, `get_keyword_metrics` | +| **GSC MCP** | em `disabledServers` | `get_search_console_performance`, `inspect_urls` | +| **Lighthouse MCP** | em `disabledServers` | `run_site_audit` (`runLighthouse`) ou `chrome-devtools` | -# Optimizacao conteudo on-page -curl "http://localhost:3000/content-optimization?url=URL" +### Endpoint a endpoint -# Internal linking structure -curl "http://localhost:3000/internal-linking?url=URL" +| Antigo | Novo | Nota | +|---|---|---| +| `/seo-audit` | `run_site_audit` + `get_audit_issues` | Atenção ao `maxPages` | +| `/page-speed-analyzer` | `run_site_audit` com `runLighthouse: true` | Amostra até 20 páginas | +| `/content-optimization` | `get_audit_issues` (`thin-content`, `title-*`, `meta-description-*`) | | +| `/internal-linking` | `get_audit_issues` (`orphan-page`, `broken-internal-link`, `no-outgoing-links`) | | +| `/backlink-checker` | `get_backlinks_overview` | | +| `/rank-checker` | `get_rank_tracker` (grátis) ou `get_ranked_keywords` (pago) | | +| `/competitor-analysis` | `find_serp_competitors` + `get_domain_overview` | | +| `/sitemap-generator` | **sem equivalente** | Usar plugin WP ou gerar à mão | +| Ahrefs `keyword_generator` | `research_keywords` (novas) / `get_keyword_metrics` (conhecidas) | | +| Ahrefs `get_backlinks_list` | `get_backlinks_profile` | | +| Ahrefs `get_traffic` | `get_domain_overview` | Estimado | +| Lighthouse `run_audit` | `chrome-devtools → lighthouse_audit` | Por página | +| Lighthouse `get_core_web_vitals` | `chrome-devtools → performance_start_trace` | LCP/INP/CLS reais | +| GSC `get_search_analytics` | `get_search_console_performance` | | +| GSC `check_indexing_issues` | `inspect_urls` | Até 10 URLs por chamada | +| GSC `get_sitemaps` | **sem equivalente** | Ver na UI do Search Console | -# Sitemap XML generator -curl "http://localhost:3000/sitemap-generator?url=URL" +--- -# Analise concorrencia -curl "http://localhost:3000/competitor-analysis?url=URL&competitors=site1.com,site2.com" -``` +## 2. Inventário OpenSEO (24 ferramentas) -## 2. Lighthouse MCP +### Grátis — não tocam no DataForSEO -| Tool | Funcao | Output | -|------|--------|--------| -| `run_audit(url)` | Auditoria completa | Performance, SEO, A11y, Best Practices | -| `get_performance_score(url)` | Score performance | 0-100 | -| `get_core_web_vitals(url)` | LCP, INP, CLS | Mobile + Desktop | -| `get_accessibility_score(url)` | Acessibilidade | 0-100 + issues | -| `get_seo_analysis(url)` | Analise SEO tecnico | Meta, headings, indexabilidade | -| `get_security_audit(url)` | Seguranca | HTTPS, mixed content, headers | -| `compare_mobile_desktop(url)` | Comparacao | Diferencas performance | -| `get_lcp_opportunities(url)` | Optimizacoes LCP | Preload, lazy load | -| `find_unused_javascript(url)` | JS nao usado | Tamanhos, % savings | +| Ferramenta | Função | +|---|---| +| `whoami` | Utilizador, org, modo, scopes. **Não mostra saldo em self-hosted** | +| `list_projects` | Projectos + `projectId` + mercado default | +| `create_project` | Novo projecto (nome, domínio, mercado) | +| `run_site_audit` | Crawl same-origin, robots-aware. `maxPages` **default 50** | +| `get_audit_status` | Progresso (fase, páginas, Lighthouse) | +| `get_audit_issues` | Relatório priorizado. Filtros `severity`/`issueType` | +| `get_audit_pages` | Páginas crawladas com dados SEO por página | +| `get_search_console_performance` | Search Analytics: cliques, impressões, CTR, posição | +| `inspect_urls` | URL Inspection do GSC (até 10 URLs): indexação, canónico | +| `get_rank_tracker` | Configs de rank tracking + último snapshot | +| `save_keywords` | Guardar keywords no projecto (idempotente) | +| `list_saved_keywords` | Keywords guardadas + métricas em cache | -## 3. SEO Ahrefs MCP (via API) +### Pagas — consomem créditos -| Tool | Funcao | Dados | -|------|--------|-------| -| `get_backlinks_list(domain)` | Lista backlinks | DR, UR, anchor text | -| `keyword_generator(keyword, country)` | Ideias keywords | Volume, KD, CPC | -| `get_traffic(domain)` | Trafego estimado | Visitas mensais, keywords | -| `keyword_difficulty(keyword)` | Dificuldade keyword | 0-100 (KD score) | +| Ferramenta | Custo aprox. | Função | +|---|---|---| +| `get_keyword_metrics` | lote | **Até 700 keywords/chamada**: volume, KD, intenção, CPC, tendência | +| `research_keywords` | ~30-100/seed | 1-5 seeds → ideias novas + métricas | +| `get_serp_results` | ~30-60/keyword | Google orgânico ao vivo, 1-10 keywords | +| `find_serp_competitors` | pago | Domínios que competem num conjunto de keywords | +| `get_ranked_keywords` | pago | Keywords onde um domínio posiciona, por mercado | +| `get_domain_overview` | pago | Tráfego orgânico, nº keywords, backlinks, ref. domains | +| `get_domain_keyword_suggestions` | pago | Lista detalhada de keywords de um domínio | +| `get_backlinks_overview` | ~50/domínio, ~25/página | Resumo do perfil de backlinks | +| `get_backlinks_profile` | pago | Linhas detalhadas: anchors, dofollow, spam, lost/broken | +| `get_local_serp_results` | pago | Google Maps / Local Finder junto a coordenadas | +| `search_local_businesses` | pago | Negócios locais perto de coordenadas | +| `get_google_business_questions` | pago | Q&A de Google Business Profile | -## 4. Google Search Console MCP +--- -| Tool | Funcao | Dados Reais | -|------|--------|-------------| -| `list_properties` | Listar sites verificados | URLs properties | -| `get_search_analytics(site, period)` | Queries, cliques, CTR | Ultimos 16 meses | -| `inspect_url_enhanced(site, url)` | Inspeccionar URL | Indexacao, mobile usability | -| `check_indexing_issues(site, urls)` | Problemas indexacao | Erros, avisos | -| `get_sitemaps(site)` | Listar sitemaps | Status, URLs submetidos | +## 3. Mercados -## 5. Google Analytics MCP +| Mercado | `locationCode` | `languageCode` | +|---|---|---| +| **Portugal** | `2620` | `pt` | +| EUA (default do projecto) | `2840` | `en` | -| Tool | Funcao | Metricas | -|------|--------|----------| -| `get_account_summaries` | Listar contas | Properties disponiveis | -| `run_report(property, metrics, dimensions)` | Relatorio custom | Sessions, users, bounce rate | -| `run_realtime_report(property)` | Tempo real | Utilizadores activos now | +`2620` = Portugal, confirmado empiricamente (SERP devolve domínios `.pt`). **Não inventar códigos** — validar sempre por uma query de teste. Referência oficial: `dataforseo.com/help-center/locations`. -## Propriedades GSC Disponiveis +**Aviso:** alguns países são servidos por dados do Google Ads — volume/CPC funcionam, mas KD, intenção e analytics de domínio não estão disponíveis. + +--- + +## 4. Limitações conhecidas (verificadas, não presumidas) + +1. **Issues sem URL.** `get_audit_issues` e `get_audit_pages` devolvem só contagens agregadas via bridge MCP. As linhas por URL vivem em `structuredContent.issues`, que a bridge não entrega. `get_audit_pages` trunca em ~25 linhas mesmo com `limit: 1000`. + → Contorno: `details.mcpMeta.url` traz o link do relatório na UI. + +2. **Sem medidor de créditos.** `whoami` em self-hosted devolve o mesmo output antes e depois de chamadas pagas. Os custos documentados são estimativas do schema. O contador real está na conta DataForSEO. + +3. **`maxPages` default 50.** A causa mais comum de auditorias falsamente limpas. + +4. **GSC anonimiza queries.** Totais por query são sempre inferiores aos totais por página. Usar a vista por página para números globais. + +5. **GSC não filtra por posição.** Striking distance filtra-se do lado do cliente. + +6. **Lag do GSC:** os últimos ~3 dias podem estar incompletos. Datas em Pacific Time. Máximo 16 meses de histórico. + +--- + +## 5. Propriedades Search Console disponíveis ``` sc-domain:descomplicar.pt @@ -81,14 +119,6 @@ https://alojadamaria.com/ https://e-commerce.descomplicar.pt/ ``` -## Requisitos +--- -- **SEO Tools API** deve estar a correr: `~/mcp-servers/seo-tools-api/start.sh` -- **GSC** requer autenticacao OAuth na primeira utilizacao -- **GA** requer ADC credentials configuradas (`gcloud auth application-default login`) - -## Limitacoes - -- Ahrefs API tem rate limiting (100 req/day free tier) -- GSC data maximo: 16 meses historico -- Lighthouse scores variam +/- 5 pontos entre execucoes (network dependent) +**Actualizado:** 30-07-2026 | Substitui a versão baseada em SEO Tools API + Ahrefs + GSC/Lighthouse MCP diff --git a/marketing/skills/seo-audit/references/template-relatorio-auditoria.md b/marketing/skills/seo-audit/references/template-relatorio-auditoria.md index dc71dff..64f72c6 100644 --- a/marketing/skills/seo-audit/references/template-relatorio-auditoria.md +++ b/marketing/skills/seo-audit/references/template-relatorio-auditoria.md @@ -183,11 +183,14 @@ H1: [Texto] OK --- ## Ferramentas Utilizadas -- SEO Tools API (localhost:3000) -- Lighthouse MCP -- SEO Ahrefs MCP -- Google Search Console MCP -- Google Analytics MCP (opcional) +- OpenSEO — crawl e issues (`run_site_audit`, `get_audit_issues`) +- OpenSEO — Search Console (`get_search_console_performance`) +- OpenSEO — keywords e SERP (`get_keyword_metrics`, `get_serp_results`) +- OpenSEO — autoridade (`get_backlinks_overview`, `get_domain_overview`) +- chrome-devtools — Core Web Vitals por página (opcional) + +**Cobertura do crawl**: [N páginas crawladas] de [M páginas com impressões no GSC] +**Chamadas pagas**: [listar] — custo estimado, não medido (OpenSEO não expõe saldo) --- diff --git a/marketing/skills/seo-content-optimization/SKILL.md b/marketing/skills/seo-content-optimization/SKILL.md index ab510eb..57c34e0 100644 --- a/marketing/skills/seo-content-optimization/SKILL.md +++ b/marketing/skills/seo-content-optimization/SKILL.md @@ -1,7 +1,6 @@ --- name: seo-content-optimization description: Optimizacao de conteudo para motores de busca. Melhora conteudo existente com palavras-chave, estrutura e legibilidade. -layer: wiki --- # SEO Content Optimization @@ -162,8 +161,100 @@ mcp__notebooklm__notebook_query({ ## Ferramentas Recomendadas -### Validacao +### No stack (usar primeiro — são estes que temos) -- **Google Search Console** - Monitorizacao, indexacao -- **PageSpeed Insights** - Core Web Vitals -- **Schema Validator** \ No newline at end of file +| Necessidade | Ferramenta OpenSEO | Custo | +|---|---|---| +| Monitorização, indexação | `get_search_console_performance`, `inspect_urls` | grátis | +| Auditoria técnica completa | `run_site_audit` → `get_audit_issues` | grátis | +| Conteúdo fino, títulos, metas | `get_audit_issues` (`thin-content`, `title-*`, `meta-description-*`) | grátis | +| Keyword research | `get_keyword_metrics` (conhecidas) / `research_keywords` (novas) | pago | +| Backlinks | `get_backlinks_overview`, `get_backlinks_profile` | pago | +| Core Web Vitals | `chrome-devtools → performance_start_trace` | grátis | + +Inventário e tabela de migração: `../seo-audit/references/ferramentas-api.md` + +### Externas (validação manual) + +- **Schema Validator** — testar structured data (schema.org/validator) +- **Rich Results Test** — Google rich results +- **Mobile-Friendly Test** — Google mobile test +- **AnswerThePublic** — long-tail questions +- **Google Trends** — sazonalidade de keywords + +### Optimizacao + +- **TinyPNG/Squoosh** - Comprimir imagens +- **Cloudflare** - CDN, cache +- **WP Rocket/Autoptimize** - WordPress performance + +--- + +## Checklist Pre-Publicacao + +### Tecnico + +- [ ] Title tag optimizado (50-60 chars, keyword inicio) +- [ ] Meta description unica (150-160 chars, CTA) +- [ ] H1 unico com keyword principal +- [ ] Imagens com alt text descritivo +- [ ] URL amigavel (< 60 chars, keyword) +- [ ] Canonical definido +- [ ] Open Graph configurado (title, description, image) +- [ ] Schema.org implementado (Article/FAQPage) +- [ ] Mobile-friendly (test Google) +- [ ] HTTPS activo +- [ ] Core Web Vitals green (LCP, INP, CLS) + +### Conteudo + +- [ ] > 1200 palavras (topics competitivos) +- [ ] Keyword density 1-2% +- [ ] 2-3 internal links relevantes +- [ ] 1-2 external links autoritativos (DR > 40) +- [ ] Autor identificado + bio +- [ ] Data publicacao visivel +- [ ] Experiencia real demonstrada +- [ ] FAQ section (min 3 perguntas) + +### Engagement + +- [ ] CTA claro e visivel +- [ ] Formulario/contacto (se aplicavel) +- [ ] Social share buttons +- [ ] Imagens optimizadas (< 200KB, WebP) +- [ ] Video embed (se relevante) + +--- + +## Referencias Detalhadas + +Para conteudo tecnico detalhado, consultar: + +- [references/structured-data.md](references/structured-data.md) - Meta tags completas, Schema.org (Organization, Article, FAQ, HowTo, Product), Core Web Vitals (LCP, INP, CLS com codigo), URL structure, Keyword Research com benchmarks + +--- + +## Protocolo de Execucao + +1. **Analise Inicial** - Verificar requisitos e contexto +2. **Preparacao** - Validar acesso a recursos +3. **Execucao** - Operacoes incrementais com validacao +4. **Validacao** - Verificar resultados obtidos +5. **Conclusao** - Documentar alteracoes e proximos passos + +--- + +**Standards:** Google 2026 (E-E-A-T, INP, Helpful Content) + +--- + +## 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/marketing/skills/seo-content-optimization/references/structured-data.md b/marketing/skills/seo-content-optimization/references/structured-data.md index daa1e46..9b509e0 100644 --- a/marketing/skills/seo-content-optimization/references/structured-data.md +++ b/marketing/skills/seo-content-optimization/references/structured-data.md @@ -249,13 +249,16 @@ https://site.pt/este-url-e-muito-longo-com-muitas-palavras-desnecessarias/ ### Ferramentas -| Ferramenta | Uso | Métricas | -|------------|-----|----------| -| Google Keyword Planner | Volume, CPC | Volume mensal, competição | -| Ahrefs | KD, SERP analysis | Keyword Difficulty, DR necessário | -| Semrush | Concorrência | Gap analysis, trending | -| AnswerThePublic | Long-tail questions | Questões reais utilizadores | -| Google Trends | Sazonalidade | Tendência temporal | +| Ferramenta | Uso | Métricas | Custo | +|------------|-----|----------|-------| +| **OpenSEO** `get_keyword_metrics` | Hidratar até 700 keywords conhecidas | Volume, KD, intenção, CPC, tendência | pago (lote) | +| **OpenSEO** `research_keywords` | Descobrir keywords novas (1-5 seeds) | Volume, KD, ideias relacionadas | pago (~30-100/seed — estimativa do schema, não medida) | +| **OpenSEO** `get_search_console_performance` | O que já posiciona (dados próprios) | Cliques, impressões, CTR, posição | **grátis** | +| **OpenSEO** `get_ranked_keywords` | Keywords de um domínio (nosso ou concorrente) | Posição, volume, tráfego | pago | +| AnswerThePublic | Long-tail questions | Questões reais de utilizadores | grátis | +| Google Trends | Sazonalidade | Tendência temporal | grátis | + +**Ordem obrigatória:** Search Console primeiro (grátis e são dados de primeira mão), só depois as pagas. Mercado PT: `locationCode: 2620`, `languageCode: "pt"`. ### Keyword Difficulty Benchmarks diff --git a/marketing/skills/seo-report/SKILL.md b/marketing/skills/seo-report/SKILL.md index 462cb9e..d9450cb 100644 --- a/marketing/skills/seo-report/SKILL.md +++ b/marketing/skills/seo-report/SKILL.md @@ -1,31 +1,13 @@ --- name: seo-report -description: Relatorio de auditoria SEO completo com Lighthouse, Google Search Console e exportacao para Google Docs. Analisa Core Web Vitals, desempenho, SEO on-page e gera recomendacoes accionaveis. -layer: wiki +description: Relatório SEO completo com dados reais via OpenSEO (Search Console, crawl, Core Web Vitals, backlinks) e exportação para Google Docs. Prioriza por retorno e gera plano de acção. Usar quando "relatório SEO", "seo report", "relatório cliente SEO", "auditoria para cliente". --- # Skill: /seo-report -Gera relatorio SEO completo com dados de multiplas fontes e exporta automaticamente para Google Docs. +Relatório SEO para cliente, com dados reais do **OpenSEO**, exportado para Google Docs. ---- - -## Contexto NotebookLM - -ANTES de executar, consultar notebook para contexto especializado: - -| Notebook | ID | Consultar quando | -|----------|-----|-----------------| -| Marketing Digital PT | `4c595973` | Sempre | - -``` -mcp__notebooklm__notebook_query({ - notebook_id: "4c595973-ba10-420a-a3bf-e4389e424ad3", - query: "" -}) -``` - -**Procedimento relacionado:** `PROC-DMARC-Email-Entregabilidade.md` -- consultar quando o relatorio envolve email deliverability. +Diferença face a `/seo-audit`: a auditoria é o **diagnóstico técnico interno**; o report é o **entregável ao cliente** — mesma recolha, apresentação orientada a decisão e a orçamento. --- @@ -33,127 +15,115 @@ mcp__notebooklm__notebook_query({ `/seo-report ` ou `/seo-report ` ---- - -## Exemplos - ```bash -# Relatorio basico (envia para emanuelalmeidaa@gmail.com) /seo-report https://descomplicar.pt - -# Relatorio para cliente especifico /seo-report https://cliente.pt cliente@email.com - -# Relatorio com analise concorrencia /seo-report https://site.pt --competitors=concorrente1.pt,concorrente2.pt ``` --- -## Fontes de Dados +## Fontes de dados -| Fonte | Dados Recolhidos | Tempo | -|-------|------------------|-------| -| **Lighthouse (Desktop)** | Performance, SEO, Accessibility, Best Practices | ~30s | -| **Lighthouse (Mobile)** | Core Web Vitals, INP, comparacao mobile/desktop | ~30s | -| **Lighthouse (Optimizacoes)** | Oportunidades LCP, JS nao usado, images optimization | ~15s | -| **GSC** | Cliques, impressoes, CTR, posicao media, top queries, tendencia 90 dias | ~10s | -| **SEO Tools API** | Meta tags, imagens, alt text, links internos/externos, estrutura HTML | ~5s | -| **Ahrefs (opcional)** | DR, UR, backlinks, referring domains | ~10s | +| Fonte | Ferramenta | Dados | Custo | +|---|---|---|---| +| **Search Console** | `get_search_console_performance` | Cliques, impressões, CTR, posição, por query e por página | grátis | +| **Indexação** | `inspect_urls` | Estado de indexação (até 10 URLs) | grátis | +| **Crawl técnico** | `run_site_audit` → `get_audit_issues` | Issues por severidade, Lighthouse em amostra | grátis | +| **Core Web Vitals** | `chrome-devtools → performance_start_trace` | LCP, INP, CLS por página | grátis | +| **Keywords** | `get_keyword_metrics` | Volume, KD, intenção (até 700/chamada) | pago | +| **Autoridade** | `get_backlinks_overview`, `get_domain_overview` | Backlinks, ref. domains, tráfego estimado | pago | +| **Concorrência** | `find_serp_competitors`, `get_serp_results` | Quem ocupa a SERP | pago | -**Tempo Total:** ~1m40s (sem concorrencia) | ~3m (com 2 concorrentes) +**Tempo:** ~5-10 min (crawl de 600 páginas demora ~4 min). Não é instantâneo — avisar o cliente. --- ## Workflow -1. Validar URL de entrada -2. Verificar se site esta no GSC (skip se nao) -3. Executar auditorias em paralelo: - - Lighthouse Desktop + Mobile - - Core Web Vitals - - SEO Tools API - - GSC Analytics (se disponivel) - - Ahrefs (se habilitado) -4. Processar e formatar dados -5. Gerar relatorio Markdown -6. Criar Google Doc e partilhar -7. Retornar link do documento - ---- - -## Estrutura do Relatorio - -O relatorio final tem 8 seccoes: - -1. **Sumario Executivo** -- Top 5 descobertas + accao imediata recomendada -2. **Pontuacoes Globais** -- Desktop vs Mobile (Performance, SEO, A11y, Best Practices) -3. **Core Web Vitals** -- LCP, INP, CLS com oportunidades de optimizacao -4. **GSC Analytics** -- Performance overview, top queries, oportunidades CTR (ultimos 90 dias) -5. **Analise On-Page** -- Meta tags, imagens SEO, internal linking -6. **Backlinks e Autoridade** -- DR, UR, top backlinks, estrategia -7. **Plano de Accao** -- Priorizado (critico/importante/melhoria) com impacto e esforco -8. **Roadmap Trimestral** -- Fundacao tecnica -> Conteudo e autoridade -> Consolidacao - ---- - -## Propriedades GSC Disponiveis - ``` -sc-domain:descomplicar.pt -https://emanuelalmeida.pt/ -https://carstuff.pt/ -https://solarfvengenharia.com/ -https://aquisevende.pt/ -https://alojadamaria.com/ -https://e-commerce.descomplicar.pt/ +1. whoami + list_projects → projectId e mercado (GATE: PT = 2620/pt) +2. GSC por query + por página → paginar até esgotar +3. Dimensionar o crawl → maxPages ≥ nº páginas com impressões + 25% +4. run_site_audit → poll get_audit_status até "completed" +5. get_audit_issues → critical → warning → info +6. Cruzar fase 2 com fase 5 → páginas com procura E com defeito = lista de trabalho +7. [pago, opcional] keywords, backlinks, SERP +8. Gerar Markdown → Google Doc → partilhar ``` +**Os passos 1-6 são grátis e produzem o grosso do relatório.** O passo 7 só se o cliente pagar análise competitiva. + --- -## Notas Tecnicas +## Estrutura do relatório (8 secções) + +1. **Sumário executivo** — 5 descobertas + a acção imediata. Más notícias primeiro. +2. **Realidade actual** — cliques, impressões, CTR global, distribuição por posição, branded vs não-branded. +3. **Onde está o retorno** — striking distance (pos 4-20, ≥25 impressões) e desperdício (pos >40 com procura alta). +4. **Estado técnico** — issues por severidade, com **cobertura do crawl declarada**. +5. **Core Web Vitals** — LCP / INP / CLS nas páginas que importam (não em todas). +6. **Autoridade** — backlinks e ref. domains, se contratado. +7. **Plano de acção** — prioridade (crítico/importante/melhoria) × esforço × impacto estimado. +8. **Roadmap trimestral** — fundação técnica → conteúdo → consolidação. + +--- + +## Regras de honestidade do relatório + +Um relatório SEO é um documento comercial. Isso torna a precisão **mais** importante, não menos. + +- **Declarar sempre a cobertura do crawl.** "1337 issues em 600 páginas crawladas de ~640 com impressões." Sem isto, o número de issues não significa nada. +- **Não apresentar contagens como URLs verificados.** Se a bridge só deu contagens, dizê-lo e anexar o link da UI. +- **Custos são estimativas.** O OpenSEO não expõe saldo — nunca escrever "gastámos X créditos" como facto. +- **Separar medido de inferido.** Marcar as inferências. Um cliente que descobre uma inferência apresentada como facto deixa de confiar no resto. +- **CTR baixo em posição alta não é problema de ranking.** É título/meta. Dizer isso — é a recomendação mais barata e de maior retorno que existe. + +--- + +## Notas técnicas ### Requisitos -- SEO Tools API a correr: `~/mcp-servers/seo-tools-api/start.sh` -- Google Workspace MCP configurado -- GSC authentication (OAuth primeira vez) +- OpenSEO acessível (`whoami` responde) +- Propriedade ligada ao Search Console (senão, relatório sem fase GSC — declarar) +- `google-workspace` MCP para o Google Doc -### Erros Comuns -- **Site nao em GSC:** Relatorio gerado sem dados GSC (aviso incluido) -- **Lighthouse timeout:** Retry automatico (3x) -- **Ahrefs rate limit:** Skip backlinks, aviso no relatorio +### Erros comuns +| Erro | Sintoma | Solução | +|---|---|---| +| **`maxPages` por omissão** | Relatório limpo demais, poucos issues | Redimensionar pelo nº de páginas do GSC e relançar | +| Site fora do GSC | Fase 2 vazia | Gerar sem GSC, com aviso destacado | +| Mercado errado | Dados de keywords em inglês/EUA | `locationCode: 2620`, `languageCode: "pt"` | +| Crawl a demorar | `get_audit_status` em `crawling` | Normal — 600 páginas ≈ 4 min. Fazer poll, não cancelar | --- -## References (conteudo detalhado) +## References -| Ficheiro | Conteudo | -|----------|----------| -| `references/template-relatorio.md` | Template completo do relatorio com todas as tabelas e seccoes | -| `references/implementacao-tecnica.md` | Workflow mermaid, codigo JS, funcoes GSC, notas tecnicas | +| Ficheiro | Conteúdo | +|---|---| +| `references/template-relatorio.md` | Template completo com tabelas e secções | +| `references/implementacao-tecnica.md` | Workflow, chamadas OpenSEO, processamento | + +Inventário completo das ferramentas e tabela de migração: `../seo-audit/references/ferramentas-api.md` --- -## Anti-Patterns +## Anti-patterns -- Gerar relatorio sem dados reais (sempre usar MCPs) -- Ignorar gap mobile/desktop -- Nao priorizar recomendacoes (tudo parece igual) -- Esquecer de verificar se site esta no GSC antes de tentar recolher dados -- Relatorio sem accoes concretas e estimativas de impacto +- Gerar relatório sem dados reais. +- Omitir a cobertura do crawl (faz o relatório parecer melhor do que é). +- Listar issues por contagem em vez de por impacto. +- Apresentar estimativas de custo ou de tráfego como medições. +- Recomendações sem esforço e impacto estimados. +- Correr as fases pagas antes das grátis. --- -**Versao:** 2.1.0 | **Autor:** Descomplicar - ---- +**Versão:** 3.0.0 | **Autor:** Descomplicar® | **Motor:** OpenSEO ## Healing Log -Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. - ```jsonl -{"date":"","issue":"","fix":"","source":"user|auto"} +{"date":"2026-07-30","issue":"Skill dependia de SEO Tools API (localhost:3000), Lighthouse MCP, GSC MCP e Ahrefs — nenhum operacional. Workflow inteiro não executável.","fix":"Reescrita sobre OpenSEO; fases grátis antes das pagas; cobertura de crawl obrigatória no relatório.","source":"auto"} ``` - -*Adicionar nova linha após cada erro corrigido.* diff --git a/marketing/skills/seo-report/references/implementacao-tecnica.md b/marketing/skills/seo-report/references/implementacao-tecnica.md index 496f682..bcc37a4 100644 --- a/marketing/skills/seo-report/references/implementacao-tecnica.md +++ b/marketing/skills/seo-report/references/implementacao-tecnica.md @@ -1,144 +1,169 @@ -# Implementacao Tecnica - SEO Report +# Implementação Técnica — SEO Report (OpenSEO) -## Workflow Tecnico +## Workflow ```mermaid -graph LR - A[Input: URL] --> B{Site em GSC?} - B -->|Sim| C[Recolher dados GSC] - B -->|Nao| D[Skip GSC, aviso] +graph TD + A[Input: URL] --> B[whoami + list_projects] + B --> C{Mercado correcto?} + C -->|Não| C2[Passar locationCode 2620 + languageCode pt] + C -->|Sim| D[GSC: dimensions query] + C2 --> D - C --> E[Lighthouse Desktop] - D --> E + D --> E[GSC: dimensions page] + E --> F[Dimensionar crawl:
maxPages = páginas GSC + 25%] - E --> F[Lighthouse Mobile] - F --> G[Core Web Vitals] - G --> H[SEO Tools API] - H --> I{Ahrefs habilitado?} + F --> G[run_site_audit] + G --> H[poll get_audit_status] + H -->|running| H + H -->|completed| I[get_audit_issues por severidade] - I -->|Sim| J[Recolher DR/UR] - I -->|Nao| K[Skip Ahrefs] + I --> J[Cruzar: páginas com procura
E com defeito] + J --> K{Fases pagas contratadas?} - J --> L[Processar dados] - K --> L + K -->|Sim| L[get_keyword_metrics
get_backlinks_overview
get_serp_results] + K -->|Não| M[Saltar fases pagas] - L --> M[Gerar relatorio Markdown] - M --> N[Criar Google Doc] - N --> O[Partilhar com email] - - O --> P[Retornar link] + L --> N[Processar] + M --> N + N --> O[Markdown] --> P[Google Doc] --> Q[Partilhar] ``` -## Implementacao +**O ponto crítico é o nó F.** Dimensionar o crawl a partir do GSC é o que distingue um relatório verdadeiro de um relatório limpo e falso. + +--- + +## Sequência de chamadas ```javascript -async function generateSEOReport(url, options = {}) { - const { - email = 'emanuelalmeidaa@gmail.com', - competitors = [], - includeAhrefs = true - } = options; +// 1. Contexto e mercado +const me = await openseo.whoami(); +const projs = await openseo.list_projects(); +const projectId = projs[0].id; +const MARKET = { locationCode: 2620, languageCode: 'pt' }; // Portugal - // 1. Validar URL - if (!isValidURL(url)) { - throw new Error('URL invalido'); +// 2. Search Console — paginar até esgotar (grátis) +async function gscAll(dimensions) { + const rows = []; + let startRow = 0; + while (true) { + const r = await openseo.get_search_console_performance({ + projectId, dimensions, dateRange: 'last_3_months', + rowLimit: 1000, startRow + }); + const parsed = parseRows(r.text); + rows.push(...parsed); + if (!r.text.split('\n')[0].includes('more available') || !parsed.length) break; + startRow += 1000; } + return rows; +} - // 2. Recolher dados em paralelo (melhor performance) - const [ - lighthouseDesktop, - lighthouseMobile, - coreWebVitals, - seoToolsData, - gscData, - ahrefsData - ] = await Promise.allSettled([ - mcp__lighthouse__run_audit(url, 'desktop'), - mcp__lighthouse__run_audit(url, 'mobile'), - mcp__lighthouse__get_core_web_vitals(url), - fetch(`http://localhost:3000/seo-audit?url=${url}`).then(r => r.json()), - getGSCData(url), - includeAhrefs ? getAhrefsData(url) : null - ]); +const byQuery = await gscAll(['query']); +const byPage = await gscAll(['page']); - // 3. Processar e formatar - const reportData = { - url, - date: new Date().toISOString().split('T')[0], - scores: extractScores(lighthouseDesktop, lighthouseMobile), - cwv: processCoreWebVitals(coreWebVitals), - gsc: processGSCData(gscData), - onPage: processOnPageData(seoToolsData), - backlinks: processBacklinks(ahrefsData), - recommendations: generateRecommendations(/* all data */) - }; +// 3. Dimensionar o crawl a partir da realidade, não de um default +const maxPages = Math.ceil(byPage.length * 1.25); - // 4. Gerar documento Markdown - const markdown = generateReportMarkdown(reportData); +// 4. Crawl (grátis) — assíncrono, exige poll +const audit = await openseo.run_site_audit({ + projectId, url, maxPages, runLighthouse: true +}); +let status; +do { + await sleep(30_000); + status = await openseo.get_audit_status({ projectId, auditId: audit.id }); +} while (!status.text.includes('completed')); - // 5. Criar Google Doc - const docResult = await mcp__google-workspace__create_doc({ - title: `Relatorio SEO - ${extractDomain(url)} - ${reportData.date}`, - body_content: markdown, - user_google_email: email +// 5. Issues por severidade (grátis) +const critical = await openseo.get_audit_issues({ projectId, auditId: audit.id, severity: 'critical' }); +const warning = await openseo.get_audit_issues({ projectId, auditId: audit.id, severity: 'warning' }); + +// 6. Fases pagas — so se contratadas +if (options.paid) { + const kw = await openseo.get_keyword_metrics({ + projectId, keywords: strikingDistance(byQuery).map(r => r.key), ...MARKET }); - - // 6. Retornar link - return { - success: true, - doc_url: docResult.url, - summary: reportData.recommendations.slice(0, 5) - }; + const bl = await openseo.get_backlinks_overview({ projectId, target: domain }); } ``` -## Propriedades GSC Disponiveis +--- + +## Processamento — as funções que importam ```javascript -const GSC_PROPERTIES = [ - 'sc-domain:descomplicar.pt', - 'https://emanuelalmeida.pt/', - 'https://carstuff.pt/', - 'https://solarfvengenharia.com/', - 'https://aquisevende.pt/', - 'https://alojadamaria.com/', - 'https://e-commerce.descomplicar.pt/' -]; +// GSC anonimiza queries: totais por query < totais por página. +// Para números globais usar SEMPRE a vista por página. +const globals = { + clicks: sum(byPage, 'clicks'), + impressions: sum(byPage, 'impressions'), + ctr: sum(byPage, 'clicks') / sum(byPage, 'impressions') +}; -async function getGSCData(url) { - const domain = extractDomain(url); - const property = GSC_PROPERTIES.find(p => p.includes(domain)); +// O GSC não filtra por posição — filtrar do lado do cliente. +const strikingDistance = rows => rows + .filter(r => r.position >= 4 && r.position <= 20 && r.impressions >= 25) + .sort((a, b) => b.impressions - a.impressions); - if (!property) { - console.warn(`Site ${domain} nao esta no GSC. Dados GSC nao disponiveis.`); - return null; - } +// Páginas com procura real enterradas fora das primeiras 4 páginas. +const waste = rows => rows + .filter(r => r.position > 40 && r.impressions >= 300) + .sort((a, b) => b.impressions - a.impressions); - const analytics = await mcp__gsc__get_search_analytics({ - site_url: property, - start_date: daysAgo(90), - end_date: 'today', - dimensions: ['query'], - row_limit: 100 - }); +// O sinal mais accionável: primeira página, CTR nulo. +// Não é ranking — é título e meta description. +const titleProblem = rows => rows + .filter(r => r.position <= 10 && r.impressions >= 200 && r.ctr < 0.005); - return analytics; -} +// Lixo nas queries do GSC (colagens do Google Ads, operadores site:). +const isNoise = k => + (k.includes('ativado') && k.includes('correspond')) || + k.startsWith('-site:') || k.startsWith('=') || + k.length > 90 || k.includes('0,00'); ``` -## Notas Tecnicas +--- + +## Entrega + +```javascript +const doc = await googleWorkspace.docs_create_document({ + title: `Relatório SEO — ${domain} — ${today}`, + user_google_email: email +}); +await googleWorkspace.docs_append_text({ document_id: doc.id, text: markdown }); +``` + +--- + +## Notas técnicas ### Requisitos -- SEO Tools API a correr: `~/mcp-servers/seo-tools-api/start.sh` -- Google Workspace MCP configurado -- GSC authentication (OAuth primeira vez) +- OpenSEO acessível (`whoami` responde) +- Propriedade ligada ao Search Console +- `google-workspace` MCP para o documento -### Performance -- Execucao paralela de tools (1m40s total) -- Cache Lighthouse results (5 min TTL) -- Rate limiting Ahrefs API (100 req/day free) +### Tempos reais (medidos, descomplicar.pt, 07-2026) +| Fase | Duração | +|---|---| +| GSC (2 dimensões, ~1700+474 linhas) | ~10s | +| Crawl 600 páginas + Lighthouse 20 | ~4 min | +| `get_audit_issues` | instantâneo | -### Erros Comuns -- **Site nao em GSC:** Relatorio gerado sem dados GSC -- **Lighthouse timeout:** Retry automatico (3x) -- **Ahrefs rate limit:** Skip backlinks, aviso no relatorio +### Limitações +- **Issues sem URL:** `get_audit_issues` / `get_audit_pages` devolvem só contagens pela bridge MCP; `structuredContent.issues` não é entregue e `get_audit_pages` trunca em ~25 linhas. Usar `details.mcpMeta.url` para o link da UI. +- **Sem medidor de créditos:** `whoami` não muda depois de chamadas pagas. Custos são estimativas. +- **Lag do GSC:** últimos ~3 dias incompletos; datas em Pacific Time; máx. 16 meses. + +### Erros comuns +| Erro | Sintoma | Solução | +|---|---|---| +| `maxPages` por omissão (50) | Poucos issues, relatório "limpo" | Redimensionar pelo GSC, relançar | +| Site fora do GSC | Fase GSC vazia | Gerar sem GSC, aviso destacado | +| Mercado errado | Keywords em inglês/EUA | `locationCode: 2620`, `languageCode: "pt"` | +| Cancelar o crawl cedo demais | Sem `auditId` utilizável | Fazer poll; 600 páginas ≈ 4 min | + +--- + +**Actualizado:** 30-07-2026 | Substitui a implementação baseada em Lighthouse MCP + SEO Tools API + Ahrefs diff --git a/marketing/skills/seo-report/references/template-relatorio.md b/marketing/skills/seo-report/references/template-relatorio.md index 2e4ca12..546bc0d 100644 --- a/marketing/skills/seo-report/references/template-relatorio.md +++ b/marketing/skills/seo-report/references/template-relatorio.md @@ -203,13 +203,17 @@ Data: YYYY-MM-DD | Versao 2.0 (2026 Standards) ## Anexos ### A. Metodologia -- Lighthouse: 3 runs, mediana reportada -- GSC: Ultimos 90 dias completos +- Motor: OpenSEO (crawl same-origin, robots-aware) + Search Console +- Crawl: [N] páginas de [M] com impressões no GSC — **declarar sempre a cobertura** +- Search Console: últimos 3 meses; vista por página para totais (o GSC anonimiza queries) +- Core Web Vitals: Lighthouse em amostra; páginas individuais via chrome-devtools - Thresholds: Google 2026 Standards +- Custos de chamadas pagas: estimativas do schema, não medições -### B. Glossario -- **DR**: Domain Rating (Ahrefs) -- **INP**: Interaction to Next Paint (substitui FID em 2026) +### B. Glossário +- **Striking distance**: posição 4-20 com impressões relevantes — onde está o retorno +- **KD**: Keyword Difficulty +- **INP**: Interaction to Next Paint (substituiu o FID em 2026) - **E-E-A-T**: Experience, Expertise, Authoritativeness, Trust - **CTR**: Click-Through Rate diff --git a/marketing/skills/social-media/SKILL.md b/marketing/skills/social-media/SKILL.md index b292bd0..91bf50e 100644 --- a/marketing/skills/social-media/SKILL.md +++ b/marketing/skills/social-media/SKILL.md @@ -1,7 +1,6 @@ --- name: social-media description: Estrategia e gestao de conteudo para redes sociais. Planeia publicacoes, calendario de conteudo e tacticas de engagement. -layer: wiki --- # /social-media @@ -162,4 +161,44 @@ Exemplo agencia marketing: **Quando consultar:** antes de criar posts Instagram, carrosséis, stories ou posts LinkedIn/Facebook que precisem de imagem ou vídeo curto. Reutiliza matéria-prima já curada em vez de gerar do zero. -**Workflow tentativa-p \ No newline at end of file +**Workflow tentativa-primeiro:** + +1. Pesquisar via MCP `media-bank`: + ``` + mcp__media-bank__search_media( + query="", + type="image", # ou "video" para reels/stories + tema="", + orientation="square", # Instagram feed; "portrait" para stories/reels + min_quality=7, + exclude_used_in_last_days=30, + limit=5 + ) + ``` +2. Avaliar candidatos por `description_en` + `quality_score`. +3. Se ≥1 adequado → usar `path_local` como base para composição (Canva/design-engine) com overlay de texto, branding e CTA. +4. Se nenhum → fallback para geração IA. +5. Marcar uso: `mcp__media-bank__mark_used(asset_id, {type:"social-post", ref:"-", date:""})`. + +**Fallback REST** (se MCP indisponível): +```bash +SK=$(grep SERVICE_KEY /media/ealmeida/Dados/Hub/05-Projectos/Banco-Imagens-Videos/scripts/.env | cut -d= -f2) +curl -s "https://mem.descomplicar.pt/rest/v1/media_bank_assets?type=eq.image&orientation=eq.square&quality_score=gte.7&deleted_at=is.null&order=quality_score.desc&limit=5" \ + -H "apikey: $SK" -H "Authorization: Bearer $SK" +``` + +**Regra inviolável:** matéria-prima local. Usar como input para composição — NUNCA publicar o ficheiro raw como post sem edição (branding, texto, aspect ratio). + +Ver `Hub/06-Operacoes/Procedimentos/D7-Tecnologia/MCP/PROC-Media-Bank.md` (D7-MB-001) para detalhes. + +--- + +## 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/marketing/skills/trend-signal/SKILL.md b/marketing/skills/trend-signal/SKILL.md index 0ab6529..c59157a 100644 --- a/marketing/skills/trend-signal/SKILL.md +++ b/marketing/skills/trend-signal/SKILL.md @@ -5,7 +5,6 @@ description: "Obtem sinais de mercado em tempo real via X/Grok com scoring matri version: "1.0.0" created: 2026-04-07 tools: [mcp__claude-in-chrome__tabs_create_mcp, mcp__claude-in-chrome__read_page, mcp__claude-in-chrome__form_input, mcp__claude-in-chrome__computer] -layer: wiki --- # Skill: /trend-signal diff --git a/marketing/skills/video/SKILL.md b/marketing/skills/video/SKILL.md index 7ba05af..56e9aff 100644 --- a/marketing/skills/video/SKILL.md +++ b/marketing/skills/video/SKILL.md @@ -1,7 +1,6 @@ --- name: video description: Criacao de videos profissionais com Remotion (React). Planeia conteudo, scripts e workflows de producao. -layer: wiki --- # /video - Criacao de Videos com Remotion @@ -206,4 +205,143 @@ npx remotion render Video out.mp4 \ | 1:1 Quadrado | 1080x1080 | Instagram Feed | | 4:5 Portrait | 1080x1350 | Instagram Feed optimal | -- \ No newline at end of file +--- + +## Casos de Uso + +| Tipo | Duracao | Resolucao | +|------|---------|-----------| +| Logo Intro | 3-5s | 1920x1080 | +| Promo Rapida | 15-30s | 1080x1920 | +| Explainer | 60-120s | 1920x1080 | +| Social Post | 5-15s | 1080x1080 | +| YouTube Intro | 5-10s | 1920x1080 | +| Stories | 15s | 1080x1920 | + +--- + +## Boas Praticas + +### Performance + +- Usar `React.memo()` para componentes pesados +- Evitar re-renders desnecessarios +- Pre-carregar assets com `staticFile()` + +### Animacoes + +- Comecar com `interpolate()` para animacoes simples +- Usar `spring()` para movimentos naturais +- Combinar `Sequence` para organizar timeline + +### Assets + +- Colocar imagens/audio em `public/` +- Usar `staticFile("nome.png")` para referenciar +- Formatos recomendados: PNG (imagens), MP3/WAV (audio) + +--- + +## Troubleshooting + +| Problema | Solucao | +|----------|---------| +| Video preto | Verificar `AbsoluteFill` tem background | +| Fontes nao carregam | Usar `@remotion/google-fonts` | +| Animacao nao funciona | Verificar range de frames no `interpolate` | +| Erro de modulo | `rm -rf node_modules && npm install` | +| Render lento | Reduzir `--concurrency` ou usar `--crf` maior | + +--- + +## Workflow Completo + +``` +1. DEFINIR -> Duracao, resolucao, estilo +2. DESCREVER -> Prompt detalhado ao Claude +3. GERAR -> Claude cria componentes React +4. PREVIEW -> npm run dev (Remotion Studio) +5. AJUSTAR -> Refinar animacoes/timing +6. RENDER -> npx remotion render +7. EXPORTAR -> MP4/GIF/WebM conforme necessidade +``` + +--- + +## Referencias Detalhadas + +Para conteudo detalhado, consultar: + +- [references/components.md](references/components.md) - Animacoes prontas, templates, paletas de cores, tipografia, motion design, acessibilidade +- [rules/animations.md](rules/animations.md) - Animacoes fundamentais +- [rules/timing.md](rules/timing.md) - Interpolacao e easing +- [rules/transitions.md](rules/transitions.md) - Transicoes entre cenas +- [rules/sequencing.md](rules/sequencing.md) - Organizacao temporal +- [rules/fonts.md](rules/fonts.md) - Carregamento de fontes +- [rules/images.md](rules/images.md) - Trabalhar com imagens +- [rules/audio.md](rules/audio.md) - Audio e som +- [rules/tailwind.md](rules/tailwind.md) - TailwindCSS no Remotion + +--- + +## Anti-Patterns + +- Nao usar para tarefas fora do dominio de video/Remotion +- Nao usar quando outra skill mais especifica esta disponivel +- Nao executar sem confirmar requisitos com o utilizador + +--- + +**Projecto Base**: `/media/ealmeida/Dados/Dev/remotion-demo/` +**Documentacao**: [remotion.dev/docs](https://remotion.dev/docs) + +--- + +## Media Bank (D7-MB-001) + +**Quando consultar:** antes de produzir vídeos Remotion — para B-roll, clips de abertura, backgrounds e transições. Reutilizar matéria-prima evita regeneração IA cara e mantém consistência visual. + +**Workflow tentativa-primeiro:** + +1. Pesquisar via MCP `media-bank`: + ``` + mcp__media-bank__search_media( + query="", + type="video", + tema="", + orientation="landscape", + min_quality=7, + min_width=1920, + min_duration=3, + max_duration=15, + exclude_used_in_last_days=30, + limit=5 + ) + ``` +2. Avaliar candidatos por `description_en`, duração e `quality_score`. +3. Se ≥1 adequado → usar `path_local` como input directo no Remotion (`