hanh.tonguyen/paperclip
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refine mention-triggered wake behavior and self-assign rules

Browse Source 
Update agent skill to allow self-assign only on explicit @-mention
handoff with PAPERCLIP_WAKE_COMMENT_ID. Enrich wake contextSnapshot
with taskId, wakeCommentId, and wakeReason fields so agents can
identify mention-triggered runs. Clarify api-reference exception
for handoff-by-mention pattern.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Forgotten
2026-02-20 12:50:56 -06:00
parent a4ba4a72cd
commit a621b55e90
3 changed files with 33 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
skills/paperclip/references/api-reference.md
View File

@@ -214,9 +214,14 @@ The name must match the agent's `name` field exactly (case-insensitive). This tr
**Do NOT:**
- Use @-mentions as a substitute for task assignment. If you need someone to do work, create a task.
- Use @-mentions as your default assignment mechanism. If you need someone to do work, create/assign a task.
- Mention agents unnecessarily. Each mention triggers a heartbeat that costs budget.
**Exception (handoff-by-mention):**
- If an agent is explicitly @-mentioned with a clear directive to take the task, that agent may read the thread and self-assign via checkout for that issue.
- This is a narrow fallback for missed assignment flow, not a replacement for normal assignment discipline.
---
## Cross-Team Work and Delegation
@@ -417,7 +422,7 @@ Terminal states: `done`, `cancelled`
| ------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------- |
| Start work without checkout | Another agent may claim it simultaneously | Always `POST /issues/:id/checkout` first |
| Retry a `409` checkout | The task belongs to someone else | Pick a different task |
| Look for unassigned work | You're overstepping; managers assign work | If you have no assignments, exit the heartbeat |
| Look for unassigned work | You're overstepping; managers assign work | If you have no assignments, exit, except explicit mention handoff |
| Exit without commenting on in-progress work | Your manager can't see progress; work appears stalled | Leave a comment explaining where you are |
| Create tasks without `parentId` | Breaks the task hierarchy; work becomes untraceable | Link every subtask to its parent |
| Cancel cross-team tasks | Only the assigning team's manager can cancel | Reassign to your manager with a comment |