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
| Field | Is |
|---|---|
title | The outcome in one line: "Checkout: a customer can pay for a basket" says what will exist; "Checkout" does not. Required. |
description | What needs to be done and how to tell it is finished. Required, and never empty. |
why | At least one reason the work matters, for whoever picks it up. Optional. |
type | task for planned work; bug, issue or incident for a problem, shown in its own colour. |
priority | A number; the higher, the more important. Not set means 0. |
value, size | Numbers 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
| Status | Means | Can move to |
|---|---|---|
draft | An idea nobody should start yet. It has a title and a description, and is never listed as next. | open, cancelled |
open | Ready to be worked on. A new task starts here unless it is created as a draft. | draft, in_progress, done, cancelled |
in_progress | Someone is working on it now. Set when the work really starts, never to reserve it. | open, paused, in_review, done, cancelled |
paused | Work was started and has stopped without finishing. | open, in_progress, cancelled |
in_review | The work is done and someone else has to check it. | in_progress, done, cancelled |
done | Finished, and shown to work. Finished: it no longer holds back what depends on it. | open |
cancelled | It will not be done. Finished: it no longer holds back what depends on it. | draft, open |
Moves
| From \ to | draft | open | in_progress | paused | in_review | done | cancelled |
|---|---|---|---|---|---|---|---|
draft | · | yes | no | no | no | no | yes |
open | yes | · | yes | no | no | yes | yes |
in_progress | no | yes | · | yes | yes | yes | yes |
paused | no | yes | yes | · | no | no | yes |
in_review | no | no | yes | no | · | yes | yes |
done | no | yes | no | no | no | · | no |
cancelled | yes | yes | no | no | no | no | · |
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
| Status | Means |
|---|---|
open | Work on it goes on. A new project starts here. |
in_preview | Its result can be looked at, and is not final. |
ready | Its result is there. Finished: tasks that depend on the project stop waiting. |
broken | Something is wrong with it as a whole. Tasks that depend on it are flagged. |
cancelled | It 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
| Type | Is |
|---|---|
task | Planned work. The default. |
bug | Something that should work and does not. |
issue | A problem or an open question that needs attention. |
incident | Something that is failing right now and needs urgent action. |
Link types
| Type | Reverse name | From | To | What it does |
|---|---|---|---|---|
contains | is contained | project or task | task | Groups 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 on | is depended on by | task | task or project | The 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 to | is assigned | task | user | Says 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 answer | Is |
|---|---|
is_next | The task is open, is not deleted, has an active path through its projects and groups, and has no unfinished dependency |
is_waiting, waiting_for | The 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_to | Who has it, from its "assigned to" links |
progress | For a group and a project: finished tasks out of all the tasks inside, at any depth |
has_problems, problems | Where the plan contradicts itself |
Problems
| Problem | What is wrong |
|---|---|
unfinished_dependency | A 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_container | An 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_contents | A group is done, but tasks already inside it are not finished: one was reopened or restored afterwards. |
depends_on_broken_project | An unfinished task depends on a project that is marked broken. |
project_broken | The project is marked broken. |
ready_with_unfinished_tasks | The project is marked ready, but tasks in it are not finished. |
contains_task_with_problems | The project holds tasks that have problems of their own. |
Users
| Type | Is | May call |
|---|---|---|
admin | Whoever maintains the instance. Creates users, resets keys, deletes for good, reads the service's status. | 21 of 21 operations |
person | A human that work can be assigned to. | 19 of 21 operations |
agent | An AI agent. | 19 of 21 operations |
| User | Type | For |
|---|---|---|
admin | admin | Maintenance. It always needs its API key, which config init writes into the config file. |
user | person | A person that agents can assign work to. It has no key until one is issued. |
agent1 | agent | Who 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
| Kind | ID | Example |
|---|---|---|
| Project | Its prefix: 2 to 8 letters. Without a prefix, a number | WEB |
| Task | 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 | WEB-012, 012 |
| User | USER- and a number | USER-004 |
| A task created | Gets as its ID |
|---|---|
| In a project that has a prefix | The project's prefix and a number |
| In a project that has a prefix, under a parent whose ID has another prefix | The project's prefix and a number |
| Under a parent whose ID has a prefix, with no project given | The prefix of the parent's ID and a number |
| In a project whose ID is a number, under a parent whose ID has a prefix | The prefix of the parent's ID and a number |
| In a project whose ID is a number | A number alone |
| Under a parent whose ID is a number alone | A number alone |
| In no project and under no parent | A 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-12findsWEB-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
| Limit | Is | On |
|---|---|---|
title | 500 | Characters in a title. |
text | 4000 | Characters in a description. |
why | 1000 | Characters in a reason. |
username | 32 | Characters in a username. |
page | 100 | Items in one page of a list that answers in pages. See Lists and pages. |
blocking | 20 | Items 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_create | 30 | Entries 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.