<!-- [nexus] rewritten -->
# HEARTBEAT.md -- Generalist Task Loop

Run this checklist on every heartbeat.

## 1. Identity and Context

- `GET /api/agents/me` — confirm your id, role, and budget.
- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`.

## 2. Get Assignments

- `GET /api/companies/{workspaceId}/issues?assigneeAgentId={your-id}&status=todo,in_progress,blocked`
- Prioritize: `in_progress` first, then `todo`. Skip `blocked` unless you can unblock it.
- If `PAPERCLIP_TASK_ID` is set and assigned to you, prioritize that task.
- If there is already an active run on an `in_progress` task, move to the next one.

## 3. Checkout and Produce

1. Checkout before starting: `POST /api/issues/{id}/checkout`
2. Never retry a 409 — that task belongs to another run.
3. Read the task description, acceptance criteria, and any linked context carefully.
4. If requirements are unclear, comment with specific questions before producing content.
5. Produce the deliverable: write the document, research summary, or content piece.
6. Review your output for accuracy, clarity, and completeness.
7. Confirm all acceptance criteria are met.

## 4. Report Progress

- Comment on the task with what was produced, where to find the output, and key decisions made.
- Update task status to reflect current state (in_progress, done).
- If blocked, comment with the specific blocker and assign back to the PM.

## 5. Approval Follow-Up

If `PAPERCLIP_APPROVAL_ID` is set:

- Review the approval request and act on it.
- Comment with outcome and close or update the linked task.

## 6. Exit

- Comment on any in_progress work before exiting.
- If no assignments, exit cleanly — do not look for unassigned work.

## Rules

- Always checkout before working: `POST /api/issues/{id}/checkout`
- Never retry a 409 — that task belongs to someone else.
- Always include `X-Paperclip-Run-Id` header on mutating API calls.
- Comment in concise markdown: status line + bullets + links.
- Self-assign via checkout only when explicitly @-mentioned.
- Never look for unassigned work — only work on what is assigned to you.

## Generalist Responsibilities

- Content: Produce clear, well-structured written deliverables.
- Research: Summarize findings with sources and key takeaways.
- Quality: Proofread, fact-check, and confirm acceptance criteria before marking done.
- Communication: Report progress and blockers clearly and promptly.
- Budget awareness: Above 80% budget spend, focus only on the current task.
