@@ -12,7 +12,7 @@ The `wiki-maintainer` skill enforces the workflow and file formats. This file ov
-`entities/` — discrete things this project tracks. Reserved for future use (individual skills if they accumulate non-obvious context, tools we adopt).
-`concepts/` — design decisions, technical gotchas, refactor notes. Most pages live here.
-`packages/` — currently empty. Would be used if we extract a package (e.g. a CLI) from this repo.
-`sources/` — one summary per ingested external doc; carries `ingested:` and `raw_path:` frontmatter.
-`summaries/` — one summary per ingested external doc; carries `ingested:` and `raw_path:` frontmatter.
-`overview.md` — single project-wide overview. Read this first if new to the repo.
«finalize <topic>», «выкати в вики», «promote <topic>».
---
# mappa-brainstorm-promote
Финализация созревшего брейнсторм-буфера на столе босса (`~/projects/.workshop/`) — **процедура** (линейная: от чтения буфера до архивации), не цикл в смысле повторения: запускается явно на финальном буфере и доводит его до конца (промоушен + таски + архив). В форкфлоу встаёт между работой (`mappa-task-work`) и финишем (`mappa-closing-ritual`). Четыре ветки маршрутизации:
Финализация созревшего брейнсторм-буфера, который живёт **как mappa-сущность
типа `brainstorm`** (status=buffer). Это общий механизм mappa — ровно как
`task.create` или `wiki.create`: буфер существует в mappa, скил доводит его до
конца (промоут контента в вики + action-items тасками). Никакой
workshop-специфики: скил триггерится из любой папки, работает с brainstorm-
сущностями любого проекта.
> **Location-agnostic.** Скил триггерится из любой папки — босс-штормы
> происходят где угодно, запись живёт на столе. Все относительные пути ниже
> (`.brainstorm/`, `.archive/`, `.wiki/`, `index.md`) разрешаются относительно
> `~/projects/.workshop/` **независимо от CWD**; git-команды явно указывают
> `-C ~/projects/.workshop`.
Процедура линейная (от чтения буфера до промоута и тасок), не цикл: запускается
явно на финальном буфере и доводит его до конца. В форкфлоу встаёт между
работой (`mappa-task-work`) и финишем (`mappa-closing-ritual`).
- **workshop-meta** → локальный `.wiki/concepts/` (методология самой зоны).
- **domain** → глобал через `mcp__projects-meta__knowledge_ingest` в `~/projects/<proj>/.wiki/`.
- **mappa-service** → сервисные борды (mappa, .common, …): таски/вики-сущности через `mcp__mappa__task_create`/`wiki_create` (**create — карв-аут без лиза**, wiki:2660; update — version+409); pointers-таска НЕ нужна, если спека уже в вики проекта (wiki:NNNN); review-umbrella — сервисная таска; covering-письмо в инбокс цели.
- **skill** → `~/projects/claude-skills/skills/<name>/SKILL.md` (только шапка + пустой каркас тела, локальный коммит без push/install/build-hermes).
Буфер уезжает в `.archive/`. Action-items уходят тасками в target-проект. **Всегда, при любом маршруте, в воркшоп-вики остаётся summary-страница.**
**Промоут контента — всегда через `mcp__mappa__brainstorm_promote`:**
атомарно создаёт wiki-страницу (slug из буфера, body сохраняется) в проекте из
вызова и переводит буфер в `archive` (номер/slug стабильны, решение 20; рёбра
parent_of, событие `brainstorm.promoted`). Никаких файловых каналов. Action-items
уходят тасками в target-проект через `mcp__mappa__task_create` (карв-аут без
лиза, #1054; последовательно, не батчем).
## When to use
- «промоутни брейнсторм», «finalize <topic>», «выкати в вики», «promote <topic>».
- Пользователь явно ссылается на `.workshop/.brainstorm/<topic>.md` как на готовый к промоушену.
- «промоутни брейнсторм», «finalize <topic>», «выкати в вики», «promote
<topic>».
- Пользователь ссылается на brainstorm-сущность (brainstorm:N) или на тему
буфера, который созрел и готов к промоушену.
## Inputs
-Путь`.brainstorm/<topic>.md` или просто `<topic>`.
- Для skill-ветки дополнительно: `<name>` нового скила (если не указан — спросить, предложить производное от topic).
-Brainstorm-реф`brainstorm:N` или `<topic>` (slug/тема буфера) + project (если
буфер не в текущем проекте — спросить).
- Для skill-ветки дополнительно: `<name>` нового скила (если не указан —
спросить, предложить производное от topic).
## Decision flow
```
.brainstorm/<topic>.md
brainstorm-сущность в mappa (type=brainstorm, status=buffer)
│
▼
read + summarize (1–2 paragraphs)
find + read (entity_search type=brainstorm → entity_get полный body)
- **domain** — доменное содержимое для какого-то целевого проекта.
- **skill** — методология общего назначения, оформляется как скил в `~/projects/claude-skills/`.
3.**Если domain:**
- Спросить целевой проект (имя папки в `~/projects/`).
- Валидация: вызвать `mcp__projects-meta__meta_status`, убедиться что проект известен; иначе — abort с сообщением «зарегистрируй проект через setup-projects-meta».
- **Определить канал борда:** есть ли у проекта файловая доска `.tasks/STATUS.md` (file channel) или борд живёт в mappa-сущностях (service channel — сервисные проекты: mappa, .common, …). Проверка: файл `.tasks/STATUS.md` в чек-ауте (file) против `mcp__mappa__task_list(project=<proj>)` / `entity_search` (service). Если файловой доски нет, а mappa-сущности есть → **service channel**.
4.**Если domain + service channel (mappa-борд, fold-in 1):**
- **Create — карв-аут, лиз НЕ нужен** (wiki:2660): `task_create`/`wiki_create`
без claim_token (интерактивный контракт, поллер вне mappa).
- **Спека → вики-сущность:** `mcp__mappa__wiki_create(project, slug, body)` (или `wiki_update(project, id, version, …)`, если страница уже есть). Если спека уже в вики проекта (wiki:NNNN) — не дублировать, описание импл-тасок ссылается на неё. **Frontmatter-summary (wiki:2661):** при создании пиши `summary:` одной строкой в frontmatter — карточки `wiki.search` и поиск по вики читают его.
- **Pointers-таска НЕ нужна**, если спека уже в вики проекта — дыра pointers закрыта инлайн (описание импл-тасок прямо ссылается на спеку).
- **Импл-таски:** `mcp__mappa__task_create(project, slug, title, description, status='ready')` — **ПОСЛЕДОВАТЕЛЬНО, не батчем** (см. NB в шаге 7).
- **Covering-письмо:** `mcp__mappa__inbox_send(project=<target>, from=<своя>, subject='Промоушен <topic>: таски <#N>…', body=<перечень>).` — канон mappa-delegation: таска на борде не пингует живую сессию.
5.**Если skill:**
- Спросить `<name>` нового скила (если не указан) — валидный slug (`[a-z0-9-]+`).
- Валидация: `~/projects/claude-skills/skills/<name>/`НЕ должна существовать. Если существует — **abort**с сообщением «скил `<name>` уже существует, обновляйся обычным маршрутом в `claude-skills/`, этот скил не для апдейтов».
- Валидация: `~/projects/claude-skills/` сам репозиторий существует. Если нет — abort с сообщением «клонируй claude-skills/ через update-claude-skills или вручную».
6.**Парсинг action-items:**
- regex по строкам вида `- [ ] ...`, `- [ ]`, секции после `## Следующие шаги`/`## TODO`/`## Next steps`/`## Action items`.
- Показать список, дать редактировать/удалять/добавлять.
- Если 0 action-items — продолжить, не блокировать.
Если `knowledge_ingest` падает → abort до tasks_create и до `git mv`. Сообщить пользователю.
- **skill:** двухпроходной.
**Проход первый (этот скил):**
1. **Диалог по `description`** — поведенческий контракт активации скила. Показать пользователю summary буфера и спросить:
- На каких триггер-фразах скил должен активироваться? (минимум 2-3, лучше — пары русский/английский)
- Что скил делает в одном предложении?
- Когда скил **не должен** активироваться (антипаттерны)?
Из ответов собрать `description` строкой ~200-400 символов в стиле существующих скилов (см. `~/projects/claude-skills/skills/*/SKILL.md` для примеров).
2. **Preview + confirm** (обязательно):
```
Писать в: ~/projects/claude-skills/skills/<name>/SKILL.md
- **STOP.** Не запускать `install.sh`. Не делать `git push`. Не править `hermes/mapping.yaml`. Это всё уйдёт тасками на шаге 7.
**Проход второй** — пользователь явно зовёт «доведём `<name>`» в этой же или следующей сессии. Источник лежит в `.archive/<date>-<topic>.md`, тело каркаса дописывается глазами. Вне scope этого скила.
8. **Создание тасок:**
> **NB (2026-08-24, инцидент mappa-skill-suite):** таски создавать **ПОСЛЕДОВАТЕЛЬНО**, не батчем и не параллельно. Параллельный `tasks_create` → гонка на sha-CAS общего счётчика (agenda-репо): часть тасок падает с PushRejected (при промоуте mappa-skill-suite 6/7 упали, повторены последовательно). Один `tasks_create` → дождаться ответа → следующий.
- **domain (mandatory pre-impl) — `[<topic>-pointers]`:** **первой** создать таску, заполняющую `.wiki/CLAUDE.md` Domain conventions у target-проекта пойнтерами на спецификацию. Без неё импл-таски будут подняты со stub'ом в Domain conventions, и следующий агент попадёт в дыру: dense `where_stopped` one-liner + пустой stub = угадывание порогов / таксономий / pipeline-этапов. Параметры:
- `target_project: <target>`
- `slug: <topic>-pointers`
- `status: ready`
- `description:` шаблон ниже
- `next_action:` готовый блок текста для копирования в `.wiki/CLAUDE.md` (шаблон ниже)
Description-шаблон:
```
Bootstrap-pointers для design <topic>. Pre-fills target's `.wiki/CLAUDE.md`
Domain conventions ссылками на спецификацию. Дизайн не лежит в этом репо —
только pointer-stub. Без этой таски следующий агент попадёт в дыру:
Why each decision was made, what was rejected and why, anti-patterns.
3. **Local `overview.md`** — thin summary of (1), used as quick orientation
only — never as the source of truth.
Do **not** invent thresholds, taxonomies, container topology, or pipeline
stages from task `where_stopped` lines alone — those are pointers, not
specifications.
---
Закоммитить: `wiki(claude): add design-context pointers for <topic>`.
```
Конкретные значения, которые промоутер должен подставить **заранее** в
текст next_action перед `tasks_create`:
- `<topic>` — тема промоушена (тот же slug, что используется в `concepts/<topic>.md` и в `.archive/<YYYY-MM-DD>-<topic>.md`).
- `<YYYY-MM-DD>` — сегодняшняя дата (та же, что в шаге 9 архивации).
Если `tasks_create` для `<topic>-pointers` упала → **abort** до content-тасок и до review. Без pointers оставшиеся таски бесполезны: импл-агент будет угадывать. Сообщить пользователю, буфер оставить на месте.
- **workshop-meta / domain (content):** для каждого action-item:
- `mcp__projects-meta__tasks_create` с `project: <target>` (для domain) или с `project: <inferred>` (для workshop-meta — спросить пользователя если неоднозначно).
- Title — первая строка action-item; description — остальное.
- **skill:** **всегда** добавляются три baseline-таски в `project: claude-skills`:
- `[<name>-install]` — запустить `install.sh` в `~/projects/claude-skills/`, проверить что скил активируется в новой сессии, сделать `/reload-plugins`.
- `[<name>-hermes-mapping]` — добавить запись в `~/projects/claude-skills/hermes/mapping.yaml`. Режим: `auto` если скил чисто стилевой / response-style, `pending` если скил трогает инструменты или окружение (требует отдельного аудита).
- `[<name>-test-trigger]` — прогнать триггер-фразы из `description` на тестовом буфере: убедиться что активируется на своих фразах И не активируется на 2-3 близких чужих (false-positive check).
Плюс content-таски из самого буфера (если были) — также в `project: claude-skills`, slug-prefix `<name>-`.
- Если N-я таска упала — продолжить остальные, в конце сообщить какие созданы / какие нет.
- Запомнить slug'и созданных импл-тасок для шага 9.
9. **Review-чекпоинт.** Создаётся всегда для skill-промоушена; для domain-промоушена — только если N≥1 импл-тасок; для workshop-meta или N=0 (domain) — skip с пометкой в логе.
- **domain (N≥1):**
- `mcp__projects-meta__tasks_create`:
- `target_project: <target>`
- `slug: <topic>-review`
- `status: blocked`
- `blocker:` `«bootstrap: <topic>-pointers; impl-tasks: <номера #n через запятую>»` — блокеры по номерам (номер = машинный ключ; слаги оставить в скобках для читаемости).
- `description:` шаблон ниже.
- `next_action:` «Дождаться 🟢 у всех blocker-тасок (включая `<topic>-pointers` — без него pointers в `.wiki/CLAUDE.md` не залиты, и review будет читать stub). Прочитать спецификацию (см. путь в description). Для каждой импл-таски: `git show <commit>`, прогнать тесты в её scope'е, сверить с acceptance criteria. Findings → новые follow-up tasks через `mcp__projects-meta__tasks_create`.»
Description-шаблон (domain):
```
Code-review checkpoint для брейнсторма <topic> (промоушен <YYYY-MM-DD>).
**Спецификация:** <путь к промоушенному design-документу — concepts/<topic>.md в target-wiki>.
**Pre-impl bootstrap:** `<topic>-pointers` (заполнил `.wiki/CLAUDE.md` Domain conventions — без него review бы читал stub).
**Импл-таски (review против их acceptance criteria):** <номера #n из шага 9, слаги в скобках>.
**Кто делает:** **не имплементер.** Следующая сессия в этом проекте (другая модель / другой день / другой агент) поднимает таску с чистым контекстом. «Я только что это написал» bias = главный риск.
**Чек-лист ревью:**
- Прочитать спецификацию (acceptance criteria каждой импл-таски).
- `git log --oneline` shipped-коммитов (по slug или scope в commit-message).
- Для каждой импл-таски: прогнать соответствующие тесты, реально проверить что они доходят до своих веток (не coverage-illusion).
- Сверить дизайн-decisions со shipped-кодом (signature, params, error-paths, безопасность).
- Findings — отдельные follow-up tasks (`<topic>-<gap>-fix` или подобное) через `tasks_create`.
**Закрытие:** только когда все findings зафайлены ИЛИ ревьюер подтвердил «нет findings» в close-note.
```
- **skill:**
- `mcp__projects-meta__tasks_create`:
- `target_project: claude-skills`
- `slug: <name>-review`
- `status: blocked`
- `blocker:` `«impl-tasks: <name>-install, <name>-hermes-mapping, <name>-test-trigger[, content-impls если были]»` — номера `#n` из шага 9 (слаги в скобках для читаемости).
- `description:` шаблон ниже.
- `next_action:` «Дождаться 🟢 у baseline-тасок. Прогнать поведенческий smoke-test (см. чек-лист в description). Findings → follow-up tasks через `tasks_create`.»
Description-шаблон (skill):
```
Skill-review checkpoint для <name> (промоушен <YYYY-MM-DD>).
**Импл-таски:** <name>-install, <name>-hermes-mapping, <name>-test-trigger[, content-impls] — номера #n из шага 9.
**Кто делает:** **не имплементер.** Другая сессия / другой день / другой агент. Identity-not-location: ревьюер работает в любой папке, где есть доступ к файлам (см. `.workshop/.wiki/concepts/workshop-architecture.md` §5.1).
**Поведенческий smoke-test (это и есть acceptance):**
- Скил активируется в чистой сессии на каждой триггер-фразе из `description` (русский И английский варианты).
- Скил **не** активируется на 2-3 близких но не своих фразах из соседних доменов (false-positive check).
- Каждый шаг секции `Steps` отрабатывает на тестовом буфере без ошибок.
- `Failure modes` уводят в abort, не в частичный успех с грязным состоянием.
- `What NOT to do` соответствует реальности — нет дыры между правилом и реализацией.
Findings — обычные follow-up tasks (`<name>-<gap>-fix` или подобное) через `tasks_create` в `claude-skills`.
**Закрытие:** только когда все findings зафайлены ИЛИ ревьюер подтвердил «нет findings» в close-note.
**NB по семверу:** `version: 0.1.0` записан промоутером. Дальнейшие инкременты — ответственность владельца `claude-skills/`, **не** этого скила и не ревьюера. Если ревью требует правок — правит владелец, бампит он же.
```
- Если `tasks_create` review-таски упала — сообщить пользователю, **продолжить** к шагу 11 (архивация буфера). Review-таску можно создать вручную позже из `.archive/<date>-<topic>.md`.
- **domain (service channel):** review-umbrella — **сервисная таска**: `mcp__mappa__task_create(project=<target>, slug=<topic>-review, status='blocked', blocker=<номера импл-тасок через запятую>, description=<шаблон domain выше, спека = wiki:NNNN в вики проекта>)` — create = карв-аут (без лиза). Pointers-таска отсутствует (спека в вики).
**Covering-письмо в инбокс цели (оба канала; канон mappa-delegation).** После создания тасок — `inbox_send` получателю-проекту: таска на борде не пингует живую сессию, письмо = пинг + контекст. File channel: `mcp__mappa__inbox_send(project=<target>, from=<своя>, subject='[event: created] <topic> — <N> тасок', body=<перечень: #N slug> )`. Service channel: то же, но `from` = своя папка (или сервисный адрес) и тело ссылается на wiki:NNNN-спеку.
10. **Workshop-wiki summary (обязательно для всех маршрутов):**
`Write` → `.wiki/concepts/<topic>.md` с frontmatter:
- **Что решили** — ключевые решения раундов (не пересказ, а outcomes).
- **Куда промочено** — полный путь: target-wiki / claude-skills / local concepts.
- **Задачи** — перечень slug'ов, созданных в шаге 7.
- **Ссылки** — архив буфера + связанные концепты в workshop-вики + глобальная вики.
Для **workshop-meta**: summary — сокращение полного контента (который уже в `.wiki/concepts/<topic>.md` шага 6); если шаг 6 уже записал туда полный файл — шаг 9 его дополняет секцией «Куда промочено / Задачи» или пропускается (не дублировать).
Затем обновить `index.md` — добавить строку в нужную секцию.
Если `Write` упал → сообщить, **не блокировать** архивацию (summary менее критична чем content-промоушен).
**Только** если шаги 6 и 7 прошли (или прошли с допустимым partial — пользователь подтвердил). Иначе — оставить буфер на месте, чтобы можно было ретраиить.
12. **Лог:** дописать в `.wiki/log.md`:
```
<date> promoted <topic> → <destination> [created N tasks in <proj>]
```
Для skill — `<destination>` = `claude-skills/skills/<name>/SKILL.md (skeleton)`.
13. **Финальный отчёт пользователю:**
- Куда промочено (полный путь).
- Какие таски созданы (id, title, проект).
- Куда уехал исходник.
- **Для skill:** напомнить что нужен второй проход «доведём `<name>`» для дописывания тела каркаса.
1.**Найти буфер в mappa.** `mcp__mappa__entity_search(type='brainstorm',
project=<проект>, q=<topic>)` → в результатах brainstorm:N + **internal id**.
Прочитать полный буфер: `mcp__mappa__entity_get(id=<internal id>)` — тело =
running record (frontmatter + раунды).
Если буфера нет в mappa — создать brainstorm-сущность через
`mcp__mappa__brainstorm_create` (или HTTP `POST /entities` type=brainstorm,
контракт решения 7/#1054). Не изобретать файловые буферы.
2. **Показать summary буфера (≤2 абзаца).**
3. **Спросить target-проект** — куда промоутить контент. По умолчанию — проект,
где буфер живёт (брейншторм ведут там, где тема релевантна). Проверить, что
проект существует в mappa: `mcp__mappa__entity_search` type=project
(или `mcp__mappa__entity_search` с q=<имя проекта>). Если нет — abort с
сообщением.
4. **Если target = skill (пользователь хочет оформить как скил):**
- Спросить `<name>` нового скила (если не указан) — валидный slug
(`[a-z0-9-]+`).
- Валидация (порядок важен): сначала проверить, что `~/projects/skills/`
сам репозиторий существует. Если нет — **abort** с сообщением «клонируй
skills через update-skills или вручную».
- Затем: `~/projects/skills/skills/<name>/` НЕ должна существовать.
Если существует — **abort**с сообщением «скил `<name>` уже существует,
обновляйся обычным маршрутом в `~/projects/skills/`, этот скил не для
апдейтов».
- Двухпроходной каркас: диалог по `description` (триггер-контракт активации:
минимум 2-3 фразы, пары русский/английский; что делает; антипаттерны) →
- Куда промочено: `wiki:NNNN` (спека в вики target).
- Архив: `brainstorm:N` (status=archive, номер стабилен).
- Какие таски созданы (ref, title, проект).
- **Для skill:** напомнить про второй проход «доведём `<name>`».
## Failure modes
- `.brainstorm/<topic>.md` отсутствует → abort.
- `mcp__projects-meta` недоступен → abort до записей.
- Целевой проект (для domain) не найден в `meta_status` → abort.
- `knowledge_ingest` упал → abort до `tasks_create` и `git mv`. Буфер остаётся.
- **Service channel:** create упал (гонка счётчика/переходный период) → **повторить последовательно**, не батчем; при стабильном отказе — abort до архивации.
- **Service channel:** спека уже существует в вики проекта (wiki:NNNN) → не дублировать `wiki_create`, ссылаться на неё.
- **domain:** `tasks_create` для `[<topic>-pointers]` упал → **abort** до content-тасок и до review-таски. Без pointers оставшиеся таски бесполезны (агент будет угадывать). Сообщить пользователю; буфер оставить на месте для retry.
- `tasks_create` упал на N-й content-таске → продолжить остальные. Сообщить partial. **Не делать** `git mv` без подтверждения пользователя.
- `tasks_create` упал на review-таске (шаг 8) → не блокировать; перейти к архивации, сообщить пользователю чтобы создал вручную из `.archive/`.
- **Skill:** `~/projects/claude-skills/` не существует → abort с сообщением «клонируй через update-claude-skills или вручную».
- **Skill:** `~/projects/claude-skills/skills/<name>/` уже существует → abort с сообщением «скил уже существует, обновляйся обычным маршрутом в `claude-skills/`».
- **Skill:** пользователь не подтвердил preview перед записью → abort, состояние не меняется.
- **Skill:** локальный `git commit` в `claude-skills/` упал (например, не настроен user.email) → файл остаётся, сообщить пользователю что коммит нужно сделать руками; **не** делать `git mv` буфера до подтверждения.
- Буфер не найден в 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/<name>/` уже существует → abort.
- **Skill:** пользователь не подтвердил preview → abort, состояние не меняется.
сообщить что коммит нужно сделать руками; промоут буфера не блокируется.
## Side effects
- **Всегда (любой маршрут):** создаёт summary-страницу `.wiki/concepts/<topic>.md` в `.workshop/` + добавляет строку в `index.md`.
- **workshop-meta:** summary IS контент (шаг 6 записывает полное тело; шаг 9 дополняет секцию «задачи/ссылки» или пропускается если уже полный).
- **domain:** создаёт запись в target-wiki через MCP (`mcp__projects-meta__knowledge_ingest`).
- **domain (service channel):** создаёт спека-сущность в вики mappa-проекта (`mcp__mappa__wiki_create`, карв-аут wiki:2660); импл-таски + review-umbrella — сервисные таски (`mcp__mappa__task_create`, карв-аут); covering-письмо в инбокс цели (`inbox_send`). Pointers-таска НЕ создаётся (спека уже в вики).
- **domain:** создаёт также **mandatory pre-impl** таску `[<topic>-pointers]` в target — pre-filled блок текста для `.wiki/CLAUDE.md` Domain conventions (ссылки на global wiki slug + workshop archive trace + local overview.md). Без неё последующий импл-агент попадает в дыру: where_stopped one-liner + пустой Domain conventions stub.
- **skill:** создаёт `~/projects/claude-skills/skills/<name>/SKILL.md` — **только шапка + пустой каркас**. Локальный коммит в `claude-skills/`. **Без** установки, push, или build-hermes — это всё в созданных baseline-тасках.
- Создаёт N тасок в target `.tasks/` через MCP.
- Для domain (N≥1) или skill: создаёт зонтичную review-таску (status=blocked, blocker=impl-slugs; для domain — также включает `<topic>-pointers`) в том же target.
- **Семвер скилов:** при target=skill промоутер записывает `version: 0.1.0` в шапку. Дальнейшие инкременты — ответственность владельца `claude-skills/`, **не** этого скила. При попытке промоушена в существующий скил — abort (см. Failure modes).
пустой 6-секционный каркас) + локальный коммит в `~/projects/skills/`.
**Без** install.sh, push, build-hermes — это в baseline-тасках.
- Создаёт N тасок в target через `mcp__mappa__task_create` (карв-аут).
- Создаёт review-umbrella таску (status=blocked, blocker=impl#).
- Отправляет covering-письмо в инбокс target.
## What NOT to do
- Неписать доменное содержимое в локальный `.wiki/concepts/` (правило #1 из `.workshop/CLAUDE.md`). Summary-страница шага 11 — это trace/навигация, не domain-контент.
- Не пропускать шаг 9 (workshop-wiki summary) — именно так следующая сессия узнаёт что буфер был и куда ушёл.
- Неделать `git mv` буфера до успеха promotion+tasks.
- Не удалять буфер вместо `git mv` — теряется история.
- **Skill:** не пытаться автоматически переформатировать тело буфера в каркас `Steps`/`Failure modes`/etc. — это поведенческий контракт, не косметика. Каркас остаётся пустым; тело дописывается во втором проходе глазами.
- **Skill:** не запускать `install.sh`. Не делать `git push` в `claude-skills/`. Не править `hermes/mapping.yaml`. Не запускать `build-hermes.py`. Это работа baseline-тасок, не промоутера.
- **Skill:** не бампить `version` после первой записи (это работа владельца `claude-skills/`).
- **Skill:** не промоутить в существующий скил (см. Failure modes — abort).
- **Skill:** не пропускать обязательный preview + confirm перед `Write` — действие выходит за пределы мастерской, изменяет соседний репозиторий.
- **Service channel:** не батчить `task_create` (гонка sha-CAS счётчика, инцидент 2026-08-24: 6/7 упали) — только последовательно. Create — карв-аут, лиз не нужен.
- **Service channel:** не плодить pointers-таску, если спека уже в вики проекта (wiki:NNNN) — описание импл-тасок ссылается на неё инлайн.
- **Service channel:** не забывать covering-письмо в инбокс цели — таска на борде не пингует живую сессию.
- **Не использовать файловые каналы** — буферживёт в mappa brainstorm-сущности,
**Immutable.** Read, never edit. The only allowed modification is appending a `> Status:` blockquote when the user explicitly asks for a status audit.
Place raw inputs here — articles, transcripts, PDFs, screenshots — exactly as they came in. The agent reads from `raw/`, writes summaries into `../sources/`, and never modifies raw files.
Place raw inputs here — articles, transcripts, PDFs, screenshots — exactly as they came in. The agent reads from `raw/`, writes summaries into `../summaries/`, and never modifies raw files.
For large or path-sensitive sources that live outside the repo, register them here:
@@ -307,7 +307,7 @@ For large or path-sensitive sources that live outside the repo, register them he
\`\`\`
```
The empty subdirectories (`entities/`, `concepts/`, `packages/`, `sources/`)
The empty subdirectories (`entities/`, `concepts/`, `packages/`, `summaries/`)
description: Use when capturing external content into a markdown-based knowledge base, wiki `raw/` directory, or any pipeline that must preserve the source's full text — for web pages, PDFs, DOCX/PPTX/XLSX, EPUB, CSV/JSON/XML, ZIP archives, images (with OCR/EXIF), audio (with transcription), or YouTube URLs. Also use when WebFetch returned an LLM-summarized version but the raw content is what's needed.
---
@@ -52,7 +52,7 @@ No mount caveats: the CLI is a normal local process. The old Docker `-v` mount t
1. markitdown "https://example.com/foo.pdf" -o .wiki/raw/<slug>.md (kebab-case, Latin only)
2. Inspect the head of the result. If it looks like a sign-in/cookie/consent page, abort — ask the user for an alternative (manual save, paste, authenticated source).
3. Register the new file in .wiki/raw/README.md.
4. Hand off to the wiki ingest workflow (creates sources/<slug>.md summary + entity/concept updates).
4. Hand off to the wiki ingest workflow (creates summaries/<slug>.md summary + entity/concept updates).
```
For a huge (book-length) document, write straight to a file with `-o` and summarize *from the saved file* — do not pipe the whole markdown through working context.
@@ -63,7 +63,7 @@ For a huge (book-length) document, write straight to a file with `-o` and summar
|---|---|---|
| Output is a Google/Microsoft sign-in page in some random language | URI behind auth wall | Ask user to export the content manually (Save as PDF, copy-paste) and put it in `raw/` |
| Output is mostly nav/cookie banner text | Site is JS-rendered or anti-bot | Try the cached or print URL; or ask user for HTML export |
| Output lacks images / diagrams | Markdown is text-only by design | Save the original asset separately under `raw/assets/`; reference it from the `sources/` summary |
| Output lacks images / diagrams | Markdown is text-only by design | Save the original asset separately under `raw/assets/`; reference it from the `summaries/` summary |
| `markitdown: command not found` | CLI not on `PATH` | Confirm with `markitdown --version` (expect `markitdown 0.1.6`); install with `pip install markitdown[all]` if missing |
| Huge output (book-length) | Whole document converted in one call | Use `-o <file>` to save raw, then summarize *from the saved file* — do not hold the entire markdown in working context |
description: Use when working across multiple projects on one or many machines — cross-project task aggregation (`mcp__projects-meta__tasks_*`), shared Gitea-backed wiki query / ingest (`mcp__projects-meta__knowledge_*`), or sync diagnostics (`mcp__projects-meta__meta_status`). Triggers on phrases like "across all projects", "what's on the boards", "check shared wiki", "search projects-wiki", "ingest into shared wiki", "что у меня на досках", "по всем проектам", "общая вики", "cross-project status", or any time the user wants to see / mutate state in another repo than the current cwd. v1.1.0 mandates a Step 0 freshness gate (probe `meta_status`, sync if stale, pull `projects-wiki` before shared-wiki writes) — see SKILL body. Mutation tools require two-step preview → confirm. Skip for the **current** project's tasks/wiki — those live on disk in `.tasks/` / `.wiki/`.
---
@@ -12,7 +12,7 @@ description: Use when working across multiple projects on one or many machines
`projects-meta-mcp` is a local stdio MCP server. Two responsibilities:
1.**Cross-project task aggregation** — parses `.tasks/STATUS.md` from every repo on the user's Gitea, caches them in `~/.cache/projects-mcp/tasks.json`. Read tools (`tasks_aggregate`, `tasks_search`, `tasks_get`) hit the cache. Mutations (`tasks_create`, `tasks_update`, `tasks_close`) commit back to Gitea with sha-based optimistic lock.
2.**Shared knowledge wiki** — single Gitea repo (`projects-wiki`) cloned at `~/projects/projects-wiki/` with content at `~/projects/projects-wiki/.wiki/`, structured as packages / concepts / entities / sources / raw. `knowledge_search` + `knowledge_get` for queries, `knowledge_ingest` + `knowledge_promote` for writes.
2.**Shared knowledge wiki** — single Gitea repo (`projects-wiki`) cloned at `~/projects/projects-wiki/` with content at `~/projects/projects-wiki/.wiki/`, structured as packages / concepts / entities / summaries / raw. `knowledge_search` + `knowledge_get` for queries, `knowledge_ingest` + `knowledge_promote` for writes.
Source of truth: Gitea (`https://git.kzntsv.site`, owner `OpeItcLoc03`). Cache and clone are local convenience.
@@ -140,8 +140,8 @@ Use MCP only for **other** projects, **other** machines, or **shared** wiki cont
| `mcp__projects-meta__knowledge_promote` | `target_project`, `slug`, `body` (+ opt `frontmatter`, `source_project`) | Move `raw/<slug>.md` → `summaries/<slug>.md` with auto `raw_path` link |
`target_project` is **qualified**`<owner>/<repo>` (e.g. `victor/books`, `OpeItcLoc03/skills`), or the literal `agenda` for the cross-project meta-board (resolves via `agenda_tasks_repo` in `auth.toml`). Bare names (`books`) are rejected with a hint to use the qualified form. Cross-cutting design: shared wiki → `concepts/projects-meta-multi-owner`.
@@ -225,7 +225,7 @@ User: "close `[projects-meta-skills]` in skills"
| Acting on a stale `tasks_aggregate` without checking `meta_status` | Step 0 — Freshness gate is mandatory. If `cache_age_minutes` > 10 (or errors > 0), run `node ~/projects/.common/lib/projects-meta-mcp/dist/sync.js` first. |
| Skipping `git -C ~/projects/projects-wiki pull` before `knowledge_ingest` / `knowledge_promote` | sha-based optimistic lock will reject the commit (422) and the failure is opaque. Pull is unconditional for shared-wiki writes — fast-forward is a no-op when current. |
| Treating sync 401/403 as "MCP is fine, the page just doesn't exist yet" | 401/403 means the Gitea token is dead. Stop, tell the user to rotate `gitea_token` in `~/.config/projects-mcp/auth.toml`. Never guess on stale data. |
| Calling `knowledge_ingest` with the wrong `type` | `type` must be one of `entities` / `concepts` / `packages` / `sources` / `raw`. Mis-typed pages land in the wrong section and break `index.md`. |
| Calling `knowledge_ingest` with the wrong `type` | `type` must be one of `entities` / `concepts` / `packages` / `summaries` / `raw`. Mis-typed pages land in the wrong section and break `index.md`. |
| Forgetting `domain="all"` when searching across families | Default `domain` is auto-detected from cwd; use `"all"` if the wiki page lives in a different family. |
| Passing bare project name (`target_project: "books"`) to mutation tools | v2.x rejects bare names. Use qualified `<owner>/<repo>` (e.g. `victor/books`, `OpeItcLoc03/skills`). Literal `agenda` is the only exception (cross-project meta-board). |
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
