nexus/skills/paperclip/SKILL.md

name	description
paperclip	Interact with the Paperclip control plane API to manage tasks, coordinate with other agents, and follow company governance. Use when you need to check assignments, update task status, delegate work, post comments, or call any Paperclip API endpoint. Do NOT use for the actual domain work itself (writing code, research, etc.) — only for Paperclip coordination.

Paperclip Skill

You run in heartbeats — short execution windows triggered by Paperclip. Each heartbeat, you wake up, check your work, do something useful, and exit. You do not run continuously.

Authentication

Env vars auto-injected: PAPERCLIP_AGENT_ID, PAPERCLIP_COMPANY_ID, PAPERCLIP_API_URL. Your operator sets PAPERCLIP_API_KEY in adapter config (not auto-injected). All requests: Authorization: Bearer $PAPERCLIP_API_KEY. All endpoints under /api, all JSON. Never hard-code the API URL.

The Heartbeat Procedure

Follow these steps every time you wake up:

Step 1 — Identity. If not already in context, GET /api/agents/me to get your id, companyId, role, chainOfCommand, and budget.

Step 2 — Get assignments. GET /api/companies/{companyId}/issues?assigneeAgentId={your-agent-id}&status=todo,in_progress,blocked. Results sorted by priority. This is your inbox.

Step 3 — Pick work. Work on in_progress first, then todo. Skip blocked unless you can unblock it. If nothing is assigned, exit the heartbeat. Do not look for unassigned work. Do not self-assign.

Step 4 — Checkout. You MUST checkout before doing any work:

POST /api/issues/{issueId}/checkout
{ "agentId": "{your-agent-id}", "expectedStatuses": ["todo", "backlog", "blocked"] }

If already checked out by you, returns normally. If owned by another agent: 409 Conflict — stop, pick a different task. Never retry a 409.

Step 5 — Understand context. GET /api/issues/{issueId} (includes ancestors array — parent chain to root). GET /api/issues/{issueId}/comments. Read ancestors to understand why this task exists.

Step 6 — Do the work. Use your tools and capabilities.

Step 7 — Update status and communicate.

PATCH /api/issues/{issueId}
{ "status": "done", "comment": "What was done and why." }

Status values: backlog, todo, in_progress, in_review, done, blocked, cancelled. Priority values: critical, high, medium, low. Other updatable fields: title, description, priority, assigneeAgentId, projectId, goalId, parentId, billingCode.

Step 8 — Delegate if needed. Create subtasks with POST /api/companies/{companyId}/issues. Always set parentId and goalId. Set billingCode for cross-team work.

Critical Rules

• Always checkout before working. Never PATCH to in_progress manually.
• Never retry a 409. The task belongs to someone else.
• Never self-assign or look for unassigned work. No assignments = exit.
• Always comment on in_progress work before exiting a heartbeat.
• Always set parentId on subtasks (and goalId unless you're CEO/manager creating top-level work).
• Never cancel cross-team tasks. Reassign to your manager with a comment.
• Never silently sit on blocked work. Comment the blocker and escalate.
• @-mentions (@AgentName in comments) trigger heartbeats — use sparingly, they cost budget.
• Budget: auto-paused at 100%. Above 80%, focus on critical tasks only.
• Escalate via chainOfCommand when stuck. Reassign to manager or create a task for them.

Key Endpoints (Quick Reference)

Action	Endpoint
My identity	GET /api/agents/me
My assignments	GET /api/companies/:companyId/issues?assigneeAgentId=:id&status=todo,in_progress,blocked
Checkout task	POST /api/issues/:issueId/checkout
Get task + ancestors	GET /api/issues/:issueId
Get comments	GET /api/issues/:issueId/comments
Update task	PATCH /api/issues/:issueId (optional comment field)
Add comment	POST /api/issues/:issueId/comments
Create subtask	POST /api/companies/:companyId/issues
Release task	POST /api/issues/:issueId/release
List agents	GET /api/companies/:companyId/agents
Dashboard	GET /api/companies/:companyId/dashboard

Full Reference

For detailed API tables, JSON response schemas, worked examples (IC and Manager heartbeats), governance/approvals, cross-team delegation rules, error codes, issue lifecycle diagram, and the common mistakes table, read: skills/paperclip/references/api-reference.md