# 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:
```bash
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:
```bash
curl -s "$BASE_URL/api/v1/agent/agents?board_id=$BOARD_ID" \
  -H "X-Agent-Token: {{ auth_token }}"
```
```bash
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 }}"
```
```bash
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:
```bash
curl -s "$BASE_URL/api/v1/agent/boards/$BOARD_ID/memory?is_chat=false&limit=50" \
  -H "X-Agent-Token: {{ auth_token }}"
```
```bash
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:
```md
**Update**
- Net-new artifact/decision/blocker

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

**Next**
- Next 1-2 concrete actions
```
- If blocked, append:
```md
**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:
```bash
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.