Vigile
SearchContents

How it works

Statuses and the rules of moving

A status says what is really happening to a task, and others read it to decide what to do. So the service checks every move, and refuses the ones that would make the plan untrue.

The statuses of a task

The statuses of a task and the moves between them A task can move from draft to open, cancelled; open to draft, in_progress, done, cancelled; in_progress to open, paused, in_review, done, cancelled; paused to open, in_progress, cancelled; in_review to in_progress, done, cancelled; done to open; cancelled to draft, open. draft open in_progress paused in_review done cancelled
Every move a task can make. An arrow with two heads goes both ways. The table below says the same.
StatusMeansCan move to
draftAn idea nobody should start yet. It has a title and a description, and is never listed as next.open, cancelled
openReady to be worked on. A new task starts here unless it is created as a draft.draft, in_progress, done, cancelled
in_progressSomeone is working on it now. Set when the work really starts, never to reserve it.open, paused, in_review, done, cancelled
pausedWork was started and has stopped without finishing.open, in_progress, cancelled
in_reviewThe work is done and someone else has to check it.in_progress, done, cancelled
doneFinished, and shown to work. Finished: it no longer holds back what depends on it.open
cancelledIt will not be done. Finished: it no longer holds back what depends on it.draft, open

What is checked when a task moves

A change of status goes through set_task_status, and is refused when:

  1. The task is already in that status. History gets no empty entries. For in_progress this is what keeps two agents from taking one task: the second is told that it is in progress, and whether it is assigned to others or to nobody.
  2. The move is not one of those above. A draft cannot go straight to done; a done task can only be reopened.
  3. It is being started or finished while something it depends on is unfinished. The refusal names the items in the way.
  4. It is being finished while it contains unfinished tasks, at any depth. A group is closed only over finished work.
  5. It is being started by someone it is not assigned to. Taking work over is a change of its assigned to link, made on purpose.
  6. It is being cancelled while it contains tasks in progress or in review, at any depth. Work that is under way is finished or moved out first.

What else happens with a move:

  • Starting a task that is assigned to nobody assigns it to whoever starts it.
  • A task that is done or cancelled is finished: it stops holding back what depends on it.
  • Reopening a done task keeps the earlier completion in its timeline and history.
  • Each status a task goes through is kept, with when and by whom.

What a refusal carries

A refusal is not only a "no". It carries the rule that refused the change and actions that would resolve it, and with some rules the items in the way:

{
  "error": {
    "code": "rule_violation",
    "message": "Task WEB-003 cannot be started: it is waiting for a dependency to finish.",
    "rule": "unfinished_dependencies",
    "blocking": [
      { "kind": "task", "id": "WEB-002", "title": "Cart page lists the items and the total", "status": "open" }
    ],
    "actions": [
      "Finish or cancel the items it depends on.",
      "Or call remove_link with type \"depends on\" if the dependency no longer applies.",
      "Or call list_next_tasks to pick work that can start now."
    ]
  }
}

It is the same over MCP, over HTTP and on the command line, where it is printed in words. An agent that follows one of the actions gets on; one that repeats the same call is refused again.

The statuses of a project

StatusMeans
openWork on it goes on. A new project starts here.
in_previewIts result can be looked at, and is not final.
readyIts result is there. Finished: tasks that depend on the project stop waiting.
brokenSomething is wrong with it as a whole. Tasks that depend on it are flagged.
cancelledIt will not be finished. Finished: tasks that depend on the project stop waiting.

Any move between them is allowed, other than to the status the project already has. Marking a project ready while it holds unfinished tasks is allowed too: it shows up as a problem on the project, not as a refusal.

Reference