---
name: clip-instructions
description: Editar e gerir AGENTS.md de agentes Paperclip — ver, editar, rever histórico de versões. O AGENTS.md é o "cérebro" do agente. Usar quando "clip instructions", "editar agente", "atualizar AGENTS.md", "mudar comportamento agente", "instruções agente".
context: fork
version: "1.0.0"
created: 2026-04-07
---

# /clip-instructions — Gerir AGENTS.md dos Agentes

O `AGENTS.md` é o ficheiro de instruções que define identidade, missão, comportamento e regras de cada agente. É injectado a cada heartbeat — editar o ficheiro tem efeito imediato no próximo run.

Aceita argumento: nome do agente (ex: `/clip-instructions CTO`).

## Constantes

```
BD: PGPASSWORD="paperclip" psql -h localhost -p 54329 -U paperclip -d paperclip
COMPANY_ID: ebe10308-efd7-453f-86ab-13e6fe84004f
```

## Passo 1: Encontrar agente e localizar AGENTS.md

```sql
SELECT id, name, role, title,
  adapter_config->>'instructionsFilePath' as instructions_path,
  adapter_config->>'instructionsRootPath' as instructions_root
FROM agents
WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
AND LOWER(name) LIKE LOWER('%{{NOME}}%');
```

Se `instructions_path` é NULL ou não começa com `/` → CRITICO (AGENTS.md não está a ser carregado).

## Passo 2: Ler ficheiro actual

```bash
cat "{{instructions_path}}"
```

Apresentar conteúdo completo. Identificar secções:
- `## Identidade` — nome, papel, tipo, modelo, budget
- `## Missão` — objectivo principal
- `## Comportamento` — regras de actuação
- `## Skills` / `## MCPs` — ferramentas
- `## Heartbeat` — intervalo, checklist
- `## Equipa` — quem reporta a quem

## Passo 3: Modo de actuação

### Ver (sem edições pedidas)
Apresentar resumo estruturado das secções principais.

### Editar (utilizador pede alteração específica)

1. Ler ficheiro completo com Read
2. Identificar a secção a alterar
3. Propor a alteração ao utilizador ("Vou mudar X para Y — confirmas?")
4. Executar com Edit após confirmação
5. Verificar que o ficheiro ficou correcto

**Regras de edição segura:**
- Nunca reescrever o ficheiro completo — usar Edit para alterações cirúrgicas
- Preservar frontmatter YAML se existir
- Manter estrutura de secções existente
- Após editar, mostrar diff resumido das alterações

### Criar novo AGENTS.md (agente sem instruções)

Se `instructions_path` está definido mas o ficheiro não existe:

```bash
ls "{{instructions_path}}" 2>/dev/null || echo "NAO_EXISTE"
```

Criar directório se necessário:
```bash
mkdir -p "{{instructions_root}}"
```

Template mínimo para novo AGENTS.md:
```markdown
# {{NOME}}

## Identidade

- **Nome:** {{NOME}}
- **Papel:** {{ROLE}} — reporta ao {{SUPERVISOR}}
- **Tipo:** {{TIPO}} (executor/analyst/manager)
- **Modelo:** {{MODELO}}
- **Budget:** {{BUDGET}} cents/mês

## Missão

{{DESCRICAO_MISSAO}}

## Comportamento

### Regras

- **Foco** — executar apenas tarefas dentro do scope definido
- **Escalação** — problemas fora de scope → reportar ao supervisor
- **PT-PT** — sempre com acentuação correcta

## Heartbeat

- **Intervalo:** {{INTERVALO}}s
- **Checklist:** ver issues atribuídas, executar, reportar

## Equipa

- Reporta ao: {{SUPERVISOR}}
```

## Passo 4: Verificar após edição

Confirmar que o Paperclip reconhece o ficheiro actualizado:
```bash
curl -s "http://localhost:3100/api/agents/{{AGENT_ID}}/instructions-bundle" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" | python3 -c "import sys,json; d=json.load(sys.stdin); print('OK' if d.get('content') else 'VAZIO')"
```

- OK = AGENTS.md carregado pelo servidor
- VAZIO / erro = path errado ou ficheiro não encontrado

## Casos especiais

### Actualizar model no AGENTS.md

Se o agente mudou de modelo (ex: gemini → claude), actualizar tanto o AGENTS.md como o `adapter_config`:
```sql
UPDATE agents
SET adapter_config = jsonb_set(adapter_config, '{model}', '"{{NOVO_MODELO}}"'::jsonb)
WHERE id = '{{AGENT_ID}}'
AND company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f';
```

### Rever historial de versões (config_revisions)

```sql
SELECT cr.id, cr.created_at::timestamp(0), a.name as criado_por
FROM agent_config_revisions cr
LEFT JOIN agents a ON cr.created_by_agent_id = a.id
WHERE cr.agent_id = '{{AGENT_ID}}'
ORDER BY cr.created_at DESC
LIMIT 10;
```

### Rollback via API

```bash
curl -s -X POST "http://localhost:3100/api/agents/{{AGENT_ID}}/config-revisions/{{REVISION_ID}}/rollback" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

---

## Formato de output

```
## Instruções — {{NOME}} ({{role}})

**Ficheiro:** {{instructions_path}}
**Estado:** carregado / não encontrado / path inválido

### Resumo actual
**Missão:** [1 linha]
**Modelo:** {{model}} | **Budget:** {{budget}} cents | **Heartbeat:** {{intervalo}}s
**Regras principais:** [lista]
**Skills:** [lista ou "nenhuma"]

### Alterações efectuadas (se editou)
[diff resumido]
```

---

## Healing Log

```jsonl
{"date":"2026-04-07","issue":"instructionsFilePath relativo — AGENTS.md não carregava após criação via SQL","fix":"Path deve ser sempre absoluto. Verificar com query adapter_config->>'instructionsFilePath' NOT LIKE '/%'","source":"auto"}
```