diff --git a/skills/mappa-brainstorm-promote/SKILL.md b/skills/mappa-brainstorm-promote/SKILL.md index c5b64ff..9a770f4 100644 --- a/skills/mappa-brainstorm-promote/SKILL.md +++ b/skills/mappa-brainstorm-promote/SKILL.md @@ -1,247 +1,252 @@ --- name: mappa-brainstorm-promote author: ours -version: 1.6.0 +version: 1.7.0 description: > - Finalize a matured brainstorm buffer (mappa entity type=brainstorm, status=buffer): - read buffer → choose target project → promote via mcp__mappa__brainstorm_promote - (atomic buffer → wiki-страница в target + archive, решение 7) → extract - action-items into target tasks (mcp__mappa__task_create, карв-аут) → review - umbrella → covering letter. Общий механизм mappa, как task.create/wiki.create — - никакой workshop-специфики. Старое имя — триггер-синоним: - workshop-promote-brainstorm. Triggers (user): «промоутни брейнсторм», - «finalize », «выкати в вики», «promote ». + Finalize a matured brainstorm buffer (mappa entity type=brainstorm, + status=buffer): read buffer → choose target project → promote via + mcp__mappa__brainstorm_promote (atomic buffer → wiki-page in target + + archive, decision 7) → extract action-items into target tasks + (mcp__mappa__task_create, carve-out) → review umbrella → covering letter. + A general mappa mechanism, like task.create/wiki.create — no workshop + specifics. Old name — trigger-synonym: workshop-promote-brainstorm. + Triggers (bilingual): «промоутни брейнсторм», «finalize », «выкати в + вики», «promote », "promote the brainstorm", "finalize ". --- # mappa-brainstorm-promote -Финализация созревшего брейнсторм-буфера, который живёт **как mappa-сущность -типа `brainstorm`** (status=buffer). Это общий механизм mappa — ровно как -`task.create` или `wiki.create`: буфер существует в mappa, скил доводит его до -конца (промоут контента в вики + action-items тасками). Никакой -workshop-специфики: скил триггерится из любой папки, работает с brainstorm- -сущностями любого проекта. +Finalizing a matured brainstorm buffer that lives **as a mappa entity of type +`brainstorm`** (status=buffer). This is a general mappa mechanism — exactly +like `task.create` or `wiki.create`: the buffer exists in mappa, the skill +takes it to the end (promote the content into the wiki + action-items as +tasks). No workshop specifics: the skill triggers from any folder, works with +brainstorm entities of any project. -Процедура линейная (от чтения буфера до промоута и тасок), не цикл: запускается -явно на финальном буфере и доводит его до конца. В форкфлоу встаёт между -работой (`mappa-task-work`) и финишем (`mappa-closing-ritual`). +The procedure is linear (from reading the buffer to promotion and tasks), not +a loop: it's launched explicitly on the final buffer and takes it to the end. +In the forkflow it sits between work (`mappa-task-work`) and finish +(`mappa-closing-ritual`). -**Промоут контента — всегда через `mcp__mappa__brainstorm_promote`:** -атомарно создаёт wiki-страницу (slug из буфера, body сохраняется) в проекте из -вызова и переводит буфер в `archive` (номер/slug стабильны, решение 20; рёбра -parent_of, событие `brainstorm.promoted`). Никаких файловых каналов. Action-items -уходят тасками в target-проект через `mcp__mappa__task_create` (карв-аут без -лиза, #1054; последовательно, не батчем). +**Content promotion — always via `mcp__mappa__brainstorm_promote`:** +atomically creates a wiki page (slug from the buffer, body preserved) in the +project from the call and moves the buffer to `archive` (number/slug stable, +decision 20; parent_of edges, `brainstorm.promoted` event). No file channels. +Action-items go as tasks to the target project via `mcp__mappa__task_create` +(carve-out without a lease, #1054; sequentially, not batched). ## When to use - «промоутни брейнсторм», «finalize », «выкати в вики», «promote - ». -- Пользователь ссылается на brainstorm-сущность (brainstorm:N) или на тему - буфера, который созрел и готов к промоушену. + », "promote the brainstorm". +- The user references a brainstorm entity (brainstorm:N) or a buffer topic + that matured and is ready for promotion. ## Inputs -- Brainstorm-реф `brainstorm:N` или `` (slug/тема буфера) + project (если - буфер не в текущем проекте — спросить). -- Для skill-ветки дополнительно: `` нового скила (если не указан — - спросить, предложить производное от topic). +- Brainstorm ref `brainstorm:N` or `` (buffer slug/topic) + project (if + the buffer is not in the current project — ask). +- For the skill branch additionally: `` of the new skill (if not + specified — ask, propose a derivation from the topic). ## Decision flow ``` -brainstorm-сущность в mappa (type=brainstorm, status=buffer) +brainstorm entity in mappa (type=brainstorm, status=buffer) │ ▼ - find + read (entity_search type=brainstorm → entity_get полный body) + find + read (entity_search type=brainstorm → entity_get full body) │ ▼ - ask: target project (куда промоутить) + ask: target project (where to promote) │ - ├── обычный проект → brainstorm_promote(project=) - │ → wiki-страница (спека) в вики target + ├── ordinary project → brainstorm_promote(project=) + │ → wiki page (spec) in the target wiki │ └── skill → dialog: description (trigger contract) → preview + confirm - → mkdir + Write SKILL.md (каркас) в ~/projects/skills/ + → mkdir + Write SKILL.md (skeleton) in ~/projects/skills/ → git add + commit (local, no push/install) │ ▼ - parse action-items from buffer body + parse action-items from the buffer body │ ▼ - for each: mcp__mappa__task_create (ПОСЛЕДОВАТЕЛЬНО, не батчем) + for each: mcp__mappa__task_create (SEQUENTIALLY, not batched) │ ▼ review-umbrella: mcp__mappa__task_create (blocked, blocker=impl#) │ ▼ - covering-письмо: mcp__mappa__inbox_send (канон mappa-delegation) + covering letter: mcp__mappa__inbox_send (mappa-delegation canon) │ ▼ - финальный отчёт (wiki:NNNN — спека, brainstorm:N — архив, таски) + final report (wiki:NNNN — spec, brainstorm:N — archive, tasks) ``` ## Steps -1. **Найти буфер в mappa.** `mcp__mappa__entity_search(type='brainstorm', - project=<проект>, q=)` → в результатах brainstorm:N + **internal id**. - Прочитать полный буфер: `mcp__mappa__entity_get(id=)` — тело = - running record (frontmatter + раунды). +1. **Find the buffer in mappa.** `mcp__mappa__entity_search(type='brainstorm', + project=, q=)` → in the results brainstorm:N + **internal + id**. Read the full buffer: `mcp__mappa__entity_get(id=)` — + body = running record (frontmatter + rounds). - Если буфера нет в mappa — создать brainstorm-сущность через - `mcp__mappa__brainstorm_create` (или HTTP `POST /entities` type=brainstorm, - контракт решения 7/#1054). Не изобретать файловые буферы. + If the buffer is not in mappa — create a brainstorm entity via + `mcp__mappa__brainstorm_create` (or HTTP `POST /entities` type=brainstorm, + contract decision 7/#1054). Don't invent file buffers. -2. **Показать summary буфера (≤2 абзаца).** +2. **Show the buffer summary (≤2 paragraphs).** -3. **Спросить target-проект** — куда промоутить контент. По умолчанию — проект, - где буфер живёт (брейншторм ведут там, где тема релевантна). Проверить, что - проект существует в mappa: `mcp__mappa__entity_search` type=project - (или `mcp__mappa__entity_search` с q=<имя проекта>). Если нет — abort с - сообщением. +3. **Ask the target project** — where to promote the content. Default — the + project where the buffer lives (brainstorms are run where the topic is + relevant). Verify the project exists in mappa: + `mcp__mappa__entity_search` type=project (or `mcp__mappa__entity_search` + with q=). If not — abort with a message. -4. **Если target = skill (пользователь хочет оформить как скил):** - - Спросить `` нового скила (если не указан) — валидный slug +4. **If target = skill (the user wants it as a skill):** + - Ask `` of the new skill (if not specified) — a valid slug (`[a-z0-9-]+`). - - Валидация (порядок важен): сначала проверить, что `~/projects/skills/` - сам репозиторий существует. Если нет — **abort** с сообщением «клонируй - skills через update-skills или вручную». - - Затем: `~/projects/skills/skills//` НЕ должна существовать. - Если существует — **abort** с сообщением «скил `` уже существует, - обновляйся обычным маршрутом в `~/projects/skills/`, этот скил не для - апдейтов». - - Двухпроходной каркас: диалог по `description` (триггер-контракт активации: - минимум 2-3 фразы, пары русский/английский; что делает; антипаттерны) → - preview + confirm → `Write` каркаса (шапка + 6 пустых секций) → локальный - `git commit` в `~/projects/skills/`. **Без** install.sh, push, - build-hermes — это в baseline-тасках шага 7. Тело каркаса дописывается - вторым проходом глазами (вне scope этого скила). + - Validation (order matters): first check that `~/projects/skills/` itself + is a repository. If not — **abort** with the message "clone skills via + update-skills or manually". + - Then: `~/projects/skills/skills//` must NOT exist. If it exists — + **abort** with the message "skill `` already exists, update through + the normal route in `~/projects/skills/`, this skill is not for updates". + - Two-pass skeleton: dialog on `description` (activation trigger contract: + minimum 2-3 phrases, Russian/English pairs; what it does; antipatterns) → + preview + confirm → `Write` of the skeleton (header + 6 empty sections) → + local `git commit` in `~/projects/skills/`. **Without** install.sh, push, + build-hermes — those are in the baseline tasks of step 7. The body of the + skeleton is written in a second pass by eye (outside this skill's scope). -5. **Промоут контента (всегда через `brainstorm_promote`, решение 7):** +5. **Content promotion (always via `brainstorm_promote`, decision 7):** `mcp__mappa__brainstorm_promote(project=, brainstorm_id=)` - - Атомарно: buffer → wiki-страница (slug из буфера, body сохраняется, рёбра - parent_of buffer→wiki и refs→buffer) + буфер → `archive` + значимое событие - `brainstorm.promoted`. - - **Frontmatter-summary (wiki:2661):** убедиться, что в теле буфера есть - `summary:` одной строкой в frontmatter — карточки `wiki.search` читают его. - Если нет — дописать через `mcp__mappa__brainstorm_update` (PATCH - /brainstorm/:id, title/body/status, optimistic version+409) перед промоутом. - - Повторный промоут архивированного буфера → ошибка (one-shot, идемпотентно - через статус). Сверить `brainstorm_id` (internal) из шага 1. - - Если `brainstorm_promote` упал (конфликт версии, 409) → retry со свежим - internal id; при стабильном отказе — abort до создания тасок. + - Atomically: buffer → wiki page (slug from the buffer, body preserved, + parent_of buffer→wiki edges and refs→buffer) + buffer → `archive` + + significant `brainstorm.promoted` event. + - **Frontmatter-summary (wiki:2661):** make sure the buffer body has + `summary:` as one line in the frontmatter — `wiki.search` cards read it. + If missing — append via `mcp__mappa__brainstorm_update` (PATCH + /brainstorm/:id, title/body/status, optimistic version+409) before the + promotion. + - Re-promoting an archived buffer → error (one-shot, idempotent via + status). Cross-check `brainstorm_id` (internal) from step 1. + - If `brainstorm_promote` failed (version conflict, 409) → retry with the + fresh internal id; on a stable failure — abort before creating tasks. -6. **Парсинг action-items:** regex по строкам вида `- [ ] ...` в теле буфера, - секции после `## Следующие шаги`/`## TODO`/`## Next steps`/ - `## Action items`. Показать список, дать редактировать/удалять/добавлять. - Если 0 action-items — продолжить, не блокировать. +6. **Action-items parsing:** regex over lines like `- [ ] ...` in the buffer + body, sections after `## Следующие шаги`/`## TODO`/`## Next steps`/ + `## Action items`. Show the list, allow editing/removing/adding. If 0 + action-items — continue, don't block. -7. **Создание тасок:** +7. **Task creation:** - > **NB:** таски создавать **ПОСЛЕДОВАТЕЛЬНО**, не батчем. Один - > `task_create` → дождаться ответа → следующий. + > **NB:** create tasks **SEQUENTIALLY**, not batched. One `task_create` → + > wait for the response → the next one. - - **Обычный target:** для каждого action-item — + - **Ordinary target:** for each action-item — `mcp__mappa__task_create(project=, slug=, title, description, - status='ready')`. Create — карв-аут, лиз не нужен (wiki:2660/#1054). - Описание импл-таски ссылается на спеку (wiki:NNNN из шага 5). - - **Skill:** три baseline-таски в `project='skills'`: - - `[-install]` — запустить `install.sh` в `~/projects/skills/`, - проверить активацию в новой сессии. - - `[-hermes-mapping]` — запись в `~/projects/skills/hermes/mapping.yaml` - (режим `auto` для стилевых, `pending` если трогает тулы/окружение). - - `[-test-trigger]` — прогнать триггер-фразы из description: - активируется на своих, не активируется на 2-3 близких чужих. - Плюс content-таски из буфера (если были) — тоже в `project='skills'`, + status='ready')`. Create — carve-out, no lease needed (wiki:2660/#1054). + The impl task description references the spec (wiki:NNNN from step 5). + - **Skill:** three baseline tasks in `project='skills'`: + - `[-install]` — run `install.sh` in `~/projects/skills/`, + verify activation in a new session. + - `[-hermes-mapping]` — a record in + `~/projects/skills/hermes/mapping.yaml` (mode `auto` for style ones, + `pending` if it touches tools/environment). + - `[-test-trigger]` — run the trigger phrases from the description: + activates on its own, doesn't activate on 2-3 close foreign ones. + Plus content tasks from the buffer (if any) — also in `project='skills'`, slug-prefix `-`. - - Если N-я таска упала — продолжить остальные, в конце сообщить какие - созданы / какие нет. Запомнить slug'и для review-umbrella. + - If the N-th task failed — continue the rest, report at the end which were + created / which weren't. Remember the slugs for the review-umbrella. -8. **Review-umbrella (для target с импл-тасками и для skill — всегда):** +8. **Review-umbrella (for a target with impl tasks, and for skill — always):** `mcp__mappa__task_create(project=, slug=-review, - status='blocked', blocker=<номера импл-тасок через запятую>, description=<чек-лист>)` + status='blocked', blocker=, description=)` - - **Кто делает:** не имплементер. Следующая сессия в этом проекте (другая - модель / другой день / другой агент) с чистым контекстом. «Я только что - это написал» bias = главный риск. - - Чек-лист: прочитать спеку (wiki:NNNN из шага 5), `git log` shipped-коммитов, - для каждой импл-таски прогнать тесты и сверить с acceptance criteria, - findings → follow-up tasks через `task_create`. - - Закрытие: все findings зафайлены ИЛИ ревьюер подтвердил «нет findings» - в close-note. - - Если review-таска упала — сообщить, **продолжить** к шагу 9 (промоут уже - сделан, буфер в archive). + - **Who does it:** not the implementer. The next session in this project (a + different model / different day / different agent) with a clean context. + The "I just wrote this" bias is the main risk. + - Checklist: read the spec (wiki:NNNN from step 5), `git log` of the + shipped commits, for each impl task run the tests and cross-check with + acceptance criteria, findings → follow-up tasks via `task_create`. + - Closing: all findings filed OR the reviewer confirmed "no findings" in + the close-note. + - If the review task failed — report, **continue** to step 9 (the promotion + is already done, the buffer is in archive). -9. **Covering-письмо в инбокс цели (канон mappa-delegation).** Таска на борде - не пингует живую сессию, письмо = пинг + контекст: +9. **Covering letter to the target's inbox (mappa-delegation canon).** A task + on the board doesn't ping a live session, a letter = ping + context: - `mcp__mappa__inbox_send(project=, from=<своя папка>, subject='Промоушен - : таски <#N…>', body=<перечень + wiki:NNNN спека>)` + `mcp__mappa__inbox_send(project=, from=, subject='Promotion + : tasks <#N…>', body=)` -10. **Финальный отчёт пользователю:** - - Куда промочено: `wiki:NNNN` (спека в вики target). - - Архив: `brainstorm:N` (status=archive, номер стабилен). - - Какие таски созданы (ref, title, проект). - - **Для skill:** напомнить про второй проход «доведём ``». +10. **Final report to the user:** + - Where it was promoted: `wiki:NNNN` (spec in the target wiki). + - Archive: `brainstorm:N` (status=archive, number stable). + - Which tasks were created (ref, title, project). + - **For skill:** remind about the second pass "let's flesh out ``". ## Failure modes -- Буфер не найден в mappa (нет brainstorm-сущности) → abort, сообщить: создать - через `brainstorm_create` (шаг 1) или HTTP POST /entities. -- `entity_search`/`entity_get` упал (API-ошибка, не пустой результат) → abort - с текстом ошибки; не создавать буфер по догадке. -- Target-проект не существует в mappa → abort до промоута. -- `brainstorm_promote` упал (409 версия / стабильный отказ) → retry со свежим - internal id; при повторном отказе — abort до создания тасок. Буфер остаётся - в buffer — ретраится позже. -- Буфер уже `archive` (повторный вызов) → abort: промоут one-shot, - идемпотентность через статус (решение 7). -- `task_create` упал на N-й content-таске → продолжить остальные, сообщить - partial. Промоут уже сделан — буфер не откатывается. -- `task_create` review-umbrella упал → не блокировать, сообщить пользователю - (создать вручную из шага 8). -- `inbox_send` (covering-письмо) упал → промоут и таски не откатываются; - сообщить пользователю, письмо можно отправить позже (промоут уже виден - в графе/инбоксе цели). -- **Skill:** `~/projects/skills/` не существует → abort. -- **Skill:** `~/projects/skills/skills//` уже существует → abort. -- **Skill:** пользователь не подтвердил preview → abort, состояние не меняется. -- **Skill:** локальный `git commit` в `~/projects/skills/` упал → файл остаётся, - сообщить что коммит нужно сделать руками; промоут буфера не блокируется. +- Buffer not found in mappa (no brainstorm entity) → abort, report: create via + `brainstorm_create` (step 1) or HTTP POST /entities. +- `entity_search`/`entity_get` failed (API error, not an empty result) → abort + with the error text; don't create a buffer by guess. +- Target project doesn't exist in mappa → abort before promotion. +- `brainstorm_promote` failed (409 version / stable refusal) → retry with the + fresh internal id; on a repeated failure — abort before creating tasks. The + buffer stays in buffer — retried later. +- Buffer already `archive` (repeated call) → abort: promotion is one-shot, + idempotence via status (decision 7). +- `task_create` failed on the N-th content task → continue the rest, report + partial. The promotion is already done — the buffer is not rolled back. +- `task_create` review-umbrella failed → don't block, report to the user + (create manually from step 8). +- `inbox_send` (covering letter) failed → promotion and tasks are not rolled + back; report to the user, the letter can be sent later (the promotion is + already visible in the graph/inbox of the target). +- **Skill:** `~/projects/skills/` doesn't exist → abort. +- **Skill:** `~/projects/skills/skills//` already exists → abort. +- **Skill:** user didn't confirm the preview → abort, state unchanged. +- **Skill:** local `git commit` in `~/projects/skills/` failed → the file + stays, report that the commit needs to be done by hand; the buffer promotion + is not blocked. ## Side effects -- **Всегда:** `brainstorm_promote` — атомарно wiki-страница в target + буфер → - `archive` + рёбра parent_of (wiki→buffer, refs→buffer) + событие - `brainstorm.promoted`. -- **Обычный target:** спека-страница в вики целевого проекта (с - frontmatter-summary, wiki:2661) + импл-таски + review-umbrella + covering-письмо. -- **Skill:** каркас `~/projects/skills/skills//SKILL.md` (только шапка + - пустой 6-секционный каркас) + локальный коммит в `~/projects/skills/`. - **Без** install.sh, push, build-hermes — это в baseline-тасках. -- Создаёт N тасок в target через `mcp__mappa__task_create` (карв-аут). -- Создаёт review-umbrella таску (status=blocked, blocker=impl#). -- Отправляет covering-письмо в инбокс target. +- **Always:** `brainstorm_promote` — atomically wiki page in the target + + buffer → `archive` + parent_of edges (wiki→buffer, refs→buffer) + + `brainstorm.promoted` event. +- **Ordinary target:** spec page in the target project's wiki (with + frontmatter-summary, wiki:2661) + impl tasks + review-umbrella + covering letter. +- **Skill:** skeleton `~/projects/skills/skills//SKILL.md` (only header + + empty 6-section skeleton) + local commit in `~/projects/skills/`. + **Without** install.sh, push, build-hermes — those are in the baseline tasks. +- Creates N tasks in the target via `mcp__mappa__task_create` (carve-out). +- Creates a review-umbrella task (status=blocked, blocker=impl#). +- Sends a covering letter to the target's inbox. ## What NOT to do -- **Не использовать файловые каналы** — буфер живёт в mappa brainstorm-сущности, - никаких `.brainstorm/`/`.archive/` записей. -- **Не использовать `mcp__projects-meta__tasks_create` / `knowledge_ingest` / - `knowledge_promote`** — файловые каналы выпилены. Таски — - `mcp__mappa__task_create`, вики — `brainstorm_promote` (контент) + - `wiki_create`/`wiki_update` (доп. страницы). -- Не делать `git mv` буфера в архив — промоут архивирует сам. -- Не удалять буфер вместо промоута — теряется граф-история (parent_of, refs). -- Не батчить `task_create` (гонка; инцидент 2026-08-24: 6/7 упали) — только - последовательно. -- Не забывать covering-письмо — таска на борде не пингует живую сессию. -- **Skill:** не переформатировать тело буфера в каркас автоматически — тело - дописывается вторым проходом глазами. -- **Skill:** не запускать `install.sh`, не делать push, не править - `hermes/mapping.yaml` — это baseline-таски. -- **Skill:** не промоутить в существующий скил (abort). +- **Don't use file channels** — the buffer lives in a mappa brainstorm entity, + no `.brainstorm/`/`.archive/` records. +- **Don't use `mcp__projects-meta__tasks_create` / `knowledge_ingest` / + `knowledge_promote`** — file channels are removed. Tasks — + `mcp__mappa__task_create`, wiki — `brainstorm_promote` (content) + + `wiki_create`/`wiki_update` (extra pages). +- Don't `git mv` the buffer into the archive — the promotion archives it itself. +- Don't delete the buffer instead of promoting — the graph history is lost + (parent_of, refs). +- Don't batch `task_create` (race; incident 2026-08-24: 6/7 failed) — only + sequentially. +- Don't forget the covering letter — a task on the board doesn't ping a live session. +- **Skill:** don't automatically reformat the buffer body into the skeleton — + the body is written in a second pass by eye. +- **Skill:** don't run `install.sh`, don't push, don't edit + `hermes/mapping.yaml` — those are baseline tasks. +- **Skill:** don't promote into an existing skill (abort).