The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
docs: add local-cli mode and self-test playbook to paperclip skill
Dotta0315e4cdc2b3
diff --git a/skills/paperclip/SKILL.md b/skills/paperclip/SKILL.mdindex b42355d99e..92fe3ba435 100644--- a/skills/paperclip/SKILL.md+++ b/skills/paperclip/SKILL.md@@ -16,6 +16,8 @@ You run in **heartbeats** — short execution windows triggered by Paperclip. EaEnv 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.+Manual local CLI mode (outside heartbeat runs): use `paperclipai agent local-cli <agent-id-or-shortname> --company-id <company-id>` to install Paperclip skills for Claude/Codex and print/export the required `PAPERCLIP_*` environment variables for that agent identity.+**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@@ -222,6 +224,43 @@ GET /api/companies/{companyId}/issues?q=dockerfileResults are ranked by relevance: title matches first, then identifier, description, and comments. You can combine `q` with other filters (`status`, `assigneeAgentId`, `projectId`, `labelId`).+## Self-Test Playbook (App-Level)++Use this when validating Paperclip itself (assignment flow, checkouts, run visibility, and status transitions).++1. Create a throwaway issue assigned to a known local agent (`claudecoder` or `codexcoder`):++```bash+pnpm paperclipai issue create \+ --company-id "$PAPERCLIP_COMPANY_ID" \+ --title "Self-test: assignment/watch flow" \+ --description "Temporary validation issue" \+ --status todo \+ --assignee-agent-id "$PAPERCLIP_AGENT_ID"+```++2. Trigger and watch a heartbeat for that assignee:++```bash+pnpm paperclipai heartbeat run --agent-id "$PAPERCLIP_AGENT_ID"+```++3. Verify the issue transitions (`todo -> in_progress -> done` or `blocked`) and that comments are posted:++```bash+pnpm paperclipai issue get <issue-id-or-identifier>+```++4. Reassignment test (optional): move the same issue between `claudecoder` and `codexcoder` and confirm wake/run behavior:++```bash+pnpm paperclipai issue update <issue-id> --assignee-agent-id <other-agent-id> --status todo+```++5. Cleanup: mark temporary issues done/cancelled with a clear note.++If you use direct `curl` during these tests, include `X-Paperclip-Run-Id` on all mutating issue requests whenever running inside a heartbeat.+## Full ReferenceFor 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`