0d73e1b407
Export agentConfigurationDoc from all adapters for LLM reflection. Inject PAPERCLIP_APPROVAL_ID, PAPERCLIP_APPROVAL_STATUS, and PAPERCLIP_LINKED_ISSUE_IDS into local adapter environments. Update SKILL.md with approval handling procedure, issue-approval linking, and config revision documentation. Add new paperclip-create-agent skill for CEO-driven agent hiring workflows. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
114 lines
6.6 KiB
Markdown
114 lines
6.6 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), `PAPERCLIP_WAKE_REASON` (why this run was triggered), `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.
|
|
|
|
**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 — 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.** `GET /api/companies/{companyId}/issues?assigneeAgentId={your-agent-id}&status=todo,in_progress,blocked`. Results sorted by priority. This is your inbox.
|
|
|
|
**Step 4 — 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 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"] }
|
|
```
|
|
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.** `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 7 — Do the work.** Use your tools and capabilities.
|
|
|
|
**Step 8 — 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 9 — 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.
|
|
- **Hiring**: use `paperclip-create-agent` skill for new agent creation workflows.
|
|
|
|
## Comment Style (Required)
|
|
|
|
When posting issue comments, use concise markdown with:
|
|
|
|
- a short status line
|
|
- bullets for what changed / what is blocked
|
|
- links to related entities when available (`[Issue XYZ](/issues/<id>)`, `[Approval](/approvals/<id>)`, `[Agent](/agents/<id>)`)
|
|
|
|
Example:
|
|
|
|
```md
|
|
## Update
|
|
|
|
Submitted CTO hire request and linked it for board review.
|
|
|
|
- Approval: [ca6ba09d](/approvals/ca6ba09d-b558-4a53-a552-e7ef87e54a1b)
|
|
- Pending agent: [CTO draft](/agents/66b3c071-6cb8-4424-b833-9d9b6318de0b)
|
|
- Source issue: [PC-142](/issues/244c0c2c-8416-43b6-84c9-ec183c074cc1)
|
|
```
|
|
|
|
## 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`
|