descomplicar-meta-plugin/STANDARDS.md

Descomplicar Meta-Plugin Standards

Regras Oficiais do Ecossistema Claude Code Descomplicar® Versão 1.1.0 | 2026-02-04

---

Documentação Completa

Este documento contém as regras principais. Para guias detalhados, consultar:

Guia	Descrição	Linhas
01-GUIA-SKILLS.md	Guia definitivo para skills	~455
02-GUIA-AGENTS.md	Guia definitivo para agents	~639
03-GUIA-HOOKS.md	Guia completo de hooks	~1184
04-GUIA-PLUGINS.md	Guia de plugins	~509
05-CHECKLISTS.md	Checklists de validação	~400
06-TEMPLATES.md	Templates prontos	~528

---

Princípios Fundamentais

1. Discovery-First

PESQUISAR → AVALIAR → ADAPTAR → INTEGRAR

Antes de criar qualquer componente novo:

1. Pesquisar nos marketplaces (anthropics, community)
2. Descarregar e avaliar múltiplas opções
3. Adaptar/combinar o melhor de cada
4. Integrar no ecossistema Descomplicar

2. Database as Source of Truth

Toda a configuração vive na BD MySQL (ealmeida_desk24):

• Componentes: cr_agents, cr_skills, cr_mcps, cr_lsps, cr_sdks
• Relacionamentos: cr_agent_mcps, cr_agent_lsps, cr_agent_skills, etc.
• Telemetria: cr_agent_usage, cr_skill_usage, etc.
• Intelligence: cr_decision_trees, cr_recommendations

3. Relationship-Driven

Cada componente existe num grafo de relacionamentos:

Agent ←→ MCPs (primary/recommended/available)
Agent ←→ LSPs (primary/recommended/available)
Agent ←→ Skills
Agent ←→ Agents (collaborations)
SDK ←→ Agents + Skills + MCPs

---

Regras de Skills

R-SKL-001: Estrutura Obrigatória

---
name: skill-name                    # lowercase-with-hyphens, <64 chars
description: >                      # <1024 chars, OBRIGATÓRIO
  [Capacidade]. Use when [triggers], or when user mentions "[keywords]".
author: Descomplicar® Crescimento Digital
version: X.Y.Z                      # semver
user_invocable: true|false
desk_task: XXXX                     # ID tarefa Desk CRM
allowed-tools: Tool1, Tool2         # mínimos necessários
---

R-SKL-002: Limite de Tamanho

Componente	Limite
SKILL.md total	<500 linhas
Description	<1024 caracteres
Nome	<64 caracteres

R-SKL-003: Description Formula

[Capacidade principal]. [Capacidades secundárias].
Use when [trigger1], [trigger2], or when user mentions
"[keyword1]", "[keyword2]", "[keyword3]".

Mínimo 5 keywords específicas.

R-SKL-004: Progressive Disclosure

