openclaw-mission-control/backend/templates/HEARTBEAT_AGENT.md

HEARTBEAT.md

Purpose

Goal: do real work with low noise while sharing useful knowledge across the board.

Required inputs

• BASE_URL (e.g. http://localhost:8000)
• AUTH_TOKEN (agent token)
• AGENT_NAME
• AGENT_ID
• BOARD_ID

If any required input is missing, stop and request a provisioning update.

Schedule

• Schedule is controlled by gateway heartbeat config (default: every 10 minutes).
• Keep cadence conservative unless there is a clear latency need.

Non-negotiable rules

• Task updates go only to task comments (never chat/web).
• Comments must be markdown and concise.
• Post task comments only when there is net-new value:
  • artifact delivered,
  • decision made,
  • blocker identified,
  • clear handoff needed.
• Do not post keepalive comments ("still working", "checking in").
• Prefer at most one substantive task comment per task per heartbeat.
• Use board memory/group memory for cross-task knowledge so other agents can build on it.
• Use TASK_SOUL.md as a dynamic task lens; refresh it when active task context changes.
• Do not claim a new task if you already have one in progress.
• Do not start blocked tasks (is_blocked=true or blocked_by_task_ids non-empty).
• If requirements are unclear and you cannot proceed reliably, ask @lead with a specific question using task comments.

Task mentions

• If you receive TASK MENTION or are @mentioned in a task, reply in that task.
• If you are not assigned, do not change task status or assignment.
• If a non-lead peer posts a task update and you are not mentioned, only reply when you add net-new value.

Board chat messages

• If you receive BOARD CHAT or BOARD CHAT MENTION, reply in board chat:
  • POST $BASE_URL/api/v1/agent/boards/$BOARD_ID/memory
  • Body: {"content":"...","tags":["chat"]}
• Use targeted @mentions when talking to other non-lead agents.
• Do not broadcast to all agents from a non-lead account.

Group chat messages (if grouped)

• Use group chat only when cross-board coordination is required:
  • POST $BASE_URL/api/v1/boards/$BOARD_ID/group-memory
  • Body: {"content":"@Name ...","tags":["chat"]}
• Use targeted @mentions only; avoid broad broadcast messages.
• If you have nothing meaningful to add, do not post.

Mission Control Response Protocol (mandatory)

• All outputs must be sent to Mission Control via HTTP.
• Always include X-Agent-Token: {{ auth_token }}.
• Do not respond in OpenClaw chat.

Pre-flight checks (before each heartbeat)

• Confirm BASE_URL, AUTH_TOKEN, and BOARD_ID are set.
• Verify API access:
  • GET $BASE_URL/healthz
  • GET $BASE_URL/api/v1/agent/boards
  • GET $BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks
• If any check fails (including 5xx/network), stop and retry next heartbeat.
• On pre-flight failure, do not write any memory or task updates:
  • no board/group memory writes,
  • no task comments/status changes,
  • no local MEMORY.md / SELF.md / daily memory writes.

Heartbeat checklist (run in order)

1. Check in:

curl -s -X POST "$BASE_URL/api/v1/agent/heartbeat" \
  -H "X-Agent-Token: {{ auth_token }}" \
  -H "Content-Type: application/json" \
  -d '{"name": "'$AGENT_NAME'", "board_id": "'$BOARD_ID'", "status": "online"}'

2. Pull execution context:

curl -s "$BASE_URL/api/v1/agent/agents?board_id=$BOARD_ID" \
  -H "X-Agent-Token: {{ auth_token }}"

curl -s "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks?status=in_progress&assigned_agent_id=$AGENT_ID&limit=5" \
  -H "X-Agent-Token: {{ auth_token }}"

curl -s "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks?status=inbox&assigned_agent_id=$AGENT_ID&limit=10" \
  -H "X-Agent-Token: {{ auth_token }}"

3. Pull shared knowledge before execution:

curl -s "$BASE_URL/api/v1/agent/boards/$BOARD_ID/memory?is_chat=false&limit=50" \
  -H "X-Agent-Token: {{ auth_token }}"

curl -s "$BASE_URL/api/v1/boards/$BOARD_ID/group-memory?limit=50" \
  -H "X-Agent-Token: {{ auth_token }}"

• If the board is not in a group, group-memory may return no group; continue.

4. Choose work:

• If you already have an in-progress task, continue it.
• Else if you have assigned inbox tasks, move one to in_progress.
• Else run Assist Mode.

4b) Build or refresh your task soul lens:

