verstak-docs/AGENTS.md

AGENTS.md - Verstak Platform

Руководство для coding agents, работающих над Верстаком.

Язык общения с пользователем: русский. Названия API, файлов, команд, commit messages и технических сущностей можно оставлять на английском.

1. Назначение проекта

Верстак - local-first рабочая платформа вокруг дел. Дело собирает заметки, файлы, документы, ссылки, действия, журнал, активность, браузерные материалы и секреты в одном локальном vault.

Новая архитектурная цель: Верстак не монолитное приложение, а платформа с динамическими плагинами.

2. Главные инварианты

• Core не содержит notes/files/editor/activity/journal/browser inbox как обязательные внутренние фичи.
• Пользовательские функции реализуются как динамические плагины.
• Официальные плагины работают через тот же plugin runtime, что и сторонние.
• Плагины зависят от capabilities, а не от конкретных plugin IDs, если им нужна способность.
• Отсутствие optional capability не ошибка; UI action просто не появляется или плагин работает в degraded mode.
• Выключение плагина не удаляет пользовательские данные.
• Vault остается local-first и человекочитаемым.
• Sync server, browser extension и official plugins должны быть выделяемыми репозиториями.
• Секреты не хранятся как plain text notes.

3. Архитектурные документы

Перед работой прочитать:

• verstak-platform-docs/01_Product_Vision.md
• verstak-platform-docs/02_Platform_Architecture.md
• verstak-platform-docs/04_Plugin_System.md
• verstak-platform-docs/05_Official_Plugins.md
• verstak-platform-docs/06_Migration_Strategy.md

Если код противоречит документам, не молча подгонять документы под код. Сначала понять, это старый монолитный долг или осознанное новое решение.

4. Plugin Rules

Manifest обязателен. Плагин должен объявлять:

• id;
• name;
• version;
• apiVersion;
• provides;
• requires;
• optionalRequires;
• permissions;
• frontend/backend entry, если есть;
• contributes, если есть UI/actions/settings.

Нельзя:

• импортировать другой плагин напрямую;
• вызывать приватные backend methods другого плагина;
• читать чужой storage namespace без разрешения;
• создавать actions, если нет нужной capability;
• ронять приложение при ошибке плагина.

5. Plugin Manager

Plugin Manager UI - обязательный core-модуль.

Он должен показывать:

• installed plugins;
• enable/disable;
• status: loaded, disabled, failed, incompatible, degraded;
• version/apiVersion;
• source: official/local/third-party;
• provided capabilities;
• required/optional capabilities;
• permissions;
• settings button, если плагин предоставляет settings panel;
• diagnostics/error text.

6. Note/File Rules

Для notes:

• canonical folder: Notes/;
• Overview note: Notes/Overview.md;
• title и filename должны быть синхронизированы;
• filename строится из title как человекочитаемая безопасная проекция;
• при конфликте имени операция не должна молча добавлять _2; нужен conflict dialog/suggestion.

Для files:

• file plugin не должен жестко зависеть от markdown editor;
• edit/preview actions появляются только при наличии соответствующих capabilities;
• opening external app остается fallback.

7. Work Style

После каждого этапа:

• build/check;
• targeted tests;
• ручная проверка ключевого сценария, если есть UI;
• self-review на забытые imports, dead code, orphaned functions, old monolith paths;
• обновить документацию, если изменился контракт.

Не принимать отчет "сделано", пока не проверено:

• приложение собирается;
• старые сценарии не сломаны;
• plugin enable/disable не оставляет мусорный UI;
• optional capabilities реально optional;
• failed plugin не роняет shell.

8. Запрет на монолитный откат

Если задача просит добавить новую пользовательскую функцию, сначала определить:

• это core platform feature?
• это official plugin?
• это capability?
• это contribution point?

Если функция относится к заметкам, файлам, редакторам, просмотру, activity, journal, browser inbox, search, secrets, import/export - по умолчанию это плагин, а не core.