exchanger-themes/AGENTS.md

Инструкции для ИИ-агентов

Этот файл — единственный авторитетный набор агентских правил для проекта ExchangerThemeDlcBuilder. Перед любым изменением прочитайте его полностью.

Назначение и границы проекта

• Проект создаёт, проверяет, показывает и собирает внешние PCK-темы Exchanger.
• Рабочая область агента по умолчанию ограничена этой папкой. Соседний проект Exchanger можно читать для сверки host-контракта, но нельзя менять без отдельного явного поручения пользователя.
• Код бизнес-логики, оплаты, COM-контроллера и настроек автомата принадлежит Exchanger. Темы считаются доверенными и могут содержать собственную GDScript-логику визуальных и вспомогательных runtime-компонентов, но прямые зависимости от внутренних узлов host нужно документировать.
• Перед изменениями прочитайте README.md, docs/PROJECT_CONTEXT.md и профильный документ из docs/README.md. Для сцен обязательно прочитайте docs/BINDING_CONTRACT.md.

Обязательная долговременная память

• MCP-сервер agentmemory используется постоянно. Канонический project id: exchanger-theme-dlc-builder.
• Первое действие с инструментами в каждой задаче — memory_recall или memory_smart_search по затрагиваемой подсистеме. Повторите поиск перед работой с незнакомой частью проекта или при противоречии памяти и файлов.
• После каждого устойчивого открытия, решения, изменения архитектуры/контракта/структуры, найденной ошибки и законченного блока QA сохраняйте атомарную запись через memory_save.
• Записывайте назначение файлов, связи, команды и фактические результаты проверок, а не сырые логи. Репозиторий и свежий запуск имеют приоритет над устаревшей памятью.
• Перед финальным ответом обязательно сохраните итоговое состояние, изменённые файлы, проверки и незакрытые вопросы. При делегировании передайте подагенту эти же требования.

Godot и инструменты

• Ziva-Godot категорически запрещён без исключений. Нельзя использовать сервер, tools, plugins, skills, ресурсы или документацию с этим именем даже для чтения и диагностики.
• Для Godot Editor разрешён только MCP-сервер godot-ai. Перед работой со сценами проверьте сессию, сведения о проекте, открытую иерархию и журнал. Если godot-ai недоступен, используйте безопасные shell-команды и файловое редактирование, но не Ziva-Godot.
• Текстовые файлы меняйте точечно через apply_patch. Не перезаписывайте пользовательские файлы shell-трюками и не запускайте форматирование всего проекта без необходимости.
• Сохраняйте чужие и незавершённые изменения. Перед удалением, переносом или массовой генерацией точно проверьте цель. themes/<id>/package/ является единственным исходником и не должен очищаться неявно. Постоянного корневого staging-каталога нет.

Неподвижные правила темы

• Целевой формат preview: 720×1280, портретная ориентация.
• Внутри тематических сцен разрешены обычные возможности Godot: GDScript, сигналы, анимации, шейдеры, частицы, аудио, видео и процедурные визуальные эффекты.
• Production-содержимое — только themes/<id>/package/. source/, references и preview tooling не должны попадать в PCK. Канонический namespace res://exchanger_theme_dlc/ создаётся только внутри изолированного временного build-workspace и готового PCK.
• Все девять production-сцен имеют канонические пути/имена/root metadata из manifest v2.
• Production-сцены и их вложенные сцены могут содержать доверенный GDScript и любые необходимые Godot-узлы, включая Timer, AudioStreamPlayer* и HTTPRequest. Скрипты темы исполняются и в preview, и после инстанцирования PCK в Exchanger.
• Каждый обязательный элемент содержит уникальный exchanger_binding_id, точный тип и ID из contracts/screen_bindings.v2.json. Каталог v2 содержит 9 экранов и 481 биндинг; его package-копия должна совпадать байт-в-байт.
• При любом добавлении, удалении, переименовании или изменении binding ID, пути, типа, fallback, структуры binding-каталога либо правил разрешения биндингов обязательно в рамках той же задачи обновите E:\Danil\Projects\Godot\ExchangerThemeDlcBuilder\docs\BINDING_CONTRACT.md. Изменение биндингов не считается завершённым, пока документ не соответствует фактическому контракту и не проверен вместе с contracts/screen_bindings.v2.json и host-контрактом Exchanger.
• Production-сцена владеет каждым визуальным узлом, включая состояния Home, кнопки готовых сумм и фиксированные строки настроек. Exchanger не должен добавлять, удалять, переносить или стилизовать Control внутри внешнего ThemeView: host только находит существующие узлы, подключает сигналы и обновляет значения/видимость/доступность.
• SETTINGS содержит заранее созданные скрытые панели текстовой и цифровой экранных клавиатур. Host может менять подписи/видимость/доступность клавиш и подключать сигналы, но не создаёт и не перестраивает их визуальное дерево.
• SETTINGS также содержит theme-owned раздел «Сервис» и скрытый диалог учёта жетонов. Заголовки обоих хопперов имеют отдельные binding-id для точных остатков. Host меняет только остатки, тексты, видимость/доступность и подписывает кнопки; создавать или перестраивать эти элементы в runtime запрещено.
• Видимый русский текст должен быть естественным и понятным владельцу автомата. Используйте «промо» и «промо-ролик», не «реклама». Внутренние English identifiers не переименовывайте.

Рабочий цикл

1. Восстановите контекст из agentmemory и документов.
2. Активируйте нужную тему: ./activate-theme.ps1 -ThemeId <id>.
3. Меняйте themes/<id>/package/ напрямую; preview загружает эти же файлы без промежуточной копии.
4. Проверяйте binding overlay и все девять вкладок preview в 720×1280; сохраняйте статический фон и центрирование содержимого.
5. Выполните ./tools/Test-PackagedBindingContract.ps1, затем ./test-theme.ps1 -ThemeId <id>.
6. Соберите ./build-theme.ps1 -ThemeId <id>. Установка в пользовательский каталог Exchanger — отдельное внешнее изменение и выполняется только когда оно входит в поручение.
7. Через godot-ai проверьте preview и runtime-журнал. При изменении host-контракта отдельно проверьте PCK в Exchanger.
8. Обновите относящиеся к изменению docs и agentmemory.

Делегирование и критерии готовности

• Делегируйте только независимые, чётко ограниченные задачи. Укажите рабочую папку, запрет Ziva-Godot, обязательную память, допустимые файлы и проверки. Не позволяйте нескольким агентам одновременно править одни и те же файлы.
• Задача готова, когда исходники находятся в правильной теме, contract check и validator проходят, preview smoke и визуальная проверка девяти экранов не выявляют ошибок, production PCK не содержит builder tooling/референсов, документация соответствует фактам, а результат сохранён в памяти.