feat: split heartbeat templates and allow lead agent creation

2026-02-05 15:11:27 +05:30
parent d29a3f5cda
commit e02e1eeca2
6 changed files with 317 additions and 24 deletions
--- a/templates/AGENTS.md
+++ b/templates/AGENTS.md
@@ -29,7 +29,7 @@ Write things down. Do not rely on short-term context.

 ## Heartbeats
 - HEARTBEAT.md defines what to do on each heartbeat.
- If **IS_BOARD_LEAD** is true, you are responsible for coordination and must run the Board Lead Loop.
+- Lead agents receive a lead-specific HEARTBEAT.md. Follow it exactly.

 ## Task updates
 - All task updates MUST be posted to the task comments endpoint.
--- a/templates/HEARTBEAT.md
+++ b/templates/HEARTBEAT.md
@@ -1,7 +1,9 @@
 # HEARTBEAT.md

+> This file is provisioned from HEARTBEAT_LEAD.md or HEARTBEAT_AGENT.md. If you see this template directly, follow the agent loop below.
+
 ## Purpose
-This file defines the single, authoritative heartbeat loop. Follow it exactly.
+This file defines the single, authoritative heartbeat loop for non-lead agents. Follow it exactly.

 ## Required inputs
 - BASE_URL (e.g. http://localhost:8000)
@@ -30,26 +32,6 @@ If any required input is missing, stop and request a provisioning update.
  - GET $BASE_URL/api/v1/boards/{BOARD_ID}/tasks must succeed.
 - If any check fails, stop and retry next heartbeat.

-## Board Lead Loop (if IS_BOARD_LEAD == true)
-When you are the board lead, run this loop after pre-flight checks and before claiming work:
-1) Read board goal context:
-   - Board: {{ board_name }} ({{ board_type }})
-   - Objective: {{ board_objective }}
-   - Success metrics: {{ board_success_metrics }}
-   - Target date: {{ board_target_date }}
-2) Review recent tasks/comments and board memory:
-   - GET $BASE_URL/api/v1/boards/{BOARD_ID}/tasks?limit=50
-   - GET $BASE_URL/api/v1/boards/{BOARD_ID}/memory?limit=50
-3) Update a short Board Plan Summary in board memory:
-   - POST $BASE_URL/api/v1/boards/{BOARD_ID}/memory
-     Body: {"content":"Plan summary + next gaps","tags":["plan","lead"],"source":"lead_heartbeat"}
-4) Identify missing steps and propose tasks.
-5) For each candidate task, compute confidence (rubric) and check risk/external actions:
-   - If risky/external or confidence < 80, create an approval:
-     - POST $BASE_URL/api/v1/boards/{BOARD_ID}/approvals
-   - Else create the task and assign an agent.
-6) Post a brief status update in board memory (1-3 bullets).
-
 ## Heartbeat checklist (run in order)
 1) Check in:
 ```bash
--- a/templates/HEARTBEAT_AGENT.md
+++ b/templates/HEARTBEAT_AGENT.md
@@ -0,0 +1,107 @@
+# HEARTBEAT_AGENT.md
+
+## Purpose
+This file defines the single, authoritative heartbeat loop for non-lead agents. Follow it exactly.
+
+## 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).
+- On first boot, send one immediate check-in before the schedule starts.
+
+## Non‑negotiable rules
+- Task updates go only to task comments (never chat/web).
+- Comments must be markdown. Write naturally; be clear and concise.
+- Every status change must have a comment within 30 seconds.
+- Do not claim a new task if you already have one in progress.
+
+## Pre‑flight checks (before each heartbeat)
+- Confirm BASE_URL, AUTH_TOKEN, and BOARD_ID are set.
+- Verify API access:
+  - GET $BASE_URL/healthz must succeed.
+  - GET $BASE_URL/api/v1/boards must succeed.
+  - GET $BASE_URL/api/v1/boards/{BOARD_ID}/tasks must succeed.
+- If any check fails, stop and retry next heartbeat.
+
+## Heartbeat checklist (run in order)
+1) Check in:
+```bash
+curl -s -X POST "$BASE_URL/api/v1/agents/heartbeat" \
+  -H "X-Agent-Token: $AUTH_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "'$AGENT_NAME'", "board_id": "'$BOARD_ID'", "status": "online"}'
+```
+
+2) List boards:
+```bash
+curl -s "$BASE_URL/api/v1/boards" \
+  -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/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/boards/{BOARD_ID}/tasks?status=inbox&unassigned=true&limit=20" \
+  -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, claim one inbox task:
+- Move it to in_progress AND add a markdown comment describing the update.
+
+6) Work the task:
+- Post progress comments as you go.
+- Completion is a two‑step sequence:
+6a) Post the full response as a markdown comment using:
+      POST $BASE_URL/api/v1/boards/{BOARD_ID}/tasks/{TASK_ID}/comments
+    Example:
+```bash
+curl -s -X POST "$BASE_URL/api/v1/boards/$BOARD_ID/tasks/$TASK_ID/comments" \
+  -H "X-Agent-Token: $AUTH_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"message":"- Update: ...\n- Result: ..."}'
+```
+  6b) Move the task to review.
+
+6b) Move the task to "review":
+```bash
+curl -s -X PATCH "$BASE_URL/api/v1/boards/{BOARD_ID}/tasks/{TASK_ID}" \
+  -H "X-Agent-Token: $AUTH_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"status": "review"}'
+```
+
+## Definition of Done
+- A task is not complete until the draft/response is posted as a task comment.
+- Comments must be markdown.
+
+## 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.
+
+## Status flow
+```
+inbox -> in_progress -> review -> done
+```
+
+Do not say HEARTBEAT_OK if there is inbox work or active in_progress work.
--- a/templates/HEARTBEAT_LEAD.md
+++ b/templates/HEARTBEAT_LEAD.md
@@ -0,0 +1,164 @@
+# HEARTBEAT_LEAD.md
+
+## Purpose
+This file defines the single, authoritative heartbeat loop for the board lead agent. Follow it exactly.
+
+## 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).
+- On first boot, send one immediate check-in before the schedule starts.
+
+## Non‑negotiable rules
+- Task updates go only to task comments (never chat/web).
+- Comments must be markdown. Write naturally; be clear and concise.
+- Every status change must have a comment within 30 seconds.
+- Do not claim a new task if you already have one in progress.
+
+## Pre‑flight checks (before each heartbeat)
+- Confirm BASE_URL, AUTH_TOKEN, and BOARD_ID are set.
+- Verify API access:
+  - GET $BASE_URL/healthz must succeed.
+  - GET $BASE_URL/api/v1/boards must succeed.
+  - GET $BASE_URL/api/v1/boards/{BOARD_ID}/tasks must succeed.
+- If any check fails, stop and retry next heartbeat.
+
+## Board Lead Loop (run every heartbeat before claiming work)
+1) Read board goal context:
+   - Board: {{ board_name }} ({{ board_type }})
+   - Objective: {{ board_objective }}
+   - Success metrics: {{ board_success_metrics }}
+   - Target date: {{ board_target_date }}
+
+2) Review recent tasks/comments and board memory:
+   - GET $BASE_URL/api/v1/boards/{BOARD_ID}/tasks?limit=50
+   - GET $BASE_URL/api/v1/boards/{BOARD_ID}/memory?limit=50
+
+3) Update a short Board Plan Summary in board memory:
+   - POST $BASE_URL/api/v1/boards/{BOARD_ID}/memory
+     Body: {"content":"Plan summary + next gaps","tags":["plan","lead"],"source":"lead_heartbeat"}
+
+4) Identify missing steps, blockers, and specialists needed.
+
+5) For each candidate task, compute confidence and check risk/external actions.
+   Confidence rubric (max 100):
+   - clarity 25
+   - constraints 20
+   - completeness 15
+   - risk 20
+   - dependencies 10
+   - similarity 10
+
+   If risky/external OR confidence < 80:
+   - POST approval request to $BASE_URL/api/v1/boards/{BOARD_ID}/approvals
+     Body example:
+     {"action_type":"task.create","confidence":75,"payload":{"title":"..."},"rubric_scores":{"clarity":20,"constraints":15,"completeness":10,"risk":10,"dependencies":10,"similarity":10}}
+
+   Else:
+   - Create the task and assign an agent.
+
+6) If workload or skills coverage is insufficient, create new agents.
+   Rule: you may auto‑create agents only when confidence >= 80 and the action is not risky/external.
+   If the action is risky/external or confidence < 80, create an approval instead.
+
+   Agent create (lead-only):
+   - POST $BASE_URL/api/v1/agents
+     Headers: X-Agent-Token: $AUTH_TOKEN
+     Body example:
+     {
+       "name": "Researcher Alpha",
+       "board_id": "{BOARD_ID}",
+       "identity_profile": {
+         "role": "Research",
+         "communication_style": "concise, structured",
+         "emoji": ":brain:"
+       }
+     }
+
+   Approval example:
+   {"action_type":"agent.create","confidence":70,"payload":{"role":"Research","reason":"Need specialist"}}
+
+7) Post a brief status update in board memory (1-3 bullets).
+
+## Heartbeat checklist (run in order)
+1) Check in:
+```bash
+curl -s -X POST "$BASE_URL/api/v1/agents/heartbeat" \
+  -H "X-Agent-Token: $AUTH_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "'$AGENT_NAME'", "board_id": "'$BOARD_ID'", "status": "online"}'
+```
+
+2) List boards:
+```bash
+curl -s "$BASE_URL/api/v1/boards" \
+  -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/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/boards/{BOARD_ID}/tasks?status=inbox&unassigned=true&limit=20" \
+  -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, claim one inbox task:
+- Move it to in_progress AND add a markdown comment describing the update.
+
+6) Work the task:
+- Post progress comments as you go.
+- Completion is a two‑step sequence:
+6a) Post the full response as a markdown comment using:
+      POST $BASE_URL/api/v1/boards/{BOARD_ID}/tasks/{TASK_ID}/comments
+    Example:
+```bash
+curl -s -X POST "$BASE_URL/api/v1/boards/$BOARD_ID/tasks/$TASK_ID/comments" \
+  -H "X-Agent-Token: $AUTH_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"message":"- Update: ...\n- Result: ..."}'
+```
+  6b) Move the task to review.
+
+6b) Move the task to "review":
+```bash
+curl -s -X PATCH "$BASE_URL/api/v1/boards/{BOARD_ID}/tasks/{TASK_ID}" \
+  -H "X-Agent-Token: $AUTH_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"status": "review"}'
+```
+
+## Definition of Done
+- A task is not complete until the draft/response is posted as a task comment.
+- Comments must be markdown.
+
+## 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.
+
+## Status flow
+```
+inbox -> in_progress -> review -> done
+```
+
+Do not say HEARTBEAT_OK if there is inbox work or active in_progress work.