paperclip-task-bridge

1---2name: paperclip-task-bridge3description: Create, comment on, update, and list Paperclip tasks from Hermes using scoped Paperclip API credentials.4---5 6# Paperclip Task Bridge7 8Use this skill when a Hermes-originated request needs to create or update Paperclip work directly. This is the Hermes-to-Paperclip direction, separate from Paperclip waking Hermes through the `hermes_local` or `hermes_gateway` adapter.9 10## Required Environment11 12Configure these in Hermes env/profile secrets, not in prompt text:13 14- `PAPERCLIP_API_URL` - Paperclip base URL, with or without `/api`.15- `PAPERCLIP_BRIDGE_API_KEY` - a Paperclip agent API key created with `scope.kind = "task_bridge"`.16 17Optional:18 19- `PAPERCLIP_API_KEY` - fallback env var for older profiles; it must still contain a `task_bridge` scoped key, never a full agent key.20- `PAPERCLIP_COMPANY_ID` - skips one identity lookup when set.21- `PAPERCLIP_AGENT_ID` - skips one identity lookup when set.22- `PAPERCLIP_RUN_ID` - sent as `X-Paperclip-Run-Id` on mutating requests when Hermes is running inside a Paperclip heartbeat.23 24Never print or paste API keys. The helper reads credentials from environment variables and only prints response summaries. Do not put a normal claimed agent API key in an internet-facing Hermes runtime; normal keys can use broad same-company Paperclip routes.25 26## Create a Bridge Key27 28Create the key from a board-authenticated Paperclip API session and store the returned token once:29 30```sh31curl -X POST "$PAPERCLIP_API_URL/api/agents/$HERMES_AGENT_ID/keys" \32  -H "Authorization: Bearer $BOARD_API_KEY" \33  -H "Content-Type: application/json" \34  -d '{35    "name": "Hermes task bridge",36    "scope": {37      "kind": "task_bridge",38      "parentIssueId": "00000000-0000-4000-8000-000000000000"39    }40  }'41```42 43Use `parentIssueId` or `parentIssueIds` when Hermes should only create child tasks under approved work. Use `projectId` or `projectIds` when the approved boundary is a project. A bridge key can create tasks only inside that boundary, can comment/update only bridge-created or assigned issues, and cannot use company-wide issue list/search/read surfaces.44 45## Helper46 47Run the helper from this skill directory:48 49```sh50node ./paperclip-task.mjs --help51```52 53Commands:54 55```sh56node ./paperclip-task.mjs list-assigned57node ./paperclip-task.mjs create-task --parent-id "00000000-0000-4000-8000-000000000000" --title "Investigate checkout failures" --description "Capture failing request and root cause."58node ./paperclip-task.mjs comment --issue PAP-123 --body "Found the failing request path."59node ./paperclip-task.mjs update-status --issue PAP-123 --status in_review --comment "Ready for review."60```61 62`create-task` defaults to assigning the task to the authenticated Hermes agent so the work is immediately actionable. Use `--unassigned` to create backlog work instead. Use `--assignee-agent-id <uuid>` only when the Paperclip API key has permission to assign work to that agent.63 64For multiline bodies, prefer files or stdin:65 66```sh67node ./paperclip-task.mjs create-task --title "Write rollout note" --description-file ./task.md68node ./paperclip-task.mjs comment --issue PAP-123 --body-file -69```70 71## Workflow Expectations72 73- Keep tasks company-scoped by using the company resolved from the scoped agent key.74- Let Paperclip activity logging come from the normal API endpoints; do not write local logs that include credentials.75- Use comments for durable progress.76- Use `update-status` only when the issue has a real disposition: `done`, `in_review`, `blocked`, `todo`, `in_progress`, `backlog`, or `cancelled`.77- Use `list-assigned` before creating duplicate work when the user asks about current Paperclip assignments.78