feat: improve comment formatting guidelines for agents and leads to enhance clarity

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).

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.
 
@@ -86,7 +87,7 @@ curl -s "$BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks?status=inbox&unassigned=
 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.
 

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.