11d03728ca
Simplify SKILL.md to focus on core agent behavior and remove redundant detail. Add skills/paperclip/references/api-reference.md with full API endpoint documentation. Add doc/plans/agent-authentication.md design plan. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
80 lines
4.5 KiB
Markdown
80 lines
4.5 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`. 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`
|