> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dotbot.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Task management MCP tools reference

> Reference for all 10 dotbot task management MCP tools - creation, retrieval, metadata updates, state transitions, and review management - with parameters and usage notes.

dotbot exposes 10 MCP tools for managing the task queue. These tools are the primary interface between the AI agent and the dotbot runtime during autonomous execution. Tools are auto-discovered from `src/mcp/tools/` inside the dotbot install, and no registration is required. Tasks flow through a defined lifecycle: `todo → in-progress → done`. Side states `needs-input`, `needs-review`, `failed`, `skipped`, and `cancelled` handle paused work, human review gates, errors, unnecessary tasks, and permanent stops.

***

## Creation

### `task_create`

Creates a single new task in the `todo` queue. The runtime owns schema validation, ID generation, atomic write, and activity-log emission. **Required:** `name`.

<ParamField path="name" type="string" required>
  Brief, descriptive name for the task.
</ParamField>

<ParamField path="description" type="string">
  Detailed description of what the task does and why it is needed.
</ParamField>

<ParamField path="category" type="string">
  Task category. Validated at runtime against the active settings.
</ParamField>

<ParamField path="priority" type="integer">
  Priority from `1` (highest) to `100` (lowest).
</ParamField>

<ParamField path="effort" type="string">
  Effort estimate. One of `XS` (1 day), `S` (2-3 days), `M` (1 week), `L` (2 weeks), `XL` (3+ weeks).
</ParamField>

<ParamField path="type" type="string" default="prompt">
  Task type. One of `prompt`, `prompt_template`, `script`, `mcp`, `task_gen`. Non-prompt types are non-LLM and still run inside the workflow worktree.
</ParamField>

<ParamField path="status" type="string">
  Initial status. Defaults to `todo` in the runtime.
</ParamField>

<ParamField path="dependencies" type="array of strings">
  Task IDs that must reach a satisfying terminal status before this task starts.
</ParamField>

<ParamField path="acceptance_criteria" type="array of strings">
  Criteria that must be met for the task to be considered complete.
</ParamField>

<ParamField path="outputs" type="array of strings">
  Expected output artefacts produced by the task.
</ParamField>

<ParamField path="provenance" type="object">
  Optional provenance bag (workflow, run\_id, source). Standalone tasks omit this.
</ParamField>

<ParamField path="extensions" type="object">
  Free-form extension fields preserved verbatim by the runtime.
</ParamField>

<ParamField path="needs_review" type="boolean">
  When `true`, the agent must call `task_mark_needs_review` instead of setting status to `done` when finishing the task. The work then waits for human approval via `task_submit_review`.
</ParamField>

***

### `task_create_bulk`

Creates multiple tasks at once from a roadmap or specification. Accepts the same per-task fields as `task_create`, plus planning-specific extension fields. When called from inside a workflow task, new tasks inherit the current WorkflowRun provenance unless explicit provenance is supplied. **Required:** `tasks` (array of task objects, each requiring `name`).

<ParamField path="tasks" type="array of objects" required>
  Array of task objects. Each object supports all the same fields as `task_create`, plus the following planning-specific fields stored under `extensions.workflow`:

  * `steps` (array of strings) - Implementation or test steps.
  * `group_id` (string) - Source task group ID (e.g. `grp-1`) linking the task back to its planning group.
  * `applicable_decisions` (array of strings) - Decision IDs that constrain this task.
  * `human_hours` (number) - Estimated hours without AI assistance. Used in cost reporting.
  * `ai_hours` (number) - Estimated hours with AI assistance. Used in cost reporting.
</ParamField>

***

## Retrieval

### `task_get`

Reads a single task by its canonical ID. **Required:** `task_id`.

<ParamField path="task_id" type="string" required>
  Canonical task ID (`t_XXXXXXXX`).
</ParamField>

***

### `task_get_next`

Returns the next runnable task. The runtime selects the highest-priority task matching the requested status, optionally scoped to a WorkflowRun.

<ParamField path="status" type="string" default="todo">
  Status to draw candidates from. Defaults to `todo`.
</ParamField>

<ParamField path="run_id" type="string">
  Restrict the search to tasks under a specific WorkflowRun.
</ParamField>

***

### `task_get_context`

Returns the runtime context bundle for a task: the task record, parent WorkflowRun, single-session task standard, and same-task handoff resume context. Called at the start of execution to load everything the agent needs for a task in a single call. **Required:** `task_id`.

<ParamField path="task_id" type="string" required>
  Canonical task ID (`t_XXXXXXXX`).
</ParamField>

***

### `task_list`

Lists tasks with optional filtering by status, WorkflowRun, or workflow name.

<ParamField path="status" type="string">
  Filter by status. One of `todo`, `in-progress`, `needs-input`, `needs-review`, `done`, `failed`, `skipped`, `cancelled`.
</ParamField>

<ParamField path="run_id" type="string">
  Filter to tasks belonging to a specific WorkflowRun.
</ParamField>