SKILL.md (essencial, <500 linhas)
├── docs/reference.md (detalhes)
├── templates/*.md (templates)
└── scripts/*.sh (automação)

Máximo 1 nível de referência.

R-SKL-005: Secções Obrigatórias

1. Quando Usar - Cenários de activação
2. Quando NÃO Usar - Limites explícitos
3. Protocolo - Passos de execução
4. Exemplos - Input/output concreto

R-SKL-006: Registo BD

Toda skill deve ter entrada em:

• cr_skills (entidade)
• cr_agent_skills (quais agentes usam)
• cr_skill_mcps (quais MCPs precisa)

R-SKL-007: Qualidade Mínima

Score >= 70 para produção:

• Description optimizada (25%)
• Estrutura correcta (20%)
• Tamanho adequado (15%)
• Exemplos práticos (15%)
• Limites definidos (10%)
• Tools mínimos (10%)
• Testada 3+ cenários (5%)

---

Regras de Agents

R-AGT-001: Estrutura Obrigatória

---
name: agent-slug                    # lowercase-with-hyphens
description: >                      # capacidades + triggers
  [Especialização]. Use for [triggers], "[keywords]".
model: sonnet|opus|haiku
tools: Tool1, Tool2, Tool3
allowed-mcps: mcp1, mcp2
skills: skill1, skill2
category: dev|business|infra|research|content
author: Descomplicar® Crescimento Digital
version: X.Y.Z
desk_task: XXXX
---

R-AGT-002: Categorias Válidas

Categoria	Descrição	Tools Típicos
dev	Desenvolvimento	Read, Write, Edit, Bash
business	Negócio/Marketing	Read, WebSearch
infra	Infraestrutura	Bash, Read
research	Pesquisa	Read, WebFetch, WebSearch
content	Conteúdo	Read, Write

R-AGT-003: Mapeamento MCPs (cr_agent_mcps)

Tipo	Descrição	Regra
primary	Essencial	Sempre disponível, auto-load
recommended	Útil	Activar quando relevante
available	Opcional	Disponível sob demanda

Máximo:

• 5 MCPs primary
• 8 MCPs recommended
• 15 MCPs available

R-AGT-004: Mapeamento LSPs (cr_agent_lsps)

Agentes de categoria dev devem ter LSPs mapeados:

Linguagem Principal	LSP Primary
PHP	intelephense
TypeScript/JS	typescript-language-server
Python	pyright
SQL	sql-language-server
YAML	yaml-language-server

R-AGT-005: Colaborações (cr_agent_collaborations)

Tipo	Descrição	Exemplo
technical	Mesmo domínio	php-dev ↔ db-specialist
cross-domain	Domínios diferentes	wp-dev ↔ seo-specialist
sequential	Passa trabalho	research → planning → exec
parallel	Trabalho simultâneo	marketing ∥ sales

R-AGT-006: Secções Obrigatórias

1. Identidade - Persona do agente
2. Especialização - Domínio de expertise
3. Workflow - Como aborda tarefas
4. Limites - O que NÃO faz
5. Colaborações - Com quem trabalha

R-AGT-007: Decision Trees

Todo agente activo deve ter entrada em cr_decision_trees:

INSERT INTO cr_decision_trees (name, agent_id, trigger_keywords, confidence_score)
VALUES ('agent-tasks', (SELECT id FROM cr_agents WHERE slug = 'agent-slug'),
        'keyword1, keyword2, keyword3', 0.75);

---

Regras de MCPs

R-MCP-001: Registo Obrigatório

INSERT INTO cr_mcps (slug, name, description, transport_type, status)
VALUES ('mcp-slug', 'MCP Name', 'Description', 'stdio|sse|http', 'active');

R-MCP-002: Mapeamento de Tools

Todas as tools do MCP devem estar em cr_mcp_tools:

INSERT INTO cr_mcp_tools (mcp_id, tool_name, description)
VALUES ((SELECT id FROM cr_mcps WHERE slug = 'mcp-slug'),
        'tool_name', 'Tool description');

R-MCP-003: Categorização

Categoria	MCPs
Core	filesystem, mcp-time
CRM	desk-crm-v3
Communication	google-workspace, imap
Infrastructure	ssh-unified, cwp
Knowledge	dify-kb, wikijs, memory-supabase
Development	gitea, n8n
External	tavily, context7

R-MCP-004: Gateway vs Local

Tipo	Quando Usar
Gateway	MCPs partilhados, BD centralizada
Local	MCPs de alta frequência, filesystem

---

Regras de LSPs

R-LSP-001: Registo Obrigatório

INSERT INTO cr_lsps (slug, name, language, package_manager, package_name, status)
VALUES ('lsp-slug', 'LSP Name', 'Language', 'npm|pip|cargo', 'package', 'active');

R-LSP-002: Mapeamento por Linguagem

Linguagem	LSP Padrão	Agentes
PHP	intelephense	php-, wordpress-, perfex-*
TypeScript	typescript-language-server	javascript-, elementor-
Python	pyright	automation-*, dev-helper
SQL	sql-language-server	database-, crm-
YAML	yaml-language-server	easypanel-, n8n-
Bash	bash-language-server	cwp-, backup-

R-LSP-003: Verificação Automática

O meta-plugin deve verificar periodicamente:

1. LSPs configurados estão instalados
2. Versões actualizadas
3. Agentes dev têm LSPs mapeados

---

Regras de Hooks

R-HKS-001: Eventos Disponíveis

Evento	Quando	Uso
SessionStart	Início de sessão	Health check, context load
SessionStop	Fim de sessão	Cleanup, telemetria
PreToolUse	Antes de tool	Validação, contagem
PostToolUse	Depois de tool	Logging, triggers
SubagentStart	Início de subagent	Context injection
SubagentStop	Fim de subagent	Resultado capture

R-HKS-002: Formato

{
  "hooks": {
    "EventName": [{
      "type": "command",
      "command": "${PLUGIN_ROOT}/scripts/hook-script.sh"
    }]
  }
}

R-HKS-003: Segurança

• Scripts devem falhar silenciosamente (não bloquear Claude)
• Timeout máximo: 5 segundos
• Sem operações destrutivas automáticas
• Log de todas as execuções

R-HKS-004: Auto-Triggers

Condição	Trigger	Acção
>10 tool calls	worklog	Background task
>20 tool calls	reflect	Background task
Erro 2x consecutivo	reflect	Análise
Mudança projecto	worklog	Fecha sessão anterior

---

Regras de Plugins

R-PLG-001: Estrutura

plugin-name/
├── .claude-plugin/
│   └── plugin.json         # Manifesto obrigatório
├── commands/               # /plugin:command
├── skills/                 # Skills bundled
├── agents/                 # Agents bundled
├── hooks/
│   └── hooks.json
├── scripts/
├── sql/                    # Migrations BD
└── README.md

R-PLG-002: Manifesto

{
  "name": "plugin-name",
  "version": "X.Y.Z",
  "description": "Description",
  "capabilities": {
    "commands": true,
    "skills": true,
    "agents": true,
    "hooks": true,
    "mcp": true,
    "lsp": true
  },
  "commands": ["cmd1", "cmd2"],
  "skills": ["skill1", "skill2"],
  "agents": ["agent1"],
  "dependencies": {
    "mcps": ["mcp1", "mcp2"]
  }
}

R-PLG-003: Namespacing

• Commands: plugin:command
• Skills: plugin:skill ou plugin/skill
• Agents: ficheiro em agents/

---

Regras de Telemetria

R-TEL-001: Tracking Obrigatório

Componente	Tabela	Campos
Agent	cr_agent_usage	agent_id, success, duration_sec
Skill	cr_skill_usage	skill_id, success, duration_sec
MCP Tool	cr_mcp_tool_usage	mcp_tool_id, response_time_ms, success
LSP	cr_lsp_usage	lsp_id, operation, response_time_ms

R-TEL-002: Métricas de Saúde

Métrica	Threshold	Acção
Success Rate	<90%	Investigar erros
Avg Duration	>120s	Optimizar
Unused (dias)	>90	Considerar arquivar
Error Spike	>5 em 1h	Alerta imediato

R-TEL-003: Retenção

• Dados detalhados: 90 dias
• Agregados: 1 ano
• Decision tree updates: baseado em últimos 30 dias

---

Workflow de Integração

Novo Componente (Skill/Agent/MCP/LSP)

1. PESQUISAR
   └── Verificar marketplaces existentes
   └── Identificar implementações similares

2. AVALIAR
   └── Descarregar candidatos
   └── Testar funcionalidade
   └── Comparar qualidade

3. ADAPTAR
   └── Extrair melhores práticas
   └── Adaptar para padrões Descomplicar
   └── Adicionar integrações (BD, hooks)

4. INTEGRAR
   └── Registar em BD (cr_*)
   └── Mapear relacionamentos
   └── Criar decision tree
   └── Adicionar telemetria

5. VALIDAR
   └── Testar 3+ cenários
   └── Verificar score qualidade
   └── Documentar no Desk CRM

Discovery de Plugins

/descomplicar:discover
   │
   ├── Fetch marketplace oficial
   ├── Fetch community repos
   ├── Avaliar relevância (keywords match)
   ├── Score de qualidade
   └── Gerar relatório de recomendações

---

Comandos do Meta-Plugin

Comando	Função
/descomplicar:status	Dashboard completo
/descomplicar:sync	Sincronizar BD
/descomplicar:discover	Descobrir plugins
/descomplicar:agent-config	Configurar agente
/descomplicar:relationships	Gerir relacionamentos
/descomplicar:telemetry	Ver métricas
/descomplicar:decision-trees	Gerir decision trees
/descomplicar:lsps	Gerir LSPs

---

Versionamento

• Major (X.0.0): Breaking changes em estrutura BD
• Minor (0.X.0): Novas funcionalidades
• Patch (0.0.X): Bug fixes, ajustes

---

Conformidade

Todo componente deve passar no checklist antes de produção:

□ Estrutura conforme regras R-*
□ Registado em BD (cr_*)
□ Relacionamentos mapeados
□ Telemetria configurada
□ Decision tree (se agent)
□ Testado 3+ cenários
□ Score qualidade >= 70
□ Documentado no Desk CRM

---

STANDARDS.md v1.0.0 | Descomplicar® | 2026-02-04