КОНСТИТУЦИЯ РАЗРАБОТКИ ПЛАГИНА MAESTRO

Версия 1.4 — 07.11.2026. Принята пользователем (rura). v1.1: добавлена ссылка на SYSTEM_PROMPT.md (ст. 11.1). v1.2: ONTOLOGY.md в цепочку онбординга (ст. 11.1) + правило «онтология в том же коммите» (ст. 8.5). v1.3: ст. 6 приведена в соответствие с рантаймом LM Studio 0.4.26+ (production.js=ESM-лаунчер, импортирует src→dist в рантайме; горячая замена dist без ребандлинга; in-place lms dev --install запрещён; установщик исключает src по .lmsignore) — по итогу релиза-инцидента 06.11.2026. v1.4: ст. 1.5 — сдвиг объекта: объектом управления является оркестрация (любые позиции), её документ объекта — ORCHESTRATION.md; включён в цепочку онбординга (ст. 11.1) — по решению пользователя 07.11.2026. Обязательна для любого агента (модель в чате LM Studio с инструментами maestro, внешний агент с доступом к файлам/shell), выполняющий изменения кода, конфигурации или деплоя плагина maestro.

Сопутствующие документы (в этом же каталоге):

ORCHESTRATION.md — документ объекта управления (оркестрация): позиции, общие слои, свидетельство, правила решений.
ONTOLOGY.md — онтология объекта: структура, процессы, инварианты, напряжения и направления развития.
DEVELOPMENT.md — технический справочник: модель рантайма LM Studio, команды lms, API SDK.
README.md — публичное описание плагина (инструменты, настройки).

Статья 1. Объект и область применения

1.1. Объект: плагин LM Studio maestro (артефакт brdcastro/maestro, rev 81) и его разработочный клон. 1.2. Клон (единое рабочее место разработки): ~/ai-projects/LM_Studio/maestro (owner в manifest: rura, git-репозиторий). 1.3. Активный установленный экземпляр: ~/.lmstudio/extensions/plugins/brdcastro/maestro — он обслуживает чаты LM Studio (и, как правило, самого агента). 1.4. Всё, что не описано настоящей Конституцией, — см. DEVELOPMENT.md; при противоречии Конституция имеет приоритет. 1.5. Объектом управления является оркестрация — деятельность, объектом которой служит деятельность агентов (чат-позиция maestro, headless-позиции Pi, детерминированные скрипты). Настоящая Конституция действует на каждой позиции; документ слоя объекта — ORCHESTRATION.md. Пункты 1.1–1.4 описывают реализацию чат-позиции (maestro) как объект разработки.

Статья 2. Инварианты (нарушение недопустимо)

