claude-plugins/gestao/skills/clip-routine/SKILL.md

name, description, context

name	description	context
clip-routine	Gerir routines Paperclip — listar crons activos, ver execuções, criar/editar routines. Usar quando "clip routine", "routines clip", "crons paperclip", "automações clip".	fork

/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:

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:

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:

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

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

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

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

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

SELECT rr.status, rr.triggered_at, rr.completed_at, LEFT(rr.error, 80) as erro
FROM routine_runs rr
JOIN routines r ON rr.routine_id = r.id
WHERE r.company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
AND LOWER(r.title) LIKE LOWER('%{{TITULO}}%')
ORDER BY rr.triggered_at DESC LIMIT 10;

Modo criar routine (nova)

Passo 1: Obter CEO ID

SELECT id FROM agents
WHERE name = 'CEO' AND company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f';

Passo 2: Obter projecto

SELECT id, name FROM projects
WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f';

Passo 3: Criar routine (SEMPRE atribuída ao CEO)

INSERT INTO routines (id, company_id, project_id, title, description, assignee_agent_id, priority, status, created_at, updated_at)
VALUES (
  gen_random_uuid(),
  'ebe10308-efd7-453f-86ab-13e6fe84004f',
  '{{PROJECT_ID}}',
  '{{TITULO}}',
  'CADEIA: CEO → {{C_LEVEL}} → {{DIRECTOR}} → {{ESPECIALISTA}}. {{DESCRICAO_TAREFA}}',
  '{{CEO_ID}}',
  '{{PRIORIDADE}}',
  'active',
  NOW(), NOW()
)
RETURNING id, title;

Passo 4: Criar cron trigger

CRITICO: O kind DEVE ser 'schedule' (nao 'cron'). O scheduler do Paperclip so processa triggers com kind = 'schedule'. Tambem e OBRIGATORIO popular next_run_at — sem ele o scheduler ignora o trigger.

-- Calcular next_run_at antes de inserir
-- Para crons diarios (ex: 0 8 * * *), usar:
--   (CURRENT_DATE + 1) AT TIME ZONE 'Europe/Lisbon' + INTERVAL '{{HORA}} hours'
-- Para crons recorrentes (ex: 0 */4 * * *), calcular proximo slot

INSERT INTO routine_triggers (id, company_id, routine_id, kind, label, enabled, cron_expression, timezone, next_run_at, created_at, updated_at)
VALUES (
  gen_random_uuid(),
  'ebe10308-efd7-453f-86ab-13e6fe84004f',
  '{{ROUTINE_ID}}',
  'schedule',
  '{{LABEL}}',
  true,
  '{{CRON_EXPRESSION}}',
  'Europe/Lisbon',
  {{NEXT_RUN_AT}},
  NOW(), NOW()
)
RETURNING id, cron_expression, next_run_at;

Exemplos de next_run_at:

• 0 8 * * * → (CURRENT_DATE + 1) AT TIME ZONE 'Europe/Lisbon' + INTERVAL '8 hours'
• 0 */6 * * * → date_trunc('hour', NOW()) + INTERVAL '6 hours'
• 0 9 * * 1 → proxima segunda-feira as 09h

Confirmar sempre com o utilizador: título, cadeia, cron, projecto.

Diagnostico: routines que nao disparam

Se routines nao disparam, verificar:

Invocar tool MCP: mcp__paperclip__diag_routine_triggers_broken

Corrigir com:

UPDATE routine_triggers SET kind = 'schedule', next_run_at = {{NEXT_RUN}}, updated_at = NOW()
WHERE id = '{{TRIGGER_ID}}';

Diagnostico: pipeline noticias

Se noticias nao estao a ser publicadas, verificar esta cadeia:

1. Routine triggers → kind='schedule'? next_run_at populado? last_fired_at recente?
2. CEO heartbeat → apanha a issue da routine? delega ao CGO?
3. CGO → delega ao Intelligence Researcher?
4. Intelligence Researcher → cria issues PUBLICAR NOTICIA? (assignee fica NULL — normal)
5. Cron assign-copywriter.sh → atribui ao Copywriter a cada 5 min?
6. Copywriter → acorda com wakeOnDemand? publica no WordPress?
7. Artigo publicado → acentuacao OK? links com aspas? titulo normalizado?

Verificar ponto a ponto com:

-- Ponto 1: triggers
SELECT r.title, rt.kind, rt.next_run_at, rt.last_fired_at
FROM routine_triggers rt JOIN routines r ON rt.routine_id = r.id
WHERE r.title LIKE 'Pesquisa diaria%noticias%' ORDER BY rt.cron_expression;

-- Ponto 4-5: issues PUBLICAR NOTICIA
SELECT i.title, i.status, a.name as assignee, i.created_at
FROM issues i LEFT JOIN agents a ON i.assignee_agent_id = a.id
WHERE i.title LIKE 'PUBLICAR NOTICIA%' AND i.created_at > NOW() - INTERVAL '24 hours'
ORDER BY i.created_at DESC;

-- Ponto 6: Copywriter runs
SELECT hr.status, hr.started_at FROM heartbeat_runs hr
JOIN agents a ON hr.agent_id = a.id WHERE a.name = 'Copywriter'
AND hr.started_at > NOW() - INTERVAL '24 hours' ORDER BY hr.started_at DESC;

-- Ponto 7: artigos publicados (via SSH server)
-- wp --allow-root post list --category=noticias --date_query='{"after":"1 day ago"}' --fields=ID,post_title

Cadeias de delegação por área

Área	Cadeia
Infraestrutura/WP/Backups/SSL	CEO → CTO → Dir. Infraestrutura → Especialista
Desenvolvimento/MCPs/N8N	CEO → CTO → Dir. Desenvolvimento/Automação → Especialista
Email/Tickets/Processos	CEO → COO → Dir. Suporte/Operações → Especialista
Financeiro/Facturação	CEO → CFO → Dir. Financeiro → Finance Manager
Marketing/SEO/Conteúdo/Ads	CEO → CMO → Dir. relevante → Especialista
Vendas/Leads/Propostas	CEO → CRO → Dir. Comercial → Especialista
Inteligência/Pesquisa	CEO → CGO → Dir. IA/Estratégia → Especialista
Analytics/Dados	CEO → CDO → Analytics Agent

Formato de output

Para modo lista (heartbeats):

## Heartbeats Clip — [data]

| Agente | Tier | Intervalo | Enabled | Último HB | OK 24h | Fail 24h |
...

Para modo lista (routines):

## Routines Clip — [data]

| Título | Cron | Assignee | Cadeia | Próximo run | Enabled |
...

Total: 5 routines activas no Paperclip (4 atribuídas ao CEO, 1 ao COO) + 9 migradas para n8n

Para modo ver:

## Routine: {{NOME}}

**Cadeia:** {{cadeia_delegação}}
**Cron:** {{cron}} | **Enabled:** {{enabled}}
**Último trigger:** {{last_triggered_at}}

### Últimas 10 execuções
| Status | Triggered | Completed | Erro |
...

Taxa sucesso 24h: N/N (N%)

---

Healing Log

Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.

{"date":"","issue":"","fix":"","source":"user|auto"}

Adicionar nova linha após cada erro corrigido.