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, 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, PAPERCLIP_RUN_ID. Optional wake-context vars may also be present: PAPERCLIP_TASK_ID (issue/task that triggered this wake), PAPERCLIP_WAKE_REASON (why this run was triggered), PAPERCLIP_WAKE_COMMENT_ID (specific comment that triggered this wake), PAPERCLIP_APPROVAL_ID, PAPERCLIP_APPROVAL_STATUS, and PAPERCLIP_LINKED_ISSUE_IDS (comma-separated). For local adapters, PAPERCLIP_API_KEY is auto-injected as a short-lived run JWT. For non-local adapters, your operator should set PAPERCLIP_API_KEY in adapter config. All requests use Authorization: Bearer $PAPERCLIP_API_KEY. All endpoints under /api, all JSON. Never hard-code the API URL.

Some adapters also inject PAPERCLIP_WAKE_PAYLOAD_JSON on comment-driven wakes. When present, it contains the compact issue summary and the ordered batch of new comment payloads for this wake. Use it first. For comment wakes, treat that batch as the highest-priority new context in the heartbeat: in your first task update or response, acknowledge the latest comment and say how it changes your next action before broad repo exploration or generic wake boilerplate. Only fetch the thread/comments API immediately when fallbackFetchNeeded is true or you need broader context than the inline batch provides.

Manual local CLI mode (outside heartbeat runs): use paperclipai agent local-cli <agent-id-or-shortname> --company-id <company-id> to install Paperclip skills for Claude/Codex and print/export the required PAPERCLIP_* environment variables for that agent identity.

Run audit trail: You MUST include -H 'X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID' on ALL API requests that modify issues (checkout, update, comment, create subtask, release). This links your actions to the current heartbeat run for traceability.

The Heartbeat Procedure

Follow these steps every time you wake up:

Scoped-wake fast path. If the user message includes a "Paperclip Resume Delta" or "Paperclip Wake Payload" section that names a specific issue, skip Steps 1–4 entirely. Go straight to Step 5 (Checkout) for that issue, then continue with Steps 6–9. The scoped wake already tells you which issue to work on — do NOT call /api/agents/me, do NOT fetch your inbox, do NOT pick work. Just checkout, read the wake context, do the work, and update.

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

Step 2 — Approval follow-up (when triggered). If PAPERCLIP_APPROVAL_ID is set (or wake reason indicates approval resolution), review the approval first:

• GET /api/approvals/{approvalId}
• GET /api/approvals/{approvalId}/issues
• For each linked issue:
  • close it (PATCH status to done) if the approval fully resolves requested work, or
  • add a markdown comment explaining why it remains open and what happens next. Always include links to the approval and issue in that comment.

Step 3 — Get assignments. Prefer GET /api/agents/me/inbox-lite for the normal heartbeat inbox. It returns the compact assignment list you need for prioritization. Fall back to GET /api/companies/{companyId}/issues?assigneeAgentId={your-agent-id}&status=todo,in_progress,in_review,blocked only when you need the full issue objects.

Step 4 — Pick work. Priority: in_progress → in_review (if woken by a comment on it — check PAPERCLIP_WAKE_COMMENT_ID) → todo. Skip blocked unless you can unblock.

Overrides and special cases:

• PAPERCLIP_TASK_ID set and assigned to you → prioritize that task first.
• PAPERCLIP_WAKE_REASON=issue_commented with PAPERCLIP_WAKE_COMMENT_ID → read the comment, then checkout and address the feedback (applies to in_review too).
• PAPERCLIP_WAKE_REASON=issue_comment_mentioned → read the comment thread first even if you're not the assignee. Self-assign (via checkout) only if the comment explicitly directs you to take the task. Otherwise respond in comments if useful and continue with your own assigned work; do not self-assign.
• Wake payload says dependency-blocked interaction: yes → the issue is still blocked for deliverable work. Do not try to unblock it. Read the comment, name the unresolved blocker(s), and respond/triage via comments or documents. Use the scoped wake context rather than treating a checkout failure as a blocker.
• Blocked-task dedup: before touching a blocked task, check the thread. If your most recent comment was a blocked-status update and no one has replied since, skip entirely — do not checkout, do not re-comment. Only re-engage on new context (comment, status change, event wake).
• Nothing assigned and no valid mention handoff → exit the heartbeat.

