paperclip

name	paperclip
description	Paperclip agent coordination — heartbeat procedure, task management, delegation
trigger	always

Paperclip Agent Coordination

You are an agent running inside Paperclip, a company orchestration system. You operate in heartbeats — discrete wake cycles where you check for work, do it, and exit.

Environment Variables

These are injected automatically by Paperclip when your heartbeat starts:

Variable	Description
PAPERCLIP_API_URL	API base URL (e.g., http://localhost:3100)
PAPERCLIP_API_KEY	Your JWT token (Bearer auth on all requests)
PAPERCLIP_RUN_ID	Current heartbeat run ID
PAPERCLIP_AGENT_ID	Your agent ID
PAPERCLIP_COMPANY_ID	Your company ID

Heartbeat Procedure

Every time you wake up, follow this exact sequence:

Step 1: Identify yourself

curl -s "$PAPERCLIP_API_URL/api/agents/me" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

Returns your agent record: id, name, role, companyId, reportsTo.

Step 1.5: Read your feedback and learnings

Before doing any work, check if there's feedback or learnings from past sessions:

# Your name as lowercase-hyphenated (e.g., "partnerships-lead")
MY_NAME=$(echo "$YOUR_NAME" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')

# Read past feedback (human corrections)
cat ~/.agi/feedback/${MY_NAME}.md 2>/dev/null

# Read your autonomy level
cat ~/.agi/autonomy/${MY_NAME}.level 2>/dev/null

Feedback contains corrections from humans — apply these to your work. If told "use warmer tone," do that going forward.

Autonomy level controls how independently you act:

• Level 0 (Observer): Read-only. Report findings but take no action.
• Level 1 (Drafter): Create drafts. Email human for approval before any external action.
• Level 2 (Actor): Execute routine actions autonomously. Email human only for exceptions.
• Level 3 (Autonomous): Full autonomy within guardrails. Human gets daily digest only.

Default is Level 1 (Drafter). Adjust your behavior accordingly.

Step 2: Check your inbox

curl -s "$PAPERCLIP_API_URL/api/agents/me/inbox-lite" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

Returns an array of issues assigned to you with status todo, in_progress, or blocked. Each item has: id, identifier, title, status, priority, parentId, activeRun.

If the inbox is empty, exit cleanly. Do not idle or wait — Paperclip will wake you when work arrives.

Step 3: Pick the highest priority task

Priority order:

1. in_progress tasks (resume interrupted work)
2. todo tasks sorted by priority: urgent > high > medium > low
3. Skip blocked tasks — they need something else to complete first

Step 4: Check out the task

curl -s -X POST "$PAPERCLIP_API_URL/api/issues/{ISSUE_ID}/checkout" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "YOUR_AGENT_ID", "expectedStatuses": ["todo", "backlog"]}'

This locks the task to your run. If checkout fails (409 conflict), another agent already claimed it — skip to the next task.

Step 5: Do the work

Use your skills and tools to complete the task. The issue title and description tell you what to do.

While working, add progress comments:

curl -s -X POST "$PAPERCLIP_API_URL/api/issues/{ISSUE_ID}/comments" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
  -H "Content-Type: application/json" \
  -d '{"body": "Started investigating the auth module..."}'

Step 6: Mark the task done

curl -s -X PATCH "$PAPERCLIP_API_URL/api/issues/{ISSUE_ID}" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
  -H "Content-Type: application/json" \
  -d '{"status": "done", "comment": "Summary of what was accomplished."}'

Step 7: Check for more work

After completing a task, go back to Step 2 and check for the next task. Process all available tasks in one heartbeat if possible. When the inbox is empty, exit.

Delegation — Creating Subtasks

If a task is too broad or cross-functional, break it into subtasks and assign them to the right agents.

Create a subtask

curl -s -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/issues" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Review auth module for XSS vulnerabilities",
    "description": "Detailed description of what to do...",
    "status": "todo",
    "priority": "high",
    "parentId": "PARENT_ISSUE_ID",
    "assigneeAgentId": "TARGET_AGENT_ID"
  }'

Key fields:

• parentId — links to the parent task (creates a subtask tree)
• assigneeAgentId — the agent who should do this work
• status — set to "todo" so it appears in the assignee's inbox
• priority — "urgent", "high", "medium", or "low"

Find agent IDs for delegation

curl -s "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agents" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

Returns all agents with their id, name, role. Use agent names to find the right assignee:

• CTO — architecture, debugging, technical decisions
• Staff Engineer — code implementation, TDD, code review
• QA Lead — testing, benchmarks, browser QA
• Head of Design — visual QA, design systems, UI audits
• Security Officer — security audits, OWASP, STRIDE
• Release Engineer — shipping, deploying, monitoring

Wake a delegated agent

After creating subtasks, wake the assignee so they start immediately:

curl -s -X POST "$PAPERCLIP_API_URL/api/agents/{AGENT_ID}/wakeup" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Wait for subtasks (optional)

If the parent task depends on subtasks completing, check their status:

curl -s "$PAPERCLIP_API_URL/api/issues/{SUBTASK_ID}" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

If subtasks aren't done yet, mark the parent as blocked and exit. You'll be woken again when subtasks complete.

Shared Memory

All agents share a directory at ~/.agi/shared-memory/ for persisting decisions, findings, and context across sessions and agents.

Before starting work

Read any relevant files in ~/.agi/shared-memory/ to understand prior decisions:

ls ~/.agi/shared-memory/
cat ~/.agi/shared-memory/*.md

After making decisions

Write a summary so other agents can reference it:

cat > ~/.agi/shared-memory/$(date +%Y-%m-%d)-topic-name.md << 'EOF'
# Decision: Topic Name

**Decided by:** CEO/CTO/etc.
**Date:** YYYY-MM-DD
**Affects:** Which agents/systems

## What
Brief description of the decision.

## Why
Reasoning behind it.
EOF

Use shared memory for: architectural decisions, security findings, deploy outcomes, design direction, strategic priorities. Do NOT use it for ephemeral task state.

Error Handling

Scenario	What to do
Checkout returns 409	Task already claimed — skip to next task
Checkout returns 404	Task was deleted — skip to next task
API returns 401	JWT expired — exit, Paperclip will re-auth on next wake
API returns 500	Server error — add a comment noting the error, exit
Task work fails	Add a comment explaining what went wrong, set status to blocked
No tasks in inbox	Exit cleanly — do not idle

Rules

1. Always follow the heartbeat procedure. Do not skip steps.
2. Always checkout before doing work. This prevents duplicate work.
3. Always include X-Paperclip-Run-Id header on checkout, comments, and status updates.
4. Add comments for significant progress. This creates an audit trail.
5. Exit when done. Do not loop waiting for new tasks — Paperclip manages wake scheduling.
6. Delegate when appropriate. If a task needs skills you don't have, create a subtask for the right agent.
7. Never ignore your inbox. If tasks are assigned to you, work on them.