feat: enhance markdown formatting guidelines for comments and feedback in agent and lead documentation

frontend/src/app/boards/[boardId]/page.tsx

@@ -1695,9 +1695,48 @@ export default function BoardDetailPage() {
               <p className="text-xs font-semibold uppercase tracking-wider text-slate-500">
                 Description
               </p>
-              <p className="text-sm text-slate-700 whitespace-pre-wrap break-words">
-                {selectedTask?.description || "No description provided."}
-              </p>
+              {selectedTask?.description ? (
+                <div className="prose prose-sm max-w-none text-slate-700">
+                  <ReactMarkdown
+                    components={{
+                      p: ({ ...props }) => (
+                        <p className="mb-3 last:mb-0" {...props} />
+                      ),
+                      ul: ({ ...props }) => (
+                        <ul className="mb-3 list-disc pl-5" {...props} />
+                      ),
+                      ol: ({ ...props }) => (
+                        <ol className="mb-3 list-decimal pl-5" {...props} />
+                      ),
+                      li: ({ ...props }) => (
+                        <li className="mb-1" {...props} />
+                      ),
+                      strong: ({ ...props }) => (
+                        <strong className="font-semibold" {...props} />
+                      ),
+                      h1: ({ ...props }) => (
+                        <h1 className="mb-2 text-base font-semibold" {...props} />
+                      ),
+                      h2: ({ ...props }) => (
+                        <h2 className="mb-2 text-sm font-semibold" {...props} />
+                      ),
+                      h3: ({ ...props }) => (
+                        <h3 className="mb-2 text-sm font-semibold" {...props} />
+                      ),
+                      code: ({ ...props }) => (
+                        <code className="rounded bg-slate-100 px-1 py-0.5 text-xs" {...props} />
+                      ),
+                      pre: ({ ...props }) => (
+                        <pre className="overflow-auto rounded-lg bg-slate-900 p-3 text-xs text-slate-100" {...props} />
+                      ),
+                    }}
+                  >
+                    {selectedTask.description}
+                  </ReactMarkdown>
+                </div>
+              ) : (
+                <p className="text-sm text-slate-500">No description provided.</p>
+              )}
             </div>
             <div className="space-y-3">
               <div className="flex items-center justify-between">

templates/AGENTS.md

@@ -37,4 +37,5 @@ Write things down. Do not rely on short-term context.
 - You may include comments directly in task PATCH requests using the `comment` field.
 - Comments should be clear, well‑formatted markdown. Use headings, bullets, checklists, or tables when they improve clarity.
 - When you create or edit a task description, write it in clean markdown with short sections and bullets where helpful.
+- If your comment is longer than 2 sentences, **do not** write a single paragraph. Use a short heading + bullet list so each point is scannable.
 - Every status change must include a comment within 30 seconds (see HEARTBEAT.md).

templates/HEARTBEAT_AGENT.md

@@ -20,6 +20,7 @@ If any required input is missing, stop and request a provisioning update.
 - 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.
+- 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.
 - Do not claim a new task if you already have one in progress.
 - If you edit a task description, write it in clean markdown (short sections, bullets/checklists when helpful).
@@ -99,7 +100,7 @@ Example:
 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- ...\n\n### Next\n- ..."}'
+  -d '{"message":"### Update\n- Bullet point 1\n- Bullet point 2\n\n### Next\n- Next step"}'
 ```
   6b) Move the task to review.
 

templates/HEARTBEAT_LEAD.md

@@ -25,6 +25,7 @@ If any required input is missing, stop and request a provisioning update.
 - 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.
+- If your feedback is longer than 2 sentences, do **not** write a single paragraph. Use a short heading + bullets so each idea is on its own line.
 
 ## Task mentions
 - If you are @mentioned in a task comment, you may reply **regardless of task status**.