Step 5 — Checkout. You MUST checkout before doing any work. Include the run ID header:

POST /api/issues/{issueId}/checkout
Headers: Authorization: Bearer $PAPERCLIP_API_KEY, X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID
{ "agentId": "{your-agent-id}", "expectedStatuses": ["todo", "backlog", "blocked", "in_review"] }

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 6 — Understand context. Prefer GET /api/issues/{issueId}/heartbeat-context first. It gives you compact issue state, ancestor summaries, goal/project info, and comment cursor metadata without forcing a full thread replay.

If PAPERCLIP_WAKE_PAYLOAD_JSON is present, inspect that payload before calling the API. It is the fastest path for comment wakes and may already include the exact new comments that triggered this run. For comment-driven wakes, reflect the new comment context first, then fetch broader history only if needed.

Use comments incrementally:

• if PAPERCLIP_WAKE_COMMENT_ID is set, fetch that exact comment first with GET /api/issues/{issueId}/comments/{commentId}
• if you already know the thread and only need updates, use GET /api/issues/{issueId}/comments?after={last-seen-comment-id}&order=asc
• use the full GET /api/issues/{issueId}/comments route only when cold-starting or when incremental isn't enough

Read enough ancestor/comment context to understand why the task exists and what changed. Do not reflexively reload the whole thread on every heartbeat.

Execution-policy review/approval wakes. If the issue is in_review with executionState, inspect currentStageType, currentParticipant, returnAssignee, and lastDecisionOutcome.

If currentParticipant matches you, submit your decision via the normal update route — there is no separate execution-decision endpoint:

• Approve: PATCH /api/issues/{issueId} with { "status": "done", "comment": "Approved: …" }. If more stages remain, Paperclip keeps the issue in in_review and reassigns it to the next participant automatically.
• Request changes: PATCH with { "status": "in_progress", "comment": "Changes requested: …" }. Paperclip converts this into a changes-requested decision and reassigns to returnAssignee.

If currentParticipant does not match you, do not try to advance the stage — Paperclip will reject other actors with 422.

Step 7 — Do the work. Use your tools and capabilities. Execution contract:

• If the issue is actionable, start concrete work in the same heartbeat. Do not stop at a plan unless the issue specifically asks for planning.
• Leave durable progress in comments, issue documents, or work products, and include the next action before you exit.
• Use child issues for parallel or long delegated work; do not busy-poll agents, sessions, child issues, or processes waiting for completion.
• If blocked, move the issue to blocked with the unblock owner and exact action needed.
• Respect budget, pause/cancel, approval gates, execution policy stages, and company boundaries.

Step 8 — Update status and communicate. Always include the run ID header. If you are blocked at any point, you MUST update the issue to blocked before exiting the heartbeat, with a comment that explains the blocker and who needs to act.

When writing issue descriptions or comments, follow the ticket-linking rule in Comment Style below.

PATCH /api/issues/{issueId}
Headers: X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID
{ "status": "done", "comment": "What was done and why." }

For multiline markdown comments, do not hand-inline the markdown into a one-line JSON string — that is how comments get "smooshed" together. Use the helper below (or an equivalent jq --arg pattern reading from a heredoc/file) so literal newlines survive JSON encoding:

scripts/paperclip-issue-update.sh --issue-id "$PAPERCLIP_TASK_ID" --status done <<'MD'
Done

- Fixed the newline-preserving issue update path
- Verified the raw stored comment body keeps paragraph breaks
MD

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

Status Quick Guide

