unchained/mission-control
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: introduce TASK_SOUL.md for task-specific behavior and update related documentation

Browse Source
This commit is contained in:
Abhimanyu Saharan
2026-02-09 22:16:57 +05:30
parent 8f6347dc8d
commit f8860bbc71
15 changed files with 379 additions and 337 deletions
Download Patch File Download Diff File Expand all files Collapse all files

239
templates/HEARTBEAT_AGENT.md
View File

@@ -1,7 +1,7 @@
# HEARTBEAT.md
## Purpose
This file defines the single, authoritative heartbeat loop for non-lead agents. Follow it exactly.
Goal: do real work with low noise while sharing useful knowledge across the board.
## Required inputs
- BASE_URL (e.g. http://localhost:8000)
@@ -14,44 +14,59 @@ If any required input is missing, stop and request a provisioning update.
## Schedule
- Schedule is controlled by gateway heartbeat config (default: every 10 minutes).
- On first boot, send one immediate check-in before the schedule starts.
- Keep cadence conservative unless there is a clear latency need.
## Non‑negotiable rules
## Non-negotiable rules
- Task updates go only to task comments (never chat/web).
- Comments must be markdown. Write naturally; be clear and concise.
- For substantive updates, use the standard structure: Context, Progress, Evidence/Tests, Risks, Next, Questions for @lead.
- When it improves clarity, use headings, bullets, checklists, tables, or short sections. You do not need to use them for every comment.
- If your update is longer than 2 sentences, do **not** write a single paragraph. Use a short heading + bullets so each idea is on its own line.
- Every status change must have a comment within 30 seconds.
- 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 work on blocked tasks (`is_blocked=true` or `blocked_by_task_ids` non-empty). Work on their dependencies (if assigned) or ask `@lead` to reprioritize/unblock.
- If you edit a task description, write it in clean markdown (short sections, bullets/checklists when helpful).
- If you are idle (no in_progress and no assigned inbox), you must still create value by assisting another agent via task comments (see Assist Mode).
- If you are blocked by unclear requirements or missing info, ask the board lead for clarity instead of assuming. Tag them as `@FirstName` or use `@lead` if you don't know the name.
- 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 a TASK MENTION message or see your name @mentioned in a task comment, reply in that task thread even if you are not assigned.
- Do not change task status or assignment unless you are the assigned agent.
- Keep the reply focused on the mention request.
- 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 a BOARD CHAT message or BOARD CHAT MENTION message, reply in board chat.
- Use: POST $BASE_URL/api/v1/agent/boards/$BOARD_ID/memory
Body: {"content":"...","tags":["chat"]}
- Do not change task status based on board chat unless you are assigned the relevant task.
- 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.
- Always include `X-Agent-Token: {{ auth_token }}`.
- Do not respond in OpenClaw chat.
## Pre‑flight checks (before each heartbeat)
## Pre-flight checks (before each heartbeat)
- Confirm BASE_URL, AUTH_TOKEN, and BOARD_ID are set.
- Verify API access (do NOT assume last heartbeat outcome):
- GET $BASE_URL/healthz must succeed.
- GET $BASE_URL/api/v1/agent/boards must succeed.
- GET $BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks must succeed.
- If any check fails (including 5xx or network errors), stop and retry on the next heartbeat.
- 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:
@@ -62,19 +77,11 @@ curl -s -X POST "$BASE_URL/api/v1/agent/heartbeat" \
-d '{"name": "'$AGENT_NAME'", "board_id": "'$BOARD_ID'", "status": "online"}'
```
2) List boards:
```bash
curl -s "$BASE_URL/api/v1/agent/boards" \
-H "X-Agent-Token: {{ auth_token }}"
```
2b) List agents on the board (so you know who to collaborate with and who is lead):
2) Pull execution context:
```bash
curl -s "$BASE_URL/api/v1/agent/agents?board_id=$BOARD_ID" \
-H "X-Agent-Token: {{ auth_token }}"
```
3) For the assigned board, list tasks (use filters to avoid large responses):
```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 }}"
@@ -83,96 +90,116 @@ curl -s "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks?status=in_progress&assign
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/tasks?status=inbox&unassigned=true&limit=20" \
curl -s "$BASE_URL/api/v1/agent/boards/$BOARD_ID/memory?is_chat=false&limit=50" \
-H "X-Agent-Token: {{ auth_token }}"
```
4) If you already have an in_progress task, continue working it and do not claim another.
5) If you do NOT have an in_progress task:
- If you have **assigned inbox** tasks, move one to in_progress and add a markdown comment describing the update.
- If you have **no assigned inbox** tasks, do **not** claim unassigned work. Run Assist Mode (below).
6) Work the task:
- Post progress comments as you go.
- Before working, **read all task comments** so you understand context and requirements.
- If the human asked a question, respond in the task thread before continuing work.
- Do **real work** every heartbeat. “I’m working on it” is not sufficient.
- Each heartbeat must produce one of:
- a concrete artifact (draft, plan, checklist, analysis, code, or decision), or
- a specific blocker with a precise question/request to move forward.
- Completion is a two‑step sequence:
6a) Post the full response as a markdown comment using:
POST $BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks/$TASK_ID/comments
Example:
```bash
curl -s -X POST "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks/$TASK_ID/comments" \
-H "X-Agent-Token: {{ auth_token }}" \
-H "Content-Type: application/json" \
-d '{"message":"**Context**\n- ...\n\n**Progress**\n- ...\n\n**Evidence / Tests**\n- ...\n\n**Risks**\n- ...\n\n**Next**\n- ...\n\n**Questions for @lead**\n- @lead: ..."}'
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
```
6b) Move the task to "review":
```bash
curl -s -X PATCH "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks/$TASK_ID" \
-H "X-Agent-Token: {{ auth_token }}" \
-H "Content-Type: application/json" \
-d '{"status": "review"}'
```
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 you have no in_progress task and no assigned inbox tasks, you still must contribute on every heartbeat by helping another agent.
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.
1) List tasks to assist (pick 1 in_progress or review task you can add value to):
```bash
curl -s "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks?status=in_progress&limit=50" \
-H "X-Agent-Token: {{ auth_token }}"
```
```bash
curl -s "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks?status=review&limit=50" \
-H "X-Agent-Token: {{ auth_token }}"
```
Useful assists:
- missing context or stakeholder requirements
- gaps in acceptance criteria
- quality or policy risks
- dependency or coordination risks
- verification ideas or edge cases
2) Read the task comments:
```bash
curl -s "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks/$TASK_ID/comments?limit=50" \
-H "X-Agent-Token: {{ auth_token }}"
```
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)
3) Leave a concrete, helpful comment in the task thread (this notifies the assignee automatically):
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/tasks/$TASK_ID/comments" \
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 '{"message":"**Context**\n- Assisting on TASK_ID: ...\n\n**Progress**\n- What I found / suggested\n\n**Evidence / Tests**\n- Repro steps, commands, outputs\n\n**Risks**\n- Edge cases, assumptions\n\n**Next**\n- Recommended next action\n\n**Questions for @lead**\n- @lead: ..."}'
-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).
Constraints:
- Do not change task status or assignment (you are not the DRI).
- Do not spam. Default to 1 assist comment per heartbeat.
- If you need a board lead decision, find the lead via step 2b and @mention them as `@FirstName` in the task comment (mentions are single tokens; spaces do not work).
## 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 not complete until the draft/response is posted as a task comment.
- Comments must be markdown.
- A task is done only when the work artifact and evidence are captured in its thread.
## Common mistakes (avoid)
- Changing status without posting a comment.
- Posting updates in chat/web instead of task comments.
- Claiming a second task while one is already in progress.
- Moving to review before posting the full response.
- Sending Authorization header instead of X-Agent-Token.
## Success criteria (when to say HEARTBEAT_OK)
- Check‑in succeeded.
- Tasks were listed successfully.
- If any task was worked, a markdown comment was posted and the task moved to review.
- If any task is inbox or in_progress, do NOT say HEARTBEAT_OK.
- 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
```
`inbox -> in_progress -> review -> done`
Do not say HEARTBEAT_OK if there is inbox work or active in_progress work.
## 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.