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,166 @@
+---
+name: clip-agent
+description: Gerir agente Paperclip individual — estado, config, AGENTS.md, histórico runs, issues. Aceita nome como argumento. Usar quando "clip agent", "agente clip", "ver agente", "estado do CTO".
+context: fork
+layer: wiki
+---
+
+# /clip-agent — Gerir Agente Paperclip
+
+Aceita argumento: nome do agente (ex: `/clip-agent CTO`).
+
+## Constantes
+
+```
+BD: PGPASSWORD="paperclip" psql -h localhost -p 54329 -U paperclip -d paperclip
+COMPANY_ID: ebe10308-efd7-453f-86ab-13e6fe84004f
+AGENTS_PATH: /media/ealmeida/Dados/Hub/04-Stack/02.06-Clip/agents/
+```
+
+## Procedimento
+
+### Passo 1: Contexto completo do agente
+
+Invocar tool MCP: `mcp__paperclip__diag_agent_full_context(agent_name="{{NOME}}")`
+
+Esta tool retorna config, últimas runs, membership, permissões e tokens — cobre os Passos 1, 3, 6, 7 e 7b de uma só vez. Se multiplos resultados, mostrar lista e pedir clarificacao.
+
+### Passo 2: Hierarquia
+
+Quem lhe reporta:
+```sql
+SELECT name, role, status FROM agents
+WHERE reports_to = '{{AGENT_ID}}'
+AND company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
+ORDER BY role, name;
+```
+
+A quem reporta:
+```sql
+SELECT name, role FROM agents WHERE id = '{{REPORTS_TO_ID}}';
+```
+
+### Passo 3: Ultimas 5 runs
+
+```sql
+SELECT hr.status, hr.started_at, hr.finished_at, LEFT(hr.error, 80) as erro
+FROM heartbeat_runs hr
+WHERE hr.agent_id = '{{AGENT_ID}}'
+ORDER BY hr.started_at DESC LIMIT 5;
+```
+
+### Passo 4: Issues atribuidas
+
+```sql
+SELECT title, status, priority FROM issues
+WHERE assignee_agent_id = '{{AGENT_ID}}'
+AND status NOT IN ('done','cancelled')
+ORDER BY priority, status;
+```
+
+### Passo 4b: Verificar falsos blockers (INC-07)
+
+Se o agente tem issues `blocked`, invocar tool MCP: `mcp__paperclip__diag_false_blockers` e filtrar pelo agente. TODO: criar diag_* tool per-agent se uso recorrente.
+
+Se `sub_activas > 0` e o agente está operacional → falso blocker. Alertar: "Issue {{ID}} marcada como blocked mas tem sub-tasks activas — deveria ser in_progress."
+
+### Passo 5: AGENTS.md
+
+Procurar em `AGENTS_PATH`:
+```bash
+find /media/ealmeida/Dados/Hub/04-Stack/02.06-Clip/agents/ -name "AGENTS.md" -exec grep -l "{{NOME}}" {} \;
+```
+
+Se encontrado, ler e apresentar resumo (primeiras 30 linhas).
+
+## Formato de output
+
+```
+## Agente: {{NOME}}
+
+**Role:** {{role}} | **Status:** {{status}} | **Ultimo heartbeat:** {{last_heartbeat_at}}
+**Reporta a:** {{reports_to_name}} | **Budget:** {{spent}}/{{budget}} ({{pct}}%)
+**Tokens cached:** {{tokens_M}}M | **CWD:** {{cwd}} | **Model:** {{model}}
+
+### Equipa (reportam a este agente)
+| Nome | Role | Status |
+...
+
+### Ultimas 5 runs
+| Status | Início | Fim | Erro |
+...
+
+### Issues atribuidas
+| Titulo | Status | Prioridade |
+...
+
+### Skills atribuidas
+[lista de desiredSkills ou "Sem skills (apenas built-in paperclip)"]
+
+### AGENTS.md
+[resumo ou path]
+```
+
+### Passo 6: Skills do agente
+
+```sql
+SELECT
+  adapter_config->'paperclipSkillSync'->'desiredSkills' as desired_skills
+FROM agents
+WHERE id = '{{AGENT_ID}}';
+```
+
+Se nao NULL, listar as skills. Se NULL, indicar "Sem skills atribuidas (apenas built-in paperclip)".
+
+Para ver detalhes das skills disponiveis na empresa:
+```sql
+SELECT name, slug, key, source_type FROM company_skills
+WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
+ORDER BY name;
+```
+
+### Skills atribuídas ao agente
+
+```sql
+-- Ver skills desejadas (configuradas via API)
+SELECT
+  a.name as agente,
+  a.adapter_config->'paperclipSkillSync'->'desiredSkills' as desired_skills
+FROM agents a
+WHERE a.id = '{{AGENT_ID}}';
+```
+
+**Acções disponíveis:**
+- Ver skills da empresa: `SELECT name, slug FROM company_skills WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'`
+- Atribuir skills via API (fetch no browser): `POST /api/agents/{{AGENT_ID}}/skills/sync` com `{ "desiredSkills": ["slug1", "slug2"] }`
+
+### Membership (OBRIGATÓRIO — sem isto, permissões não funcionam)
+
+A função `hasPermission()` verifica **primeiro** se o agente tem membership activa em `company_memberships`. Sem membership → permissão negada mesmo com grants correctos.
+
+```sql
+-- Verificar membership
+SELECT status, membership_role FROM company_memberships
+WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
+AND principal_id = '{{AGENT_ID}}';
+```
+
+Se **0 rows** → agente não tem membership. Criar:
+```sql
+INSERT INTO company_memberships (id, company_id, principal_type, principal_id, status, membership_role, created_at, updated_at)
+VALUES (gen_random_uuid(), 'ebe10308-efd7-453f-86ab-13e6fe84004f', 'agent', '{{AGENT_ID}}', 'active', 'member', NOW(), NOW());
+```
+
+**Nota:** Agentes criados via SQL directo NÃO recebem membership automaticamente — apenas os onboarded via fluxo OpenClaw/hiring. Sempre criar membership ao adicionar agentes manualmente.
+
+### Permissões do agente
+
+```sql
+SELECT permission_key FROM principal_permission_grants
+WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
+AND principal_id = '{{AGENT_ID}}';
+```
+
+Para adicionar `tasks:assign` (necessário para delegação):
+```sql
+INSERT INTO principal_permissi