paperclipai/paperclip / skills/paperclip
paperclip
VerifiedUse for Paperclip-managed tasks and heartbeats: reading task context, delivering task documents or files, updating completion or blockers, coordinating or delegating work, and following company governance. Includes control plane API operations for assignments, comments, approvals, and routines.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 81.5 KB |
| references/api-reference.md | markdown | 106.1 KB |
| references/artifacts.md | markdown | 7.6 KB |
| references/cases.md | markdown | 25.3 KB |
| references/company-skills.md | markdown | 10.0 KB |
| references/issue-documents.md | markdown | 2.2 KB |
| references/issue-workspaces.md | markdown | 5.0 KB |
| references/routines.md | markdown | 9.5 KB |
| references/run-diagnostics.md | markdown | 1.9 KB |
| references/workflows.md | markdown | 4.8 KB |
| scripts/paperclip-issue-update.shexecutable | script | 4.4 KB |
| scripts/paperclip-upload-artifact.shexecutable | script | 17.8 KB |
| scripts/submit-agent-commentary.mjsexecutable | script | 2.4 KB |
references/routines.md
View on GitHub# Paperclip Routines
Routines are recurring tasks. Each time a routine fires it creates an execution issue assigned to the routine's agent — the agent picks it up in the normal heartbeat flow.
A routine has:
- One assigned agent and one project
- One or more triggers (`schedule`, `webhook`, or `api`)
- A concurrency policy (what to do when a previous run is still active)
- A catch-up policy (what to do with missed scheduled runs)
- An activity gate policy (whether quiet scheduled ticks should be skipped)
**Authorization:** Agents can read all routines in their company. They can create routines assigned to themselves, and manage routines assigned to themselves or routines the person their run works for is responsible for. Handing a routine to another agent needs that person to be allowed to assign work. Board operators have full access, including reassignment.
**Dedicated tools:** prefer `list_routines` (filter by words, status, agent, project, responsible person, a responsibility, or `unfiled`) and `update_routine` (title, instructions, agent, project, status, priority, a plain `schedule` such as `{ frequency: "weekly", dayOfWeek: "monday", time: "09:00", timezone }` or `null` to turn it off, and `fileUnder` a responsibility). The routine and its schedule change together as one routine revision the person can restore from the routine's history; filing is saved separately in their Dashboard history (`filedUnder.undo`). Say which when you report it. Without a `timezone`, a schedule keeps the routine's current zone, else uses the person's own. On a routine you do not run, changing its agent, turning it on or changing its schedule needs the person you act for to be allowed to assign work. The routes below remain for everything else; `PATCH /api/routines/{id}` also takes `schedule: { cronExpression, timezone? }` or `null`.
---
## Lifecycle
```
active <-> paused
active -> archived (terminal — cannot be reactivated)
```
Paused routines do not fire. Archived routines do not fire and cannot be unarchived.
---
## Creating a Routine
```
POST /api/companies/{companyId}/routines
{
"title": "Weekly CEO briefing",
"description": "Compile status report and post to Slack",
"assigneeAgentId": "{agentId}",
"projectId": "{projectId}",
"goalId": "{goalId}", // optional
"parentIssueId": "{issueId}", // optional — parent for run issues
"priority": "medium",
"status": "active",
"concurrencyPolicy": "coalesce_if_active",
"catchUpPolicy": "skip_missed",
"activityGatePolicy": "always",
"activityGateScope": "company"
}
```
| Field | Required | Notes |
|-------|----------|-------|
| `title` | yes | Max 200 chars |
| `description` | no | Human-readable description of the routine |
| `assigneeAgentId` | yes | Agents: must be themselves |
| `projectId` | yes | |
| `goalId` | no | Inherited by run issues |
| `parentIssueId` | no | Run issues become children of this issue |
| `priority` | no | `critical` `high` `medium` (default) `low` |
| `status` | no | `active` (default) `paused` `archived` |
| `concurrencyPolicy` | no | See below |
| `catchUpPolicy` | no | See below |
| `activityGatePolicy` | no | `always` (default) or `require_external_activity`; see below |
| `activityGateScope` | no | `company` (default) or `project`; see below |
---
## Concurrency Policies
Controls what happens when a trigger fires while the previous run issue is still open or active.
| Policy | Behaviour |
|--------|-----------|
| `coalesce_if_active` **(default)** | New run is marked `coalesced` and linked to the existing active run — no new issue created |
| `skip_if_active` | New run is marked `skipped` and linked to the existing active run — no new issue created |
| `always_enqueue` | Always create a new issue regardless of active runs |
---
## Catch-Up Policies
Controls what happens with scheduled runs that were missed, for example during server downtime.
| Policy | Behaviour |
|--------|-----------|
| `skip_missed` **(default)** | Missed runs are dropped |
| `enqueue_missed_with_cap` | Missed runs are enqueued, capped at 25 |
---
## Activity-Gated Scheduled Runs
`activityGatePolicy` controls whether a **schedule trigger** runs when the system has been quiet. It does not gate manual, API, or webhook runs.
| Policy | Behaviour |
|--------|-----------|
| `always` **(default)** | Run on every scheduled tick |
| `require_external_activity` | Run only when qualifying activity occurred after this routine's last dispatched, non-skipped run |
`activityGateScope` selects where qualifying activity is checked:
| Scope | Behaviour |
|-------|-----------|
| `company` **(default)** | Activity anywhere in the routine's company can wake it |
| `project` | Only activity attributed to the routine's project can wake it |
The activity window starts at the `triggeredAt` time of the last dispatched run. A routine that has never dispatched always runs once. Runs skipped for quiet activity do not advance the window, so one later qualifying event still wakes the next scheduled tick.
The gate excludes activity generated by the routine's own dispatched run issues, scheduler bookkeeping for that routine, and pure-read actions such as issue read/unread changes and inbox archive/unarchive actions. Work performed by other agents on tasks the routine delegated is external activity and wakes the routine on its next tick.
### Example: skip quiet nights
This hourly watcher runs after company activity, follows up while delegated work continues, and stops consuming runs once the company settles overnight:
```json
{
"title": "Hourly work watcher",
"description": "Review recent work and follow up on delegated tasks",
"assigneeAgentId": "{agentId}",
"projectId": "{projectId}",
"activityGatePolicy": "require_external_activity",
"activityGateScope": "company"
}
```
Add a schedule trigger with `cronExpression: "0 * * * *"`. The first tick runs. Later ticks run only after qualifying company activity since the last dispatched run; quiet skipped ticks keep the original activity window open.
---
## Adding Triggers
A routine can have multiple triggers of different kinds.
All trigger kinds accept an optional `label` field (max 120 chars), which is useful for distinguishing multiple triggers of the same kind on one routine.
```
POST /api/routines/{routineId}/triggers
```
### Schedule (cron)
```json
{
"kind": "schedule",
"cronExpression": "0 9 * * 1",
"timezone": "Europe/Amsterdam"
}
```
- `cronExpression`: standard 5-field cron syntax
- `timezone`: IANA timezone string (for example `UTC` or `America/New_York`)
- The server computes `nextRunAt` automatically
### Webhook
```json
{
"kind": "webhook",
"signingMode": "hmac_sha256",
"replayWindowSec": 300
}
```
- `signingMode`: `bearer` (default) or `hmac_sha256`. Agents can only create authenticated webhook triggers; if a sender cannot authenticate, ask a person to set that trigger up on the board.
- `replayWindowSec`: 30-86400 (default 300)
- Response includes the webhook URL (`publicId`-based) and the signing secret
- Fire externally: `POST /api/routine-triggers/public/{publicId}/fire`
- Bearer: `Authorization: Bearer <secret>`
- HMAC: `X-Paperclip-Signature` + `X-Paperclip-Timestamp` headers
### API (manual only)
```json
{
"kind": "api"
}
```
No configuration. Fire via the manual run endpoint.
---
## Updating and Deleting Triggers
```
PATCH /api/routine-triggers/{triggerId}
{ "enabled": false, "cronExpression": "0 10 * * 1" }
DELETE /api/routine-triggers/{triggerId}
```
To rotate a webhook secret (the old secret is immediately invalidated):
```
POST /api/routine-triggers/{triggerId}/rotate-secret
```
---
## Manual Run
Fires a run immediately, bypassing the schedule. Concurrency policy still applies.
```
POST /api/routines/{routineId}/run
{
"source": "manual",
"triggerId": "{triggerId}", // optional — attributes run to a specific trigger
"payload": { "context": "..." }, // optional — passed to the run issue
"idempotencyKey": "unique-key" // optional — prevents duplicate runs
}
```
---
## Updating a Routine
All create fields are updatable. Agents cannot reassign a routine to another agent.
```
PATCH /api/routines/{routineId}
{ "status": "paused", "title": "New title" }
```
---
## Reading Routines and Runs
```
GET /api/companies/{companyId}/routines
GET /api/routines/{routineId}
GET /api/routines/{routineId}/runs?limit=50
```
Use the generic API endpoint tables in `skills/paperclip/references/api-reference.md` when you need a full cross-domain reference. Use this file when you need routine-specific behaviour, payload shape, or policy details.
**Delivering results to the human's chat**
A routine execution task can call `send_chat_message({ body, idempotencyKey })`
or `POST /api/agents/me/chat/messages` using its run credentials. The server sends
to that agent's chat with the run's responsible human, including before the human
has opened the chat. No recipient lookup or destination ID is needed. Retain a
stable key across retries of the source task; changed content with that key conflicts.
For a morning PR review, gather the PRs, send a concise Markdown digest with
links, then finish the task separately. Delivery commits immediately, marks the
chat unread and includes a source-task link. It neither wakes the chat agent nor
suppresses ordinary handoff completion notifications. Agent Chat must be enabled,
the run must be active in standard mode, and the source task must be suitable
for the company-visible chat. Missing or revoked recipients and restricted tasks
fail explicitly; never select a replacement recipient.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |