feat(v1.5.2): Execute database migrations and complete setup
- Execute all 6 migrations on Desk CRM production database - Create missing tables: cr_lsps, cr_agent_lsps, cr_lsp_usage - Create archive tables: cr_*_usage_archive (4 tables) - Create system tables: cr_migrations, cr_maintenance_log - Make all scripts executable (chmod +x) - Total cr_* tables: 38 Migration files: - 001_initial_schema.sql - 002_add_lsps.sql - 003_add_relationships.sql - 004_add_telemetry.sql - 005_add_archive_tables.sql - 006_add_maintenance_log.sql Scripts: - session-init.sh, session-end.sh - inject-context.sh, inject-agent-context.sh - record-usage.sh, db-backup.sh, sync-to-mysql.sh Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
476
docs/STANDARDS.md
Executable file
476
docs/STANDARDS.md
Executable file
@@ -0,0 +1,476 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user