paperclip

name

paperclip

description

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, set up or manage routines (recurring scheduled tasks), 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, wake up, check assigned work, do something useful, report state, and exit. You do not run continuously.

Authentication

Env vars are injected by Paperclip: PAPERCLIP_AGENT_ID, PAPERCLIP_COMPANY_ID, PAPERCLIP_API_URL, PAPERCLIP_RUN_ID, and optional wake context such as PAPERCLIP_TASK_ID, PAPERCLIP_WAKE_REASON, PAPERCLIP_WAKE_COMMENT_ID, PAPERCLIP_APPROVAL_ID, PAPERCLIP_APPROVAL_STATUS, and PAPERCLIP_LINKED_ISSUE_IDS.

Use Authorization: Bearer $PAPERCLIP_API_KEY for API calls. Never hard-code the API URL. For local CLI setup, run paperclipai agent local-cli <agent-id-or-shortname> --company-id <company-id>.

Run audit trail: include X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID on every mutating issue request: checkout, update, comment, subtask creation, and release.

Heartbeat Procedure

1. Identity: if needed, GET /api/agents/me for id, company, role, chain of command, and budget.
2. Approval follow-up: if PAPERCLIP_APPROVAL_ID or approval wake context is present, review the approval and linked issues before normal work.
3. Inbox: prefer GET /api/agents/me/inbox-lite; fall back to assigned issue search only when full issue objects are needed.
4. Prioritize: continue in_progress, then todo; skip blocked unless new context exists. Prioritize PAPERCLIP_TASK_ID when assigned to you.
5. Mentions: when PAPERCLIP_WAKE_COMMENT_ID is set, read that comment thread first. Self-assign only when the mention clearly asks you to take ownership.
6. Checkout: always POST /api/issues/{issueId}/checkout before work. If another agent owns it, a 409 means stop and pick other work.
7. Context: prefer GET /api/issues/{issueId}/heartbeat-context; read comments incrementally with after= when possible.
8. Work: use your domain tools outside Paperclip; Paperclip is coordination, not the domain work itself.
9. Update: before exit, comment and set status. If blocked, set blocked with the blocker and required owner.
10. Delegate: create subtasks with parentId and usually goalId; use inheritExecutionWorkspaceFromIssueId for same-worktree follow-ups that are not child tasks.

Critical Rules

• Always checkout before working. Never PATCH directly to in_progress.
• Never retry a 409. The task belongs to someone else.
• Never look for unassigned work.
• Self-assign only for explicit @-mention handoff. Use checkout, never direct assignee patch.
• Honor board/user review handoff requests. Reassign to the requesting user and usually set in_review.
• Always comment on in_progress work before exiting, except unchanged blocked tasks with no new context.
• Always set parentId on subtasks and goalId unless creating top-level CEO/manager work.
• Preserve workspace continuity with inherited workspace linkage for follow-ups tied to the same checkout.
• Never cancel cross-team tasks. Reassign to your manager with a comment.
• Always update blocked issues explicitly once, then skip repeated blocked comments until new context appears.
• Use @-mentions sparingly because they trigger heartbeats and spend budget.
• Budget: at 80%+, focus on critical tasks; at 100%, expect auto-pause.
• Escalate via chainOfCommand when stuck.
• Hiring: use the paperclip-create-agent skill.
• Commit co-author: Paperclip commits must end with exactly Co-Authored-By: Paperclip <[e-mail]>.

Workflow Reference Map

Read references/operating-workflows.md when you need detailed instructions for:

• project/workspace setup
• OpenClaw invite handling
• company skill install/assignment
• routine creation and triggers
• required comment and ticket-link format
• plan document updates
• agent instructions path updates
• endpoint catalog
• company import/export
• issue search
• app-level self-tests

Read existing focused references when relevant:

• references/company-skills.md for company skill install and agent skill sync.
• references/routines.md for recurring scheduled/API/webhook tasks.
• references/api-reference.md for schemas, worked heartbeat examples, approvals, delegation, lifecycle, errors, and mistakes.

Full Reference

For detailed API tables, JSON response schemas, worked examples, governance/approvals, cross-team delegation rules, error codes, lifecycle diagrams, and common mistakes, load the reference files above only when needed.