Vigile
SearchContents

DocumentationOperations

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.

The operation's own description: what an agent reads to decide whether and how to call it.
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_at and unchanged_since. get has those.
MCP tool
create_task
HTTP
POST /api/create-task
Command
vigile create-task

Input

FieldTakesWhat it is
titlestring
1 to 500 characters
required
descriptionstring
at most 4000 characters
requiredWhat needs to be done and how to tell it is finished. Required.
whystring
1 to 1000 characters
optionalWhy 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"optionalWhat 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.
projectstringoptionalThe ID of the project that contains the task.
parentstringoptionalThe 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.
prioritynumberoptionalThe higher, the more important. Not set means 0.
valuenumberoptionalHow valuable the task is; the higher, the more. Helps choose among tasks of equal priority.
sizenumberoptionalHow large the task is; the higher, the larger. Helps choose among tasks of equal priority.
depends_onarray of string
at most 30
optionalIDs of tasks or projects that must be finished before this task can start.
assigned_toarray of string
at most 30
optionalUsernames or IDs of the users who will work on it.
draftbooleanoptionaltrue 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 agent1

HTTP

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 as draft when draft is true.
  • project puts it into a project and parent into 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 parent set to it. Nothing else has to be done.
  • depends_on and assigned_to make 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, or deleted for 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.