From 0f251e28f8f2f826d95f9b11a0d71cd54a03997b Mon Sep 17 00:00:00 2001
From: Abhimanyu Saharan <asaharan@onemindservices.com>
Date: Thu, 5 Feb 2026 23:45:37 +0530
Subject: [PATCH] feat: improve comment formatting guidelines for agents and
 leads to enhance clarity

---
 templates/AGENTS.md          | 7 +------
 templates/HEARTBEAT_AGENT.md | 5 +++--
 templates/HEARTBEAT_LEAD.md  | 1 +
 3 files changed, 5 insertions(+), 8 deletions(-)

diff --git a/templates/AGENTS.md b/templates/AGENTS.md
index a0ffc198..2de21fd4 100644
--- a/templates/AGENTS.md
+++ b/templates/AGENTS.md
@@ -35,10 +35,5 @@ Write things down. Do not rely on short-term context.
 - All task updates MUST be posted to the task comments endpoint.
 - Do not post task updates in chat/web channels under any circumstance.
 - You may include comments directly in task PATCH requests using the `comment` field.
-- Required comment fields (markdown):
-  - `status`: inbox | in_progress | review | done
-  - `summary`: one line
-  - `details`: 1–3 bullets
-  - `next`: next step or handoff request
-- Comments must be markdown content (no plain‑text status updates).
+- Comments should be clear, well‑formatted markdown. Use headings, bullets, checklists, or tables when they improve clarity.
 - Every status change must include a comment within 30 seconds (see HEARTBEAT.md).
diff --git a/templates/HEARTBEAT_AGENT.md b/templates/HEARTBEAT_AGENT.md
index c7c98887..1cbcb67d 100644
--- a/templates/HEARTBEAT_AGENT.md
+++ b/templates/HEARTBEAT_AGENT.md
@@ -19,6 +19,7 @@ If any required input is missing, stop and request a provisioning update.
 ## Non‑negotiable rules
 - Task updates go only to task comments (never chat/web).
 - Comments must be markdown. Write naturally; be clear and concise.
+- When it improves clarity, use headings, bullets, checklists, tables, or short sections. You do not need to use them for every comment.
 - Every status change must have a comment within 30 seconds.
 - Do not claim a new task if you already have one in progress.
 
@@ -81,12 +82,12 @@ curl -s "$BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks?status=inbox&unassigned=
 - 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:
+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":"- Update: ...\n- Result: ..."}'
+  -d '{"message":"### Update\n- ...\n\n### Next\n- ..."}'
 ```
   6b) Move the task to review.
 
diff --git a/templates/HEARTBEAT_LEAD.md b/templates/HEARTBEAT_LEAD.md
index 8a268982..26f8a16c 100644
--- a/templates/HEARTBEAT_LEAD.md
+++ b/templates/HEARTBEAT_LEAD.md
@@ -24,6 +24,7 @@ If any required input is missing, stop and request a provisioning update.
 - All outputs must go to Mission Control via HTTP (never chat/web).
 - You are responsible for **proactively driving the board toward its goal** every heartbeat. This means you continuously identify what is missing, what is blocked, and what should happen next to move the objective forward. You do not wait for humans to ask; you create momentum by proposing and delegating the next best work.
 - You are responsible for **increasing collaboration among other agents**. Look for opportunities to break work into smaller pieces, pair complementary skills, and keep agents aligned on shared outcomes. When you see gaps, create or approve the tasks that connect individual efforts to the bigger picture.
+- When you leave review feedback, format it as clean markdown. Use headings/bullets/tables when helpful, but only when it improves clarity.
 
 ## Mission Control Response Protocol (mandatory)
 - All outputs must be sent to Mission Control via HTTP.