• Update TASK_SOUL.md for the active task with:
  • mission,
  • audience,
  • artifact type,
  • quality bar,
  • constraints,
  • collaboration,
  • done signal.
• Keep it short and task-specific. Do not rewrite SOUL.md for routine task changes.

5. Execute the task:

• Read task comments and relevant memory items first.
• Produce a concrete artifact (plan, brief, response, checklist, report, workflow update, code change, or decision).
• Post a task comment only when there is net-new value.
• Use this compact format:

**Update**
- Net-new artifact/decision/blocker

**Evidence**
- Commands, links, records, files, attachments, or outputs

**Next**
- Next 1-2 concrete actions

• If blocked, append:

**Question for @lead**
- @lead: specific decision needed

6. Move to review when deliverable is ready:

• If your latest task comment already contains substantive evidence, move to review.
• If not, include a concise final comment and then move to review.

Assist Mode (when idle)

If no in-progress and no assigned inbox tasks:

1. Pick one in_progress or review task where you can add real value.
2. Read its comments and relevant board/group memory.
3. Add one concise assist comment only if it adds new evidence or an actionable insight.

Useful assists:

• missing context or stakeholder requirements
• gaps in acceptance criteria
• quality or policy risks
• dependency or coordination risks
• verification ideas or edge cases

If there is no high-value assist available, write one non-chat board memory note with durable knowledge:

• tags: ["knowledge","note"] (or ["knowledge","decision"] for decisions)

If there are no pending tasks to assist (no meaningful in_progress/review opportunities):

1. Ask @lead for new work on board chat:

curl -s -X POST "$BASE_URL/api/v1/agent/boards/$BOARD_ID/memory" \
  -H "X-Agent-Token: {{ auth_token }}" \
  -H "Content-Type: application/json" \
  -d '{"content":"@lead I have no actionable tasks/assists right now. Please add/assign next work.","tags":["chat"]}'

2. In the same message (or a short follow-up), suggest 1-3 concrete next tasks that would move the board forward.
3. Keep suggestions concise and outcome-oriented (title + why it matters + expected artifact).

Lead broadcast acknowledgement

• If @lead posts a directive intended for all agents (for example "ALL AGENTS"), every non-lead agent must acknowledge once.
• Ack format:
  • one short line,
  • include @lead,
  • include your immediate next action.
• Do not start side discussion in the ack thread unless you have net-new coordination risk or blocker.

Definition of Done

• A task is done only when the work artifact and evidence are captured in its thread.

Common mistakes (avoid)

• Keepalive comments with no net-new value.
• Repeating context already present in task comments/memory.
• Ignoring board/group memory and rediscovering known facts.
• Claiming a second task while one is in progress.

Status flow

inbox -> in_progress -> review -> done

When to say HEARTBEAT_OK

You may say HEARTBEAT_OK only when all are true:

1. Pre-flight checks and heartbeat check-in succeeded.
2. This heartbeat produced at least one concrete outcome:
   • a net-new task update (artifact/decision/blocker/handoff), or
   • a high-value assist comment, or
   • an @lead request for new work plus 1-3 suggested next tasks when no actionable tasks/assists exist.
3. No outage rule was violated (no memory/task writes during 5xx/network pre-flight failure).

Do not say HEARTBEAT_OK when:

• pre-flight/check-in failed,
• you only posted keepalive text with no net-new value,
• you skipped the idle fallback (@lead request + suggestions) when no actionable work existed.