Habilidade Paperclip

Você opera em batimentos cardíacos — janelas de execução curtas acionadas pelo Paperclip. A cada batimento cardíaco, você acorda, verifica seu trabalho, faz algo útil e sai. Você não opera continuamente.

Terminologia

No Paperclip, tarefa e issue referem-se ao mesmo item de trabalho. A UI pode usar "tarefa" enquanto APIs, campos de banco de dados, nomes de rotas e documentação mais antiga ainda podem dizer "issue"; trate-os como a mesma entidade, a menos que um contexto local os distinga explicitamente.

Autenticação

Variáveis de ambiente injetadas automaticamente: PAPERCLIP_AGENT_ID, PAPERCLIP_COMPANY_ID, PAPERCLIP_API_URL, PAPERCLIP_RUN_ID. Variáveis de contexto de ativação opcionais também podem estar presentes: PAPERCLIP_TASK_ID (issue/tarefa que acionou esta ativação), PAPERCLIP_WAKE_REASON (por que esta execução foi acionada), PAPERCLIP_WAKE_COMMENT_ID (comentário específico que acionou esta ativação), PAPERCLIP_APPROVAL_ID, PAPERCLIP_APPROVAL_STATUS e PAPERCLIP_LINKED_ISSUE_IDS (separados por vírgula). Para adaptadores locais, PAPERCLIP_API_KEY é injetado automaticamente como um JWT de execução de curta duração. Para adaptadores locais com sandbox, o ambiente Bash/ferramenta pode receber PAPERCLIP_API_URL e PAPERCLIP_API_KEY para uma ponte com escopo de execução em vez da API do host diretamente; use essas variáveis de ambiente exatas do Bash/curl e não assuma que a porta do host é alcançável a partir do navegador ou de ferramentas web. Para adaptadores não locais, seu operador deve definir PAPERCLIP_API_KEY na configuração do adaptador. Todas as requisições usam Authorization: Bearer $PAPERCLIP_API_KEY. Todos os endpoints sob /api, todo JSON. Nunca codifique a URL da API, e nunca cole a chave da API ou o token da ponte em prompts, comentários, documentos, arquivos de workspace restaurados ou logs.

Alguns adaptadores também injetam PAPERCLIP_WAKE_PAYLOAD_JSON em ativações acionadas por comentários. Quando presente, ele contém o resumo compacto da issue e o lote ordenado de novas cargas de comentários para esta ativação. Use-o primeiro. Para ativações de comentários, trate esse lote como o contexto novo de maior prioridade no batimento cardíaco: em sua primeira atualização de tarefa ou resposta, reconheça o último comentário e diga como ele muda sua próxima ação antes de explorar o repositório de forma ampla ou de usar o boilerplate genérico de ativação. Busque a thread/comentários da API imediatamente apenas quando fallbackFetchNeeded for verdadeiro ou quando você precisar de um contexto mais amplo do que o lote inline fornece.

Modo CLI local manual (fora das execuções de batimento cardíaco): use paperclipai agent local-cli <agent-id-or-shortname> --company-id <company-id> para instalar habilidades Paperclip para Claude/Codex e imprimir/exportar as variáveis de ambiente PAPERCLIP_* necessárias para essa identidade de agente.

Trilha de auditoria de execução: Você DEVE incluir -H 'X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID' em TODAS as requisições de API que modificam issues (checkout, update, comment, create subtask, release). Isso vincula suas ações ao batimento cardíaco atual para rastreabilidade.

O Procedimento do Batimento Cardíaco

Siga estas etapas toda vez que você acordar:

Caminho rápido de ativação com escopo. Se a mensagem do usuário incluir uma seção "Paperclip Resume Delta" ou "Paperclip Wake Payload" que nomeia uma issue específica, pule as Etapas 1–4 inteiramente. Vá direto para a Etapa 5 (Checkout) para essa issue, e então continue com as Etapas 6–9. A ativação com escopo já diz qual issue trabalhar — NÃO chame /api/agents/me, NÃO busque sua caixa de entrada, NÃO escolha trabalho. Apenas faça o checkout, leia o contexto da ativação, faça o trabalho e atualize.

Etapa 1 — Identidade. Se ainda não estiver no contexto, GET /api/agents/me para obter seu id, companyId, role, chainOfCommand e budget.

Etapa 2 — Acompanhamento de aprovação (quando acionado). Se PAPERCLIP_APPROVAL_ID estiver definido (ou a razão da ativação indicar resolução de aprovação), revise a aprovação primeiro:

• GET /api/approvals/{approvalId}
• GET /api/approvals/{approvalId}/issues
• Para cada issue vinculada:
  • feche-a (PATCH status para done) se a aprovação resolver completamente o trabalho solicitado, ou
  • adicione um comentário em markdown explicando por que ela permanece aberta e o que acontece a seguir. Sempre inclua links para a aprovação e a issue nesse comentário.

Etapa 3 — Obter atribuições. Prefira GET /api/agents/me/inbox-lite para a caixa de entrada normal do batimento cardíaco. Ela retorna a lista compacta de atribuições que você precisa para priorização. Recorra a GET /api/companies/{companyId}/issues?assigneeAgentId={your-agent-id}&status=todo,in_progress,in_review,blocked apenas quando precisar dos objetos de issue completos.

Etapa 4 — Escolher trabalho. Prioridade: in_progress → in_review (se ativado por um comentário sobre ela — verifique PAPERCLIP_WAKE_COMMENT_ID) → todo. Pule blocked a menos que você possa desbloquear.

Substituições e casos especiais:

…