---
name: workflow-misc
description: Воркфлоу для задач, не попадающих в фича/фикс/план/дебаг — документация, конфиги, зависимости, рефакторинг, настройка окружения. Триггеры: пользователь просит «обнови зависимости», «настрой линтер», «добавь пакет», «отрефактори», «обнови документацию», «почисти», «настрой CI».
---

# Прочее — Воркфлоу вспомогательных задач

Вспомогательная задача проходит 4 шага:
1. Контекст + риск → понять что нужно, классифицировать по риску
2. Исследование → проверить best practices (только для среднего и высокого риска)
3. Выполнение → сделать изменение (высокий риск — после подтверждения)
4. Сдача → проверить и сообщить результат

## Шаг 1: Контекст + классификация по риску

Определить тип задачи и уровень риска:

**🟢 Низкий риск (делать сразу, без подтверждения):**
- Обновление README, комментариев, документации
- Удаление неиспользуемых файлов
- Косметические правки конфигов (форматирование, сортировка)
- Добавление минорной dev-зависимости (prettier plugin, типы)

**🟡 Средний риск (исследование + сообщить план):**
- Добавление нового пакета в production-зависимости
- Минорное обновление зависимостей
- Настройка линтера, форматтера, pre-commit хуков
- Изменение скриптов в package.json

**🔴 Высокий риск (исследование + подтверждение пользователя):**
- Мажорное обновление фреймворка или ключевой зависимости
- Рефакторинг (любой)
- Настройка / изменение CI/CD пайплайна
- Миграция конфигурации на новый формат
- Изменение структуры проекта

Оценить влияние:
```
Задача: [что нужно сделать]
Риск: 🟢 / 🟡 / 🔴
Затронутые файлы: [список]
Что может сломаться: [если 🟡 или 🔴]
```

**🔴 Высокий риск → показать план и ждать подтверждения пользователя до начала работы.**

## Шаг 2: Исследование (🟡 и 🔴)

Для 🟢 — пропустить, сразу к выполнению.

**Когда нужно исследование:**
- Добавление нового пакета → проверить альтернативы, размер, активность, совместимость
- Обновление мажорной версии → прочитать CHANGELOG, найти breaking changes
- Настройка CI/CD → проверить документацию провайдера
- Миграция конфига → проверить новый формат

```
Найдено: [что выяснил]
Рекомендация: [что предлагаю и почему]
```

## Шаг 3: Выполнение

### Документация

- Обновлять существующее, не создавать дубликаты
- Краткость важнее полноты
- Формат должен соответствовать остальной документации проекта

### Зависимости

```bash
# Перед добавлением — проверить что похожего нет в дереве
npm ls [пакет]

# Добавление
npm install [пакет]
# package-lock.json ВСЕГДА коммитить вместе с package.json

# Обновление — с проверкой breaking changes
npm outdated
npm update [пакет]

# Удаление — проверить что не используется в коде
grep -r "[пакет]" src/ app/ components/ lib/
npm uninstall [пакет]
```

**Правило lock-файла:** `package-lock.json` всегда входит в коммит вместе с `package.json`. При параллельной работе нескольких агентов lock-файл может конфликтовать — это нормально, решается через `npm install` после merge.

### Рефакторинг

**Только по запросу пользователя. Никогда по своей инициативе.**

Перед началом:
- Убедиться что есть точка отката (коммит / ветка)
- Не расширять скоуп — рефакторить только то, что просили

Верификация «функционал после = функционал до»:
```bash
# Если есть тесты
npm test

# Если тестов нет — ручная проверка:
# 1. npm run dev → работает
# 2. Открыть затронутые страницы в браузере → работают
# 3. Проверить все импорты затронутых модулей → нет ошибок
# 4. Проверить что переименования не сломали другие файлы:
grep -r "[старое-имя]" src/ app/
```

### Конфигурация

- Перед изменением — сохранить копию текущего конфига в истории чата
- После изменения — проверить что все скрипты (`dev`, `build`, `lint`) работают

### Переменные окружения (Adjutant-специфично)

При добавлении, переименовании или изменении переменной окружения:

```bash
# 1. Проверить все скрипты — нет ли других мест со старым/похожим именем
grep -rn "OLD_VAR_NAME" scripts/

# 2. Проверить зарезервированные имена (запрещены в cron-среде)
# Нельзя: GIT_DIR, HOME, PATH, SHELL, USER, PWD, TERM

# 3. Обновить .env.example
# 4. Паттерн чтения с fallback (обязателен для API-ключей):
#    os.environ.get("PRIMARY_KEY") or os.environ.get("FALLBACK_KEY", "")
```

Пример прошлой ошибки: `GIT_DIR` переименован в `ADJUTANT_DIR` в 11 скриптах — переменная была зарезервирована git и ломала git-операции внутри скриптов.

**Пример (обновление пакета, 🔴 высокий риск):**
```
1. npm outdated next → текущая 14.2, доступна 15.1
2. Прочитать next.js changelog → breaking: App Router изменения
3. Показать пользователю: «Мажорное обновление, breaking changes в X, Y. Обновляю?»
4. [после подтверждения] npm install next@15.1
5. Исправить breaking changes в app/layout.tsx
6. npm run dev → работает
7. npm run build → собирается без ошибок
```

**Пример (настройка линтера, 🟡 средний риск):**
```
1. npm ls eslint → не установлен
2. npm install -D eslint @eslint/js
3. Создать eslint.config.js по документации
4. Добавить скрипт в package.json: "lint": "eslint src/"
5. npm run lint → исправить найденные ошибки
6. npm run dev → работает
```

## Шаг 4: Сдача

После выполнения:
- `npm run dev` работает без ошибок
- `npm run build` работает (если применимо)
- Изменение работает как ожидалось
- Существующий функционал не сломан

Следовать workflow-done — полный чеклист приёмки.
Формат сдачи:

```
Сделано: [что выполнено]
Риск: [🟢 / 🟡 / 🔴]
Затронуто: [какие файлы изменены]
Проверено: [что работает]
```