feat(gestao): adicionar 9 skills /clip-* + migrar 5 para diag tools MCP
Skills clip-* nunca tinham sido committed. Adicionadas todas (9): clip, clip-agent, clip-health, clip-instructions, clip-issue, clip-org, clip-routine, clip-skill, clip-vision. Migração para mcp__paperclip__diag_* (17 substituições em 5 skills): - clip: 5 substituições (agents_by_status, false_blockers, token burn, stuck routines, company_skills_summary) - clip-agent: 2 (agent_full_context consolida 4 passos, false_blockers) - clip-health: 8 (budget_orphans, missing_permissions, missing_heartbeat, routine_triggers_broken, false_blockers, heartbeat_token_usage, prompt_too_long_errors, stuck_routines, zombie_parents) - clip-org: 1 (agent_hierarchy) - clip-routine: 1 (routine_triggers_broken) Sem substituições (CRUD-específico sem diag_* equivalente): clip-instructions, clip-issue, clip-skill — mantêm psql. Refs: Desk #2041, mcp-paperclip feature/diagnostics-db Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,200 @@
|
||||
---
|
||||
name: clip-issue
|
||||
description: Criar e gerir issues Paperclip — lançar objectivos ao CEO, ver progresso, comentar. Usar quando "clip issue", "criar issue", "lançar objectivo", "ver issues clip". Issues seguem cadeia de delegação hierárquica.
|
||||
context: fork
|
||||
---
|
||||
|
||||
# /clip-issue — Gerir Issues Paperclip
|
||||
|
||||
Modos: lista (sem args), criar (com titulo), ver (com ID).
|
||||
|
||||
## Constantes
|
||||
|
||||
```
|
||||
BD: PGPASSWORD="paperclip" psql -h localhost -p 54329 -U paperclip -d paperclip
|
||||
COMPANY_ID: ebe10308-efd7-453f-86ab-13e6fe84004f
|
||||
API: http://localhost:3100/api
|
||||
```
|
||||
|
||||
## Modo lista (sem argumentos)
|
||||
|
||||
```sql
|
||||
SELECT i.id, i.title, i.status, i.priority, a.name as assignee, i.created_at
|
||||
FROM issues i LEFT JOIN agents a ON i.assignee_agent_id = a.id
|
||||
WHERE i.company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
|
||||
AND i.status NOT IN ('done','cancelled')
|
||||
ORDER BY
|
||||
CASE i.priority WHEN 'critical' THEN 1 WHEN 'high' THEN 2 WHEN 'medium' THEN 3 ELSE 4 END,
|
||||
i.status, i.created_at DESC;
|
||||
```
|
||||
|
||||
Para ver concluidas tambem:
|
||||
```sql
|
||||
-- Adicionar: AND i.status IN ('done') AND i.updated_at > NOW() - INTERVAL '7 days'
|
||||
```
|
||||
|
||||
## Modo criar (com titulo)
|
||||
|
||||
### Passo 1: Obter CEO ID
|
||||
|
||||
```sql
|
||||
SELECT id FROM agents
|
||||
WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
|
||||
AND name = 'CEO';
|
||||
```
|
||||
|
||||
### Passo 2: Criar issue
|
||||
|
||||
Preferir API (quando JWT funciona):
|
||||
```bash
|
||||
curl -s -X POST "http://localhost:3100/api/companies/ebe10308-efd7-453f-86ab-13e6fe84004f/issues" \
|
||||
-H "Authorization: Bearer $PAPERCLIP_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"title": "{{TITULO}}",
|
||||
"description": "{{DESCRICAO}}",
|
||||
"priority": "{{PRIORIDADE}}",
|
||||
"assigneeAgentId": "{{CEO_ID}}"
|
||||
}'
|
||||
```
|
||||
|
||||
Fallback via BD (OBRIGATORIO incluir identifier e issue_number):
|
||||
```sql
|
||||
-- Passo 2a: Obter proximo numero
|
||||
SELECT issue_counter FROM companies WHERE id = 'ebe10308-efd7-453f-86ab-13e6fe84004f';
|
||||
-- Guardar o valor como NEXT_NUM
|
||||
|
||||
-- Passo 2b: Criar issue COM identifier
|
||||
INSERT INTO issues (id, company_id, title, description, priority, assignee_agent_id, status, identifier, issue_number, created_at, updated_at)
|
||||
VALUES (
|
||||
gen_random_uuid(),
|
||||
'ebe10308-efd7-453f-86ab-13e6fe84004f',
|
||||
'{{TITULO}}',
|
||||
'{{DESCRICAO}}',
|
||||
'{{PRIORIDADE}}',
|
||||
'{{CEO_ID}}',
|
||||
'todo',
|
||||
'DES-{{NEXT_NUM}}',
|
||||
{{NEXT_NUM}},
|
||||
NOW(), NOW()
|
||||
)
|
||||
RETURNING id, identifier, title, status;
|
||||
|
||||
-- Passo 2c: Incrementar counter (CRITICO — nunca esquecer)
|
||||
UPDATE companies SET issue_counter = {{NEXT_NUM}} + 1 WHERE id = 'ebe10308-efd7-453f-86ab-13e6fe84004f';
|
||||
```
|
||||
|
||||
**NUNCA criar issues via SQL sem identifier e issue_number.** Causa bug de duplicate key que bloqueia toda a criacao de issues no Paperclip.
|
||||
|
||||
Confirmar titulo e prioridade com o utilizador antes de criar. Prioridades: critical, high, medium, low.
|
||||
|
||||
### Nota sobre delegação hierárquica
|
||||
|
||||
Issues criadas pelo Board (Emanuel) são sempre atribuídas ao CEO. O CEO delega pela cadeia:
|
||||
- CEO cria sub-issue ao C-Level adequado
|
||||
- C-Level cria sub-issue ao Director
|
||||
- Director atribui ao especialista
|
||||
|
||||
Quando routines disparam, geram issues ao CEO que segue o mesmo fluxo. A cadeia está na descrição da routine (campo `description` começa com `CADEIA: CEO → ...`).
|
||||
|
||||
## Semântica de estados (referência rápida)
|
||||
|
||||
Ao criar, alterar ou interpretar estados de issues:
|
||||
|
||||
- **`todo`** — não iniciada, aguarda pickup
|
||||
- **`in_progress`** — trabalho em curso, **incluindo aguardar sub-tasks delegadas**
|
||||
- **`blocked`** — APENAS impedimento real (agente em erro, falta de permissão, dependência externa, aguarda decisão humana)
|
||||
- **`done`** — concluída com resultado verificado
|
||||
- **`cancelled`** — abandonada por decisão superior
|
||||
|
||||
**Regra INC-07:** `blocked` ≠ "delegué e estou à espera". Aguardar sub-task activa = `in_progress`. Se ao listar issues vires `blocked` sem impedimento real, alertar o utilizador.
|
||||
|
||||
## Modo ver (com ID ou titulo parcial)
|
||||
|
||||
```sql
|
||||
SELECT i.*, a.name as assignee
|
||||
FROM issues i LEFT JOIN agents a ON i.assignee_agent_id = a.id
|
||||
WHERE i.company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
|
||||
AND (i.id::text LIKE '%{{ARG}}%' OR LOWER(i.title) LIKE LOWER('%{{ARG}}%'));
|
||||
```
|
||||
|
||||
Comentarios:
|
||||
```sql
|
||||
SELECT ic.body, ic.created_at, a.name as author
|
||||
FROM issue_comments ic
|
||||
LEFT JOIN agents a ON ic.author_agent_id = a.id
|
||||
WHERE ic.issue_id = '{{ISSUE_ID}}'
|
||||
ORDER BY ic.created_at ASC;
|
||||
```
|
||||
|
||||
## Modo comentar
|
||||
|
||||
```sql
|
||||
INSERT INTO issue_comments (id, company_id, issue_id, author_user_id, body, created_at, updated_at)
|
||||
VALUES (gen_random_uuid(), 'ebe10308-efd7-453f-86ab-13e6fe84004f', '{{ISSUE_ID}}', 'v1N5OccPn9DGq6iog7qW9nEvnXYFT3iO', '{{COMENTARIO}}', NOW(), NOW())
|
||||
RETURNING id;
|
||||
```
|
||||
|
||||
Nota: `author_user_id = 'v1N5OccPn9DGq6iog7qW9nEvnXYFT3iO'` (Emanuel) → comentário aparece como Board/humano no dashboard. Nunca usar `'board'` — não é um user_id válido.
|
||||
|
||||
## Modo checkout / release
|
||||
|
||||
Checkout reserva a issue para trabalho activo (sinaliza ao Paperclip que está em curso).
|
||||
Release liberta a issue de volta a `todo`.
|
||||
|
||||
**Checkout via API:**
|
||||
```bash
|
||||
curl -s -X POST "http://localhost:3100/api/issues/{{ISSUE_ID}}/checkout" \
|
||||
-H "Authorization: Bearer $PAPERCLIP_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"agentId": "{{AGENT_ID}}"}'
|
||||
```
|
||||
|
||||
**Release via API:**
|
||||
```bash
|
||||
curl -s -X POST "http://localhost:3100/api/issues/{{ISSUE_ID}}/release" \
|
||||
-H "Authorization: Bearer $PAPERCLIP_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{}'
|
||||
```
|
||||
|
||||
**Fallback via BD (se API falhar):**
|
||||
```sql
|
||||
-- Checkout manual
|
||||
UPDATE issues SET status = 'in_progress', updated_at = NOW()
|
||||
WHERE id = '{{ISSUE_ID}}'
|
||||
AND company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
|
||||
RETURNING identifier, title, status;
|
||||
|
||||
-- Release manual
|
||||
UPDATE issues SET status = 'todo', updated_at = NOW()
|
||||
WHERE id = '{{ISSUE_ID}}'
|
||||
AND company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
|
||||
RETURNING identifier, title, status;
|
||||
```
|
||||
|
||||
**Nota:** O par checkout/release é importante para o pipeline do Paperclip — evita que dois agentes peguem na mesma issue em simultâneo.
|
||||
|
||||
## Formato de output
|
||||
|
||||
Adaptar ao modo. Para lista:
|
||||
```
|
||||
## Issues Clip — [data]
|
||||
|
||||
| # | Titulo | Status | Prioridade | Assignee |
|
||||
...
|
||||
|
||||
Total: N abertas (N critical, N high, N medium, N low)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Healing Log
|
||||
|
||||
Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.
|
||||
|
||||
```jsonl
|
||||
{"date":"2026-04-07","issue":"author_user_id = 'board' em comentários — não é user_id válido, comentário não aparecia no dashboard","fix":"Usar 'v1N5OccPn9DGq6iog7qW9nEvnXYFT3iO' (ID real de Emanuel no Paperclip)","source":"auto"}
|
||||
```
|
||||
|
||||
*Adicionar nova linha após cada erro corrigido.*
|
||||
Reference in New Issue
Block a user