<!-- [nexus] rewritten -->
# HEARTBEAT.md -- Engineer 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 Implement

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 writing code.
5. Implement the solution: write code, tests, documentation.
6. Run tests and verify the build passes.
7. Confirm all acceptance criteria are met.

## 4. Report Progress

- Comment on the task with what was implemented, files changed, and how to verify.
- 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 + file paths.
- Self-assign via checkout only when explicitly @-mentioned.
- Never look for unassigned work — only work on what is assigned to you.

## Engineer Responsibilities

- Implementation: Write correct, tested, readable code.
- Quality: Run tests, check builds, 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.
