Завдання — rtok docs

rtok веде один пронумерований план на проєкт. Кожен checkout, worktree й агент проєкту бере номери завдань з одного лічильника, тому два агенти не обирають той самий id. Тут описано команди завдань і MCP-інструменти; ключі конфігурації — у config.md, а id агентів і worktree, з якими працюють агенти, — у agents-and-worktrees.md.

Id

Id верхнього рівня — префікс з ASCII-літер і число, наприклад A12. Підзавдання додає одне число через крапку: A12.3.
Глибина — два рівні. У завдання можуть бути підзавдання; у підзавдання своїх підзавдань бути не може.
Префікс задається в [tasks] prefix, від 1 до 8 літер. Якщо він порожній, rtok бере першу літеру назви проєкту у верхньому регістрі (rtok дає R).
Введення не чутливе до регістру. Виведення — у верхньому регістрі.
Id беруться з лічильника проєкту в сховищі rtok. Перед кожним новим id лічильник піднімається вище за найбільший id, який уже є в адаптера, тож завдання, що прийшло через pull, не отримає повторний номер. Лічильник враховує id з будь-яким префіксом, тому зміна префікса не скидає нумерацію. Номери підзавдань рахуються окремо для кожного батька.

Статуси

Статус	Значення
`open`	у плані, не розпочато
`in-progress`	у плані, в роботі
`done`	завершено; виходить з плану
`closed`	не будемо робити; виходить з плану

open і in-progress — активні. list показує лише активні завдання, якщо не вказано --all, який додає завершені.
Батька з активними підзавданнями завершити не можна. Перехід у done або closed відхиляється, а помилка перелічує підзавдання, якщо не вказано --force.
Парсер також приймає слова, якими часто користуються агенти: todo і pending замість open, completed замість done, wontdo, won't-do і not-planned замість closed. Підкреслення замість дефіса теж працює, тож in_progress приймається.

Адаптер disk

Адаптер disk використовується за замовчуванням. Кожне завдання — один Markdown-файл у каталозі tasks у корені checkout:

tasks/A12 - ship-the-thing.md
tasks/done/A7 - old-work.md

Ім'я файла — <id> - <slug>.md. Slug — рядкові латинські літери та цифри, з'єднані дефісами, не довший за 48 символів. Заголовок у імені не зберігається, він у front matter.
Front matter містить id, title, status, parent (лише для підзавдань), created_at і updated_at (Unix-секунди). Захоплення додає assignee, blocked_by і priority (0–4, поле опускається, коли воно дорівнює 2). Адаптер disk зберігає ще conflicts_with і parallel, порожні поля опускаються; GitHub і GitLab зберігають їх мітками rtok:conflicts:<id> і rtok:parallel поруч з rtok:needs:<id> і rtok:p:<n>, власні мітки користувача не зачіпаються. Файли, записані до цих ключів, і далі читаються. Опис — тіло файла під front matter.
Файли належать тому checkout, у якому запущено команду. Номери спільні через сховище, але worktree читає й записує файли завдань на своїй гілці, тому вони потрапляють в інші checkout через git.
Завершені та закриті завдання переносяться до tasks/done/, тож план — це лістинг каталогу.
Запис іде у тимчасовий файл, який потім перейменовується на місце.
Файли, що не відповідають шаблону <id> - <slug>.md, ігноруються, тож README поруч із завданнями не заважає.

Приклад файла завдання:

---
id: A12
title: Ship the thing
status: open
created_at: 1790000000
updated_at: 1790000000
---

Why the task exists and what done means.

Команди