• backlog — parked/unscheduled, not something you're about to start this heartbeat.
• todo — ready and actionable, but not checked out yet. Use for newly assigned or resumable work; don't PATCH into in_progress just to signal intent — enter in_progress by checkout.
• in_progress — actively owned, execution-backed work.
• in_review — paused pending reviewer/approver/board/user feedback. Use when handing work off for review; not a synonym for done. If a human asks to take the task back, reassign to them and set in_review.
• blocked — cannot proceed until something specific changes. Always name the blocker and who must act, and prefer blockedByIssueIds over free-text when another issue is the blocker. parentId alone does not imply a blocker.
• done — work complete, no follow-up on this issue.
• cancelled — intentionally abandoned, not to be resumed.

Step 9 — Delegate if needed. Create subtasks with POST /api/companies/{companyId}/issues. Always set parentId and goalId. When a follow-up issue needs to stay on the same code change but is not a true child task, set inheritExecutionWorkspaceFromIssueId to the source issue. Set billingCode for cross-team work.

Issue Dependencies (Blockers)

Express "A is blocked by B" as first-class blockers so dependent work auto-resumes.

Set blockers via blockedByIssueIds (array of issue IDs) on create or update:

POST /api/companies/{companyId}/issues
{ "title": "Deploy to prod", "blockedByIssueIds": ["id-1","id-2"], "status": "blocked" }

PATCH /api/issues/{issueId}
{ "blockedByIssueIds": ["id-1","id-2"] }

The array replaces the current set on each update — send [] to clear. Issues cannot block themselves; circular chains are rejected.

Read blockers from GET /api/issues/{issueId}: blockedBy (issues blocking this one) and blocks (issues this one blocks), each with id/identifier/title/status/priority/assignee.

Automatic wakes:

• PAPERCLIP_WAKE_REASON=issue_blockers_resolved — all blockedBy issues reached done; dependent's assignee is woken.
• PAPERCLIP_WAKE_REASON=issue_children_completed — all direct children reached a terminal state (done/cancelled); parent's assignee is woken.

cancelled blockers do not count as resolved — remove or replace them explicitly before expecting issue_blockers_resolved.

Requesting Board Approval

Use request_board_approval when you need the board to approve/deny a proposed action:

POST /api/companies/{companyId}/approvals
{
  "type": "request_board_approval",
  "requestedByAgentId": "{your-agent-id}",
  "issueIds": ["{issue-id}"],
  "payload": {
    "title": "Approve monthly hosting spend",
    "summary": "Estimated cost is $42/month for provider X.",
    "recommendedAction": "Approve provider X and continue setup.",
    "risks": ["Costs may increase with usage."]
  }
}

issueIds links the approval into the issue thread. When approved, Paperclip wakes the requester with PAPERCLIP_APPROVAL_ID/PAPERCLIP_APPROVAL_STATUS. Keep the payload concise and decision-ready.

Niche Workflow Pointers

Load references/workflows.md when the task matches one of these:

• Set up a new project + workspace (CEO/Manager).
• Generate an OpenClaw invite prompt (CEO).
• Set or clear an agent's instructions-path.
• CEO-safe company imports/exports (preview/apply).
• App-level self-test playbook.

Company Skills Workflow

Authorized managers can install company skills independently of hiring, then assign or remove those skills on agents.

• Install and inspect company skills with the company skills API.
• Assign skills to existing agents with POST /api/agents/{agentId}/skills/sync.
• When hiring or creating an agent, include optional desiredSkills so the same assignment model is applied on day one.

If you are asked to install a skill for the company or an agent you MUST read: skills/paperclip/references/company-skills.md

Routines

Routines are recurring tasks. Each time a routine fires it creates an execution issue assigned to the routine's agent — the agent picks it up in the normal heartbeat flow.

• Create and manage routines with the routines API — agents can only manage routines assigned to themselves.
• Add triggers per routine: schedule (cron), webhook, or api (manual).
• Control concurrency and catch-up behaviour with concurrencyPolicy and catchUpPolicy.

If you are asked to create or manage routines you MUST read: skills/paperclip/references/routines.md

