feat(core-tools): adiciona plugin core-tools (agents, skills, knowledge e metadados do projeto)

2026-10-28 16:08:27 +00:00
parent de490943e5
commit 83a69e681c
28 changed files with 2708 additions and 0 deletions
@@ -0,0 +1,184 @@
+---
+name: metrics
+description: Dashboard de metricas de performance de skills e agentes com telemetria quantitativa, trending temporal, alertas de degradacao e calculo de ROI.
+layer: wiki
+---
+
+# SKILL: Performance Metrics Dashboard
+
+## Proposito
+
+Dashboard interactivo de performance de skills e agents com metricas quantitativas automaticas gravadas em Desk DB.
+
+Complementa `/reflect` (qualitativo) com dados quantitativos, `/worklog` com metricas objectivas, e PDCA com decisoes data-driven.
+
+---
+
+## Quando Usar
+
+- Ver performance de skills/agents
+- Identificar degradacoes de performance
+- Validar melhorias PDCA
+- Analise ROI de optimizacoes
+- Dashboard executivo de automacao
+
+---
+
+## Comandos
+
+| Comando | Funcao |
+|---------|--------|
+| `/metrics` | Overview geral (30 dias) |
+| `/metrics <skill-name>` | Detalhes de skill especifica |
+| `/metrics --project <id>` | Metricas por projecto |
+| `/metrics --trend` | Trending temporal |
+| `/metrics --compare` | Comparacao vs baseline |
+| `/metrics --kb` | Metricas Dify KB |
+| `/metrics --roi` | ROI por cliente/projecto |
+| `/metrics --export` | Exportar JSON/CSV |
+| `/metrics --alerts` | Listar alertas activos |
+| `/metrics --tools` | **Telemetria local de tool calls (ver secção Local Tool Telemetry)** |
+
+---
+
+## Local Tool Telemetry (G3.1-B)
+
+Desde 08-04-2026 há captura universal de **todas** as tool calls do Claude Code via hook PostToolUse (`~/.claude/hooks/telemetry-posttool-hook.sh`). Complementa a telemetria Desk CRM com dados locais imediatos.
+
+**Ficheiro:** `~/.claude-work/tool-invocations.jsonl` (1 linha por tool call: ts, session, tool_use_id, tool_name, success, error)
+
+**Agregador:** `/media/ealmeida/Dados/Dev/ClaudeDev/tool-metrics.py`
+
+```bash
+# Overview últimas 24h
+python3 /media/ealmeida/Dados/Dev/ClaudeDev/tool-metrics.py
+
+# Só hoje
+python3 /media/ealmeida/Dados/Dev/ClaudeDev/tool-metrics.py --today
+
+# Últimos 7 dias
+python3 /media/ealmeida/Dados/Dev/ClaudeDev/tool-metrics.py --last 7d
+
+# Filtrar por sessão
+python3 /media/ealmeida/Dados/Dev/ClaudeDev/tool-metrics.py --session <session_id>
+
+# Output JSON (para pipeline/grafos)
+python3 /media/ealmeida/Dados/Dev/ClaudeDev/tool-metrics.py --json
+```
+
+**Output:** total de invocations, sessões únicas, top 20 tools (contagem + %), falhas por tool com amostras de erro, top 5 sessões por volume.
+
+**Limitações conhecidas:**
+- Duration não é capturada (harness não entrega duration no hook payload). Apenas contagem e success/failure.
+- Tokens não capturáveis via hooks (não estão no payload).
+- Só captura tool calls que chegam ao PostToolUse — tool calls bloqueados por hooks PreToolUse não aparecem.
+
+Ver `04-Stack/CHANGELOG.md` bloco 08-04-2026 sessão 2 para contexto do gap e decisão de scope.
+
+### Agregacoes Disponiveis
+
+1. **avg** - Medias de performance (padrao)
+2. **count** - Contagens por status
+3. **trend** - Evolucao temporal (semanal)
+4. **compare** - Comparacao com baseline
+5. **detailed** - Listagem detalhada
+
+---
+
+## Execucao
+
+### 1. Verificar Tools MCP
+
+```javascript
+// Tools necessarios (MCP desk-crm-v3)
+const REQUIRED_TOOLS = [
+  'mcp__desk-crm-v3__log_skill_metric',
+  'mcp__desk-crm-v3__get_skill_metrics'
+];
+// Se tools nao disponiveis -> query SQL directa como fallback
+```
+
+### 2. Query Metricas
+
+**Via MCP (preferencial):**
+
+```javascript
+const metrics = await mcp__desk_crm_v3__get_skill_metrics({
+  days: 30,
+  aggregate: 'avg',
+  limit: 10
+});
+```
+
+**Fallback SQL:** Ver [references/sql-queries.md](references/sql-queries.md)
+
+### 3. Formatar Output
+
+```
+Performance Overview (ultimos {days} dias)
+
+Top Skills/Agents:
+| Nome           | Usos | Avg Time | Trend | Status |
+|----------------|------|----------|-------|--------|
+| /orcamento     | 45   | 18min    | -12%  | OK     |
+| /lead-approach | 38   | 22min    | +5%   | Alerta |
+| wp-plugin-dev  | 32   | 47min    | -8%   | OK     |
+```
+
+### 4. Analise Especifica
+
+```javascript
+const details = await get_skill_metrics({
+  name: skill_name,
+  days: 30,
+  aggregate: 'detailed'
+});
+
+const baseline = await query(
+  "SELECT baseline_duration_ms FROM tblskill_agent_baselines WHERE name = ?",
+  [skill_name]
+);
+const improvement = ((baseline - current_avg) / baseline * 100);
+```
+
+---
+
+## Alertas Automaticos
+
+```javascript
+const degraded = await get_skill_metrics({
+  aggregate: 'compare',
+  days: 7
+});
+
+const alerts = degraded.results.filter(r =>
+  r.performance_status === 'DEGRADED'
+);
+
+if (alerts.length > 0) {
+  // Output alertas e sugerir /reflect para investigar
+}
+```
+
+### Trigger Reflect se Degradacao
+
+```javascript
+if (degradation_pct > 15) {
+  // AUTO: Invocar reflect-agent em background
+  Task({
+    subagent_type: 'reflect-agent',
+    background: true,
+    model: 'sonnet',
+    prompt: `PERFORMANCE DEGRADATION: ${name} +${degradation_pct}%`
+  });
+}
+```
+
+---
+
+## Integracao com Outros Sistemas
+
+| Comando | Foco | Quando Usar |
+|---------|------|-------------|
+| `/taskforce kb-health` | Saude sistema KB | Visao arquitectural |
+| `/metrics --kb` | Performance queries