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.
string
required
Brief, descriptive name for the task.
string
Detailed description of what the task does and why it is needed.
string
Task category. Validated at runtime against the active settings.
integer
Priority from
1 (highest) to 100 (lowest).string
Effort estimate. One of
XS (1 day), S (2-3 days), M (1 week), L (2 weeks), XL (3+ weeks).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.string
Initial status. Defaults to
todo in the runtime.array of strings
Task IDs that must reach a satisfying terminal status before this task starts.
array of strings
Criteria that must be met for the task to be considered complete.
array of strings
Expected output artefacts produced by the task.
object
Optional provenance bag (workflow, run_id, source). Standalone tasks omit this.
object
Free-form extension fields preserved verbatim by the runtime.
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.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).
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.
Retrieval
task_get
Reads a single task by its canonical ID. Required: task_id.
string
required
Canonical task ID (
t_XXXXXXXX).task_get_next
Returns the next runnable task. The runtime selects the highest-priority task matching the requested status, optionally scoped to a WorkflowRun.
string
default:"todo"
Status to draw candidates from. Defaults to
todo.string
Restrict the search to tasks under a specific WorkflowRun.
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.
string
required
Canonical task ID (
t_XXXXXXXX).task_list
Lists tasks with optional filtering by status, WorkflowRun, or workflow name.
string
Filter by status. One of
todo, in-progress, needs-input, needs-review, done, failed, skipped, cancelled.string
Filter to tasks belonging to a specific WorkflowRun.
string
Filter to tasks materialised from a specific workflow name.
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.
string
required
Canonical task ID (
t_XXXXXXXX).string
Updated description.
integer or string
Updated priority.
array of strings
Updated dependency list.
array of strings
Updated acceptance criteria.
array of strings
Updated expected outputs.
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.State transitions
All status changes go throughtask_set_status. The runtime enforces the closed transition table below and returns 422 invalid transition if the requested move is not permitted.
Task statuses
Allowed transitions
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.
string
required
Canonical task ID (
t_XXXXXXXX).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.string
Human-readable reason, written to the activity log.
string
Machine-readable reason when status is
skipped (e.g. condition-not-met, not-applicable).string
Human-readable detail when status is
skipped.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.
string
required
Canonical task ID (
t_XXXXXXXX).string
One-sentence summary of what was done and why it warrants review. Shown to the reviewer.
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.
string
required
Canonical task ID (
t_XXXXXXXX). Must be in needs-review status.boolean
required
true to approve and complete the task; false to reject and return it to todo.string
Reviewer comment. Required when rejecting, optional when approving.
string
Specific description of what the implementation got wrong. Used when rejecting to guide the next attempt.