descomplicar-meta-plugin/docs/STANDARDS.md

# Descomplicar Meta-Plugin Standards

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

---

## 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

```yaml
---
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

```markdown
---
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`:

```sql
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

```sql
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`:

```sql
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

```sql
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

```json
{
  "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

```json
{
  "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