From f683eba02f8c66f83b6e1e4b01c5050e0a9e3d3d Mon Sep 17 00:00:00 2001 From: Abhimanyu Saharan Date: Sat, 7 Feb 2026 03:52:08 +0530 Subject: [PATCH] docs: enforce dependency blocking workflow in agent templates --- templates/HEARTBEAT_AGENT.md | 1 + templates/HEARTBEAT_LEAD.md | 16 +++++++++++++++- 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/templates/HEARTBEAT_AGENT.md b/templates/HEARTBEAT_AGENT.md index 564d1d78..7111e7dd 100644 --- a/templates/HEARTBEAT_AGENT.md +++ b/templates/HEARTBEAT_AGENT.md @@ -24,6 +24,7 @@ If any required input is missing, stop and request a provisioning update. - 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. +- Do not start work on blocked tasks (`is_blocked=true` or `blocked_by_task_ids` non-empty). Work on their dependencies (if assigned) or ask `@lead` to reprioritize/unblock. - 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. diff --git a/templates/HEARTBEAT_LEAD.md b/templates/HEARTBEAT_LEAD.md index d4d305c7..a972a848 100644 --- a/templates/HEARTBEAT_LEAD.md +++ b/templates/HEARTBEAT_LEAD.md @@ -178,6 +178,19 @@ Checklist: PATCH $BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks/$TASK_ID Body: {"assigned_agent_id":"AGENT_ID"} +5a) Dependencies / blocked work (mandatory): +- If a task depends on another task, set `depends_on_task_ids` immediately (either at creation time or via PATCH). +- A task with incomplete dependencies must remain **not in progress** and **unassigned** so agents don't waste time on it. + - Keep it `status=inbox` and `assigned_agent_id=null` (the API will force this for blocked tasks). +- Delegate the dependency tasks first. Only delegate the dependent task after it becomes unblocked. +- Each heartbeat, scan for tasks where `is_blocked=true` and: + - Ensure every dependency has an owner (or create a task to complete it). + - When dependencies move to `done`, re-check blocked tasks and delegate newly-unblocked work. + +Dependency update (lead‑allowed): +PATCH $BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks/$TASK_ID +Body: {"depends_on_task_ids":["DEP_TASK_ID_1","DEP_TASK_ID_2"]} + 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". @@ -210,8 +223,9 @@ Checklist: - Leads **can** create tasks directly when confidence >= 70 and the action is not risky/external. POST $BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks Body example: - {"title":"...","description":"...","priority":"high","status":"inbox","assigned_agent_id":null} + {"title":"...","description":"...","priority":"high","status":"inbox","assigned_agent_id":null,"depends_on_task_ids":["DEP_TASK_ID"]} - Task descriptions must be written in clear markdown (short sections, bullets/checklists when helpful). +- If the task depends on other tasks, always set `depends_on_task_ids`. If any dependency is incomplete, keep the task unassigned and do not delegate it until unblocked. - If confidence < 70 or the action is risky/external, request approval instead: POST $BASE_URL/api/v1/agent/boards/$BOARD_ID/approvals Body example: