From 73eb23734f25c570d88665e672f80d740797c632 Mon Sep 17 00:00:00 2001 From: Aron Prins Date: Mon, 20 Apr 2026 16:38:04 +0200 Subject: [PATCH] docs: use structured agent mentions in paperclip skill (#4103) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - Agents coordinate work through tasks and comments, and @-mentions are part of the wakeup path for cross-agent handoffs and review requests > - The current repo skill still instructs machine-authored comments to use raw `@AgentName` text as the default mention format > - But the current backend mention parsing is still unreliable for multi-word display names, so agents following that guidance can silently fail to wake the intended target > - This pull request updates the Paperclip skill and API reference to prefer structured `agent://` markdown mentions for machine-authored comments > - The benefit is a low-risk documentation workaround that steers agents onto the mention format the server already resolves reliably while broader runtime fixes are reviewed upstream ## What Changed - Updated `skills/paperclip/SKILL.md` to stop recommending raw `@AgentName` mentions for machine-authored comments - Updated `skills/paperclip/references/api-reference.md` with a concrete workflow: resolve the target via `GET /api/companies/{companyId}/agents`, then emit `[@Display Name](agent://)` - Added explicit guidance that raw `@AgentName` text is fallback-only and unreliable for names containing spaces - Cross-referenced the current upstream mention-bug context so reviewers can connect this docs workaround to the open parser/runtime fixes Related issue/PR refs: #448, #459, #558, #669, #722, #1412, #2249 ## Verification - `pnpm -r typecheck` - `pnpm build` - `pnpm test:run` currently fails on upstream `master` in existing tests unrelated to this docs-only change: - `src/__tests__/worktree.test.ts` — `seeds authenticated users into minimally cloned worktree instances` timed out after 20000ms - `src/__tests__/onboard.test.ts` — `keeps tailnet quickstart on loopback until tailscale is available` expected `127.0.0.1` but got `100.125.202.3` - Confirmed the git diff is limited to: - `skills/paperclip/SKILL.md` - `skills/paperclip/references/api-reference.md` ## Risks - Low risk. This is a docs/skill-only change and does not alter runtime behavior. - It is a mitigation, not a full fix: it helps agent-authored comments that follow the Paperclip skill, but it does not fix manually typed raw mentions or other code paths that still emit plain `@Name` text. - If upstream chooses a different long-term mention format, this guidance may need to be revised once the runtime-side fix lands. ## Model Used - OpenAI Codex desktop agent on a GPT-5-class model. Exact deployed model ID and context window are not exposed by the local harness. Tool use enabled, including shell execution, git, and GitHub CLI. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --- skills/paperclip/SKILL.md | 2 +- skills/paperclip/references/api-reference.md | 14 +++++++++++--- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/skills/paperclip/SKILL.md b/skills/paperclip/SKILL.md index 2eecf53e..0e817fc3 100644 --- a/skills/paperclip/SKILL.md +++ b/skills/paperclip/SKILL.md @@ -309,7 +309,7 @@ If you are asked to create or manage routines you MUST read: - **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. - **Use first-class blockers** when a task depends on other tasks. Set `blockedByIssueIds` on the dependent issue so Paperclip automatically wakes the assignee when all blockers are done. Prefer this over ad-hoc "blocked by X" comments. -- **@-mentions** (`@AgentName` in comments) trigger heartbeats — use sparingly, they cost budget. +- **@-mentions** trigger heartbeats — use sparingly, they cost budget. For machine-authored comments, do not rely on raw `@AgentName` text. Resolve the target agent first, then emit a structured mention as `[@Agent Name](agent://)`. - **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. That skill links to reusable agent instruction templates, including `Coder` and `QA`, so hiring agents can start from proven `AGENTS.md` patterns without bloating this heartbeat skill. diff --git a/skills/paperclip/references/api-reference.md b/skills/paperclip/references/api-reference.md index 225ff3ec..aef921f8 100644 --- a/skills/paperclip/references/api-reference.md +++ b/skills/paperclip/references/api-reference.md @@ -415,14 +415,22 @@ Use markdown formatting and include links to related entities when they exist: Where `` is the company prefix derived from the issue identifier (e.g., `PAP-123` → prefix is `PAP`). -**@-mentions:** Mention another agent by name using `@AgentName` to automatically wake them: +**@-mentions:** Agent mentions in comments can automatically wake the target agent. + +For machine-authored comments, do not rely on raw `@AgentName` text. Raw text is unreliable for names containing spaces. Instead: + +1. Resolve the target agent with `GET /api/companies/{companyId}/agents` +2. Find the agent's exact display name and `id` +3. Emit a structured markdown mention using the agent ID: ``` POST /api/issues/{issueId}/comments -{ "body": "@EngineeringLead I need a review on this implementation." } +{ "body": "[@QA Reviewer](agent://qa-agent-id) please review this implementation." } ``` -The name must match the agent's `name` field exactly (case-insensitive). This triggers a heartbeat for the mentioned agent. @-mentions also work inside the `comment` field of `PATCH /api/issues/{issueId}`. +The reliable machine-authored format is `[@Display Name](agent://)`. This triggers a heartbeat for the mentioned agent. Structured agent mentions also work inside the `comment` field of `PATCH /api/issues/{issueId}`. + +Raw `@AgentName` text may still work for some single-token names, but treat it as a fallback only, not the default. **Do NOT:**