.bot/systems/mcp/tools/ — no registration is required. Tasks flow through a defined lifecycle: todo → analysing → analysed → in-progress → done. Side states needs-input, skipped, and split handle exceptions such as blocked tasks, errors, or proposals to decompose large work into smaller pieces.
Creation
task_create
Creates a single new task in the todo queue with full structured metadata. The agent calls this tool during the planning phase to queue implementation work. Required: name, description.
Brief, descriptive name for the task.
Detailed description of what the task does and why it is needed.
Task category. Validated at runtime against the active settings. Common values:
core, feature, enhancement, bugfix, infrastructure, ui-ux.Priority from
1 (highest) to 100 (lowest). Defaults to 50.Effort estimate. One of
XS (1 day), S (2-3 days), M (1 week), L (2 weeks), XL (3+ weeks).Task IDs that must be completed before this task starts.
Criteria that must be met for the task to be considered complete.
Implementation or test steps.
Standard file paths to read before implementing (e.g.
.bot/standards/backend/api.md).Agent persona file paths to load (e.g.
.bot/agents/backend-developer.md).Skill file paths to apply during implementation (e.g.
.bot/recipes/skills/write-unit-tests/SKILL.md).Decision IDs that constrain this task (e.g.
["dec-a1b2c3d4"]). The agent reads these records before implementing to respect previous architectural choices.When
true, the analysis phase interviews the user before finalising the task context.Estimated hours for a skilled developer without AI assistance. Used in cost reporting.
Estimated hours with AI-assisted development. Used in cost reporting.
Working directory for task execution, relative to the project root.
Task type. One of
prompt, prompt_template, script, mcp, task_gen. Non-prompt types skip analysis and worktree isolation.Path to a prompt template file relative to the workflow directory. Used with
prompt_template type.Path to a
.ps1 script relative to .bot/. Required for script and task_gen types.MCP tool name to call. Required for
mcp type.Arguments to pass to the MCP tool. Used with
mcp type.When
true, auto-promotes to analysed without LLM analysis. Defaults to true for non-prompt types.When
true, skips git worktree creation. Defaults to true for non-prompt types.Model alias override for this task (e.g.
Sonnet, Opus, Haiku). Overrides the process-level default for this task only.task_create_bulk
Creates multiple tasks at once from a roadmap or specification. Accepts the same per-task fields as task_create, plus a group_id field for linking tasks to their planning group. Required: tasks (array of task objects, each requiring name and description).
Array of task objects. Each object supports all the same fields as
task_create, plus group_id (string) — a source task group ID (e.g. grp-1) linking the task back to its planning group.Retrieval
task_get_next
Returns the highest-priority task ready for work. Prefers analysed tasks (pre-flight analysis complete) over todo tasks, ensuring the agent always picks up work that is ready to implement immediately.
Return full task details including description, steps, and acceptance criteria. Warning: consumes significant context window. The default returns summary fields only (
id, name, status, priority, effort, category).When
true, analysed tasks are returned before todo tasks. Set to false to get todo tasks only (for running the analysis phase explicitly).task_get_context
Retrieves the pre-built analysis context package for a task. Called by the implementation phase to load the output of the analysis phase without re-running exploration. Required: task_id.
The unique identifier of the task.
task_list
Lists tasks with optional filtering by status, category, priority range, and effort.
Filter by status. One of
todo, analysing, needs-input, analysed, in-progress, done, split, skipped, cancelled.Filter by category. One of
core, feature, enhancement, bugfix, infrastructure, ui-ux.Minimum priority value (1 = highest priority).
Maximum priority value (100 = lowest priority).
Filter by effort. One of
XS, S, M, L, XL.Maximum number of tasks to return.
Return full task details. Warning: consumes significant context window.
task_get_stats
Returns comprehensive statistics about the task queue: counts by status, effort distribution, and completion rates. Takes no parameters.
State transitions
The following tools move tasks through the lifecycle. All requiretask_id as their sole required parameter unless otherwise noted.
task_mark_todo
Resets a task to todo status. Use this to retry a task that failed or was incorrectly promoted.
task_mark_analysing
Moves a task from todo to analysing. Called at the start of the pre-flight analysis phase.
task_mark_analysed
Marks a task as analysed and stores the pre-flight analysis data package. This is the richest state-transition call — the analysis object captures everything the implementation phase needs. Required: task_id, analysis.
Pre-flight analysis data. Key sub-objects:
entities— Primary and related domain entities, plus a context summary.files— Files to modify, pattern files, and test files to update.dependencies— Task dependencies, implicit dependencies, and blocking issues.standards— Applicable standard files and relevant sections.product_context— Mission summary, entity definitions, and relevant tech stack info.implementation— Approach, key patterns, risks, and estimated token count.questions_resolved— Questions resolved during analysis (with answers and timestamps).
task_mark_in_progress
Moves a task from analysed to in-progress. Called at the start of the implementation phase.
task_mark_done
Marks a task as complete by moving it to done status.
task_mark_skipped
Marks a task as skipped and records a skip reason. Required: task_id, skip_reason.
One of
non-recoverable or max-retries.Q&A and split management
task_mark_needs_input
Pauses analysis with a structured question for a human stakeholder, or proposes a task split for human approval. Follows the AskUserQuestions pattern where option A is always the recommended choice. Required: task_id.
A structured question. Fields:
question (string), context (string), options (array of 3-5 objects with key, label, rationale), recommendation (default "A").A proposal to split the task instead of asking a question. Fields:
reason (string), sub_tasks (array of objects with name, description, effort).task_answer_question
Records a human answer to a pending question and moves the task back to analysing to continue analysis. Required: task_id, answer.
Option key (
A, B, C, D, or E) or a custom freeform answer.Optional file attachments. Each object has
name, size, and path.task_approve_split
Approves or rejects a split proposal. If approved, sub-tasks are created in todo and the original task is moved to split/. If rejected, the task returns to analysing. Required: task_id, approved.
true to approve the split, false to reject and return the task to analysing.