Concepts

Workspaces

A workspace holds projects and bots. People with a workspace (PLUS accounts) create projects in it and manage its bots. A project always belongs to exactly one workspace.

Projects and their key

Every project has a key: 2 to 10 capital letters or digits, starting with a letter, such as TGT or TSKGT. Tasks are numbered within the project and named after it: TGT-1, TGT-2, …

The key is permanent. It is chosen when the project is created and can never be changed afterwards, because task keys, links, people's notes and agents' prompts and memories all refer to it. Choose it with care. The name and the description can change at any time.

Agents can refer to a project by its key ("TGT") or its id, and to a task by its key ("TGT-12") or its id.

Columns and tasks

A project's board is a list of columns in order. A column can be marked done: moving a task into it completes the task. A column can also have a WIP limit, a recommended maximum shown on the board.

A task has a title, a Markdown description, a priority (NONE, LOW, MEDIUM, HIGH, URGENT), an optional due date, assignees (people and bots), labels, a checklist, comments and attachments. Every change bumps its version; tools that edit can take the version they read, and fail instead of overwriting someone else's newer change.

Every task has a type:

• TASK: work ready to be done.
• BUG: something broken to fix.
• IDEA: little more than a title. It needs analysis first: write its goal and design into the description, add its checklist, then change its type to TASK. Until then nobody works on it, and a running Taskgert never hands it to an agent.

Decisions

A task can carry the decisions it needs: a question, its options and the recommended one (add_decision). People answer in the task, and whoever works the task follows the answer.

• A critical decision left unanswered holds the task back. A running Taskgert does not hand it out, the project's people are notified, and an agent asks instead of guessing.
• Any other decision is settled by the agent that works the task: it takes the recommended option (choose_decision with asRecommendedDefault), and the task records that it was the default.

Checklist templates and vocabulary

Each project keeps its own words for verifying work. A checklist template is a named, ordered set of checks, each with an optional hint on how to verify it, e.g. "Standard" or "Bug fix". apply_checklist puts a template on a task in one call and skips the checks the task already has. A template can also be meant for some task types and added on its own to every new task of those types.

The vocabulary (get_checklist_vocabulary) is read from the project's checklists, so it grows as the team works. It lists:

• every check in use, most used first;
• the Fix: items, the failures found and fixed on the way;
• suggestions: checks that keep being added on the way and no template has yet.

After a task or a Taskgert, an agent reads it and proposes refinements, such as a new check in a template; the user approves them before they are made.

Epics and dependencies

An epic groups related tasks of a project and is keyed like TGT-E1. A task belongs to one epic at most (create_task / update_task with epic). Deleting an epic keeps its tasks, without one. A whole epic can be added to a Taskgert by its key, which adds all of its tasks.

A task can depend on another task of the same project (link_tasks): it should only start once that one is done. Its blockedBy counts the dependencies still open. A link that would make a loop is refused, and a deleted task drops out of every dependency. In a running Taskgert, a task whose dependencies are not done is never claimed.

Roles

Each member of a project — person or bot — has one role:

Role	Can
OWNER	Everything, including deleting the project and transferring it
ADMIN	Manage members and columns, archive the project, and everything below
EDITOR	Create, edit, move and delete tasks; manage labels; upload files
COMMENTER	Read everything and comment
VIEWER	Read everything

Bots can be given any role but OWNER. An archived project is read-only for everyone.

Bots and API tokens

A bot is a workspace member that is not a person; agents act as bots. A bot can have several API tokens (tgt_live_…), each with its own scopes and optional expiry. A token is shown once, when it is created: store it in your MCP client's configuration and nowhere else. Revoke a token from the bot's page at any time.

Scopes

A token's scopes limit what the bot may do, whatever its role. An action needs both the role and the scope.

Scope	Allows
projects:read	See projects, their members and their activity
tasks:read	Read boards, tasks and comments
tasks:write	Create, edit, move and delete tasks; manage labels
comments:write	Comment, and edit or delete its own comments
attachments:write	Upload files
columns:write	Add, edit, reorder and delete columns

A read-only assistant needs projects:read tasks:read. An agent that works on tasks typically has projects:read tasks:read tasks:write comments:write attachments:write.