Vigile
SearchContents

Documentation

The model

What a plan is made of, for looking things up. Every table on this page is made from the program: from what vigile describe prints, or from what a service did when this site was built.

For the ideas, read The plan as a graph and Statuses and the rules of moving.

Kinds of item

A plan holds projects, tasks and users, and links between them. In an ID or a reference the kind can be put in front: project:042, task:042, user:agent1.

Fields of a task

FieldIs
titleThe outcome in one line: "Checkout: a customer can pay for a basket" says what will exist; "Checkout" does not. Required.
descriptionWhat needs to be done and how to tell it is finished. Required, and never empty.
whyAt least one reason the work matters, for whoever picks it up. Optional.
typetask for planned work; bug, issue or incident for a problem, shown in its own colour.
priorityA number; the higher, the more important. Not set means 0.
value, sizeNumbers that help choose among tasks of equal priority. Optional.

Text reads back as it was written. Control characters are refused, a title is one line, and text made only of spaces counts as empty.

Statuses of a task

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

Moves

From \ todraftopenin_progresspausedin_reviewdonecancelled
draft·yesnonononoyes
openyes·yesnonoyesyes
in_progressnoyes·yesyesyesyes
pausednoyesyes·nonoyes
in_reviewnonoyesno·yesyes
donenoyesnonono·no
cancelledyesyesnononono·
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.

Besides the table, a move to in_progress or done is refused while something the task depends on is unfinished, a move to done while the task contains unfinished tasks, a move to in_progress by someone the task is not assigned to, and a move to cancelled while the task contains tasks in progress or in review. See the rules.

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.

Types of task

TypeIs
taskPlanned work. The default.
bugSomething that should work and does not.
issueA problem or an open question that needs attention.
incidentSomething that is failing right now and needs urgent action.
TypeReverse nameFromToWhat it does
containsis containedproject or tasktaskGroups tasks under a project or another task. A task can be contained more than once. A link that would create a loop is rejected.
depends onis depended on bytasktask or projectThe first task waits until the second item is finished: a task that is done or cancelled, or a project that is ready or cancelled. A link that would create a loop is rejected.
assigned tois assignedtaskuserSays who works on a task. A task can be assigned to several users.

Either name of a type works when adding or removing a link; with the reverse name the two ends are swapped. A link is stored once.

What is worked out

Never stored, and so never stale: worked out from statuses and links whenever an item is read.

In an answerIs
is_nextThe task is open, is not deleted, has an active path through its projects and groups, and has no unfinished dependency
is_waiting, waiting_forThe task is not deleted, is draft, open, in_progress, paused or in_review, and either depends on something unfinished or every path through its projects and groups is inactive; and what. A task that is done or cancelled, or deleted, is not waiting, whatever it depends on; one that is done with an unfinished dependency carries a problem instead
is_assigned, assigned_toWho has it, from its "assigned to" links
progressFor a group and a project: finished tasks out of all the tasks inside, at any depth
has_problems, problemsWhere the plan contradicts itself

Problems

ProblemWhat is wrong
unfinished_dependencyA task is in progress, in review or done, but something it depends on is not finished: the dependency was reopened, restored or added afterwards.
inside_inactive_containerAn unfinished task has no active path into the plan because every path passes through a project or group that is not active.
done_with_unfinished_contentsA group is done, but tasks already inside it are not finished: one was reopened or restored afterwards.
depends_on_broken_projectAn unfinished task depends on a project that is marked broken.
project_brokenThe project is marked broken.
ready_with_unfinished_tasksThe project is marked ready, but tasks in it are not finished.
contains_task_with_problemsThe project holds tasks that have problems of their own.

Users

TypeIsMay call
adminWhoever maintains the instance. Creates users, resets keys, deletes for good, reads the service's status.21 of 21 operations
personA human that work can be assigned to.19 of 21 operations
agentAn AI agent.19 of 21 operations
UserTypeFor
adminadminMaintenance. It always needs its API key, which config init writes into the config file.
userpersonA person that agents can assign work to. It has no key until one is issued.
agent1agentWho a connection without an API key acts as, unless the config says otherwise.

A username has lowercase letters, digits, "-" and "_", starts with a letter, and cannot read like an ID.

IDs

KindIDExample
ProjectIts prefix: 2 to 8 letters. Without a prefix, a numberWEB
TaskThe 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 numberWEB-012, 012
UserUSER- and a numberUSER-004
A task createdGets as its ID
In a project that has a prefixThe project's prefix and a number
In a project that has a prefix, under a parent whose ID has another prefixThe project's prefix and a number
Under a parent whose ID has a prefix, with no project givenThe prefix of the parent's ID and a number
In a project whose ID is a number, under a parent whose ID has a prefixThe prefix of the parent's ID and a number
In a project whose ID is a numberA number alone
Under a parent whose ID is a number aloneA number alone
In no project and under no parentA number alone

The ID is given once, when the task is created. Putting the task into another project or group afterwards, or taking it out of the one it was created in, does not change it.

  • IDs are given by the service. Numbers have at least three digits.
  • Task numbers come from one counter for the whole instance, so no two tasks share a number.
  • A number is given once, and so is a prefix, also after its project was deleted for good.
  • IDs are read without regard to capitals: web-12 finds WEB-012.

These words cannot be a project's prefix, because they start the IDs of other kinds of item: USER, TEAM, SVC, OBJ, COMMENT.

Limits

LimitIsOn
title500Characters in a title.
text4000Characters in a description.
why1000Characters in a reason.
username32Characters in a username.
page100Items in one page of a list that answers in pages. See Lists and pages.
blocking20Items named in one refusal as being in the way. blocking_total says how many there are in all when the list is cut.
links_per_create30Entries in depends_on, and in assigned_to, of one create_task.

A request body may have at most 1 MB. Text cannot contain control characters, other than line breaks and tabs in a description or a reason; a title is one line.