feat(gestao): adiciona plugin gestao (agents, skills, knowledge e metadados do projeto)

2026-10-28 16:08:53 +00:00
parent 7b2162ff29
commit de2d6f2fb5
91 changed files with 13525 additions and 0 deletions
@@ -0,0 +1,169 @@
+---
+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
+
+## Modelo de governance (desde 29-03-2026)
+
+**Todas as routines são atribuídas ao CEO.** O CEO delega pela cadeia hierárquica:
+
+```
+Routine (cron trigger) → CEO avalia e delega
+  → C-Level adiciona contexto departamental
+    → Director coordena e atribui
+      → Especialista executa
+        → Resultado sobe a cadeia com síntese progressiva
+```
+
+Cada routine tem no campo `description` a cadeia de delegação (ex: `CADEIA: CEO → CTO → Dir. Infraestrutura → Backup Specialist`).
+
+**Regras:**
+- Novas routines devem ser SEMPRE atribuídas ao CEO
+- A cadeia de delegação deve estar explícita na descrição
+- Nunca atribuir routines directamente a especialistas — quebra a visibilidade hierárquica
+
+## Dois tipos de periodicidade
+
+1. **Heartbeats** — intervalos configurados via `runtime_config` dos agentes (quando acordam)
+2. **Routines** — tarefas periódicas via tabela `routines` + `routine_triggers` com cron (o que fazem ao acordar)
+
+## Constantes
+
+```
+BD: PGPASSWORD="paperclip" psql -h localhost -p 54329 -U paperclip -d paperclip
+COMPANY_ID: ebe10308-efd7-453f-86ab-13e6fe84004f
+```
+
+## Tiers de heartbeat
+
+| Tier | Intervalo | Uso |
+|------|-----------|-----|
+| 1 | 1h (3600s) | CEO, agentes criticos |
+| 2 | 2h (7200s) | C-Level activos |
+| 3 | 4h (14400s) | Directores |
+| 4 | 6h (21600s) | Especialistas com rotina |
+| 5 | on-demand | Especialistas reactivos (sem timer) |
+
+## Modo lista (sem argumentos)
+
+Listar agentes com heartbeat configurado:
+
+```sql
+SELECT name, role, status,
+  runtime_config->'heartbeat'->>'enabled' as hb_enabled,
+  runtime_config->'heartbeat'->>'intervalSec' as hb_interval,
+  last_heartbeat_at
+FROM agents
+WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
+AND runtime_config::text != '{}'
+AND runtime_config->'heartbeat' IS NOT NULL
+ORDER BY (runtime_config->'heartbeat'->>'intervalSec')::int ASC NULLS LAST;
+```
+
+Complementar com contagem de execucoes recentes:
+
+```sql
+SELECT a.name,
+  COUNT(CASE WHEN hr.status = 'succeeded' THEN 1 END) as ok_24h,
+  COUNT(CASE WHEN hr.status = 'failed' THEN 1 END) as fail_24h
+FROM agents a
+LEFT JOIN heartbeat_runs hr ON hr.agent_id = a.id
+  AND hr.started_at > NOW() - INTERVAL '24 hours'
+WHERE a.company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
+AND a.runtime_config->'heartbeat' IS NOT NULL
+GROUP BY a.name
+ORDER BY a.name;
+```
+
+## Modo ver (com nome de agente)
+
+Ultimas 10 execucoes de um agente:
+
+```sql
+SELECT hr.status, hr.started_at, hr.finished_at, LEFT(hr.error, 80) as erro
+FROM heartbeat_runs hr
+JOIN agents a ON hr.agent_id = a.id
+WHERE a.company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
+AND LOWER(a.name) LIKE LOWER('%{{NOME}}%')
+ORDER BY hr.started_at DESC LIMIT 10;
+```
+
+## Modo criar/editar (configurar heartbeat)
+
+### Activar heartbeat
+
+```sql
+UPDATE agents SET runtime_config = jsonb_set(
+  COALESCE(runtime_config, '{}'::jsonb),
+  '{heartbeat}',
+  '{"enabled": true, "intervalSec": {{INTERVALO}}, "cooldownSec": 10, "wakeOnDemand": true, "maxConcurrentRuns": 1}'::jsonb
+)
+WHERE name = '{{NOME}}'
+AND company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
+RETURNING name, runtime_config;
+```
+
+Confirmar sempre com o utilizador:
+- Nome do agente
+- Intervalo (sugerir tier adequado ao role)
+- wakeOnDemand (true para a maioria)
+
+### Desactivar heartbeat
+
+```sql
+UPDATE agents SET runtime_config = jsonb_set(
+  runtime_config,
+  '{heartbeat,enabled}',
+  'false'::jsonb
+)
+WHERE name = '{{NOME}}'
+AND company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
+RETURNING name, runtime_config;
+```
+
+### Alterar intervalo
+
+```sql
+UPDATE agents SET runtime_config = jsonb_set(
+  runtime_config,
+  '{heartbeat,intervalSec}',
+  '{{INTERVALO}}'::jsonb
+)
+WHERE name = '{{NOME}}'
+AND company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
+RETURNING name, runtime_config;
+```
+
+## Routines do projecto (tabela routines)
+
+Alem dos heartbeats por agente, existem routines organizadas por projecto com cron triggers.
+
+**Estado actual:** 5 routines activas no Paperclip. 9 routines anteriores foram migradas para workflows n8n em https://automator.descomplicar.pt.
+
+**5 routines Paperclip:**
+- Auditoria processos e compliance (0 10 * * *)
+- Execução tarefas AikTop (*/30 * * * *)
+- Reconciliação financeira diária (0 8 * * *)
+- Varredura inteligência competitiva (0 11 * * *)
+- Monitorização workflows n8n (0 10,18 * * *) — atribuída ao COO
+
+### Listar routines activas
+
+```sql
+SELECT r.title, r.status, r.priority, a.name as assignee,
+  rt.cron_expression, rt.enabled, rt.next_run_at
+FROM routines r
+LEFT JOIN agents a ON r.assignee_agent_id = a.id
+LEFT JOIN routine_triggers rt ON rt.routine_id = r.id
+WHERE r.company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
+ORDER BY r.title;
+```
+
+### Ver execucoes de uma routine
+
+```sql
+SELECT rr.status, rr.triggered