@jakerdy/agentica 0.0.2

package/prompts/change.prompt.md

@@ -0,0 +1,915 @@
+---
+name: agentica.change
+description: Создание новой спецификации для внесения изменения в существующую реализацию
+---
+
+## Ввод пользователя
+
+```text
+$ARGUMENTS
+```
+
+Ты **ОБЯЗАН** учесть ввод пользователя (аргументы и контекст) перед тем как продолжить.
+
+## Цель и принципы работы
+
+Твоя задача — создать спецификацию изменений существующей реализации с максимальной осторожностью и точностью.
+Работай строго линейно: **Валидация → Анализ текущего → Интервью → Impact Analysis → Планирование → Создание спеки → Git → Проверка → Отчёт**.
+
+Изменение существующего кода — это **самая опасная операция**. В отличие от новой фичи, здесь уже есть:
+- Работающий код, на который полагаются пользователи.
+- Интеграции с другими модулями, которые могут сломаться.
+- Тесты, которые описывают текущий контракт.
+- История решений, которую нужно уважать.
+
+**Ключевые принципы:**
+1. **Безопасность прежде всего:** Изменения не должны сломать существующую функциональность без явного согласия.
+2. **Память как карта:** Используй `memory` для накопления фактов о текущей реализации. Все найденные зависимости, интерфейсы, точки использования сохраняй в memory.
+3. **Impact Analysis обязателен:** Перед изменением найди **все** места, которые затрагиваются.
+4. **Breaking Changes документируются:** Если апгрейд ломает API — это должно быть явно указано с планом миграции.
+5. **Инкрементальность:** Разбивай изменения на фазы, каждая из которых оставляет код в валидном состоянии.
+
+### Глобальные запреты (Safety Guards)
+
+Останови выполнение и не вноси изменения, если:
+1. Запрос требует **написания кода** напрямую — сначала должна быть создана спека (это команда `change`, не `implement`).
+2. Запрос описывает **новую фичу**, а не изменение существующей (остановись и предложи пользователю воспользоваться агентом: `create`).
+3. Код, который нужно изменить, **не существует** (остановись и предложи пользователю воспользоваться агентом: `create` для новой фичи).
+4. Пользователь просит задокументировать существующий код без изменений (остановись и предложи пользователю воспользоваться агентом: `reverse`).
+5. Изменения требуют **полной переписки архитектуры** — это не change, это новая `architect` + `refactor`.
+6. Невозможно определить скоуп изменений (слишком размыто "улучши всё").
+7. Обнаружены критические риски, которые пользователь не подтвердил (например, "это сломает production").
+
+В случае остановки: объясни причину и предложи корректную команду.
+
+## Топология и размещение файлов
+
+Спецификации изменений размещаются в `.agentica/changes/` того скоупа, к которому они относятся:
+- **Single-project:** `./.agentica/changes/`
+- **Monorepo (package):** `./packages/<name>/.agentica/changes/`
+
+**Формат имени файла:** `CH-XXXX - <Краткое описание изменения>.md`
+- `XXXX` — четырехзначный номер, определяется автоматически (следующий свободный).
+- `<Краткое описание>` — что меняется в 3-7 словах.
+
+Примеры:
+- `CH-0003 - Формат ошибок на JSON.md`
+- `CH-0015 - Миграция с Winston на Pino.md`
+- `CH-0027 - Поддержка async валидаторов.md`
+
+**Git workflow:**
+- Создается новая ветка: `<package-id>/CH-XXXX-краткое-название`
+- После каждой фазы работы делается коммит.
+- Коммиты делаются только через `run_in_terminal` с командой `git commit`.
+
+## Фаза 1: Валидация контекста и определение скоупа
+
+### Шаг 1.1: Определение скоупа изменения
+1. Прочитай `structure.md` из корня проекта.
+2. Определи тип проекта: Single-project или Monorepo.
+3. Определи **область изменения**:
+   - Если пользователь указал конкретный модуль/файл → определи его пакет.
+   - Если открыт файл в редакторе → используй его контекст.
+   - Если изменение затрагивает несколько пакетов → это **cross-package change**, требуется особый подход (спроси пользователя о приоритетном пакете или создай изменение в корневом `.agentica/`).
+   - Если неоднозначно → задай вопрос через интсрумент `ask_questions`.
+
+### Шаг 1.2: Чтение контекста проекта
+Прочитай следующие файлы из целевого скоупа (если существуют):
+1. `product.md` — продуктовый контекст.
+2. `structure.md` — структура проекта/пакета.
+3. `tech.md` — технический стек и стандарты.
+4. Список существующих файлов в `changes/` (для определения номера CH-XXXX).
+5. Список существующих файлов в `features/` и `architecture/` (возможно, изменение связано с существующей спекой).
+
+### Шаг 1.3: Поиск связанных спецификаций
+Проверь, нет ли существующих спек, которые описывают текущую реализацию:
+- Если есть `FT-XXXX` — прочитай её, чтобы понять изначальный замысел.
+- Если есть `AR-XXXX` — прочитай архитектурные решения.
+- Если есть другие `CH-XXXX` — возможно, изменение уже частично сделано.
+
+### Шаг 1.4: Определение номера CH-XXXX
+1. Просканируй директорию `.agentica/changes/` (или `./packages/<name>/.agentica/changes/`).
+2. Найди максимальный номер `CH-XXXX`.
+3. Присвой новой спеке номер `CH-(MAX+1)`.
+4. Если директория пуста — начни с `CH-0001`.
+
+## Фаза 2: Анализ текущего состояния (Reverse Engineering Light)
+
+Цель этой фазы — **понять, что сейчас есть**. Это не полный reverse (как в `agentica.reverse`), а **целевой анализ** только того, что планируется изменить.
+
+### Шаг 2.1: Определение границ анализа
+
+Определи **скоуп анализа**:
+- Если пользователь указал конкретный файл/функцию → анализируй именно его.
+- Если указан модуль → анализируй все публичные интерфейсы модуля.
+- Если изменение описано концептуально ("формат ошибок") → найди все места, где реализован текущий подход.
+
+### Шаг 2.2: Поиск целевых сущностей
+
+Используй доступные инструменты для поиска:
+1. **semantic_search** — для поиска по концепции ("error handling", "validation logic").
+2. **grep_search** — для поиска конкретных паттернов (классы, функции, константы).
+3. **file_search** — для поиска файлов по маске.
+4. **list_code_usages** — для поиска всех мест использования функции/класса.
+
+**Важно:** Для каждой найденной сущности сохраняй факт в `memory`.
+
+### Шаг 2.3: Накопление контекста через Memory
+
+Memory — это **ключ к безопасным изменениям**. Ты должен накопить карту текущей реализации, чтобы при создании спеки ничего не пропустить.
+
+**Правила использования `memory`:**
+
+1. **Категория:** Используй `file_specific` для фактов о конкретных файлах, `general` для межмодульных связей.
+
+2. **Subject (с префиксом для группировки):**
+   - Формат: `@<scope>/CH-XXXX--<тема>`
+   - `<scope>` = `root` для Single-project или `package-name` для Monorepo пакета
+   - `<тема>` = одна из: `current-impl`, `usages`, `dependencies`, `tests`, `risks`
+   
+   Примеры:
+   - `@root/CH-0023--current-impl`
+   - `@auth-service/CH-0015--usages`
+   - `@api-client/CH-0008--dependencies`
+
+3. **Fact:** Короткое утверждение (до 200 символов) о текущей реализации.
+
+4. **Citations:** Всегда указывай файл:строка или диапазон строк.
+
+5. **Reason:** Объясни, почему этот факт важен для безопасного изменения.
+
+**Примеры по категориям:**
+
+#### Текущая реализация (current-impl):
+```
+category: file_specific
+subject: @api-client/CH-0015--current-impl
+fact: ErrorHandler returns string messages with format "ERROR: [code] message"
+citations: src/errors/handler.ts:34-42
+reason: This is the current format that will be changed to JSON. Need to document it in As-Is section.
+```
+
+#### Точки использования (usages):
+```
+category: general
+subject: @api-client/CH-0015--usages
+fact: ErrorHandler.format() called in 23 places across src/api/*.ts
+citations: src/api/client.ts:56, src/api/retry.ts:89, src/api/validator.ts:123 (+ 20 more)
+reason: All these places must be updated or adapted. Critical for Impact Analysis.
+```
+
+#### Зависимости (dependencies):
+```
+category: general
+subject: @api-client/CH-0015--dependencies
+fact: CLI module depends on string error format for exit codes parsing
+citations: src/cli/runner.ts:78-92
+reason: Breaking change risk: CLI expects strings, will break if switched to JSON without adapter.
+```
+
+#### Тесты (tests):
+```
+category: file_specific
+subject: @api-client/CH-0015--tests
+fact: 15 tests in errors.test.ts assert string format with regex matching
+citations: tests/errors.test.ts:45-120
+reason: All tests will fail after change. Need to update or rewrite them in migration plan.
+```
+
+#### Риски (risks):
+```
+category: general
+subject: @api-client/CH-0015--risks
+fact: Public API exports ErrorHandler, used by 3rd party plugins
+citations: src/index.ts:12, docs/plugins.md:45
+reason: Breaking change for external consumers. Must document in Breaking Changes section.
+```
+
+### Шаг 2.4: Сканирование текущей реализации
+
+Для каждой найденной целевой сущности:
+
+1. **Прочитай реализацию:**
+   - Открой файл, где находится код.
+   - Пойми **как** и **почему** это сделано именно так.
+   - Сохрани в `memory`: "Current implementation: [описание] at [файл:строка]"
+
+2. **Найди все использования:**
+   - Используй `list_code_usages` для класса/функции.
+   - Найди все импорты, вызовы, расширения.
+   - Сохрани в `memory`: "Usage: [где] at [файл:строка] - [контекст]"
+
+3. **Найди зависимости:**
+   - Что импортирует целевой модуль?
+   - Кто импортирует целевой модуль?
+   - Есть ли циклические зависимости?
+   - Сохрани в `memory`: "Dependency: [A] → [B] at [файл:строка]"
+
+4. **Найди тесты:**
+   - Есть ли тесты для текущего поведения?
+   - Используй `grep_search` по паттернам test/spec файлов.
+   - Сохрани в `memory`: "Test: [название] covers [что] at [файл:строка]"
+
+5. **Оцени публичность API:**
+   - Экспортируется ли сущность наружу? (проверь index.ts, package.json exports)
+   - Используется ли в других пакетах?
+   - Задокументирована ли в README/docs?
+   - Сохрани в `memory`: "Public API: [сущность] exported from [файл:строка]"
+
+### Шаг 2.5: Построение карты влияния
+
+После сканирования у тебя должна быть полная карта:
+- **Что сейчас есть** (current implementation)
+- **Где используется** (all usages)
+- **Кто зависит** (dependencies graph)
+- **Что тестирует** (test coverage)
+- **Что публично** (public API surface)
+
+Эта карта станет основой для Impact Analysis.
+
+## Фаза 3: Интервью и сбор требований к изменениям
+
+### Цель интервью
+Понять **что** и **почему** нужно изменить, и какие ограничения существуют.
+
+Для задавания вопросов используй интсрумент `ask_questions`. Не перегружай пользователя, задавай по 2-4 вопроса за раз.
+
+### Когда запускать интервью
+
+**Всегда спрашивай**, если:
+1. Входные данные содержат **менее 3 предложений** описания желаемого изменения.
+2. Не ясна **мотивация** изменения (продуктовая причина, техническая причина, или и то и другое).
+3. Есть несколько возможных интерпретаций запроса.
+4. Обнаружены **Breaking Changes**, которые пользователь мог не осознавать.
+5. Изменение конфликтует с текущей архитектурой или `tech.md`.
+
+**Можно пропустить**, если:
+1. Пользователь дал детальное описание (5+ абзацев) с конкретными примерами "было → стало".
+2. Контекст полностью покрывает 4 измерения (см. ниже).
+3. Изменение локальное и очевидное (например, "исправить опечатку в названии переменной").
+
+### Структура интервью (4 измерения)
+
+#### Измерение 1: Мотивация изменения
+- **Почему** нужно изменение? (продуктовая причина, баг, технический долг, новое требование)
+- Какая проблема решается?
+- Есть ли дедлайн или срочность?
+
+Примеры вопросов:
+- "Изменение связано с багом, новым требованием или улучшением архитектуры?"
+- "Что произойдет, если не внести это изменение?"
+
+#### Измерение 2: Желаемое состояние (To-Be)
+- **Что** конкретно должно измениться?
+- Как должна выглядеть новая реализация?
+- Есть ли пример кода (Golden Snippet)?
+- Какое поведение ожидается?
+
+Примеры вопросов:
+- "Можешь привести пример кода, как должен выглядеть новый API?"
+- "Какой формат данных ожидается на выходе?"
+
+#### Измерение 3: Ограничения и совместимость
+- Нужна ли **обратная совместимость**?
+- Допустимы ли **Breaking Changes**?
+- Есть ли внешние потребители API (другие команды, клиенты, плагины)?
+- Должны ли старые данные/файлы продолжать работать?
+
+Примеры вопросов:
+- "Допустимо ли сломать существующий API, или нужна обратная совместимость?"
+- "Есть ли внешние потребители, которых нужно учесть?"
+
+#### Измерение 4: Приоритеты и риски
+- Что **критически важно** сохранить (производительность, функциональность, данные)?
+- Что **можно** принести в жертву ради изменения?
+- Есть ли риски, которые пользователь готов принять?
+
+Примеры вопросов:
+- "Если изменение потребует переписать тесты, это допустимо?"
+- "Важнее скорость внедрения или безопасность миграции?"
+
+### Критерий достаточности контекста
+
+Считай контекст **достаточным**, если ты можешь ответить на следующие вопросы:
+1. Что конкретно меняется (файлы, функции, интерфейсы)?
+2. Почему это меняется (мотивация)?
+3. Как должно выглядеть новое поведение (To-Be)?
+4. Допустимы ли Breaking Changes и как их минимизировать?
+5. Какие риски существуют и как их митигировать?
+
+Если не можешь ответить хотя бы на 3 из 5 — **продолжай интервью**.
+
+### Обнаружение неожиданных последствий
+
+Если во время анализа текущего состояния (Фаза 2) ты обнаружил риски, о которых пользователь **не упомянул** (например, Breaking Changes), обязательно **сообщи об этом** и **запроси подтверждение**:
+
+```
+Я обнаружил, что изменение формата ошибок сломает:
+1. CLI модуль, который парсит строки ошибок для определения exit кодов.
+2. 3 внешних плагина, которые используют ErrorHandler из публичного API.
+3. 15 unit-тестов, которые проверяют текущий формат.
+
+Это Breaking Changes. Допустимы ли они, или нужен план миграции с сохранением обратной совместимости?
+```
+
+Используй интсрумент `ask_questions` для получения ответа.
+
+## Фаза 4: Impact Analysis (Анализ влияния)
+
+Это **критически важная фаза**, которая отличает профессиональное изменение от "а давайте попробуем".
+
+### Шаг 4.1: Классификация изменений
+
+Определи тип изменения:
+
+1. **Non-Breaking (Безопасное):**
+   - Добавление нового функционала без изменения существующего API.
+   - Изменение внутренней реализации без изменения контракта.
+   - Исправление бага, которое не меняет ожидаемое поведение.
+
+2. **Breaking (Ломающее):**
+   - Изменение сигнатуры публичных функций/методов.
+   - Удаление публичного API.
+   - Изменение формата данных (input/output).
+   - Изменение поведения, на которое полагается внешний код.
+
+3. **Potentially Breaking (Потенциально ломающее):**
+   - Изменение приватных методов, которые могут использоваться через рефлексию.
+   - Изменение порядка выполнения (race conditions).
+   - Изменение производительности (может нарушить SLA).
+
+Сохрани классификацию в `memory`:
+```
+category: general
+subject: @<scope>/CH-XXXX--classification
+fact: Breaking change: ErrorHandler.format() signature changes from string to JSON
+citations: User confirmation + src/errors/handler.ts:34
+reason: Must document in Breaking Changes section and create migration plan
+```
+
+### Шаг 4.2: Построение графа влияния
+
+Используй накопленные facts из memory (Фаза 2) для построения полного графа:
+
+```
+Изменение: ErrorHandler.format() string → JSON
+  │
+  ├─ Прямые потребители (23 места):
+  │   ├─ src/api/client.ts:56 ❌ Breaking
+  │   ├─ src/api/retry.ts:89 ❌ Breaking
+  │   └─ ... (21 more)
+  │
+  ├─ Косвенные потребители:
+  │   ├─ CLI module (парсит строки) ❌ Breaking
+  │   ├─ Logger (форматирует вывод) ⚠️ Potentially Breaking
+  │   └─ Monitoring (отправляет метрики) ✅ Non-Breaking (не парсит)
+  │
+  ├─ Тесты:
+  │   ├─ errors.test.ts (15 тестов) ❌ All will fail
+  │   └─ integration.test.ts (5 тестов) ⚠️ May fail
+  │
+  └─ Внешние зависимости:
+      ├─ 3rd party plugins ❌ Breaking (public API)
+      └─ Documentation ⚠️ Needs update
+```
+
+Сохрани граф влияния в память:
+```
+category: general
+subject: @<scope>/CH-XXXX--impact
+fact: Direct impact: 23 call sites must be updated to handle JSON instead of string
+citations: grep results from Фаза 2
+reason: Will be used in Tasks section to create update tasks for each affected file
+```
+
+### Шаг 4.3: Оценка рисков
+
+Для каждого Breaking Change оцени риск:
+
+| Изменение | Вероятность проблем | Влияние | Митигация |
+|:----------|:-------------------|:--------|:----------|
+| Изменение формата ошибок | Высокая | Критическое | Создать adapter для обратной совместимости |
+| Обновление 23 call sites | Средняя | Среднее | Автоматический рефакторинг + ручная проверка |
+| Переписывание тестов | Низкая | Низкое | Обновить assertions в тестах |
+
+Сохрани риски в память:
+```
+category: general
+subject: @<scope>/CH-XXXX--risks
+fact: High risk: CLI module will break without backward compatibility adapter
+citations: src/cli/runner.ts:78-92
+reason: Must create deprecation path in migration plan (Phase 1 of tasks)
+```
+
+### Шаг 4.4: Определение стратегии миграции
+
+Выбери одну из стратегий:
+
+**Стратегия A: Big Bang (Одномоментная замена)**
+- Условие: Изменение локальное, нет внешних потребителей, можно обновить весь код за раз.
+- Риски: Высокие, если что-то пропущено.
+- Подходит для: Внутренних изменений без публичного API.
+
+**Стратегия B: Adapter Pattern (Адаптер для совместимости)**
+- Условие: Нужна обратная совместимость, но новый функционал тоже нужен.
+- Реализация: Старый API оборачивает новый, с deprecation warning.
+- Подходит для: Публичных API с версионированием.
+
+**Стратегия C: Feature Flag (Постепенная миграция)**
+- Условие: Изменение рискованное, нужно тестировать в production постепенно.
+- Реализация: Оба варианта существуют, переключение через флаг.
+- Подходит для: Критичных изменений с высоким риском.
+
+**Стратегия D: Deprecation Path (Удаление через версии)**
+- Условие: Изменение ломающее, но есть время на миграцию.
+- Реализация: v1 — deprecation warning, v2 — удаление старого API.
+- Подходит для: Библиотек с semver.
+
+Выбери стратегию и сохрани:
+```
+category: general
+subject: @<scope>/CH-XXXX--strategy
+fact: Migration strategy: Adapter Pattern with 2-phase rollout
+citations: Discussion with user + impact analysis
+reason: Will structure Tasks section into Phase 1 (adapter) and Phase 2 (full migration)
+```
+
+## Фаза 5: Создание спецификации изменений
+
+### Шаг 5.1: Копирование шаблона
+
+1. Найди шаблон в `.agentica/templates/change/CH-0000 - Изменение в фиче или модуле XXX.md`.
+2. Создай новый файл в целевой директории `.agentica/changes/` с номером `CH-XXXX`.
+3. Скопируй содержимое шаблона.
+
+### Шаг 5.2: Заполнение документа
+
+Используй накопленные facts из memory для заполнения каждого раздела.
+
+#### Раздел: Заголовок и описание
+
+Замени заглушки:
+- `CH-0000` → правильный номер
+- `Изменение в фиче или модуле XXX` → краткое описание из 3-7 слов
+
+Заполни вводную часть:
+- **Причина изменения:** Из Фазы 3 (мотивация)
+- **Что меняется:** Из Фазы 4 (impact analysis)
+- **Ограничения:** Из Фазы 3 (constraints)
+
+Пример:
+```markdown
+# CH-0015 - Формат ошибок на JSON
+
+В связи с необходимостью структурированной обработки ошибок в мониторинге и логировании,
+необходимо внести следующие изменения в модуль ErrorHandler:
+
+- Изменить формат возвращаемых ошибок с `string` на `{code: string, message: string, details?: any}`
+- Обновить все 23 места использования ErrorHandler.format()
+- Создать backward compatibility adapter для CLI модуля
+- Обновить документацию и тесты
+
+При этом важно учитывать следующие аспекты и ограничения:
+
+- CLI модуль должен продолжать работать без изменений (обратная совместимость через adapter)
+- Внешние плагины должны получить deprecation notice за 1 версию до Breaking Change
+- Производительность не должна пострадать (JSON.stringify не должен вызываться избыточно)
+```
+
+#### Раздел: Текущее поведение (As-Is)
+
+Используй facts из memory с subject `@<scope>/CH-XXXX--current-impl`:
+
+````markdown
+## Текущее поведение
+
+ErrorHandler в настоящее время возвращает строки в формате:
+```typescript
+// src/errors/handler.ts:34-42
+class ErrorHandler {
+  format(error: Error): string {
+    return `ERROR: [${error.code}] ${error.message}`;
+  }
+}
+```
+
+Этот формат используется в 23 местах:
+- API client (src/api/client.ts:56) — для логирования
+- Retry logic (src/api/retry.ts:89) — для принятия решения о повторе
+- CLI runner (src/cli/runner.ts:78) — для парсинга и определения exit кодов
+
+**Проблемы текущего подхода:**
+- Невозможно структурированно обработать ошибку без regex парсинга
+- Отсутствует поле для дополнительных деталей (stack trace, context)
+- Мониторинг не может корректно группировать ошибки
+````
+
+#### Раздел: Ожидаемое поведение (To-Be)
+
+Используй информацию из Фазы 3 (интервью):
+
+````markdown
+## Ожидаемое поведение
+
+ErrorHandler должен возвращать структурированный JSON объект:
+
+```typescript
+// Golden Snippet
+interface ErrorResponse {
+  code: string;        // Уникальный код ошибки (например, "AUTH_FAILED")
+  message: string;     // Человекочитаемое сообщение
+  details?: any;       // Дополнительная информация (stack, context)
+}
+
+class ErrorHandler {
+  format(error: Error): ErrorResponse {
+    return {
+      code: error.code || 'UNKNOWN_ERROR',
+      message: error.message,
+      details: {
+        stack: error.stack,
+        timestamp: new Date().toISOString()
+      }
+    };
+  }
+}
+```
+
+**Преимущества нового подхода:**
+- Структурированная обработка без парсинга
+- Возможность добавления метаданных
+- Совместимость с системами мониторинга (Sentry, Datadog)
+````
+
+#### Раздел: Impact Analysis
+
+Используй facts из memory с subject `@<scope>/CH-XXXX--impact` и граф влияния из Фазы 4:
+
+````markdown
+## Impact Analysis
+
+### Затронутые компоненты
+
+**Прямые изменения:**
+- `src/errors/handler.ts` — изменение сигнатуры `format()` метода
+- 23 файла с вызовами `ErrorHandler.format()` — обновление для работы с JSON
+
+**Косвенные изменения:**
+- `src/cli/runner.ts` — создание adapter для совместимости
+- `src/index.ts` — обновление экспортов (добавить `ErrorResponse` type)
+- `docs/errors.md` — обновление документации
+- `tests/errors.test.ts` — переписать 15 тестов
+
+### Breaking Changes
+
+⚠️ **BREAKING:** Изменение типа возвращаемого значения `ErrorHandler.format()`:
+- **Было:** `format(error: Error): string`
+- **Стало:** `format(error: Error): ErrorResponse`
+
+**Затронутые потребители:**
+1. **CLI module** (src/cli/runner.ts:78-92)
+   - Текущий код парсит строку regex'ом для извлечения кода ошибки
+   - **Решение:** Создать `ErrorAdapter.toString()` для обратной совместимости
+
+2. **External plugins** (public API)
+   - 3rd party плагины могут использовать ErrorHandler
+   - **Решение:** Добавить deprecation notice в v1.x, breaking change в v2.0
+
+3. **Logger integration** (src/utils/logger.ts:45)
+   - Логгер ожидает строку для вывода
+   - **Решение:** Автоматически вызывать `JSON.stringify()` в logger wrapper
+
+### Non-Breaking Changes (Безопасные)
+
+✅ Monitoring integration — не парсит формат, просто передает дальше
+✅ Database storage — хранит ошибки как JSONB, новый формат лучше подходит
+````
+
+#### Раздел: Необходимый контекст и важные файлы
+
+Используй facts из memory с subject `@<scope>/CH-XXXX--current-impl`, `--dependencies`, `--tests`:
+
+````markdown
+## Необходимый контекст и важные файлы проекта
+
+### Файлы, требующие изменения:
+
+**Основная реализация:**
+- `src/errors/handler.ts:34-42` — изменить сигнатуру `format()`, вернуть объект
+- `src/errors/types.ts` — добавить `interface ErrorResponse`
+
+**Все точки использования (23 файла):**
+- `src/api/client.ts:56` — обновить вызов, работать с ErrorResponse.message
+- `src/api/retry.ts:89` — обновить логику проверки, использовать ErrorResponse.code
+- `src/api/validator.ts:123` — обновить обработку ошибок валидации
+- ... (20 more files, see full list in task breakdown)
+
+**Backward compatibility:**
+- `src/cli/adapter.ts` (новый файл) — создать adapter для CLI
+  ```typescript
+  class ErrorAdapter {
+    static toString(error: ErrorResponse): string {
+      return `ERROR: [${error.code}] ${error.message}`;
+    }
+  }
+  ```
+
+**Тесты:**
+- `tests/errors.test.ts:45-120` — обновить 15 тестов, проверять объект вместо строки
+- `tests/integration/cli.test.ts:67-89` — проверить работу adapter
+
+**Документация:**
+- `docs/errors.md` — обновить примеры использования
+- `README.md` — добавить migration guide в CHANGELOG
+````
+
+#### Раздел: Задачи (Tasks)
+
+Декомпозируй изменение на **инкрементальные фазы**. Каждая фаза должна оставлять код в **валидном состоянии** (компилируется, тесты проходят).
+
+Используй выбранную стратегию миграции из Фазы 4.4:
+
+````markdown
+## Задачи
+
+### Phase 1: Создание нового API без Breaking Changes
+
+**Цель:** Добавить новый функционал параллельно со старым.
+
+- [ ] TSK-0001: Создать `interface ErrorResponse` в `src/errors/types.ts`
+- [ ] TSK-0002: Добавить метод `formatJSON()` в `ErrorHandler` (новый метод, не трогаем `format()`)
+- [ ] TSK-0003: Написать unit-тесты для `formatJSON()`
+- [ ] TSK-0004: Обновить экспорты в `src/index.ts` (добавить `ErrorResponse` type)
+- [ ] TSK-0005: Commit: "feat: add ErrorResponse type and formatJSON method"
+
+✅ **Checkpoint:** Код компилируется, все старые тесты проходят, новый функционал доступен.
+
+---
+
+### Phase 2: Создание Backward Compatibility Adapter
+
+**Цель:** Подготовить инфраструктуру для безопасной миграции CLI.
+
+- [ ] TSK-0006: Создать `src/cli/adapter.ts` с `ErrorAdapter.toString()` методом
+- [ ] TSK-0007: Написать тесты для adapter (проверить, что возвращает старый формат)
+- [ ] TSK-0008: Обновить `src/cli/runner.ts` — использовать adapter вместо прямого вызова `format()`
+- [ ] TSK-0009: Прогнать CLI интеграционные тесты
+- [ ] TSK-0010: Commit: "feat: add ErrorAdapter for CLI backward compatibility"
+
+✅ **Checkpoint:** CLI работает через adapter, готов к переходу на новый формат.
+
+---
+
+### Phase 3: Миграция внутренних потребителей
+
+**Цель:** Обновить все внутренние вызовы на использование `formatJSON()`.
+
+- [ ] TSK-0011: Обновить `src/api/client.ts:56` — использовать `formatJSON().message`
+- [ ] TSK-0012: Обновить `src/api/retry.ts:89` — использовать `formatJSON().code`
+- [ ] TSK-0013: Обновить `src/api/validator.ts:123` — использовать `formatJSON()`
+- [ ] TSK-0014: ... (создать задачу для каждого из оставшихся 20 файлов)
+- [ ] TSK-0035: Обновить unit-тесты для всех измененных файлов
+- [ ] TSK-0036: Commit: "refactor: migrate internal consumers to formatJSON"
+
+✅ **Checkpoint:** Все внутренние вызовы используют новый формат.
+
+---
+
+### Phase 4: Deprecation старого API
+
+**Цель:** Пометить старый метод `format()` как deprecated.
+
+- [ ] TSK-0037: Добавить `@deprecated` JSDoc comment к `format()` методу
+- [ ] TSK-0038: Добавить console.warn при вызове `format()` в dev mode
+- [ ] TSK-0039: Обновить документацию — добавить migration guide
+- [ ] TSK-0040: Обновить CHANGELOG.md — описать Breaking Change в следующей мажорной версии
+- [ ] TSK-0041: Commit: "docs: deprecate ErrorHandler.format() in favor of formatJSON"
+
+✅ **Checkpoint:** Пользователи предупреждены о будущем Breaking Change.
+
+---
+
+### Phase 5: Финальная замена (Breaking Change)
+
+**Цель:** Удалить старый API, сделать новый основным.
+
+⚠️ **Внимание:** Эта фаза выполняется только в новой мажорной версии (v2.0.0).
+
+- [ ] TSK-0042: Переименовать `format()` → `formatLegacy()`
+- [ ] TSK-0043: Переименовать `formatJSON()` → `format()`
+- [ ] TSK-0044: Удалить `formatLegacy()` (или оставить приватным для adapter)
+- [ ] TSK-0045: Обновить все тесты на использование нового `format()`
+- [ ] TSK-0046: Обновить документацию — убрать упоминание старого формата
+- [ ] TSK-0047: Прогнать полный набор тестов (unit + integration + e2e)
+- [ ] TSK-0048: Commit: "BREAKING: change ErrorHandler.format() to return JSON"
+
+✅ **Checkpoint:** Миграция завершена, код чистый, тесты проходят.
+
+---
+
+### Phase 6: Финальная проверка
+
+**Цель:** Убедиться, что все работает корректно.
+
+- [ ] TSK-0049: Прогнать linter (`bun run lint`) — исправить ошибки
+- [ ] TSK-0050: Прогнать formatter (`bun run format`) — отформатировать код
+- [ ] TSK-0051: Прогнать все тесты (`bun run test`) — проверить 100% прохождение
+- [ ] TSK-0052: Прогнать type checker (`bun run typecheck`) — проверить типы
+- [ ] TSK-0053: Создать PR в master с описанием изменений
+- [ ] TSK-0054: Code review — запросить ревью у команды
+````
+
+**Важные правила для задач:**
+1. Каждая задача должна быть **атомарной** (одно действие, один файл или группа связанных файлов).
+2. После каждой фазы — **коммит**. Это позволяет откатиться на любую стабильную точку.
+3. Задачи упорядочены по **безопасности**: сначала добавляем новое, потом мигрируем, потом удаляем старое.
+4. **Checkpoints** после каждой фазы описывают критерии готовности.
+
+### Шаг 5.3: Добавление дополнительных разделов
+
+Если применимо, добавь:
+
+**Раздел: Риски и митигация (опционально, если есть критичные риски)**
+
+````markdown
+## Риски и митигация
+
+| Риск | Вероятность | Влияние | Митигация |
+|:-----|:------------|:--------|:----------|
+| External plugins break | Высокая | Критическое | Deprecation path: v1.x warning, v2.0 breaking |
+| Performance degradation | Средняя | Среднее | Benchmark before/after, optimize JSON.stringify usage |
+| CLI tests fail | Низкая | Низкое | Smoke test CLI manually before commit |
+````
+
+**Раздел: Rollback план (опционально, для критичных изменений)**
+
+````markdown
+## Rollback план
+
+Если после внедрения что-то пошло не так:
+
+1. **Быстрый откат (без кода):**
+   - Feature flag: установить `USE_LEGACY_ERRORS=true` в env
+   - Restart services
+
+2. **Полный откат (через git):**
+   - `git revert <commit-hash>` на последний коммит Phase 5
+   - Откатиться к Phase 4 (deprecated API все еще работает)
+
+3. **Частичный откат (через adapter):**
+   - Вернуть вызов адаптера в проблемных местах
+   - Оставить новый API для новых мест
+````
+
+### Шаг 5.4: Сохранение файла
+
+Создай файл в целевой директории:
+- Single-project: `./.agentica/changes/CH-XXXX - <Название>.md`
+- Monorepo: `./packages/<name>/.agentica/changes/CH-XXXX - <Название>.md`
+
+## Фаза 6: Git Workflow
+
+### Шаг 6.1: Проверка наличия Git
+
+Проверь, инициализирован ли git репозиторий:
+
+```bash
+git rev-parse --is-inside-work-tree 2>/dev/null
+```
+
+Если git отсутствует — **пропусти эту фазу**, перейди к Фазе 7.
+
+### Шаг 6.2: Создание ветки
+
+Создай новую ветку для изменения:
+
+```bash
+git checkout -b change/CH-XXXX-краткое-описание
+```
+
+Пример: `change/CH-0015-json-error-format`
+
+**Правила именования:**
+- Формат: `change/CH-XXXX-kebab-case-description`
+- Максимум 50 символов
+- Только латиница и дефисы
+
+### Шаг 6.3: Коммит спецификации
+
+После создания спеки сделай первый коммит:
+
+```bash
+git add .agentica/changes/CH-XXXX*.md
+git commit -m "docs(CH-XXXX): create change specification for <краткое описание>"
+```
+
+Пример:
+```bash
+git commit -m "docs(CH-0015): create change specification for JSON error format"
+```
+
+### Шаг 6.4: Коммиты после каждой фазы
+
+**Важно:** Коммиты делаются **только** на этапе `implement`, **не** на этапе `change`.
+
+В спеке ты только **планируешь** коммиты, пиши их в задачах как:
+- `TSK-0005: Commit: "feat: add ErrorResponse type and formatJSON method"`
+
+Реальные коммиты будет делать `agentica.implement`.
+
+## Фаза 7: Финальная проверка
+
+Перед завершением работы проверь:
+
+### Чеклист качества спецификации
+
+- [ ] Номер CH-XXXX уникален (не конфликтует с существующими).
+- [ ] Заголовок и описание заполнены конкретными данными (нет "XXX", "TODO").
+- [ ] Раздел "Текущее поведение" содержит код-примеры и ссылки на файлы.
+- [ ] Раздел "Ожидаемое поведение" содержит Golden Snippet.
+- [ ] Раздел "Impact Analysis" перечисляет все Breaking Changes.
+- [ ] Раздел "Задачи" разбит на фазы с checkpoints.
+- [ ] Каждая задача атомарна (одно действие).
+- [ ] После каждой фазы есть задача на коммит.
+- [ ] Финальная фаза включает lint, format, tests.
+- [ ] Если есть Breaking Changes — есть план миграции.
+- [ ] Если есть критичные риски — есть rollback план.
+
+Если хотя бы одна проверка провалена — **дополни спеку** перед завершением.
+
+## Фаза 8: Отчёт пользователю
+
+Выдай короткое резюме.
+
+Пример:
+
+```
+✅ Спецификация изменений создана: CH-0015 - Формат ошибок на JSON
+
+📋 Скоуп: Package: api-client
+
+🎯 Тип изменения: Breaking
+
+📄 Затронутые компоненты:
+- ErrorHandler: изменение сигнатуры format() метода
+- CLI module: добавление backward compatibility adapter
+- 23 внутренних потребителя: обновление вызовов
+- Тесты: переписать 15 unit-тестов
+
+⚠️ Breaking Changes:
+- ErrorHandler.format() возвращает объект вместо строки
+- External plugins могут сломаться (требуется migration guide)
+
+📊 Статистика:
+- Файлов к изменению: 27
+- Точек использования: 23
+- Тестов требует обновления: 15
+
+🔀 Git:
+- Ветка создана: change/CH-0015-json-error-format
+- Спека закоммичена: a1b2c3d
+
+➡️ Следующий шаг:
+Для начала реализации выполни:
+`/agentica.implement --id CH-0015`
+```
+
+## Дополнительные правила
+
+### Работа с неопределённостью
+
+Если пользователь говорит "сделай как лучше":
+1. Предложи **2-3 варианта** стратегии изменения.
+2. Для каждого укажи Trade-offs (что получаем, что теряем).
+3. Рекомендуй один вариант с обоснованием.
+4. Дай пользователю выбрать через интсрумент `ask_questions`.
+
+### Работа с конфликтами
+
+Если изменение противоречит `tech.md` или существующим архитектурным решениям:
+1. Задокументируй конфликт в разделе "Риски".
+2. Предложи план согласования (создать `AR-XXXX` для изменения архитектуры).
+3. Укажи, можно ли реализовать изменение **без** нарушения стандартов (компромисс).
+
+### Работа с Cross-Package Changes
+
+Если изменение затрагивает несколько пакетов:
+1. Создай спеку в **корневом** `.agentica/changes/` (не в пакете).
+2. В разделе "Impact Analysis" перечисли все затронутые пакеты.
+3. В задачах группируй изменения по пакетам:
+   ```
+   ### Phase 2: Update package-a
+   - [ ] TSK-0010: Update package-a/src/module.ts
+   - [ ] TSK-0011: ...
+   
+   ### Phase 3: Update package-b
+   - [ ] TSK-0020: Update package-b/src/service.ts
+   - [ ] TSK-0021: ...
+   ```
+
+### Терминология и стиль
+
+- Используй термины из `tech.md` проекта.
+- Пиши кратко, но **точно**. Одно предложение лучше абзаца воды.
+- Код-примеры должны быть **рабочими** или максимально близкими к реальности.
+- Golden Snippet в разделе "Ожидаемое поведение" — обязателен для изменений API.