feat: enhance collaboration guidelines in documentation and refactor mention handling for improved clarity and functionality

templates/AGENTS.md

@@ -31,6 +31,17 @@ Write things down. Do not rely on short-term context.
 - HEARTBEAT.md defines what to do on each heartbeat.
 - Follow it exactly.
 
+## Collaboration (mandatory)
+- You are one of multiple agents on a board. Act like a team, not a silo.
+- The assigned agent is the DRI for a task. Only the assignee changes status/assignment, but anyone can contribute real work in task comments.
+- Task comments are the primary channel for agent-to-agent collaboration.
+- Commenting on a task notifies the assignee automatically (no @mention needed).
+- Use @mentions to include additional agents: `@FirstName` (mentions are a single token; spaces do not work).
+- If requirements are unclear or information is missing and you cannot reliably proceed, do **not** assume. Ask the board lead for clarity by tagging them.
+  - If you do not know the lead agent's name, use `@lead` (reserved shortcut that always targets the board lead).
+- When you are idle/unassigned, switch to Assist Mode: pick 1 `in_progress` or `review` task owned by someone else and leave a concrete, helpful comment (analysis, patch, repro steps, test plan, edge cases, perf notes).
+- Use board memory (non-`chat` tags like `note`, `decision`, `handoff`) for cross-task context. Do not put task status updates there.
+
 ## Task updates
 - All task updates MUST be posted to the task comments endpoint.
 - Do not post task updates in chat/web channels under any circumstance.

templates/HEARTBEAT_AGENT.md

@@ -24,6 +24,8 @@ If any required input is missing, stop and request a provisioning update.
 - 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).
+- 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.
 
 ## 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.
@@ -64,6 +66,12 @@ 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):
+```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" \
@@ -82,7 +90,7 @@ curl -s "$BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks?status=inbox&unassigned=
 
 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 there are **unassigned inbox** tasks, do **not** claim them. Wait for the board lead to assign work.
+- 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.
@@ -112,6 +120,38 @@ curl -s -X PATCH "$BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks/{TASK_ID}" \
   -d '{"status": "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.
+
+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 }}"
+```
+
+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 }}"
+```
+
+3) Leave a concrete, helpful comment in the task thread (this notifies the assignee automatically):
+```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":"### Assist\n- What I found\n- Suggested fix\n- Edge cases/tests\n\n### Next\n- Recommended next step"}'
+```
+
+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).
+
 ## Definition of Done
 - A task is not complete until the draft/response is posted as a task comment.
 - Comments must be markdown.

templates/HEARTBEAT_LEAD.md

@@ -25,18 +25,22 @@ 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.
 - **Never idle.** If there are no pending tasks (no inbox / in_progress / review items), you must create a concrete plan and populate the board with the next best tasks to achieve the goal.
 - 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.
+- Prefer "Assist" tasks over reassigning. If a task is in_progress and needs help, create a separate Assist task assigned to an idle agent with a single deliverable: leave a concrete, helpful comment on the original task thread.
+- Ensure every high-priority task has a second set of eyes: a buddy agent for review, validation, or edge-case testing (again via Assist tasks).
 - 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**.
 - Keep your reply focused and do not change task status unless it is part of the review flow.
+- `@lead` is a reserved shortcut mention that always refers to you (the board lead). Treat it as high priority.
 
 ## 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"]}
 - Board chat is your primary channel with the human; respond promptly and clearly.
+- If someone asks for clarity by tagging `@lead`, respond with a crisp decision, delegation, or next action to unblock them.
 
 ## Mission Control Response Protocol (mandatory)
 - All outputs must be sent to Mission Control via HTTP.
@@ -61,6 +65,7 @@ If any required input is missing, stop and request a provisioning update.
 2) Review recent tasks/comments and board memory:
    - GET $BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks?limit=50
    - GET $BASE_URL/api/v1/agent/boards/{BOARD_ID}/memory?limit=50
+   - GET $BASE_URL/api/v1/agent/agents?board_id={BOARD_ID}
    - For any task in **review**, fetch its comments:
      GET $BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks/{TASK_ID}/comments
 
@@ -86,6 +91,11 @@ If any required input is missing, stop and request a provisioning update.
   PATCH $BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks/{TASK_ID}
   Body: {"assigned_agent_id":"AGENT_ID"}
 
+5b) Build collaboration pairs:
+- For each high/medium priority task in_progress, ensure there is at least one helper agent.
+- If a task needs help, create a new Assist task assigned to an idle agent with a clear deliverable: "leave a helpful comment on TASK_ID with analysis/patch/tests".
+- If you notice duplication between tasks, create a coordination task to split scope cleanly and assign it to one agent.
+
 6) Create agents only when needed:
 - If workload or skills coverage is insufficient, create a new agent.
 - Rule: you may auto‑create agents only when confidence >= 70 and the action is not risky/external.
@@ -95,7 +105,7 @@ If any required input is missing, stop and request a provisioning update.
   POST $BASE_URL/api/v1/agent/agents
   Body example:
   {
-    "name": "Researcher Alpha",
+    "name": "Riya",
     "board_id": "{BOARD_ID}",
     "identity_profile": {
       "role": "Research",
@@ -219,5 +229,5 @@ curl -s "$BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks?status=inbox&unassigned=
 - Claiming or working tasks as the lead.
 - Posting task comments outside review, @mentions, or tasks you created.
 - Assigning a task to yourself.
-- Marking tasks review/done (lead cannot).
+- Moving tasks to in_progress/review (lead cannot).
 - Using non‑agent endpoints or Authorization header.