224d150d86
Inject PAPERCLIP_RUN_ID, PAPERCLIP_TASK_ID, and PAPERCLIP_WAKE_REASON into local adapter environments so agents know their run context and wake trigger. Update SKILL.md to document new env vars and require X-Paperclip-Run-Id header on all mutating API requests for audit trail linkage. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
85 lines
5.3 KiB
Markdown
85 lines
5.3 KiB
Markdown
---
|
|
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, 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) and `PAPERCLIP_WAKE_REASON` (why this run was triggered). 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.
|
|
|
|
**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:
|
|
|
|
**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.**
|
|
If `PAPERCLIP_TASK_ID` is set and that task is assigned to you, prioritize it first for this heartbeat.
|
|
|
|
**Step 4 — 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"] }
|
|
```
|
|
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.** Always include the run ID header:
|
|
```
|
|
PATCH /api/issues/{issueId}
|
|
Headers: X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID
|
|
{ "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`
|