setup-routines

Setup Routines — Data-Driven Routine Provisioning

This skill analyzes a Paperclip company's actual operational data to design routines that match real needs — not generic templates. The goal: replace expensive always-on heartbeats with targeted routines that fire only when needed.

Heartbeats cost tokens. Routines save money.

Analysis Framework

Before creating a single routine, run the full diagnostic. Each step feeds signal into the routine design.

Phase 1: Company Health Snapshot

Pull the dashboard for a quick pulse check.

curl -s "$PAPERCLIP_API_URL/api/companies/{companyId}/dashboard" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

Extract:

• Agent error count — agents in error state need a recovery routine
• Open vs done ratio — high open count with low velocity = bottleneck
• Blocked count — chronic blockers need an escalation routine
• Budget utilization — high utilization = routines must be lean
• Pending approvals — stalled approvals need a nudge routine

Phase 2: Issue Archaeology

Query completed and open issues to find recurring patterns.

# Recent completed issues — look for repeat categories
curl -s "$PAPERCLIP_API_URL/api/companies/{companyId}/issues?status=done&limit=100" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

# Open issues — find unassigned or stalled work
curl -s "$PAPERCLIP_API_URL/api/companies/{companyId}/issues?status=todo,in_progress,blocked&limit=50" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

Pattern mining — look for these signals in issue titles and descriptions:

Frequency analysis — count issues per category:

# Mental model for categorization (do this analysis in your head):
# Group done issues by theme:
#   CI/build failures: N issues → if N >= 3, needs a routine
#   Runtime crashes: N issues → if N >= 3, needs a routine
#   API integration: N issues → if N >= 2, needs a routine
#   Deploy issues: N issues → if N >= 2, needs a routine
#   Unassigned backlog: N items → if N >= 3 high-pri, needs triage routine

Phase 3: Agent Diagnostics

# List agents with status
curl -s "$PAPERCLIP_API_URL/api/companies/{companyId}/agents" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

Check each agent for:

• Error state — needs recovery routine (critical priority)
• Idle with open assignments — might be stuck, needs nudge
• Budget near limit — routines for this agent should be conservative
• Role-specific needs — CEO needs oversight routines, Engineer needs technical checks

Phase 4: Project & Infrastructure Context

# Project details including workspace/repo
curl -s "$PAPERCLIP_API_URL/api/projects/{projectId}" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

Check for:

• GitHub repo → can wire webhook triggers for push/PR events
• Railway/Vercel deployment → can wire deploy webhook triggers
• External API dependencies (Suno, Stripe, etc.) → need health check routines
• Database → migration safety checks post-deploy

Phase 5: Activity Timeline Analysis

curl -s "$PAPERCLIP_API_URL/api/companies/{companyId}/activity?limit=50" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

Look for:

• Activity gaps — long periods with no activity = agents might be stuck
• Burst patterns — many issues created/closed at once = reactive mode (routines should prevent this)
• Error clusters — multiple failures in a short window = systemic issue

Routine Design Rules

Priority Assignment

Schedule Design

Concurrency Policy Selection

Trigger Layering

Best practice: webhook + cron fallback for event-driven routines.

• Webhook fires immediately on the event (push, deploy, error alert)
• Cron fires daily/periodically as a safety net if webhook misses
• This gives you both real-time response AND guaranteed coverage

Provisioning Procedure

After analysis, create routines in this order:

1. Critical first — agent recovery, CI health
2. High priority — runtime patrol, triage
3. Medium — API checks, deploy verification
4. Low — audits, grooming

For each routine:

# Step 1: Create the routine
ROUTINE=$(curl -s -X POST "$PAPERCLIP_API_URL/api/companies/{companyId}/routines" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "...",
    "description": "... include specific issue references that motivated this routine ...",
    "assigneeAgentId": "...",
    "projectId": "...",
    "priority": "...",
    "status": "active",
    "concurrencyPolicy": "skip_if_active",
    "catchUpPolicy": "skip_missed"
  }')
ROUTINE_ID=$(echo "$ROUTINE" | jq -r '.id')

# Step 2: Add triggers
# Cron trigger
curl -s -X POST "$PAPERCLIP_API_URL/api/routines/$ROUTINE_ID/triggers" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "schedule", "cronExpression": "...", "timezone": "Europe/Amsterdam"}'

# Webhook trigger (if event-driven)
curl -s -X POST "$PAPERCLIP_API_URL/api/routines/$ROUTINE_ID/triggers" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "webhook", "signingMode": "bearer"}'

# Step 3: Test with manual run
curl -s -X POST "$PAPERCLIP_API_URL/api/routines/$ROUTINE_ID/run" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source": "manual"}'

Routine Description Best Practices

Always include in the description:

1. What the routine checks/does
2. Why it exists — reference specific past issues by identifier (e.g., "Recurring: SUNAA-141, SUNAA-142, SUNAA-143 — lint errors breaking CI pipeline")
3. What success looks like — the agent knows when the check passes
4. What failure triggers — what should the agent do if the check fails

This context is injected into the agent's heartbeat when the routine fires, so a well-written description = fewer wasted tokens figuring out what to do.

Verification Checklist

After provisioning all routines:

# List all active routines with triggers
curl -s "$PAPERCLIP_API_URL/api/companies/{companyId}/routines" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

# For each routine, verify triggers exist
curl -s "$PAPERCLIP_API_URL/api/routines/{routineId}" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

# Fire a manual test run on the most critical routine
curl -s -X POST "$PAPERCLIP_API_URL/api/routines/{routineId}/run" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source": "manual"}'

# Verify the run created an issue
curl -s "$PAPERCLIP_API_URL/api/routines/{routineId}/runs?limit=1" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

Output Summary Template

After completing setup, report:

## Routines Provisioned for {Company}

### Analysis Summary
- Issues analyzed: {N done} + {N open}
- Recurring patterns found: {list}
- Agents in error: {list}
- Unassigned high-priority: {count}

### Routines Created
| # | Title | Agent | Priority | Triggers | Rationale |
|---|-------|-------|----------|----------|-----------|
| 1 | ...   | ...   | ...      | ...      | Based on {issue pattern} |

### Webhook URLs (wire into external services)
- CI guard: POST {url} (GitHub push events)
- Deploy verify: POST {url} (Railway deploy events)

### Token Savings Estimate
- Previous: ~{N} heartbeats/day at ~{cost} tokens each
- Now: ~{N} targeted routine runs/day
- Estimated reduction: {X}%

Ongoing Maintenance

Routines aren't set-and-forget. Review monthly:

1. Check run history — routines that never find issues can be reduced in frequency
2. Check for new patterns — new recurring issue categories may need new routines
3. Adjust schedules — align with team's actual working hours and deploy cadence
4. Archive stale routines — if the underlying problem was permanently fixed

# Quick health check on all routines
curl -s "$PAPERCLIP_API_URL/api/companies/{companyId}/routines" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" | jq '.[] | select(.status=="active") | {title, lastTriggeredAt, lastEnqueuedAt}'

API Quick Reference

Auth Note (Local Docker)

If calling from outside the container (host machine), you need a board API key. Generate one via the Paperclip UI or by inserting a hashed key into the board_api_keys table. Agent API keys (PAPERCLIP_API_KEY) work from inside heartbeat runs but agents can only create routines assigned to themselves.