План модернізації застосунку

# Мета

Спрямувати застосунок до чистішого, швидшого й легшого в супроводі продукту без порушення поточних робочих процесів або приховування ризику в широких рефакторингах. Робота має потрапляти в невеликі, придатні до рев’ю частини з доказами для кожної зміненої поверхні.

# Принципи

• Зберігайте поточну архітектуру, якщо межа не доведено спричиняє зайві зміни, витрати продуктивності або видимі користувачам помилки.
• Надавайте перевагу найменшому правильному патчу для кожної проблеми, потім повторюйте.
• Відокремлюйте обов’язкові виправлення від необов’язкового полірування, щоб супровідники могли приймати роботу з високою цінністю без очікування суб’єктивних рішень.
• Підтримуйте поведінку, звернену до plugin, задокументованою та зворотно сумісною.
• Перевіряйте випущену поведінку, контракти залежностей і тести, перш ніж стверджувати, що регресію виправлено.
• Спершу покращуйте головний шлях користувача: онбординг, автентифікацію, чат, налаштування провайдера, керування plugin і діагностику.

# Фаза 1: Базовий аудит

Проведіть інвентаризацію поточного застосунку до внесення змін.

• Визначте головні робочі процеси користувачів і поверхні коду, які ними володіють.
• Перелічіть мертві можливості, дубльовані налаштування, неясні стани помилок і дорогі шляхи рендерингу.
• Зафіксуйте поточні команди валідації для кожної поверхні.
• Позначте проблеми як обов’язкові, рекомендовані або необов’язкові.
• Задокументуйте відомі блокери, що потребують рев’ю власника, особливо зміни API, безпеки, релізу та контракту plugin.

Критерій готовності:

• Один список проблем із посиланнями на файли від кореня репозиторію.
• Кожна проблема має серйозність, поверхню-власника, очікуваний вплив на користувача та запропонований шлях валідації.
• Спекулятивні пункти очищення не змішані з обов’язковими виправленнями.

# Фаза 2: Очищення продукту та UX

Пріоритизуйте видимі робочі процеси й усуньте плутанину.

• Уточніть текст онбордингу та порожні стани навколо автентифікації моделі, статусу Gateway і налаштування plugin.
• Видаліть або вимкніть мертві можливості там, де дія неможлива.
• Тримайте важливі дії видимими на різних адаптивних ширинах замість приховування їх за крихкими припущеннями макета.
• Консолідуйте повторювану мову статусів, щоб помилки мали одне джерело істини.
• Додайте поступове розкриття для розширених налаштувань, зберігаючи швидким основне налаштування.

Рекомендована валідація:

• Ручний успішний шлях для першого запуску та запуску наявного користувача.
• Сфокусовані тести для будь-якої логіки маршрутизації, збереження конфігурації або виведення статусу.
• Знімки екрана браузера для змінених адаптивних поверхонь.

# Фаза 3: Посилення архітектури фронтенду

Покращуйте супроводжуваність без широкого переписування.

• Перенесіть повторювані перетворення стану UI у вузькі типізовані допоміжні функції.
• Розділяйте відповідальності за отримання даних, збереження та представлення.
• Надавайте перевагу наявним хукам, сховищам і патернам компонентів над новими абстракціями.
• Розділяйте надто великі компоненти лише тоді, коли це зменшує зв’язаність або прояснює тести.
• Уникайте запровадження широкого глобального стану для локальних взаємодій панелі.

Обов’язкові обмеження:

• Не змінюйте публічну поведінку як побічний ефект розділення файлів.
• Зберігайте поведінку доступності для меню, діалогів, вкладок і клавіатурної навігації.
• Перевірте, що стани завантаження, порожні, помилкові та оптимістичні стани досі рендеряться.

# Фаза 4: Продуктивність і надійність

Спрямовуйтеся на виміряний біль, а не на широкі теоретичні оптимізації.

• Виміряйте витрати запуску, переходів між маршрутами, великих списків і транскриптів чату.
• Замініть повторювані дорогі похідні дані мемоізованими селекторами або кешованими допоміжними функціями там, де профілювання доводить цінність.
• Зменште зайві мережеві або файлові сканування на гарячих шляхах.
• Зберігайте детермінований порядок для prompt, реєстру, файлу, plugin і мережевих вхідних даних перед побудовою payload моделі.
• Додайте легкі регресійні тести для гарячих допоміжних функцій і меж контрактів.

Критерій готовності:

