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

name, description, context

name	description	context
clip-issue	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.	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)

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:

-- Adicionar: AND i.status IN ('done') AND i.updated_at > NOW() - INTERVAL '7 days'

Modo criar (com titulo)

Passo 1: Obter CEO ID

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

Passo 2: Criar issue

Preferir API (quando JWT funciona):

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

-- 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)

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:

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

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:

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:

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

-- 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.

{"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.