From b9dad31eb161a56a6fc0844f5321221c12f53c48 Mon Sep 17 00:00:00 2001 From: Forgotten Date: Wed, 25 Feb 2026 21:35:53 -0600 Subject: [PATCH] docs: update skill docs for blocked status handling and workspace API Add explicit blocked status PATCH example and clarify escalation rules in SKILL.md. Add workspace CRUD endpoints to API reference table. Co-Authored-By: Claude Opus 4.6 --- skills/paperclip/SKILL.md | 11 ++++++++--- skills/paperclip/references/api-reference.md | 4 ++++ 2 files changed, 12 insertions(+), 3 deletions(-) diff --git a/skills/paperclip/SKILL.md b/skills/paperclip/SKILL.md index a0aaad66..65b130b1 100644 --- a/skills/paperclip/SKILL.md +++ b/skills/paperclip/SKILL.md @@ -58,12 +58,17 @@ If `PAPERCLIP_WAKE_COMMENT_ID` is set, find that specific comment first and trea **Step 7 — Do the work.** Use your tools and capabilities. -**Step 8 — Update status and communicate.** Always include the run ID header: +**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`. @@ -79,7 +84,7 @@ Status values: `backlog`, `todo`, `in_progress`, `in_review`, `done`, `blocked`, - **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. +- **Always update blocked issues explicitly.** If blocked, PATCH status to `blocked` with a blocker comment before exiting, then 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. diff --git a/skills/paperclip/references/api-reference.md b/skills/paperclip/references/api-reference.md index 44f6ada0..4a562ddd 100644 --- a/skills/paperclip/references/api-reference.md +++ b/skills/paperclip/references/api-reference.md @@ -408,6 +408,10 @@ Terminal states: `done`, `cancelled` | GET | `/api/projects/:projectId` | Project details | | POST | `/api/companies/:companyId/projects` | Create project | | PATCH | `/api/projects/:projectId` | Update project | +| GET | `/api/projects/:projectId/workspaces` | List project workspaces | +| POST | `/api/projects/:projectId/workspaces` | Create project workspace | +| PATCH | `/api/projects/:projectId/workspaces/:workspaceId` | Update project workspace | +| DELETE | `/api/projects/:projectId/workspaces/:workspaceId` | Delete project workspace | | GET | `/api/companies/:companyId/goals` | List goals | | GET | `/api/goals/:goalId` | Goal details | | POST | `/api/companies/:companyId/goals` | Create goal |