2.1. Рантайм-контракт. src/index.ts обязан экспортировать main(pluginContext) (шим → dist/index.js). Шим не удаляется и не заменяется на что-либо, ломающее контракт. 2.2. Живой продакшн. Процесс активного экземпляра (node ./.lmstudio/production.js, родитель — LM Studio.app) не убивается и не перезапускается посреди активной сессии — это tool-провайдер чата самого агента. Безопасно: lms dev, lms dev --install, перезапуск LM Studio — но только с предупреждением пользователю. 2.3. Генерация. Файлы .lmstudio/*, install-state.json и содержимое node_modules/ не редактируются вручную (node_modules — только через npm ci / копирование с той же архитектурой). 2.4. Manifest. Поля owner/name/type/runner не меняются вручную. обязан совпадать с (сейчас ). ведёт (опц. ). 2.5. выполняется только при явном разрешении пользователя. 2.6. Активный экземпляр и проверенные бэкапы не удаляются. Сломанное — в карантин: . 2.7. (M5 Max, 128GB, без swap — переполнение крешит систему): перед загрузкой большой модели — и свободная RAM ≥ размер модели + 10GB. KV-кеш dense-модели на длинном контексте — главный потребитель памяти. 2.8. API-токены, passkey, личные данные не коммитятся и не публикуются.

Статья 3. Источники истины и контроль версий

3.1. Источники кода — dist/*.js. Автор плагина публикует только собранный dist (src/ в .lmsignore); TypeScript-исходников нет. Разработка — прямые правки JS. (Полная реконструкция TS-источника — отдельная задача по явному решению пользователя.) 3.2. Git — обязателен. Любое изменение клона фиксируется коммитом. Сообщение: что изменено и зачем. Запрещено оставлять клон в не-коммиченном состоянии дольше одной сессии. 3.3. Клон и активный экземпляр могут расходиться; сличение — diff -rq dist $ACTIVE/dist. Синхронизация — только через релиз (Статья 6). 3.4. База восстановления: ~/lmstudio-plugins/proverennye-iskhodniki/brdcastro__maestro (rev 81, девственно чистый) + история git клона.

Статья 4. Цикл разработки (проверен 05.11.2026)

4.1. export PATH="$HOME/.lmstudio/bin:$PATH" (lms не в PATH по умолчанию). 4.2. Запуск dev-сервера из клона: lms dev --no-notify. В логе должны появиться: [esbuild] build finished, watching for changes... и [Tools Prvdr.] / [PromptPreprocessor] Register with LM Studio. 4.3. Правка dist/ (или src/index.ts) → esbuild hot-reload автоматически → тест. 4.4. Пока dev-сервер активен, в UI LM Studio (Integrations) отключить установленный brdcastro/maestro и использовать dev-плагин — иначе дубли инструментов в промпте и вызовы «старой» версии. 4.5. Завершение: убить dev-процесс (dev-плагин deregister'ится), в UI вернуть установленный экземпляр. 4.6. Definition of Done изменения: сборка esbuild без ошибок; поведение проверено в живом чате (dev-режим); git-коммит сделан; README.md синхронизирован (Статья 8). 4.7. Dev-сервер не оставляется работать «на потом» без ведома пользователя: агент фиксирует PID и лог, сообщает о запуске и останавливает по завершении задачи.

Статья 5. Тестирование

5.1. Минимальный тест изменения инструмента: прямой вызов из чата + проверка результата

проверка error-path (некорректный аргумент → структурированная ошибка с кодом, а не crash провайдера). 5.2. При изменениях toolsProvider.js / loopGuard.js / preprocessor.js дополнительно: проверить loop-guard (3 одинаковых вызова / 2 мин → блокировка) и инжекцию памяти. 5.3. Регрессия полного набора — перед релизом и при структурных изменениях. Отчёт — в workspace (~/.maestro-toolbox/workspace/<имя-теста>/). 5.4. Консоль dev-сервера — источник ошибок запуска: Failed to execute the main function of the plugin = плагин не поднялся; исправлять до какого-либо тестирования.

Статья 6. Релиз в прод (установленный экземпляр)

6.1. Основной способ — горячая замена dist (рантайм 0.4.26+: production.js — лаунчер, в рантайме импортирует src/index.ts → dist; при смене dist пере-бандлинг не нужен), только из чистого git-коммита клона:

Затем: убедиться, что плагин отвечает в чате и новое кодировано в живых артефактах (журнал ~/.maestro-toolbox/logs/tool-calls.jsonl пополняется; новые поля в .plugin_state.json). Полный переустанов (менялись манифест/зависимости): in-place lms dev --install внутри extensions/plugins/… в 0.4.26 запрещён — только из внешней копии; установщик ставит пакет без src/ (уважает .lmsignore) — вернуть src вручную и перезапустить (полная процедура — DEVELOPMENT.md, вариант B). 6.2. Публикация (при явном разрешении): в клоне lms push → артефакт rura/maestro в Hub с новой revision. Последствия (второй артефакт с теми же именами инструментов) агент обязан описать пользователю до push. 6.3. Откат релиза: повтор 6.1 с dist из git-тега/коммита или из proverennye-iskhodniki (base rev 81); src при этом — из клона (в базе отката его нет).

Статья 7. Категории изменений и уровни согласования

Категория	Согласование
Документация (DEVELOPMENT/README-контекст, отчёты)	автономно
Bugfix в `dist/`	автономно + тест (Ст. 5)
Новый инструмент / модуль / бандл-зависимость	автономно + тест + README (Ст. 8)
Изменение конфигураций плагина (`config.js`: новые/переименованные поля, дефолты)	по запросу пользователя
Релиз в прод (Ст. 6.1)	по запросу пользователя
`lms push` (Ст. 6.2)	явное разрешение
Изменения Конституции	явное разрешение
Включение опасных фич (code execution, macOS integration) в активных чатах	явное разрешение

Статья 8. Синхронизация документации

8.1. Изменился набор инструментов или настроек → README.md правится в том же коммите. 8.2. Изменилась архитектура, рантайм-модель, workflow → DEVELOPMENT.md обновляется. 8.3. Существенные факты (code-map, workflow, инциденты) дублируются в память LM Studio (система Remember/Recall) — чтобы следующий агент восстанавливал контекст без чтения всей истории. 8.4. Документация, противоречащая коду, считается багом и устраняется в том же коммите. 8.5. Изменилась структура объекта (подсистема, хук, состояние, инвариант) или решено/добавлено напряжение из ONTOLOGY.md §7.2 → ONTOLOGY.md обновляется в том же коммите (способ обновления — раздел 8 самого документа).

Статья 9. Изменения Конституции

9.1. Изменяется пользователем либо агентом — только с явного разрешения пользователя. 9.2. Каждое изменение: новый номер версии в шапке + запись в сообщении git-коммита.

Статья 10. Действия при инциденте

10.1. Плагин не стартует / чат без инструментов: (1) диагностика — ps/lsof -a -p <pid> -d cwd активного процесса, консоль dev-сервера, lms ps (не переполнена ли машина); (2) восстановление — из git-коммита клона или из proverennye-iskhodniki + Ст. 6.1; (3) сломанное состояние — в карантин (Ст. 2.6) до восстановления; (4) отчёт пользователю: что сломано, как восстановлено, корневая причина. 10.2. Продакшн-сбой не «чинится» прямыми правками активного экземпляра — всегда через клон (git) и Ст. 6.1. 10.3. При признаках OOM (убийство процессов, свопинг-артефакты) — немедленно lms ps, не грузить новые модели, сообщить пользователю (прецедент 04.11.2026).

Статья 11. Протокол онбординга агента

11.1. Перед первым изменением в сессии прочитать: эту Конституцию, ORCHESTRATION.md (объект управления), ONTOLOGY.md (карта объекта: структура, процессы, инварианты, план развития), DEVELOPMENT.md, README.md (в системном промпте чата — SYSTEM_PROMPT.md, сжатый операционный контур этой Конституции; при расхождении приоритет у Конституции); проверить git status (чистота), lms whoami, запущен ли dev-сервер. 11.2. Долгоживущие процессы (dev-сервер, watchers): фиксировать PID и лог, сообщать пользователю, останавливать по завершении (Ст. 4.7). 11.3. При сомнении в последствиях действия (прод, публикация, состояние UI, общие каталоги ~/.lmstudio — их делят LM Studio и Bionic) — спросить пользователя. 11.4. Агент не меняет пользовательские runtime-настройки плагина (значения из 16 полей конфига) и его working directory без запроса.

maestro

maestro

КОНСТИТУЦИЯ РАЗРАБОТКИ ПЛАГИНА MAESTRO

Статья 1. Объект и область применения

Статья 2. Инварианты (нарушение недопустимо)

Статья 3. Источники истины и контроль версий

Статья 4. Цикл разработки (проверен 05.11.2026)

Статья 5. Тестирование

Статья 6. Релиз в прод (установленный экземпляр)

Статья 7. Категории изменений и уровни согласования

Статья 8. Синхронизация документации

Статья 9. Изменения Конституции

Статья 10. Действия при инциденте

Статья 11. Протокол онбординга агента

Приложение A. Быстрая шпаргалка

Приложение B. Карта кода (подробно — в DEVELOPMENT.md)

КОНСТИТУЦИЯ РАЗРАБОТКИ ПЛАГИНА MAESTRO

Статья 1. Объект и область применения

Статья 2. Инварианты (нарушение недопустимо)

Статья 3. Источники истины и контроль версий

Статья 4. Цикл разработки (проверен 05.11.2026)

Статья 5. Тестирование

Статья 6. Релиз в прод (установленный экземпляр)

Статья 7. Категории изменений и уровни согласования

Статья 8. Синхронизация документации

Статья 9. Изменения Конституции

Статья 10. Действия при инциденте

Статья 11. Протокол онбординга агента

Приложение A. Быстрая шпаргалка

Приложение B. Карта кода (подробно — в DEVELOPMENT.md)