Improve Task tool description

Improve Task prompt for plan execution.
Clarify task ordering, task granularity, concurrent starts, and clearing completed task lists.

Author: zikajk

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Clarify Task tool prompt for task ordering, task granularity, concurrent starts, and clearing finished task lists.
+
 ## 0.112.1
 
 - Fix MCP OAuth credentials cache not invalidating when the server URL changes.

resources/prompts/tools/task.md

@@ -1,6 +1,6 @@
 Task management for planning and tracking work.
 
-This tool is the authoritative task tracker. Any multi-step plan/todo list you intend to execute MUST be represented here (with `plan/start/complete`).
+This tool is the authoritative tracker for executable work in the current chat. Use it with `plan/start/complete` for multi-step work you intend to execute.
 
 When to Use:
 - Non-trivial work where progress tracking helps (multiple tasks, dependencies, or iterative debugging)
@@ -25,11 +25,15 @@ Task Schema:
 - `subject`: A brief, actionable title in imperative form (e.g. "Fix login bug")
 - `description`: Detailed description of what needs to be done, including context and STRICT acceptance criteria. Objective verification of these criteria is required for completion.
 
+Task Creation Guidance:
+- Order tasks by expected execution flow. Put prerequisite tasks before tasks that depend on them, and use `blocked_by` to record those dependencies explicitly.
+- Create tasks as independently executable units. If one step can be completed before the next begins, keep them as separate tasks. Combine planned steps only when they would be started and completed as one unit of work.
+
 Workflow & Strict Execution Rules:
 1. PLAN: Use 'plan' to create the task list with initial tasks. You MUST wait for the tool to return the generated task ids before doing anything else. Do NOT execute any work or call other tools in the same step as 'plan'.
-2. START & SYNC: Use 'start' immediately before working on a task. Start ONLY tasks you are actively working on, or will start working on right now. You are FORBIDDEN to execute any work on a task unless its status is explicitly `in_progress`.
+2. START & SYNC: Use 'start' immediately before beginning work on a task. Start ONLY tasks you are about to work on. Do not start tasks preemptively. You are FORBIDDEN to execute any work on a task unless its status is explicitly `in_progress`.
 3. DO THE WORK FIRST: After calling 'start', you MUST actually perform the work (write code, use tools, etc.). NEVER call 'complete' preemptively; only call 'complete' after the work has been done and objectively verified against the task's `description` acceptance criteria since the corresponding 'start'.
-4. SUBAGENTS & PARALLEL WORK: You may start multiple independent tasks in parallel (e.g., via delegating focused work to subagents). Batch 'start' (multiple ids) ONLY when the work is truly parallel. Only the main agent updates the task list.
+4. SUBAGENTS & PARALLEL WORK: For sequential work, keep only one task `in_progress`; later tasks must stay pending until you start them. Multiple tasks may be `in_progress` only for concurrent separate workstreams (e.g. separate subagents). Only the main agent updates the task list.
 5. COMPLETION TIMING: Once a task is verified, close it as soon as possible. Do not delay completion just to align with other tasks.
 6. ADAPTABILITY: If completing tasks reveals follow-up work, use 'add' to append new tasks.
-7. CLEANUP: When a plan is fully completed and no further work is needed, always use the 'clear' operation to clean up the workspace.
+7. CLEANUP: When all tasks are done and no further work remains, use 'clear'.