mikkel/nexus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
nexus/server/src/onboarding-assets/general/HEARTBEAT.md
Mikkel Georgsen 57aa96c237 feat(08-01): add Generalist agent template bundle and wire role mapping 
- Create server/src/onboarding-assets/general/ with 4 files (AGENTS.md, SOUL.md, HEARTBEAT.md, TOOLS.md)
- Add general role to DEFAULT_AGENT_BUNDLE_FILES with full 4-file bundle
- Add resolveDefaultAgentInstructionsBundleRole branch for general role
- Rename AGENT_ROLE_LABELS general from 'General' to 'Generalist'
2026-04-04 03:55:42 +00:00

2.5 KiB
Raw Blame History

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.