feat(skills): task-format v2 — 5-digit numbers in task files/headers, done/ folder, #n references (tasks-global-numbering)
- task-format 0.1.1→0.2.0: header `[#n slug]`, mandatory `**Created:**`, numbering rules (server counter, 5-digit file name, no # in file) - setup-tasks 1.0.0→1.1.0: v2 folder canon (yyyy-mm-dd-#####-slug.md), done/ phase, numbering in migrate - using-tasks 1.6.0→1.7.0: create via tasks_create (server number), close → done/, Created: field - delegate-task 0.4.0→0.5.0: number in inputs, staged blockers by #n, review blocker by #n - inter-session-messaging 1.1.0→1.2.0: task refs by number (#452), lifecycle letters by number Also synced catalog with newer installed versions (using-tasks 1.4.1→1.6.0, delegate-task 0.2.6→0.4.0, inter-session-messaging 1.0.0→1.1.0) — edits had gone straight to ~/.agents/skills/. fnf-testing + workshop-promote-brainstorm updated directly in ~/.agents/skills/ (no catalog source).
This commit is contained in:
BIN
dist/delegate-task.skill
vendored
BIN
dist/delegate-task.skill
vendored
Binary file not shown.
BIN
dist/inter-session-messaging.skill
vendored
BIN
dist/inter-session-messaging.skill
vendored
Binary file not shown.
BIN
dist/setup-tasks.skill
vendored
BIN
dist/setup-tasks.skill
vendored
Binary file not shown.
BIN
dist/task-format.skill
vendored
BIN
dist/task-format.skill
vendored
Binary file not shown.
BIN
dist/using-tasks.skill
vendored
BIN
dist/using-tasks.skill
vendored
Binary file not shown.
@@ -1,14 +1,17 @@
|
||||
---
|
||||
name: delegate-task
|
||||
author: ours
|
||||
version: 0.2.6
|
||||
version: 0.5.0
|
||||
description: >
|
||||
Use when delegating a task to another agent or project via
|
||||
mcp__projects-meta__tasks_create. Triggers: «делегировать таску»,
|
||||
«delegate task», «создать задачу на агента», «поставить задачу агенту»,
|
||||
«tasks_create для». Does NOT apply to self-assigned tasks on your own
|
||||
board («создать задачу себе», «task for myself», «поставить себе задачу»
|
||||
→ using-tasks), to work you do yourself, or to workshop-internal tasks.
|
||||
mcp__projects-meta__tasks_create. Every cross-project delegation is a
|
||||
pair: tasks_create + covering letter to the recipient's inbox (event:
|
||||
created) — a task on the board does not ping a live session. Triggers:
|
||||
«делегировать таску», «delegate task», «создать задачу на агента»,
|
||||
«поставить задачу агенту», «tasks_create для». Does NOT apply to
|
||||
self-assigned tasks on your own board («создать задачу себе», «task for
|
||||
myself», «поставить себе задачу» → using-tasks), to work you do yourself,
|
||||
or to workshop-internal tasks.
|
||||
---
|
||||
|
||||
# delegate-task
|
||||
@@ -36,6 +39,8 @@ description: >
|
||||
- `notify` — slug проекта-комиссионера (кому писать inbox при close/park)
|
||||
- `allow_upgrade` — `true/false` (опционально; разрешить ли fallback на tier выше если нет matching backend)
|
||||
|
||||
Номер задаче присваивает сервер (`tasks_create` из счётчика `OpeItcLoc03/agenda/task-counter`) — постановщик номер не придумывает и не резервирует. Возвращённый `#n` из preview/confirm — машинный ключ задачи: им ссылаются блокеры, письма, decision-trail.
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Pre-flight gate (6 вопросов пользователю)
|
||||
@@ -59,6 +64,8 @@ description: >
|
||||
|
||||
```
|
||||
<Цель — одно-два предложения. Acceptance criteria если есть.>
|
||||
**Спека:** <path к design-решению или .brainstorm/…> — обязательно для задач
|
||||
из дизайна/решения: импл читает дизайн, не угадывает
|
||||
|
||||
## Обязательные скилы — вызвать до начала работы
|
||||
|
||||
@@ -85,6 +92,13 @@ description: >
|
||||
|
||||
Значение: `true` (следующий трек = «см. STATUS.md») либо строка-hint с названием следующего трека. Потребитель — `using-tasks` v1.2.0+ (Task completion step 6): после close печатает `🔚 SESSION BOUNDARY …` и останавливается, не клеймя следующую задачу. Дизайн: `.wiki/concepts/delegate-task-session-break.md`.
|
||||
|
||||
**Этапные цепочки (staged breakdown):** если решение бьётся на этапы
|
||||
(1 → 1b → 3), создавай каждый этап отдельной таской со `status: blocked` +
|
||||
`blocker: <номера-предшественников> (#n1, #n2 — номера, не слаги; номер =
|
||||
машинный ключ)`. Доска показывает порядок, поллер не возьмёт зависимую
|
||||
работу раньше времени. Таски в один репо создавай последовательно, не
|
||||
параллельно (иначе sha-lock конфликт — см. Failure modes).
|
||||
|
||||
**Почему `invoke` а не триггер-фраза:** AGENTS.md ненадёжен (уплывает при compression, слабые модели игнорируют). Тело задачи читается активно — императив `invoke` это прямая команда, не пассивный матчинг.
|
||||
|
||||
### 3. Dry-run preview
|
||||
@@ -95,9 +109,33 @@ description: >
|
||||
|
||||
После OK пользователя: `tasks_create(confirm=true)`.
|
||||
|
||||
### 5. Парная review-таска (только для impl-задач)
|
||||
### 5. Сопроводительное письмо — обязательно при кросс-проектной делегации
|
||||
|
||||
Если задача имплементационная — создать парную `<slug>-review` (status=blocked, blocker=`<slug>`). Пропустить для: pointers-тасок, ops-тасок, research-тасок, любых non-impl.
|
||||
После создания **каждая кросс-проектная делегация** дублируется письмом в
|
||||
инбокс получателя (канон — `inter-session-messaging`, адрес из адресной
|
||||
книги `~/projects/.wiki/concepts/projects-address-book.md`):
|
||||
|
||||
```
|
||||
<адрес-получателя>/.agents/inbox/<ts>Z-<своя-папка>.md
|
||||
---
|
||||
from: <своя-папка>
|
||||
event: created
|
||||
slug: <task-slug>
|
||||
---
|
||||
Тело: 1-2 строки — что за задача, почему, slug; «разбери и возьми».
|
||||
```
|
||||
|
||||
Причина: таска на борде **не пингует живую сессию** получателя. Поллер
|
||||
подхватит по `Weight`/`Notify`, но живая интерактивная сессия узнаёт только
|
||||
через inbox-монитор — т.е. через письмо. Правило «task + letter, не только
|
||||
task» — общий случай (шаг 7 — его частность для downstream-задач).
|
||||
|
||||
Пропуск: self-assigned задачи на своей доске; `target=agenda` (общая доска,
|
||||
конкретного получателя нет — steering-loop через `Notify`).
|
||||
|
||||
### 6. Парная review-таска (только для impl-задач)
|
||||
|
||||
Если задача имплементационная — создать парную `<slug>-review` (status=blocked, blocker=`#n` — номер impl-таски). Пропустить для: pointers-тасок, ops-тасок, research-тасок, любых non-impl.
|
||||
|
||||
**`weight` review-таски — наследовать от impl-таски, но не ниже `needs-claude`** (проставлять явно при `tasks_create`):
|
||||
|
||||
@@ -107,7 +145,7 @@ description: >
|
||||
|
||||
Без явного `weight` поллер не маршрутизирует review-таску (reconciler её пропускает) — поэтому проставлять всегда, даже когда impl и review совпадают по tier'у.
|
||||
|
||||
### 6. Downstream-задача для ЖИВОЙ сессии → требовать task + inbox-письмо
|
||||
### 7. Downstream-задача для ЖИВОЙ сессии → требовать task + inbox-письмо
|
||||
|
||||
Если тело задачи **поручает агенту самому создать downstream-задачу** для другого проекта, где работает **живая интерактивная сессия** (напр. прог сам ставит deploy-таску админу), — в ТЗ **явно потребуй И `tasks_create`, И inbox-письмо** тому проекту (`<target>/.agents/inbox/<ts>-<from>.md`).
|
||||
|
||||
@@ -121,7 +159,10 @@ description: >
|
||||
- **Пользователь отклоняет dry-run preview** → abort.
|
||||
- **notify не указан** → переспросить, не пропускать молча. Без notify steering-loop не замыкается.
|
||||
- **weight не указан** → переспросить. Без weight поллер не знает кому отдать задачу.
|
||||
- **tasks_create упал** → сообщить пользователю, не делать retry без явного запроса.
|
||||
- **tasks_create упал** → различить: **PushRejected** (sha-lock конфликт —
|
||||
репо уехало между preview и confirm; бывает при параллельном создании в один
|
||||
репо) → **retry**: повторить confirm — сервер перечитает актуальный base_sha.
|
||||
Другие ошибки → сообщить пользователю, не делать retry без явного запроса.
|
||||
|
||||
## Side effects
|
||||
|
||||
@@ -135,8 +176,15 @@ description: >
|
||||
- Не пропускать `notify` — без него boss не узнает о завершении.
|
||||
- Не пропускать `weight` — без него fleet routing слеп.
|
||||
- Не создавать review-таску для pointers/ops/research задач — только для impl.
|
||||
- Не создавать review-таску без `weight` — reconciler/поллер её пропустит. Наследовать от impl, флор `needs-claude` (см. Step 5).
|
||||
- Не создавать review-таску без `weight` — reconciler/поллер её пропустит. Наследовать от impl, флор `needs-claude` (см. Step 6).
|
||||
- Не назначать `weight: cheap-ok` для задач где дисциплина критична (review, security, schema migration) — слабые модели могут игнорировать invoke-инструкции.
|
||||
- Не назначать `weight: needs-claude` или `cheap-ok` задачам, меняющим критическую инфраструктуру (поллер, MCP серверы, deploy, CI/CD) — только `needs-human`.
|
||||
- Не ставить `session_break` рутинно на каждую задачу — это маркер реальной границы (domain-switch / milestone / heavy infra), не дефолт; иначе `using-tasks` рвёт сессию после каждого close.
|
||||
- **Не поручать агенту создать downstream-таску для живой сессии без парного inbox-письма** (см. Step 6). `tasks_create` в чужой борд живую сессию не пингует — ТЗ обязано требовать И таску, И письмо, иначе downstream-таска висит незамеченной.
|
||||
- **Не создавать задачи из дизайна/решения без `**Спека:**`-ссылки** —
|
||||
импл-агент угадывает пороги/скоуп вместо чтения дизайна.
|
||||
- **Не создавать несколько тасок в один репо параллельно** — sha-lock
|
||||
конфликты (PushRejected); сериализуй confirm'ы.
|
||||
- **Не делегировать кросс-проектную задачу без сопроводительного письма** в
|
||||
инбокс получателя (шаг 5). `tasks_create` в чужой борд живую сессию не
|
||||
пингует — task без letter остаётся незамеченной до поллера/руки.
|
||||
- **Не поручать агенту создать downstream-таску для живой сессии без парного inbox-письма** (см. Step 7). `tasks_create` в чужой борд живую сессию не пингует — ТЗ обязано требовать И таску, И письмо, иначе downstream-таска висит незамеченной.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: inter-session-messaging
|
||||
author: ours
|
||||
version: 1.0.0
|
||||
version: 1.2.0
|
||||
description: >
|
||||
Как писать и принимать межсессионные письма (`.agents/inbox/`). Один источник
|
||||
правды по канону отправки: адрес = имя папки проекта как есть (из адресной книги
|
||||
@@ -65,6 +65,16 @@ slug: <task-slug> # опционально — если пись
|
||||
Тело — свободный markdown.
|
||||
```
|
||||
|
||||
### Ссылки на задачи — по номеру (формат v2)
|
||||
|
||||
Ссылка на задачу в письме — **по глобальному номеру**: `#452` (формат v2,
|
||||
номера — машинный ключ, уникальны по всей федерации). Не слаг — слаг может
|
||||
повторяться между проектами. Первое упоминание задачи в письме — с номером и
|
||||
слагом для читаемости: `#452 (tasks-v2-search-by-id)`, далее — просто `#452`.
|
||||
Пример: «Разбери и возьми: `#452 tasks-v2-search-by-id` (готово к имплу)».
|
||||
Резолв номера в {project, slug} — через `mcp__projects-meta__tasks_search`
|
||||
(ищет и по id) или `tasks_get_by_id`.
|
||||
|
||||
Ответ на письмо: пиши в инбокс отправителя (`from` в frontmatter полученного),
|
||||
имя файла — со своим адресом отправителя, в `in_reply_to` — имя исходного письма.
|
||||
|
||||
@@ -122,6 +132,23 @@ slug: <task-slug> # опционально — если пись
|
||||
это разговор.** Значимый дизайн-выбор должен лечь на доску (или в вики),
|
||||
инбокс лишь указывает на него.
|
||||
|
||||
### Lifecycle-уведомления: task + letter
|
||||
|
||||
Кросс-проектное действие с задачей — всегда пара «доска + письмо». Доска —
|
||||
источник правды (существование/статус/скоуп), письмо — пинг и контекст. В
|
||||
теле письма задачу называй **по номеру** (`#452`), а не только слагом:
|
||||
|
||||
| Событие | Кто пишет | Куда | event |
|
||||
|---|---|---|---|
|
||||
| Создание | комиссионер | инбокс получателя | created |
|
||||
| Закрытие | исполнитель (живая сессия) или поллер (авто-ран) | инбокс комиссионера (`Notify`) | closed |
|
||||
| Блокировка/парк | то же | то же | blocked |
|
||||
|
||||
Тело письма — 1-2 строки + номера/слаги, не дублировать доску. Живая сессия
|
||||
узнаёт о задаче ТОЛЬКО через письмо (борд не пингует); комиссионер узнаёт о
|
||||
закрытии только через `Notify`/письмо. Правило постановки — `delegate-task`
|
||||
шаг 5; правило закрытия — `using-tasks` Task completion шаг 4.
|
||||
|
||||
### Против чего это
|
||||
|
||||
Две сессии пинг-понгуют, каждая соглашается с фреймом другой и добавляет скоуп,
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: setup-tasks
|
||||
author: ours
|
||||
version: 1.0.0
|
||||
version: 1.1.0
|
||||
description: Creates or migrates a project's `.tasks/` board to the canonical layout — `STATUS.md` (the board, with emoji status legend) plus per-task `<task-slug>.md` files for each active or paused task. Use when the user says "set up tasks", "init tasks", "настрой таски", "инициализируй таски", "create task tracking", "migrate tasks to canon", "tasks broken", or whenever `using-tasks` detects a missing or non-canonical `.tasks/`. Two modes — greenfield (no `.tasks/`) and migrate (existing flat STATUS.md without per-task files). Confirmation gate before writing. Cross-platform.
|
||||
---
|
||||
|
||||
@@ -93,12 +93,13 @@ _Updated: <today>_
|
||||
|
||||
<!--
|
||||
Add one block per task, sorted by priority. Use the emoji status legend below.
|
||||
Per-task deep context lives in .tasks/<task-slug>.md (created on demand by using-tasks).
|
||||
Per-task deep context lives in .tasks/yyyy-mm-dd-#####-<slug>.md (created on demand by using-tasks).
|
||||
|
||||
Block format:
|
||||
|
||||
## 🔴 [task-slug] — short description
|
||||
**Status:** active
|
||||
## ⚪ [#1234 task-slug] — short description
|
||||
**Status:** ready
|
||||
**Created:** yyyy-mm-dd
|
||||
**Where I stopped:** one sentence — the exact thought or action interrupted
|
||||
**Next action:** one concrete step to resume immediately
|
||||
**Blocker:** (only if blocked) what is preventing progress
|
||||
@@ -117,6 +118,8 @@ _Updated: <today>_
|
||||
|
||||
No per-task files at greenfield — they're created when actual tasks are added.
|
||||
|
||||
**Task numbering (format v2).** Every task block header carries a **global task number**: `## ⚪ [#1234 task-slug] — …`. Numbers are assigned by the server (`mcp__projects-meta__tasks_create`) from the counter in `OpeItcLoc03/agenda/task-counter` — **never invent or reuse a number by hand**. The per-task file is named `yyyy-mm-dd-#####-<slug>.md` (number 5 digits with leading zeros, no `#`): `2026-06-05-00019-fix-nl-vds-reality-pq-dest.md`. In the header the number is written without leading zeros (`[#19 slug]`). Closed tasks move to `.tasks/done/` (see Phase 4c).
|
||||
|
||||
### Phase 4b — Migrate
|
||||
|
||||
In migrate mode, do *not* try to auto-parse the old flat STATUS.md. The old layout is too varied — agent-driven heuristics will mangle real work. Instead, drive the migration interactively:
|
||||
@@ -125,7 +128,7 @@ In migrate mode, do *not* try to auto-parse the old flat STATUS.md. The old layo
|
||||
2. Ask: "Which of these are real, in-flight tasks you want to keep?" Get a list.
|
||||
3. For each task, ask the four canonical fields (slug, status, branch, where-stopped, next-action). The skill never invents these.
|
||||
4. Build a fresh canonical `.tasks/STATUS.md` from those answers.
|
||||
5. Create `.tasks/<task-slug>.md` for each active or paused task using the per-task template (Goal, Key files, Decisions log, Open questions, Completed steps, Notes).
|
||||
5. Create `.tasks/yyyy-mm-dd-#####-<slug>.md` for each active or paused task using the per-task template (Goal, Key files, Decisions log, Open questions, Completed steps, Notes). File name format v2: date + 5-digit number (from the task's header `[#n slug]`) + slug, no `#`: `2026-05-08-00057-fbs-picking-list-pdf.md`.
|
||||
6. Leave the `.bak-<ts>` file in place — historical record.
|
||||
|
||||
Per-task template:
|
||||
@@ -151,12 +154,21 @@ One paragraph. What this achieves and why it matters.
|
||||
## Notes
|
||||
```
|
||||
|
||||
### Phase 4c — done/ (format v2)
|
||||
|
||||
Closed 🟢 tasks move their **per-task file** to `.tasks/done/` — the board keeps only 🔴 / 🟡 / ⚪ / 🔵 blocks. (The 🟢 block itself is archived from STATUS.md to `.tasks/.archive/done-YYYY-MM.md` — see `using-tasks`.)
|
||||
|
||||
```bash
|
||||
mkdir -p .tasks/done && git mv .tasks/yyyy-mm-dd-#####-slug.md .tasks/done/
|
||||
```
|
||||
|
||||
### Phase 5 — Verify
|
||||
|
||||
After writes:
|
||||
|
||||
- `.tasks/STATUS.md` exists and has the emoji status legend (or template comment block in greenfield).
|
||||
- For migrate: each task referenced in STATUS.md has its `<task-slug>.md` file (active and paused only).
|
||||
- Every task block header is `## <emoji> [#n slug] — …` (number present) and carries `**Created:** yyyy-mm-dd`.
|
||||
- For migrate: each task referenced in STATUS.md has its `yyyy-mm-dd-#####-<slug>.md` file (active and paused only).
|
||||
- No required content was lost (the `.bak` file is the safety net).
|
||||
|
||||
If verification fails → restore from `.bak-<ts>` and report.
|
||||
@@ -190,6 +202,8 @@ If invoked from `project-bootstrap`, return control silently.
|
||||
|
||||
- **Auto-parsing existing flat STATUS.md.** Don't. The format varies, real work is at stake — drive migration through the user, one task at a time.
|
||||
- **Inventing task slugs / branches / "where you stopped" values.** Never. Ask the user. The whole point of `.tasks/` is *real* preserved context, not hallucinated context.
|
||||
- **Inventing or reusing a task number.** Never. Numbers come only from `tasks_create` (server counter). A hand-written number collides with the global counter.
|
||||
- **File without 5-digit number** (`2026-06-05-19-slug.md`). Always `yyyy-mm-dd-#####-slug.md` — leading zeros, no `#`.
|
||||
- **Skipping confirmation on greenfield.** Yes, even greenfield needs the gate — the user might be running this in the wrong directory.
|
||||
- **Creating per-task files at bootstrap.** Don't pre-generate empty `<slug>.md` files in greenfield mode — wait until the user adds actual tasks.
|
||||
- **Editing the `.bak` file.** It's the rollback artifact; leave it alone.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: task-format
|
||||
author: ours
|
||||
version: 0.1.1
|
||||
version: 0.2.0
|
||||
description: >
|
||||
Use when writing or editing a task block in a `.tasks/STATUS.md` board that an
|
||||
autonomous task-runner ("poller") will read — so the task is actually claimed,
|
||||
@@ -21,29 +21,39 @@ The autonomous poller parses `.tasks/STATUS.md` line-by-line with **strict regex
|
||||
## Canonical block (copy this)
|
||||
|
||||
```markdown
|
||||
## ⚪ [my-task-slug] — One-line description of the work.
|
||||
## ⚪ [#1234 my-task-slug] — One-line description of the work.
|
||||
|
||||
**Status:** ready
|
||||
**Created:** 2026-08-23
|
||||
**Where I stopped:** (not started)
|
||||
**Next action:** First concrete step the claiming agent runs.
|
||||
**Branch:** master
|
||||
**Weight:** needs-claude
|
||||
**Notify:** OpeItcLoc03/workshop
|
||||
<!-- created-by: you@machine / from: OpeItcLoc03/workshop / 2026-06-11 -->
|
||||
<!-- created-by: you@machine / from: OpeItcLoc03/workshop / 2026-08-23 -->
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## The two load-bearing rules
|
||||
|
||||
1. **Header must match exactly:** `## <emoji> [<slug>] — <description>`
|
||||
1. **Header must match exactly:** `## <emoji> [#<n> <slug>] — <description>`
|
||||
- `## ` (h2, two hashes) — **not** `### `, not a bullet.
|
||||
- One status **emoji**, then `[slug]` in square brackets, then ` — ` (space, em-dash `—`, space), then the description. A `-` hyphen or `:` will not match.
|
||||
- One status **emoji**, then `[#<n> <slug>]` in square brackets — **global task number** (`#1234`, no leading zeros) + slug — then ` — ` (space, em-dash `—`, space), then the description. A `-` hyphen or `:` will not match.
|
||||
- **Number is the machine key.** Global, unique across the whole federation, encodes creation order. References (`#452` in letters, blocker fields, decision trails) point at the number. The slug is the human-readable part only.
|
||||
- Slug: short, lowercase, kebab-case, Latin.
|
||||
- A header that doesn't match is **not seen as a task at all**.
|
||||
|
||||
2. **Fields are `**Label:** value` lines** — bold label, colon, space, value. Bullet-list fields (`- **weight:** …`) and prose ("notify workshop when done") are **ignored** — the poller never reads them.
|
||||
|
||||
3. **`**Created:** yyyy-mm-dd` is mandatory** — the creation date. Written once at task creation, never edited after.
|
||||
|
||||
## Numbering
|
||||
|
||||
- **Numbers are assigned by the server** (`mcp__projects-meta__tasks_create`) from the counter in `OpeItcLoc03/agenda/task-counter` — never invent or reuse a number by hand.
|
||||
- The **file name** is `yyyy-mm-dd-#####-<slug>.md` — number **5 digits with leading zeros, no `#`**: `2026-06-05-00019-fix-nl-vds-reality-pq-dest.md`. Leading zeros make folder sort = numeric up to 99999. No `#` in the filename (it would break markdown links and Gitea URLs).
|
||||
- In the **header and text references** the number is written **without** leading zeros: `[#19 slug]`.
|
||||
|
||||
## Status emoji ↔ state
|
||||
|
||||
| Emoji | State | |
|
||||
@@ -84,8 +94,12 @@ The poller routes each claimed task to a backend by its weight tier:
|
||||
|
||||
| Mistake | Fix |
|
||||
|---|---|
|
||||
| `### Title` or a `- **id:** …` bullet list | Use the exact `## <emoji> [slug] — desc` h2 header + `**Field:**` lines. |
|
||||
| `### Title` or a `- **id:** …` bullet list | Use the exact `## <emoji> [#n slug] — desc` h2 header + `**Field:**` lines. |
|
||||
| 🟢 for a ready task | 🟢 is *done*. Ready is ⚪. |
|
||||
| Header `[slug]` without a number | Header is `[#n slug]` — the number is the machine key. |
|
||||
| `**Created:**` missing | Add `**Created:** yyyy-mm-dd` — mandatory field. |
|
||||
| Inventing a number by hand | Numbers come only from `tasks_create` (counter). Never invent/reuse. |
|
||||
| File named `2026-06-05-19-slug.md` (no leading zeros) | File is `yyyy-mm-dd-#####-slug.md`, number 5 digits: `00019`. |
|
||||
| Inventing `risk: low`, `tier: L`, `priority`, `claimable-by` | The poller routes on `**Weight:**` with three fixed values only. |
|
||||
| Notification written as prose / "Done-signal" | Use a real `**Notify:** <owner>/<repo>` field line. |
|
||||
| Omitting Weight on a task you want auto-run | Always set Weight, or the task parks. |
|
||||
@@ -93,4 +107,4 @@ The poller routes each claimed task to a backend by its weight tier:
|
||||
|
||||
## Verify
|
||||
|
||||
After editing, the block is correct when: header is `## <emoji> [slug] — …`, the emoji matches `**Status:**`, every machine-read field is a `**Label:**` line (not a bullet), and a task meant for the poller has both `**Weight:**` (not `needs-human` unless intended) and `**Notify:**`.
|
||||
After editing, the block is correct when: header is `## <emoji> [#n slug] — …`, the emoji matches `**Status:**`, `**Created:** yyyy-mm-dd` is present, every machine-read field is a `**Label:**` line (not a bullet), and a task meant for the poller has both `**Weight:**` (not `needs-human` unless intended) and `**Notify:**`.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: using-tasks
|
||||
author: ours
|
||||
version: 1.4.1
|
||||
version: 1.7.0
|
||||
description: >
|
||||
Policy skill for working with an existing `.tasks/` board (per-task files + STATUS.md).
|
||||
Use whenever the user is switching between tasks, resuming a paused task, starting a new
|
||||
@@ -35,7 +35,8 @@ If `.tasks/` is **missing**, or `STATUS.md` exists but is non-canonical (e.g. fl
|
||||
<monorepo-root>/
|
||||
.tasks/
|
||||
STATUS.md ← active board: 🔴 / 🟡 / ⚪ / 🔵 blocks, sorted by priority
|
||||
<task-slug>.md ← deep context per task, one file each
|
||||
yyyy-mm-dd-#####-<slug>.md ← deep context per task, one file each (format v2)
|
||||
done/ ← per-task files of closed 🟢 tasks (format v2)
|
||||
.lock ← runtime session lock; **gitignored** (never committed)
|
||||
.archive/
|
||||
done-YYYY-MM.md ← 🟢 done blocks moved off the board, one file per month
|
||||
@@ -43,7 +44,7 @@ If `.tasks/` is **missing**, or `STATUS.md` exists but is non-canonical (e.g. fl
|
||||
|
||||
Commit `.tasks/` to git. Decision history is valuable; diffs show how thinking evolved.
|
||||
|
||||
`STATUS.md` is the **active** board — it must stay lean so orientation reads stay cheap. Closed 🟢 tasks are archived to `.archive/done-YYYY-MM.md` once they pile up; see "### Archiving done tasks".
|
||||
`STATUS.md` is the **active** board — it must stay lean so orientation reads stay cheap. Closed 🟢 tasks are archived to `.archive/done-YYYY-MM.md` once they pile up; their **per-task files** move to `.tasks/done/` (see "### Task completion" step 9).
|
||||
|
||||
> **`.tasks/.lock` must be listed in `.gitignore`** (add `.tasks/.lock` to your project's `.gitignore`). The lock file is ephemeral runtime state, not project history — it must never be committed.
|
||||
|
||||
@@ -55,8 +56,9 @@ Commit `.tasks/` to git. Decision history is valuable; diffs show how thinking e
|
||||
# Task Board
|
||||
_Updated: YYYY-MM-DD_
|
||||
|
||||
## 🔴 [task-slug] — short description
|
||||
## 🔴 [#1234 task-slug] — short description
|
||||
**Status:** active | paused | blocked | done
|
||||
**Created:** YYYY-MM-DD
|
||||
**Where I stopped:** one sentence — the exact thought or action interrupted
|
||||
**Next action:** one concrete step to resume immediately
|
||||
**Blocker:** (only if blocked) what is preventing progress
|
||||
@@ -66,6 +68,8 @@ _Updated: YYYY-MM-DD_
|
||||
---
|
||||
```
|
||||
|
||||
**Task numbering (format v2).** Every block header carries a **global task number**: `## <emoji> [#1234 slug] — …`. The number is the machine key — global, unique across the federation, encodes creation order. Numbers are assigned by the server (`mcp__projects-meta__tasks_create`) from the counter in `OpeItcLoc03/agenda/task-counter`; **never invent or reuse a number by hand** (a hand-written number collides with the counter). Per-task files are named `yyyy-mm-dd-#####-<slug>.md` — number 5 digits with leading zeros, no `#` (folder sort = numeric). References in text use the number: `#452`.
|
||||
|
||||
**Emoji convention:**
|
||||
- 🔴 Active — currently worked on (only one at a time)
|
||||
- 🟡 Paused — in progress, resumable
|
||||
@@ -87,10 +91,10 @@ The check is enforced in the **Task completion** flow below (after close, before
|
||||
|
||||
---
|
||||
|
||||
## Per-task file format (`<task-slug>.md`)
|
||||
## Per-task file format (`yyyy-mm-dd-#####-<slug>.md`)
|
||||
|
||||
```markdown
|
||||
# <task-slug>
|
||||
# <slug>
|
||||
|
||||
## Goal
|
||||
One paragraph. What this achieves and why it matters in the monorepo.
|
||||
@@ -114,6 +118,8 @@ Reverse-chronological. Append only — never rewrite past entries.
|
||||
Temporary hypotheses, links, names of people to consult.
|
||||
```
|
||||
|
||||
The file name mirrors the header: date + 5-digit number + slug, e.g. `2026-06-05-00019-fix-nl-vds-reality-pq-dest.md` for header `[#19 fix-nl-vds-reality-pq-dest]`.
|
||||
|
||||
---
|
||||
|
||||
## Agent operations
|
||||
@@ -156,11 +162,32 @@ Temporary hypotheses, links, names of people to consult.
|
||||
4. Confirm orientation before starting work.
|
||||
|
||||
### New task creation
|
||||
1. Ask: task name (slug), goal, known key files, branch name.
|
||||
2. Create `<task-slug>.md` with Goal and Key files populated.
|
||||
3. Add ⚪ block to `STATUS.md`.
|
||||
|
||||
1. **Create via the server, not by hand.** New tasks are created with `mcp__projects-meta__tasks_create` — the server assigns the global number from the counter and writes the header `[#n slug]`, the `**Created:**` field, and the per-task file `yyyy-mm-dd-#####-<slug>.md`. Hand-editing a new block into STATUS.md with an invented number collides with the counter — don't.
|
||||
2. Ask: task name (slug), goal, known key files, branch name.
|
||||
3. After the server create: fill `<slug>` content (Goal and Key files) into the per-task file `yyyy-mm-dd-#####-<slug>.md`.
|
||||
4. Create and checkout branch if it doesn't exist.
|
||||
|
||||
Exceptions (hand-edited board): migration, retro-fitting existing tasks, or a board whose project is not in the federation cache. In those cases take the next number from `OpeItcLoc03/agenda/task-counter` (read → +1 → write) before writing the block.
|
||||
|
||||
### Design-derived impl tasks — review umbrella
|
||||
|
||||
When creating **N≥1 implementation tasks derived from a design/spec** (not
|
||||
ad-hoc), also create the review umbrella:
|
||||
|
||||
- slug: `<topic>-review`
|
||||
- status: `blocked`
|
||||
- blocker: the impl-task slugs (`<topic>-impl-1, <topic>-impl-2, …`)
|
||||
- next_action: «Дождаться 🟢 у всех blocker-тасок, затем отревьюить каждую
|
||||
против acceptance criteria из дизайна. Findings → follow-up tasks.»
|
||||
- **reviewer contract: не имплементер** — следующая сессия в проекте с
|
||||
чистым контекстом (борьба с «я только что это написал» bias).
|
||||
|
||||
The umbrella is the only mechanism that guarantees a non-implementer review:
|
||||
`workshop-promote-brainstorm` generates it for the boss-flow, this rule
|
||||
covers in-project designs. Skip for ad-hoc single tasks and for
|
||||
self-implemented work closed with the coverage check.
|
||||
|
||||
### Task completion
|
||||
1. **Pre-close coverage check.** Before setting 🟢:
|
||||
- List acceptance criteria from the per-task `<slug>.md` (or the STATUS block if no per-task file).
|
||||
@@ -168,23 +195,31 @@ Temporary hypotheses, links, names of people to consult.
|
||||
- Missing evidence on any criterion → flag to user and ask "закрывать или подождать coverage'а?". Never silently close.
|
||||
- If acceptance criteria are policy / docs-only and have no testable shape, an explicit user "ok, closed by inspection" is required (record this in the close-note).
|
||||
2. Resolve or drop all open questions.
|
||||
3. Set status to 🟢 in STATUS.md.
|
||||
4. Append final summary line to Decisions log.
|
||||
5. Remind user to delete the branch after merge.
|
||||
6. **Session-break check (after close, before claiming the next task).** Once the task is 🟢 and committed — and **before** any `tasks_claim_next` or starting the next task — read the closed task's `session_break` marker (its frontmatter `session_break`, or the `**Session break:**` field in its STATUS.md block). If present:
|
||||
5. Set status to 🟢 in STATUS.md.
|
||||
6. **Notify-письмо при закрытии (кросс-проектные таски).** Если закрываемая
|
||||
таска пришла из другого проекта (в блоке есть `**Notify:**` или
|
||||
`<!-- created-by: … from: <другой-проект> -->`) — отправить письмо
|
||||
комиссионеру в его инбокс: `<notify-проект>/.agents/inbox/<ts>Z-<своя-папка>.md`,
|
||||
frontmatter `event: closed`, `slug: <task-slug>`, тело = итог (сделано,
|
||||
acceptance, ссылки). Поллер пишет это письмо за авто-раны; **живая сессия
|
||||
пишет сама** — статус 🟢 на борде ≠ комиссионер узнал.
|
||||
7. Append final summary line to Decisions log.
|
||||
8. Remind user to delete the branch after merge.
|
||||
9. **Move the per-task file to `.tasks/done/`** (format v2): `git mv .tasks/yyyy-mm-dd-#####-<slug>.md .tasks/done/`. The board block is 🟢 (archived to `.archive/done-YYYY-MM.md` when it piles up); the deep-context file leaves the active folder.
|
||||
10. **Session-break check (after close, before claiming the next task).** Once the task is 🟢 and committed — and **before** any `tasks_claim_next` or starting the next task — read the closed task's `session_break` marker (its frontmatter `session_break`, or the `**Session break:**` field in its STATUS.md block). If present:
|
||||
- Print this line **verbatim**, substituting the closed task's slug for `[slug]` and the marker's string value for `[value | "см. STATUS.md"]` (use the literal `см. STATUS.md` when the marker is just `true`):
|
||||
|
||||
`🔚 SESSION BOUNDARY — [slug] закрыта. Рекомендую завершить текущую сессию. Следующий трек: [value | "см. STATUS.md"]`
|
||||
|
||||
- **Stop.** Do not claim or start the next task.
|
||||
- If the marker is absent → behaviour is unchanged: proceed to claim / start the next task as usual.
|
||||
7. **Archival check.** After the close is committed, if `STATUS.md` now holds **≥ 10** 🟢 done blocks, archive them (see "### Archiving done tasks"). This keeps the board lean for the next orientation read.
|
||||
11. **Archival check.** After the close is committed, if `STATUS.md` now holds **≥ 10** 🟢 done blocks, archive them (see "### Archiving done tasks"). This keeps the board lean for the next orientation read.
|
||||
|
||||
### Archiving done tasks
|
||||
|
||||
🟢 done blocks accumulate in `STATUS.md` and bloat it — and since orientation reads the whole board, a bloated file burns context on every session start (the recurring "huge STATUS.md" complaint). Keep the board lean: done blocks stay only until merged, then move to a monthly archive.
|
||||
|
||||
**Threshold.** When `STATUS.md` holds **≥ 10** 🟢 done blocks, archive them. Check at two moments: (a) right after closing a task (Task completion step 7), and (b) at session start, before orienting (Session start step 7). The threshold is a ceiling, not a target — archive in batches; don't churn one block at a time.
|
||||
**Threshold.** When `STATUS.md` holds **≥ 10** 🟢 done blocks, archive them. Check at two moments: (a) right after closing a task (Task completion step 8), and (b) at session start, before orienting (Session start step 7). The threshold is a ceiling, not a target — archive in batches; don't churn one block at a time.
|
||||
|
||||
**Where.** Append the archived blocks to `.tasks/.archive/done-YYYY-MM.md` — one file per calendar month, keyed by the date of archival. Create `.tasks/.archive/` and the month file if absent. If the month file already exists, **append**; never overwrite.
|
||||
|
||||
@@ -248,5 +283,7 @@ Pair: `using-projects-meta` declares local-first for **reads**; this rule extend
|
||||
- **One active task at a time** — only one 🔴 in STATUS.md.
|
||||
- **Keep the board lean** — orientation reads the local `STATUS.md` whole, so archive 🟢 done blocks to `.tasks/.archive/done-YYYY-MM.md` once ≥10 pile up. Never enumerate the current project's board via `tasks_aggregate` (cross-project cache) or `tasks_get_status` (single-task, by slug). See "### Archiving done tasks".
|
||||
- **Never close a task without a coverage check** — see "### Task completion" step 1. Acceptance criteria with no evidence → ask, don't auto-close.
|
||||
- **Honour `session_break`** — a closed task carrying a `session_break` marker means stop after close; never chain into `tasks_claim_next`. See "### Task completion" step 6.
|
||||
- **Honour `session_break`** — a closed task carrying a `session_break` marker means stop after close; never chain into `tasks_claim_next`. See "### Task completion" step 7.
|
||||
- **Local-first recommendations** — cwd-project board comes first; cross-project urgents are at most one footnote line.
|
||||
- **Notify-письмо при закрытии** — кросс-проектная таска закрыта → письмо комиссионеру (event: closed). Поллер пишет за авто-раны; живая сессия — сама. See "### Task completion" step 4.
|
||||
- **Design → impl tasks ⇒ review umbrella** — N≥1 impl tasks derived from a design get a `<topic>-review` umbrella (status=blocked, blocker=impl-slugs, reviewer = non-implementer session). See "### Design-derived impl tasks — review umbrella".
|
||||
|
||||
Reference in New Issue
Block a user