<ParamField path="workflow" type="string">
  Filter to tasks materialised from a specific workflow name.
</ParamField>

***

## Metadata updates

### `task_update`

Updates a task's non-status metadata. Only the fields you supply are changed; all other fields retain their current values. Use `task_set_status` for all status changes - the runtime rejects `status`, `id`, `schema_version`, `created_at`, and `completed_at` here. **Required:** `task_id`.

<ParamField path="task_id" type="string" required>
  Canonical task ID (`t_XXXXXXXX`).
</ParamField>

<ParamField path="description" type="string">
  Updated description.
</ParamField>

<ParamField path="priority" type="integer or string">
  Updated priority.
</ParamField>

<ParamField path="dependencies" type="array of strings">
  Updated dependency list.
</ParamField>

<ParamField path="acceptance_criteria" type="array of strings">
  Updated acceptance criteria.
</ParamField>

<ParamField path="outputs" type="array of strings">
  Updated expected outputs.
</ParamField>

<ParamField path="extensions" type="object">
  Namespaced task metadata. The `runner` namespace holds structured pending questions for human input. Each question requires `question` and `options` (2-5 items with `key` and `label`), and optionally `context`, `multi_select`, and `recommendation`.
</ParamField>

***

## State transitions

All status changes go through `task_set_status`. The runtime enforces the closed transition table below and returns `422 invalid transition` if the requested move is not permitted.

### Task statuses

| Status         | Meaning                                                        |
| -------------- | -------------------------------------------------------------- |
| `todo`         | Queued and waiting to be picked up.                            |
| `in-progress`  | Currently being executed by the agent.                         |
| `needs-input`  | Paused pending a human answer or decision.                     |
| `needs-review` | Completed by the agent, waiting for human review and approval. |
| `done`         | Successfully completed and verified.                           |
| `failed`       | Execution failed; diagnostic state is archived.                |
| `skipped`      | Determined unnecessary before or during execution; terminal.   |
| `cancelled`    | Permanently stopped with no recovery possible; terminal.       |

### Allowed transitions

| From           | Allowed next statuses                                                   |
| -------------- | ----------------------------------------------------------------------- |
| `todo`         | `in-progress`, `skipped`, `cancelled`                                   |
| `in-progress`  | `done`, `needs-input`, `needs-review`, `failed`, `skipped`, `cancelled` |
| `needs-review` | `done`, `todo`, `cancelled`                                             |
| `needs-input`  | `todo`, `cancelled`                                                     |
| `done`         | `todo`                                                                  |
| `failed`       | `todo`                                                                  |
| `skipped`      | `todo`                                                                  |
| `cancelled`    | *(terminal - no exits)*                                                 |

### `task_set_status`

Transitions a task to a new status. The runtime performs all side effects for the target status: `done` runs verification hooks (gitleaks, framework integrity, commit info) and closes the provider session; `failed` archives diagnostic state and emits a notification; `needs-input` writes a task-scoped handoff for the next same-task session attempt. **Required:** `task_id`, `status`.

<ParamField path="task_id" type="string" required>
  Canonical task ID (`t_XXXXXXXX`).
</ParamField>

<ParamField path="status" type="string" required>
  New status. Must be one of the values in the table above. The runtime enforces the transition table and returns `422 invalid transition` when the move is not allowed.
</ParamField>

<ParamField path="reason" type="string">
  Human-readable reason, written to the activity log.
</ParamField>

<ParamField path="skip_reason" type="string">
  Machine-readable reason when status is `skipped` (e.g. `condition-not-met`, `not-applicable`).
</ParamField>

<ParamField path="skip_detail" type="string">
  Human-readable detail when status is `skipped`.
</ParamField>

***

## Review

### `task_mark_needs_review`

Parks a completed task pending human review. Call this instead of `task_set_status(needs-review)` when the task's `extensions.review.required` flag is true - it captures the pending commit SHA atomically alongside the status transition. **Required:** `task_id`.

<ParamField path="task_id" type="string" required>
  Canonical task ID (`t_XXXXXXXX`).
</ParamField>

<ParamField path="reason" type="string">
  One-sentence summary of what was done and why it warrants review. Shown to the reviewer.
</ParamField>

***

### `task_submit_review`

Submits a human review decision for a task in `needs-review` status. Approving merges the task worktree and transitions to `done` after verification gates. Rejecting discards the worktree, appends reviewer feedback to `extensions.review.feedback`, and returns the task to `todo` for rework. **Required:** `task_id`, `approved`.

<ParamField path="task_id" type="string" required>
  Canonical task ID (`t_XXXXXXXX`). Must be in `needs-review` status.
</ParamField>

<ParamField path="approved" type="boolean" required>
  `true` to approve and complete the task; `false` to reject and return it to `todo`.
</ParamField>

<ParamField path="comment" type="string">
  Reviewer comment. Required when rejecting, optional when approving.
</ParamField>

<ParamField path="what_was_wrong" type="string">
  Specific description of what the implementation got wrong. Used when rejecting to guide the next attempt.
</ParamField>