• Кожна зміна продуктивності фіксує базовий рівень, очікуваний вплив, фактичний вплив і залишковий розрив.
• Жоден патч продуктивності не потрапляє лише на інтуїції, коли доступне дешеве вимірювання.

# Фаза 5: Посилення типів, контрактів і тестів

Підвищуйте коректність у точках меж, від яких залежать користувачі та автори plugin.

• Замініть вільні runtime-рядки дискримінованими union або закритими списками кодів.
• Валідуйте зовнішні вхідні дані наявними schema helpers або zod.
• Додайте контрактні тести навколо маніфестів plugin, каталогів провайдерів, повідомлень протоколу Gateway і поведінки міграції конфігурації.
• Тримайте шляхи сумісності в doctor або repair flows замість прихованих міграцій під час запуску.
• Уникайте тестового зв’язування з внутрішніми деталями plugin; використовуйте SDK facade і задокументовані barrels.

Рекомендована валідація:

• pnpm check:changed
• Цільові тести для кожної зміненої межі.
• pnpm build, коли змінюються lazy boundaries, пакування або опубліковані поверхні.

# Фаза 6: Документація та готовність до релізу

Тримайте користувацьку документацію узгодженою з поведінкою.

• Оновлюйте документацію разом зі змінами поведінки, API, конфігурації, онбордингу або plugin.
• Додавайте записи changelog лише для видимих користувачам змін.
• Тримайте термінологію plugin користувацькою; використовуйте внутрішні назви пакетів лише там, де це потрібно для контриб’юторів.
• Підтвердіть, що інструкції з релізу та встановлення досі відповідають поточній командній поверхні.

Критерій готовності:

• Релевантна документація оновлена в тій самій гілці, що й зміни поведінки.
• Перевірки згенерованої документації або drift API проходять, коли їх зачеплено.
• Передача роботи називає будь-яку пропущену валідацію та причину пропуску.

# Рекомендований перший зріз

Почніть зі scoped Control UI та проходу онбордингу:

• Проведіть аудит першого налаштування, готовності автентифікації провайдера, статусу Gateway і поверхонь налаштування plugin.
• Видаліть мертві дії та уточніть стани відмов.
• Додайте або оновіть сфокусовані тести для виведення статусу та збереження конфігурації.
• Запустіть pnpm check:changed.

Це дає високу цінність для користувача з обмеженим архітектурним ризиком.

# Оновлення фронтенд-skill

Використовуйте цей розділ, щоб оновити frontend-focused SKILL.md, наданий із завданням модернізації. Якщо приймаєте цю настанову як repo-local OpenClaw skill, спершу створіть .agents/skills/openclaw-frontend/SKILL.md, збережіть frontmatter, що належить цьому цільовому skill, потім додайте або замініть body guidance таким вмістом.

# Frontend Delivery Standards

Use this skill when implementing or reviewing user-facing React, Next.js,
desktop webview, or app UI work.

## Operating rules

- Start from the existing product workflow and code conventions.
- Prefer the smallest correct patch that improves the current user path.
- Separate required fixes from optional polish in the handoff.
- Do not build marketing pages when the request is for an application surface.
- Keep actions visible and usable across supported viewport sizes.
- Remove dead affordances instead of leaving controls that cannot act.
- Preserve loading, empty, error, success, and permission states.
- Use existing design-system components, hooks, stores, and icons before adding
  new primitives.

## Implementation checklist

1. Identify the primary user task and the component or route that owns it.
2. Read the local component patterns before editing.
3. Patch the narrowest surface that solves the issue.
4. Add responsive constraints for fixed-format controls, toolbars, grids, and
   counters so text and hover states cannot resize the layout unexpectedly.
5. Keep data loading, state derivation, and rendering responsibilities clear.
6. Add tests when logic, persistence, routing, permissions, or shared helpers
   change.
7. Verify the main happy path and the most relevant edge case.

## Visual quality gates

- Text must fit inside its container on mobile and desktop.
- Toolbars may wrap, but controls must remain reachable.
- Buttons should use familiar icons when the icon is clearer than text.
- Cards should be used for repeated items, modals, and framed tools, not for
  every page section.
- Avoid one-note color palettes and decorative backgrounds that compete with
  operational content.
- Dense product surfaces should optimize for scanning, comparison, and repeated
  use.

## Handoff format

Report:

- What changed.
- What user behavior changed.
- Required validation that passed.
- Any validation skipped and the concrete reason.
- Optional follow-up work, clearly separated from required fixes.