create_task
Create a task. It starts as open, ready to be worked on, unless created as a draft. Say why the work matters when you know. Give the project to place it in, and the tasks or projects it depends on, in the same call. A completed parent must be reopened first: new work is never put behind a done task container implicitly. When the work has several steps, consider grouping them: create one task for the feature or epic, then create each step with parent set to it. Grouping is optional. Set type to bug, issue or incident for a problem, so it stands out from planned work. The ID is assigned by the service: the project's prefix followed by a number.
- It
- Changes the plan, as one step that is stored whole or not at all.
- Who may call it
- Every user.
- Version
- Takes no version: it is carried out on the plan as it is at that moment. What it creates starts at version 1.
- Answers with
- The task in short. Its fields. Not in it:
description,why,links,timeline,created_at,created_by,updated_atandunchanged_since.gethas those. - MCP tool
create_task- HTTP
POST /api/create-task- Command
vigile create-task
Input
| Field | Takes | What it is | |
|---|---|---|---|
title | string 1 to 500 characters | required | |
description | string at most 4000 characters | required | What needs to be done and how to tell it is finished. Required. |
why | string 1 to 1000 characters | optional | Why this work matters. Give at least one reason; add more if there are several. Optional, but it helps whoever picks the task up decide and prioritise. |
type | "task" | "bug" | "issue" | "incident" | optional | What this is. task: planned work (the default). bug: something that should work and does not. issue: a problem or open question that needs attention. incident: something is failing right now and needs urgent action. Bugs, issues and incidents are shown apart from planned work. |
project | string | optional | The ID of the project that contains the task. |
parent | string | optional | The ID of a task that contains this one. Use it to group work: create one task for a feature or epic, then create its steps with parent set to it. Groups can hold sub-groups. A group shows how many of its tasks are finished. |
priority | number | optional | The higher, the more important. Not set means 0. |
value | number | optional | How valuable the task is; the higher, the more. Helps choose among tasks of equal priority. |
size | number | optional | How large the task is; the higher, the larger. Helps choose among tasks of equal priority. |
depends_on | array of string at most 30 | optional | IDs of tasks or projects that must be finished before this task can start. |
assigned_to | array of string at most 30 | optional | Usernames or IDs of the users who will work on it. |
draft | boolean | optional | true to create it as a draft: not ready to start, and never listed as next. |
A field that is not listed here is refused, as invalid_input. On the command line each field is an option, with hyphens for underscores: --title.
Example
The same call three ways, as agent1. It was made on the demo plan the pictures of this site show. Over HTTP and MCP, a call without a key acts as agent1 on a new instance.
Command line
vigile create-task \
--project WEB \
--parent WEB-001 \
--title "Order history lists a customer's past orders" \
--description "Done when a signed-in customer sees their last ten orders with the state of each." \
--why "Customers ask support for this every day." \
--depends-on WEB-003 \
--priority 3 \
--as agent1HTTP
curl -s http://127.0.0.1:8700/api/create-task \
-H 'content-type: application/json' \
-d '{"project":"WEB","parent":"WEB-001","title":"Order history lists a customer'\''s past orders","description":"Done when a signed-in customer sees their last ten orders with the state of each.","why":"Customers ask support for this every day.","depends_on":["WEB-003"],"priority":3}'MCP tool call
{
"name": "create_task",
"arguments": {
"project": "WEB",
"parent": "WEB-001",
"title": "Order history lists a customer's past orders",
"description": "Done when a signed-in customer sees their last ten orders with the state of each.",
"why": "Customers ask support for this every day.",
"depends_on": ["WEB-003"],
"priority": 3
}
}The answer
{
"kind": "task",
"id": "WEB-018",
"title": "Order history lists a customer's past orders",
"type": "task",
"status": "open",
"priority": 3,
"value": null,
"size": null,
"version": 1,
"contained_in": ["WEB", "WEB-001"],
"depends_on": ["WEB-003"],
"assigned_to": [],
"is_assigned": false,
"is_next": false,
"is_waiting": true,
"waiting_for": ["WEB-003"],
"has_problems": false
}
This is what a service answered when this page was built. Over HTTP it is the body of the response, over MCP the text of the tool result, and the command line prints it in words unless given --json.
A call that is refused
vigile create-task \
--project WEB \
--parent WEB-001 \
--title "Thank-you page for launch day" \
--description "Done when it is live." \
--depends-on WEB-013 \
--as agent1
{
"error": {
"code": "rule_violation",
"message": "The task would be inside Task WEB-001 and also depend on Task WEB-013, which cannot finish before Task WEB-001 does. Neither could ever finish.",
"rule": "loop",
"blocking": [
{
"kind": "task",
"id": "WEB-001",
"title": "Checkout: a customer can pay for a basket",
"status": "in_progress"
},
{
"kind": "task",
"id": "WEB-013",
"title": "Launch: the domain points to the new site",
"status": "open"
}
],
"actions": ["Leave out that dependency, or place the task somewhere else."]
}
}
What it answers
The new task in short: its id, its status, its version (1), its links, and what is worked out from them. In the example the task waits for WEB-003, so is_waiting is true and is_next is false.
Rules
- A title and a description are required. The description says what is to be done and how to tell it is finished.
- The task starts as
open, or asdraftwhendraftis true. projectputs it into a project andparentinto a group. Both can be given.- The task gets its ID now, and keeps it when it is moved. The prefix of the project it is created in, when that project has one; otherwise the prefix of its parent's ID, when that has one; otherwise none. Then a number: see how a task gets its ID.
- A task becomes a group the moment another task is created with
parentset to it. Nothing else has to be done. depends_onandassigned_tomake the links in the same step. Each takes at most 30 entries; a user can be named by its username.- What it is put into, depends on or is assigned to has to exist and not be deleted.
- A task cannot be created inside something it would also have to wait for: that is a loop, as in the refused call above, where the launch waits for the checkout the task would be part of.
Errors
invalid_input: a missing or empty title or description, text that is too long, a field the operation does not know.not_found: the project, the parent, a dependency or a user does not exist.rule_violation:loop, ordeletedfor something that is deleted.
See also
update_task changes its fields, set_task_status its status, and add_link what it depends on, where it is and who has it.