Команда	Що робить
`rtok task init [--adapter disk\|github\|gitlab] [--prefix <letters>]`	записує `[tasks]` у `.rtok.toml` checkout і друкує наступний id; префікс за замовчуванням — перша літера назви проєкту
`rtok task create <title> [-d <text> \| --body-file <path\|->] [--parent <id>] [--json]`	додає завдання під наступний вільний id (`A12`, або `A12.3` із `--parent`); `--body-file -` читає опис із stdin
`rtok task list [--status <s,…>] [--all] [--parent <id>] [--json]`	активні завдання, підзавдання виводяться з відступом під батьком; `--status` приймає список через кому
`rtok task show <id> [--json]`	одне завдання з підзавданнями, посиланням і описом
`rtok task status <id> [<status>] [--force] [--json]`	читає статус або встановлює `open`, `in-progress`, `done` чи `closed`
`rtok task next [--json]`	перше готове завдання. Якщо блокерів немає, це й далі відкрите завдання з найменшим номером без активного підзавдання
`rtok task ready [--json]`	усі завдання, які можна взяти, спочатку з вищим пріоритетом (`0` раніше за `2`)
`rtok task claim [id] [--agent <id>] [--json]`	взяти `id` або перше готове завдання. Потрібен `--agent` або `RTOK_AGENT_ID`. У GitHub і GitLab запис виконавця — остання зміна перемагає, це не compare-and-set
`rtok task release <id> [--agent <id>] [--force] [--json]`	зняти виконавця і повернути статус `open`. Лише власник, якщо не вказано `--force`
`rtok task dep <id> <blocker> [--json]`	`id` чекає, доки `blocker` не стане `done` або `closed`. Цикл відхиляється, і нічого не записується
`rtok task priority <id> <0-4> [--json]`	задати пріоритет. `0` — найвищий, `2` — типове значення, воно не зберігається
`rtok task conflict <id> <other> [--remove] [--json]`	два завдання зачіпають одні й ті самі файли, тому їх не варто вести одночасно. Зв'язок симетричний: записуються обидва файли. `task ready` позначає завдання, чий партнер у роботі, і все одно його показує. У GitHub і GitLab зберігається мітками `rtok:conflicts:<id>`
`rtok task parallel <id> [--off] [--json]`	позначити завдання як безпечне для роботи поруч з будь-яким іншим. У GitHub і GitLab зберігається міткою `rtok:parallel`

| rtok task export github\|linear [--dry-run] [--json] | односторонньо віддзеркалити завдання з диска в GitHub Issues або Linear (див. Експорт) |

Без --json команди друкують текст. З --json друкують завдання як JSON.

Експорт

rtok task export <backend> копіює завдання з диска в трекер, щоб людям, які живуть у ньому, було видно план. Працює лише з адаптером disk: файли завдань лишаються джерелом істини, rtok ніколи не читає issue назад у завдання. Правки, зроблені в трекері, перезаписуються під час наступного запуску.

GitHub (github): одна issue на завдання в [tasks.export.github] repo (інакше [tasks.github] repo, інакше remote origin). Issue пишеться так само, як її пише адаптер github: заголовок <id>. <title>, мітки rtok і rtok:<id>, мітки виконавця й залежностей (rtok:owner:…, rtok:needs:…, rtok:p:…, rtok:in-progress). Підзавдання зв’язується як sub-issue батьківського. Токен: GH_TOKEN, GITHUB_TOKEN, інакше gh auth token.
Linear (linear): одна issue на завдання в команді, яку за коротким ключем (наприклад ENG) називає [tasks.export.linear] team; з порожнім ключем експорт не запускається. Токен: особистий API-ключ у LINEAR_API_KEY (резервного CLI немає). Issue несе той самий заголовок і ті самі мітки, що й у GitHub; бракуючу мітку rtok створює сам. Статус — це workflow state Linear, обраний за типом: open — перший стан unstarted команди (інакше backlog), in-progress — started, done — completed, closed — canceled; стан змінюється лише коли статус відрізняється, тому issue, яку людина поклала в іншу колонку unstarted чи started, лишається там. Підзавдання створюється як sub-issue батьківського в Linear. Особистий ключ Linear обмежений 2 500 запитами на годину; відхилений запит падає з причиною й URL.
Завдання без issue отримує її. Якщо заголовок, опис, статус, пріоритет, виконавець, блокери або маркери конфлікту й паралельності завдання відрізняються від issue, issue оновлюється. done закриває issue як completed, closed — як not_planned, а знову активне завдання перевідкриває issue. Issue без мітки rtok:<id> не чіпаються, issue, чиє завдання зникло, лишається як є.
Завершене завдання без issue не експортується (стара історія в трекер не потрапляє), хіба що під ним висить активне підзавдання.
Запуск ідемпотентний: повторний запуск на тому самому стані не надсилає жодного запису. --dry-run читає трекер, друкує заплановані створення, оновлення, закриття та перевідкриття й нічого не надсилає. --json друкує той самий план у JSON.
Записи йдуть не частіше одного на секунду. Збій зупиняє запуск, у помилці зазначені бекенд, завдання й URL запиту; записи до збою лишаються, наступний запуск продовжує з цього місця.