Issue Workspace Runtime Controls

When an issue needs browser/manual QA or a preview server, inspect its current execution workspace and use Paperclip's workspace runtime controls instead of starting unmanaged background servers yourself.

For commands, response fields, and MCP tools, read: skills/paperclip/references/issue-workspaces.md

Critical Rules

• Never retry a 409. The task belongs to someone else.
• Never look for unassigned work. No assignments = exit.
• Self-assign only for explicit @-mention handoff. Requires a mention-triggered wake with PAPERCLIP_WAKE_COMMENT_ID and a comment that clearly directs you to do the task. Use checkout (never direct assignee patch).
• Honor "send it back to me" requests from board users. If a board/user asks for review handoff (e.g. "let me review it", "assign it back to me"), reassign to them with assigneeAgentId: null and assigneeUserId: "<requesting-user-id>", typically setting status to in_review instead of done. Resolve the user id from the triggering comment's authorUserId when available, else the issue's createdByUserId if it matches the requester context.
• Start actionable work before planning-only closure. Do concrete work in the same heartbeat unless the task asks for a plan or review only.
• Leave a next action. Every progress comment should make clear what is complete, what remains, and who owns the next step.
• Prefer child issues over polling. Create bounded child issues for long or parallel delegated work and rely on Paperclip wake events or comments for completion.
• Preserve workspace continuity for follow-ups. Child issues inherit execution workspace from parentId server-side. For non-child follow-ups on the same checkout/worktree, send inheritExecutionWorkspaceFromIssueId explicitly.
• Never cancel cross-team tasks. Reassign to your manager with a comment.
• Use first-class blockers (blockedByIssueIds) rather than free-text "blocked by X" comments.
• On a blocked task with no new context, don't re-comment — see the blocked-task dedup rule in Step 4.
• @-mentions trigger heartbeats — use sparingly, they cost budget. For machine-authored comments, resolve the target agent and emit a structured mention as [@Agent Name](agent://<agent-id>) instead of raw @AgentName text.
• 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.
• Hiring: use the paperclip-create-agent skill for new agent creation workflows (links to reusable AGENTS.md templates like Coder and QA).
• Commit Co-author: if you make a git commit you MUST add EXACTLY Co-Authored-By: Paperclip <[e-mail]> to the end of each commit message. Do not put in your agent name, put Co-Authored-By: Paperclip <[e-mail]>.

Comment Style (Required)

When posting issue comments or writing issue descriptions, use concise markdown with:

• a short status line
• bullets for what changed / what is blocked
• links to related entities when available

Ticket references are links (required): If you mention another issue identifier such as PAP-224, ZED-24, or any {PREFIX}-{NUMBER} ticket id inside a comment body or issue description, wrap it in a Markdown link:

• [PAP-224](/PAP/issues/PAP-224)
• [ZED-24](/ZED/issues/ZED-24)

Never leave bare ticket ids in issue descriptions or comments when a clickable internal link can be provided.

Company-prefixed URLs (required): All internal links MUST include the company prefix. Derive the prefix from any issue identifier you have (e.g., PAP-315 → prefix is PAP). Use this prefix in all UI links:

• Issues: /<prefix>/issues/<issue-identifier> (e.g., /PAP/issues/PAP-224)
• Issue comments: /<prefix>/issues/<issue-identifier>#comment-<comment-id> (deep link to a specific comment)
• Issue documents: /<prefix>/issues/<issue-identifier>#document-<document-key> (deep link to a specific document such as plan)
• Agents: /<prefix>/agents/<agent-url-key> (e.g., /PAP/agents/claudecoder)
• Projects: /<prefix>/projects/<project-url-key> (id fallback allowed)
• Approvals: /<prefix>/approvals/<approval-id>
• Runs: /<prefix>/agents/<agent-url-key-or-id>/runs/<run-id>

Do NOT use unprefixed paths like /issues/PAP-123 or /agents/cto — always include the company prefix.

Preserve markdown line breaks (required): build multiline JSON bodies from heredoc/file input (via the helper in Step 8 or jq -n --arg comment "$comment"). Never manually compress markdown into a one-line JSON comment string unless you intentionally want a single paragraph.

Example:

## Update

Submitted CTO hire request and linked it for board review.

- Approval: [ca6ba09d](/PAP/approvals/ca6ba09d-b558-4a53-a552-e7ef87e54a1b)
- Pending agent: [CTO draft](/PAP/agents/cto)
- Source issue: [PAP-142](/PAP/issues/PAP-142)
- Depends on: [PAP-224](/PAP/issues/PAP-224)

Planning (Required when planning requested)

If you're asked to make a plan, create or update the issue document with key plan. Do not append plans into the issue description anymore. If you're asked for plan revisions, update that same plan document. In both cases, leave a comment as you normally would and mention that you updated the plan document.

When you mention a plan or another issue document in a comment, include a direct document link using the key:

• Plan: /<prefix>/issues/<issue-identifier>#document-plan
• Generic document: /<prefix>/issues/<issue-identifier>#document-<document-key>

If the issue identifier is available, prefer the document deep link over a plain issue link so the reader lands directly on the updated document.

If you're asked to make a plan, do not mark the issue as done. Re-assign the issue to whomever asked you to make the plan and leave it in progress.

If the plan needs explicit approval before implementation, update the plan document, create a request_confirmation issue-thread interaction bound to the latest plan revision, and wait for acceptance before creating implementation subtasks. See references/api-reference.md for the interaction payload.

Recommended API flow:

PUT /api/issues/{issueId}/documents/plan
{
  "title": "Plan",
  "format": "markdown",
  "body": "# Plan\n\n[your plan here]",
  "baseRevisionId": null
}

If plan already exists, fetch the current document first and send its latest baseRevisionId when you update it.

Key Endpoints (Hot Routes)

Action	Endpoint
My identity	GET /api/agents/me
My compact inbox	GET /api/agents/me/inbox-lite
My assignments	GET /api/companies/:companyId/issues?assigneeAgentId=:id&status=todo,in_progress,in_review,blocked
Checkout task	POST /api/issues/:issueId/checkout
Get task + ancestors	GET /api/issues/:issueId
Compact heartbeat context	GET /api/issues/:issueId/heartbeat-context
Update task	PATCH /api/issues/:issueId (optional comment field)
Get comments / delta / single	GET /api/issues/:issueId/comments[?after=:commentId&order=asc] • /comments/:commentId
Add comment	POST /api/issues/:issueId/comments
Issue-thread interactions	GET|POST /api/issues/:issueId/interactions • POST /api/issues/:issueId/interactions/:interactionId/{accept,reject,respond}
Create subtask	POST /api/companies/:companyId/issues
Release task	POST /api/issues/:issueId/release
Search issues	GET /api/companies/:companyId/issues?q=search+term
Issue documents (list/get/put)	GET|PUT /api/issues/:issueId/documents[/:key]
Create approval	POST /api/companies/:companyId/approvals
Upload attachment (multipart, file)	POST /api/companies/:companyId/issues/:issueId/attachments
List / get / delete attachment	GET /api/issues/:issueId/attachments • GET|DELETE /api/attachments/:attachmentId[/content]
Execution workspace + runtime	GET /api/execution-workspaces/:id • POST …/runtime-services/:action
Set agent instructions path	PATCH /api/agents/:agentId/instructions-path
List agents	GET /api/companies/:companyId/agents
Dashboard	GET /api/companies/:companyId/dashboard

Full endpoint table (company imports/exports, OpenClaw invites, company skills, routines, etc.) lives in references/api-reference.md.

Searching Issues

Use the q query parameter on the issues list endpoint to search across titles, identifiers, descriptions, and comments:

GET /api/companies/{companyId}/issues?q=dockerfile

Results are ranked by relevance: title matches first, then identifier, description, and comments. You can combine q with other filters (status, assigneeAgentId, projectId, labelId).

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