| 1 | # Playbook: мультипроектный workspace и рациональный контекст (v1) |
| 2 | |
| 3 | **Назначение:** чтобы агент не смешивал репозитории и не расходовал контекст на лишнее при работе в домашнем workspace с множеством `.sln`, MCP-серверов и карточек в каноне. |
| 4 | |
| 5 | **Среда-независимость:** протокол живёт в `knowledge/`; применим в любой среде с доступом к канону (MCP agent-notes, клон репо, экспорт). Не требует Cursor rules. |
| 6 | |
| 7 | **Связь:** |
| 8 | - **IOP (манифест)** и **экосистема Cascade (use case)** — [IOP-манифест](https://github.com/AI-Guiders/cascade-ide/blob/develop/docs/iop-manifest-v1.md) (`docs/iop-manifest-v1.md` в cascade-ide): дисциплина отдельно от гайда по KB (SHOWCASE). |
| 9 | - `knowledge/worlds/agent-orchestration/playbook-clarification-general-query-v1.md` — если запрос размыт и не ясен даже **какой** проект затронут. |
| 10 | - `knowledge/worlds/agent-orchestration/playbook-captain-parallel-agents-v1.md` — параллельные субагенты (Task), капитан/воркер, тяжёлая разведка по репо. |
| 11 | - `knowledge/agent-memory-and-operating-principles-v1.md` — route_context, нечёткий поиск, один шаг до финала. |
| 12 | - Хаб workspace: `knowledge/work/projects/door-to-singularity/door-to-singularity/README.md`. |
| 13 | - Реестр решений: `knowledge/work/projects/door-to-singularity/solutions-registry.md`. |
| 14 | - **Жизненный цикл `scope` (создание, где хранить, публикация):** §6c ниже. |
| 15 | |
| 16 | --- |
| 17 | |
| 18 | ## 1. Триггеры (когда явно открывать этот плейбук) |
| 19 | |
| 20 | - Пользователь или задача затрагивают **несколько** каталогов/`Financial/software/open/*` без явного «только этот репо». |
| 21 | - Вопросы вида: «куда смотреть», «что за проекты», «не путай X и Y», «какой контекст грузить». |
| 22 | - Риск **перечислить** все MCP или тащить в ответ несвязанные репо. |
| 23 | |
| 24 | --- |
| 25 | |
| 26 | ## 2. Первичный якорь: один `project-id` (или явное «нет продукта») |
| 27 | |
| 28 | **Перед** длинным чтением файлов: |
| 29 | |
| 30 | 1. Определить **primary** трек: стабильный **`project-id`** из дерева `knowledge/work/projects/door-to-singularity/<project-id>/` **или** явная пометка «задача уровня workspace / только реестр / только идеи». |
| 31 | 2. Если primary неясен — **один** уточняющий вопрос или переформулировка («понимаю так: сейчас речь про …»), совместно с `route_context` по сырому запросу (см. clarification playbook). |
| 32 | 3. **Не** подмешивать описания других продуктов, если нет зависимости (интеграция, общий протокол, общий submodule). |
| 33 | |
| 34 | --- |
| 35 | |
| 36 | ## 3. Порядок навигации по канону (узко → широко) |
| 37 | |
| 38 | | Шаг | Что открыть | Зачем | |
| 39 | |-----|-------------|--------| |
| 40 | | A | `door-to-singularity/door-to-singularity/README.md` | Таблица: какие `project-id` заведены как карточки. | |
| 41 | | B | `door-to-singularity/<project-id>/README.md` | Длинный контур, backlog, связи — **если** карточка есть. | |
| 42 | | C | `solutions-registry.md` | Список `.sln`/`.slnx` и строка «канон — или нет». | |
| 43 | | D | README в корне целевого репо в workspace | Локальная сборка, команды, детали кода. | |
| 44 | |
| 45 | **Правило:** не начинать с перечисления всех строк реестра в ответе пользователю; достаточно **текущего** primary и при необходимости одной ссылки «полный список — в solutions-registry». |
| 46 | |
| 47 | --- |
| 48 | |
| 49 | ## 4. Что не считать отдельным «миром» без запроса |
| 50 | |
| 51 | - Репозитории, у которых в реестре в колонке канона стоит **«—»**, **не** тянуть в повествование, пока задача явно их не касается. |
| 52 | - **Кластеры** (например, несколько MCP + shared-библиотека): трактовать как **одну** тему до появления отдельной карточки в каноне; не распылять внимание на N почти одинаковых описаний. |
| 53 | |
| 54 | --- |
| 55 | |
| 56 | ## 5. Hot-context vs длинный KB |
| 57 | |
| 58 | - **Hot / route_context:** только то, что нужно для **текущего** шага и primary `project-id`. |
| 59 | - **Полные README карточек и kb:** когда сменили primary, появился блокер по архитектуре/контракту между репо, или пользователь запросил глубину. |
| 60 | |
| 61 | Не дублировать длинные блоки из канона в ответе целиком — **указатель + выжимка**. |
| 62 | |
| 63 | --- |
| 64 | |
| 65 | ## 6. Явные формулировки для пользователя (по желанию) |
| 66 | |
| 67 | Короткие фразы улучшают сходимость: «сейчас primary: `cascade-ide`»; «остальные MCP в реестре не трогаю, если не скажешь». |
| 68 | |
| 69 | **Маркеры в чате (как WORK/HUMAN):** см. секцию **`project-switch-protocol-v1`** в `agent-notes.md` — `[PRIMARY:<project-id>]`, `[SCOPE:door-to-singularity|portal|harvester|imc|mixed]`; дефолт из `workspace-scope-map-v1`, явный маркер в сообщении важнее. Для scope допустимы алиасы **`DTS`** и legacy **`current-projects`** → `door-to-singularity`; **`PTL`** → `portal`; **`HRV`** → `harvester`. **`EDWH`** — только алиас **`[PRIMARY:…]`** → `edw-harvester`, не scope (`project-ids-quickref-v1.md`). |
| 70 | |
| 71 | **Алиасы `project-id`:** необязательные сокращения (`CIDE`, `AFL`, …) — таблица «Алиасы → канон» в `knowledge/work/projects/door-to-singularity/door-to-singularity/project-ids-quickref-v1.md`. Агент **нормализует** алиас к канону перед выбором карточки и путей; в долговечные записи в `knowledge/` писать только канонический id. |
| 72 | |
| 73 | --- |
| 74 | |
| 75 | ## 6b. Проактивные заметки агента (куда писать без явного запроса) |
| 76 | |
| 77 | **Разрешено:** дополнять `agent-notes` (`append_agent_notes`) и точечно `knowledge/` (секции в карточках), когда это снимает повторяемую путаницу, фиксирует договорённость или экономит следующий сеанс — в духе микро-улучшений из `agent-memory-and-operating-principles-v1`. |
| 78 | |
| 79 | **Выбор карточки / `project-id`:** |
| 80 | 1. Маркеры в сообщении: `[PRIMARY:…]`, `[SCOPE:…]` (важнее дефолта из `workspace-scope-map-v1`). |
| 81 | 2. Иначе `route_context` / `read_hot_context` и блок `active-scope` в заметках. |
| 82 | 3. Иначе хаб `door-to-singularity/door-to-singularity/README.md` — таблица карточек и строка primary. |
| 83 | 4. Если всё ещё неясно — **одна** короткая пометка в начале блока («предполагаю primary: …») **или** один уточняющий вопрос; не молча класть долгоживущие факты в чужую карточку. |
| 84 | |
| 85 | **Куда класть по типу контента:** |
| 86 | - разовая операционная пометка — `append_agent_notes` или узкая секция в `agent-notes`; |
| 87 | - устойчивый факт про продукт — `knowledge/work/projects/door-to-singularity/<project-id>/` (README или отдельный kb-файл в той же карточке). |
| 88 | |
| 89 | Стабильный Primary на хабе упрощает дефолт; смена secondary-проектов не ломает правило: новая тема — проверка таблицы / маркер / один вопрос. |
| 90 | |
| 91 | --- |
| 92 | |
| 93 | ## 6c. Workspace `scope`: зачем, когда заводить новый, где хранить |
| 94 | |
| 95 | **`scope`** (строка **`active_scope`** / маркер **`[SCOPE:…]`**) — это **имя среза** оперативной памяти L1 для **отдельного корня** или семейства репозиториев на машине: чтобы MCP и агент подставляли правильный hot-context и не смешивали, например, домашний монорепо с отдельным корнем портала. Это **не** замена **`project-id`**: `SCOPE` — «в какой вселенной воркспейса», `PRIMARY` — «какой продукт в фокусе». |
| 96 | |
| 97 | ### Когда заводить **новый** scope (редко) |
| 98 | |
| 99 | - Появился **стабильный** второй (третий…) **корень** workspace или отдельная «линия жизни» репозиториев, которую **нельзя** честно отнести к уже существующему slice без путаницы. |
| 100 | - Не плодить scope «на каждый чих»: если достаточно нового **`project-id`** внутри уже существующего `work/projects/<scope>/`, новый slice не нужен. |
| 101 | |
| 102 | ### Где фиксировать (полный канон) |
| 103 | |
| 104 | 1. **Таблица путей → slice** — в hot **`agent-notes.md`**, секция **`workspace-scope-map-v1`** (у автора канона она должна быть **ниже первого `<!-- public-cut -->`**, чтобы **пути к дискам не попадали в kb-public**). Формат строк: один корень workspace на строку, `=>` и каноническое имя slice. |
| 105 | 2. **Дерево карточек** — каталог **`knowledge/work/projects/<scope>/`** и строка в таблице **`knowledge/work/projects/README.md`** (см. соглашение по колонкам «Путь | Scope | Назначение»). |
| 106 | 3. **Нормализация алиасов slice** в MCP (если используешь agent-notes-mcp) — в коде сервера: новый алиас → тот же канонический slice, что и в протоколе в **`agent-notes.md`** (**`project-switch-protocol-v1`**). |
| 107 | 4. **Краткий указатель в hot** — секции **`scope-*`** в `agent-notes.md`: одна-две строки + ссылка на `work/projects/<scope>/…`, без дублирования длинных путей в нескольких местах. |
| 108 | 5. **Проект-специфичные шаблоны** (runbook-каркасы, capture, чеклисты релиза — только этот трек) — опционально **`work/projects/<scope>/<project-id>/templates/`**. Общие каркасы KB — **`knowledge/templates/`** (см. `templates/work/README.md`); экземпляры и живые runbook’и — в дереве **`work/projects/…`**, не в корне `templates/`. |
| 109 | |
| 110 | ### Публикация |
| 111 | |
| 112 | - **`knowledge/work/`** в kb-public **не входит** (`public-kb.ignore`). Карта путей в hot **под public-cut** — тоже не входит. Внешнему читателю достаточно **механики** из **`knowledge/kb-one-pager-structure-and-protocols-v1.md`** и этого §6c без твоих путей. Архитектурное решение целиком: **`knowledge/adr/008-workspace-scope-map-hot-mcp-and-public-cut.md`**. |
| 113 | |
| 114 | --- |
| 115 | |
| 116 | ## 7. Версия |
| 117 | |
| 118 | v1.4. 2026-05-19. **Обновление 2026-05-19:** §6c п.5 — `work/projects/…/<project-id>/templates/` для трек-специфичных каркасов. |
| 119 | v1.3. 2026-05-12. **Обновление 2026-05-12:** §6c — жизненный цикл workspace `scope`, карта путей под public-cut в `agent-notes.md`. Предыдущее: v1.2. 2026-04-11. Источник: практика workspace PersonalCursorFolder + соглашение о scope `door-to-singularity` (бывш. `current-projects`). Обновление 2026-04: ссылка на `project-switch-protocol-v1`. Обновление 2026-04-02: §6b — проактивные заметки и маршрутизация в карточки. **Обновление 2026-04-11:** §6 — алиасы `project-id` и нормализация к канону (`project-ids-quickref-v1.md`). |
| 120 | |