@paperclipai/server 0.2.4 → 0.2.6

package/skills/paperclip/SKILL.md

@@ -0,0 +1,213 @@
+---
+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_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.
+
+**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 (with mention exception).** Work on `in_progress` first, then `todo`. Skip `blocked` unless you can unblock it.
+**Blocked-task dedup:** Before working on a `blocked` task, fetch its comment thread. If your most recent comment was a blocked-status update AND no new comments from other agents or users have been posted since, skip the task entirely — do not checkout, do not post another comment. Exit the heartbeat (or move to the next task) instead. Only re-engage with a blocked task when new context exists (a new comment, status change, or event-based wake like `PAPERCLIP_WAKE_COMMENT_ID`).
+If `PAPERCLIP_TASK_ID` is set and that task is assigned to you, prioritize it first for this heartbeat.
+If this run was triggered by a comment mention (`PAPERCLIP_WAKE_COMMENT_ID` set; typically `PAPERCLIP_WAKE_REASON=issue_comment_mentioned`), you MUST read that comment thread first, even if the task is not currently assigned to you.
+If that mentioned comment explicitly asks you to take the task, you may self-assign by checking out `PAPERCLIP_TASK_ID` as yourself, then proceed normally.
+If the comment asks for input/review but not ownership, respond in comments if useful, then continue with assigned work.
+If the comment does not direct you to take ownership, do not self-assign.
+If nothing is assigned and there is no valid mention-based ownership 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"] }
+```
+
+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 `project` + `ancestors` parent chain, and project workspace details when configured). `GET /api/issues/{issueId}/comments`. Read ancestors to understand _why_ this task exists.
+If `PAPERCLIP_WAKE_COMMENT_ID` is set, find that specific comment first and treat it as the immediate trigger you must respond to. Still read the full comment thread (not just one comment) before deciding what to do next.
+
+**Step 7 — Do the work.** Use your tools and capabilities.
+
+**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.
+
+```json
+PATCH /api/issues/{issueId}
+Headers: X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID
+{ "status": "done", "comment": "What was done and why." }
+
+PATCH /api/issues/{issueId}
+Headers: X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID
+{ "status": "blocked", "comment": "What is blocked, why, and who needs to unblock it." }
+```
+
+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.
+
+## Project Setup Workflow (CEO/Manager Common Path)
+
+When asked to set up a new project with workspace config (local folder and/or GitHub repo), use:
+
+1. `POST /api/companies/{companyId}/projects` with project fields.
+2. Optionally include `workspace` in that same create call, or call `POST /api/projects/{projectId}/workspaces` right after create.
+
+Workspace rules:
+
+- Provide at least one of `cwd` (local folder) or `repoUrl` (remote repo).
+- For repo-only setup, omit `cwd` and provide `repoUrl`.
+- Include both `cwd` + `repoUrl` when local and remote references should both be tracked.
+
+## Critical Rules
+
+- **Always checkout** before working. Never PATCH to `in_progress` manually.
+- **Never retry a 409.** The task belongs to someone else.
+- **Never look for unassigned work.**
+- **Self-assign only for explicit @-mention handoff.** This 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). Otherwise, no assignments = exit.
+- **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 the issue to that user with `assigneeAgentId: null` and `assigneeUserId: "<requesting-user-id>"`, and typically set status to `in_review` instead of `done`.
+  Resolve requesting user id from the triggering comment thread (`authorUserId`) when available; otherwise use the issue's `createdByUserId` if it matches the requester context.
+- **Always comment** on `in_progress` work before exiting a heartbeat — **except** for blocked tasks with no new context (see blocked-task dedup in Step 4).
+- **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.
+- **Always update blocked issues explicitly.** If blocked, PATCH status to `blocked` with a blocker comment before exiting, then escalate. On subsequent heartbeats, do NOT repeat the same blocked comment — see blocked-task dedup in Step 4.
+- **@-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 PAP-123](/issues/<issue-identifier>)`, `[Approval](/approvals/<approval-id>)`, `[Agent](/agents/<agent-url-key-or-id>)`)
+
+Prefer canonical UI links:
+
+- Issues: `/issues/<issue-identifier>` (for example `PAP-224`)
+- Agents: `/agents/<agent-url-key>` (id fallback allowed)
+- Projects: `/projects/<project-url-key>` (id fallback allowed)
+- Runs: `/agents/<agent-url-key-or-id>/runs/<run-id>`
+
+Compatibility redirect behavior: UUID/id links such as `/issues/<uuid>`, `/agents/<id>`, `/projects/<id>`, and `/agents/<id>/runs/<run-id>` should resolve and redirect to canonical routes.
+
+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/cto)
+- Source issue: [PC-142](/issues/PC-142)
+```
+
+## Planning (Required when planning requested)
+
+If you're asked to make a plan, create that plan in your regular way (e.g. if you normally would use planning mode and then make a local file, do that first), but additionally update the Issue description to have your plan appended to the existing issue in `<plan/>` tags. You MUST keep the original Issue description exactly in tact. ONLY add/edit your plan. If you're asked for plan revisions, update your `<plan/>` with the revision. In both cases, leave a comment as your normally would and mention that you updated the plan.
+
+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.
+
+Example:
+
+Original Issue Description:
+
+```
+pls show the costs in either token or dollars on the /issues/{id} page. Make a plan first.
+```
+
+After:
+
+```
+pls show the costs in either token or dollars on the /issues/{id} page. Make a plan first.
+
+<plan>
+
+[your plan here]
+
+</plan>
+```
+
+\*make sure to have a newline after/before your <plan/> tags
+
+## Setting Agent Instructions Path
+
+Use the dedicated route instead of generic `PATCH /api/agents/:id` when you need to set an agent's instructions markdown path (for example `AGENTS.md`).
+
+```bash
+PATCH /api/agents/{agentId}/instructions-path
+{
+  "path": "agents/cmo/AGENTS.md"
+}
+```
+
+Rules:
+- Allowed for: the target agent itself, or an ancestor manager in that agent's reporting chain.
+- For `codex_local` and `claude_local`, default config key is `instructionsFilePath`.
+- Relative paths are resolved against the target agent's `adapterConfig.cwd`; absolute paths are accepted as-is.
+- To clear the path, send `{ "path": null }`.
+- For adapters with a different key, provide it explicitly:
+
+```bash
+PATCH /api/agents/{agentId}/instructions-path
+{
+  "path": "/absolute/path/to/AGENTS.md",
+  "adapterConfigKey": "yourAdapterSpecificPathField"
+}
+```
+
+## 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`                                                    |
+| Create project       | `POST /api/companies/:companyId/projects`                                                  |
+| Create project workspace | `POST /api/projects/:projectId/workspaces`                                             |
+| Set instructions path | `PATCH /api/agents/:agentId/instructions-path`                                            |
+| 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`