Дошка завдань

У rtok web є сторінка Tasks лише для читання (g b), в rtok tui — вкладка tasks. Обидві показують завдання проєкту, в якому запущено процес, через той самий адаптер і в тому самому вигляді, що й rtok task list --all --json. Нічого на сторінці не змінює завдання.

Дошка: по колонці на статус (open, in progress, done, closed). Картка показує id, заголовок, батька (in R2), виконавця та посилання на issue у завдання github або gitlab, а також маркери: пріоритет, якщо він не дорівнює типовому P2, needs <id> для блокерів, conflicts <id> і parallel. Картки в колонці впорядковано за пріоритетом, потім за id.
Список: таблиця, поруч з нею подробиці вибраного завдання. Рядки доступні через Tab; Enter або Space вибирає рядок. Вибір дошки чи списку запам'ятовується в браузері. Поле фільтра шукає за id, заголовком, батьком і виконавцем.
Немає секції [tasks] ні в користувацькому конфігу, ні в .rtok.toml проєкту: сторінка повідомляє про це й підказує rtok task init. Проєкт без завдань або недоступний адаптер (немає токена, немає мережі) — це повідомлення на сторінці, а не помилка дашборда.
Розмір і свіжість: done і closed обмежено 50 найновішими в кожній колонці, решту рахує примітка; rtok task list --all показує всі. Адаптер disk читається кожні 5 секунд, github і gitlab — кожні 2 хвилини, щоб сторінка не витрачала ліміт API. Посилання на issue ведуть лише на адреси http і https.

MCP-інструменти

rtok mcp віддає ті самі операції як інструменти. Кожен повертає той самий JSON, що й відповідний прапорець --json.

MCP-інструмент	Аргументи	Те саме, що
`task_create`	`title` (обов'язковий), `description`, `parent`	`task create`
`task_list`	`status` (список або рядок через кому), `all`, `parent`	`task list`
`task_get`	`id` (обов'язковий)	`task show`
`task_status`	`id` (обов'язковий), `status`, `force`	`task status`
`task_next`	немає	`task next`
`task_ready`	немає	`task ready`
`task_claim`	`id`, `agent`	`task claim`
`task_release`	`id` (обов'язковий), `agent`, `force`	`task release`
`task_dep`	`id` (обов'язковий), `blocker` (обов'язковий)	`task dep`
`task_priority`	`id` (обов'язковий), `level` (обов'язковий, 0–4)	`task priority`
`task_conflict`	`id` (обов'язковий), `other` (обов'язковий), `remove`	`task conflict`
`task_parallel`	`id` (обов'язковий), `on` (типово true)	`task parallel`

Конфігурація

Задайте [tasks] для кожного проєкту в .rtok.toml; rtok task init записує його туди. Ключі та значення за замовчуванням узято з crates/rtok-config/default.toml:

[tasks]                               # task adapters; usually set per project in .rtok.toml
# adapter = "disk"                    # disk | github | gitlab
# prefix  = ""                        # task id prefix (R → R12); empty: first letter of the project name

[tasks.disk]
# dir = "tasks"                       # one Markdown file per task, relative to the project root; done ones go to <dir>/done

[tasks.github]
# repo    = ""                        # owner/name; empty: the origin remote
# project = 0                         # Projects v2 number whose Status field tracks tasks; 0 = issues only

[tasks.gitlab]
# url     = "https://gitlab.com"      # base URL; set it for a self-hosted instance
# project = ""                        # group/name or numeric id; empty: the origin remote

Адаптери GitHub і GitLab ще не зібрано (T441.7 та T441.8). До того часу команда завдань з adapter = "github" або "gitlab" завершується помилкою, яка це повідомляє. Їхні розділи з'являться на цій сторінці, коли вони будуть готові.