# Спек: два специализированных ИИ-помощника для разгрузки главного исполнителя

**Версия:** v1.0 от 24.05.2026
**Статус:** Draft — pre-implementation
**Источник:** brainstorming-сессия 24.05.2026 (memory: MEMORY.md + CLAUDE.md §6 + push-история 16-24.05)
**Связано:** Pravila §15 (параллельные сессии), §16 (brain governance), CLAUDE.md §3.6, project-скилы `pest-parallel-debugger` / `rls-reviewer` (прецеденты узко-специализированных проектных агентов)

---

## 1. Контекст и проблема

За 8 дней (16-24.05.2026) главный исполнитель (Opus 4.7) совершил повторяющиеся операции двух типов:

1. **Синк 4 нормативных файлов** (Pravila / PSR_v1 / Tooling / CLAUDE.md) — 26 эпизодов (v2.3→v2.27). После каждой задачи приходится править шапки, cross-refs §0, footer-счётчики, §9-changelog в 4 местах. Низкая когнитивная нагрузка, высокая частота, error-prone (известны 2 эпизода версионной коллизии параллельных веток — A11 v2.10 и discovery v2.13).

2. **Pre-flight перед выкатом на боевой liderra.ru** — ~10 выкатов с 22.05 по 24.05. 24.05 в 03:46 UTC случился живой 18-минутный инцидент (портал лёг полностью) из-за пропущенной проверки `bootstrap/cache/config.php` под `www-data` (квирк 107). Корень — pre-flight чек-лист в голове, не формализован.

Оба класса — идеальные кандидаты на отдельных ИИ-помощников: ограниченный вход/выход, повторяющийся, требует понимать смысл (не просто regex), но не творчества.

---

## 2. Цели и измеримые KPI

| Метрика | Цель |
|---------|------|
| Сокращение токенов главного исполнителя на нормативный синк | -90% (с ~70К до ~5К на эпизод) |
| Сокращение токенов главного исполнителя на pre-flight выката | -85% (с ~25К до ~3К на эпизод) |
| Доля автоматизированных синков от общего числа | ≥80% (некоторые требуют ручного — major-bump решения, новые off-phase подкатегории) |
| Live-инциденты из-за пропущенных pre-flight проверок | 0 за квартал (текущий baseline: 1 инцидент за 3 дня) |
| Цена операции (USD) | синк: $0.30/эпизод (было $0.60); выкат: $0.20/эпизод (было $0.35) |

---

## 3. Агент №1: `normative-sync`

### 3.1. Назначение

Применить нормативный синк 4 файлов (Pravila / PSR_v1 / Tooling / CLAUDE.md) после завершённой задачи, на основе brief'а главного исполнителя или git-diff.

### 3.2. Когда зовётся

- После завершения off-phase tooling integration (~3-5/неделю)
- После выпуска brain governance артефактов (схема v2/v3, новый контролёр, новый skill)
- После принятого ADR
- После любого эпизода, который меняет cross-ref пространство нормативки

Главный исполнитель решает зовёт или нет — агент не активируется автоматически.

### 3.3. Входной brief (минимум)

- Тема эпизода в одной строчке (например: «закрыли C1 marketing — 10 новых узлов #74-83, 18-я off-phase подкатегория marketing-tooling»)
- Опционально: явные version-bump targets (если minor/major решение нетривиальное)
- Опционально: ADR-номер если есть

### 3.4. Процедура (10 шагов)

1. **Pre-flight per Pravila §15.2:** `git fetch && git log HEAD..origin/main --oneline` — если есть unpushed коммиты от параллельной сессии в 8-файловом списке, остановиться и эскалировать.
2. **Контекст:** прочитать `git diff HEAD~N..HEAD --stat` чтобы понять scope.
3. **Чтение нормативки:** Pravila / PSR_v1 / Tooling / CLAUDE.md (только релевантные секции — §0, §9 / §10 history, footer-счётчики).
4. **Вычисление новых версий** по правилам:
   - minor (+0.01): добавили узел / методический параграф / cross-ref / запись в §9
   - major (+1.0): убрали правило / архитектурная инверсия / снят hard-rule
5. **Шапки:** обновить дату + версию в шапках 4 файлов.
6. **§0 cross-refs (CLAUDE.md):** обновить строки таблицы версий Pravila/PSR/Tooling до новых номеров.
7. **Footer-счётчики (если добавился узел):** Tooling §0 (КАНОН СЧЁТЧИКОВ) + CLAUDE.md §3.3 footer + §1 row 2b + §3 title. PSR_v1 R10.1 если добавился plugin/skill.
8. **§9 / История версий записи:** один абзац в каждом из 4 файлов по шаблону «vX.Y от ДД.ММ — тема. Изменения: ... Связано: ...».
9. **lefthook cross-ref-checker (C2):** `lefthook run cross-ref-checker || npx lefthook run cross-ref-checker` — если красный, итерация.
10. **Выход:** не коммитит. Отдаёт diff + краткий рапорт «синк готов, версии bumped X→Y, cross-refs verified, lefthook C2 green, добавил §9 в 4 файлах».

### 3.5. Модель и инструменты

- **Модель:** Sonnet 4.6 (Pravila §15.1 — для git-операций обязательно Sonnet/Opus, не Haiku)
- **Tools:** Read, Edit, Grep, Glob, Bash, TodoWrite
- **Skills:**
  - `superpowers:verification-before-completion` — перед итоговым рапортом убедиться что cross-ref-checker зелёный

### 3.6. Что зашиваем в system prompt

- Структура 4 файлов (где шапка / §0 cross-refs / footer-счётчики / §9-changelog)
- Правила version-bump (minor vs major)
- Pravila §15.2 8-файловый список + pre-flight протокол
- Pravila §5 п.10 worktree-эксцепшн (когда прямой Edit, когда `claude-md-management:claude-md-improver`)
- Tooling §0 «КАНОН СЧЁТЧИКОВ» (отсюда и только отсюда числа)
- Шаблон §9-записи (дата, тема, изменения, cross-refs, канал, прецедент)
- Стиль changelog (примеры — последние 5 записей из CLAUDE.md §9)

### 3.7. Границы (out of scope)

- Не правит код, миграции, схему БД
- Не пишет ADR (только цитирует уже принятый)
- Не правит саму карту `docs/automation-graph.html` (если в эпизоде менялась карта — это отдельная задача главного исполнителя)
- Не коммитит, не пушит — только готовит diff
- Не принимает решения о major bump — если не уверен, эскалирует на главного исполнителя

### 3.8. Риски и митигации

| Риск | Митигация |
|------|-----------|
| Версионная коллизия с параллельной веткой | Pre-flight §15.2 на шаге 1 — STOP при unpushed коммитах от других |
| Drift cross-ref (4 файла указывают друг на друга со старыми версиями) | lefthook cross-ref-checker (C2) на шаге 9 |
| Неправильный bump (minor вместо major) | Решение minor по умолчанию; major только при явном указании в brief'е или при удалении правила |
| Пропуск footer-счётчика | Чек-лист TodoWrite внутри агента (8 пунктов структурных правок) |
| Самовольное добавление «improvements» в несвязанные секции | Жёсткое scope-правило в system prompt: «правишь только шапки, §0, footer, §9; всё остальное — STOP» |

### 3.9. Что отдаёт

- 4 изменённых файла в рабочем дереве (uncommitted)
- Рапорт ~10 строк: «синк завершён, версии X→Y, cross-refs verified, lefthook C2 green, добавлены §9 в [файлы], затронуто [N] секций»
- Список любых эскалаций («нужен ручной выбор major/minor», «обнаружена коллизия с веткой Y», «cross-ref-checker красный после 3 итераций»)

---

## 4. Агент №2: `prod-deploy-validator`

### 4.1. Назначение

Pre-flight checklist перед выкатом на боевой `liderra.ru`. Возвращает вердикт `GO / NO-GO` с конкретной причиной.

### 4.2. Когда зовётся

Перед каждым выкатом — главный исполнитель просит «проверь готовность боевого». ~5-7 раз в неделю в активные периоды.

### 4.3. Входной brief (минимум)

- Что планируется выкатить (commit hash или короткое описание)
- Опционально: явный список файлов в патче (если выкат через scp, не через git)

### 4.4. 8 проверок

| # | Проверка | Команда | Зелёный = | Красный = |
|---|----------|---------|-----------|-----------|
| **П1** | `bootstrap/cache/config.php` владельца | `ssh liderra "stat -c '%U %Y' app/bootstrap/cache/config.php; stat -c '%Y' app/.env"` | владелец `www-data` И mtime ≥ mtime .env | владелец не www-data ИЛИ старее .env (квирк 107) |
| **П2** | `.env` line endings | `ssh liderra "file app/.env; md5sum app/.env"` | `ASCII text` (без CRLF) | `with CRLF line terminators` (квирк 105) |
| **П3** | Свободное место | `ssh liderra "df -h /"` | использовано ≤ 85% | > 85% |
| **П4** | Последний бэкап БД | `ssh liderra "ls -lt /var/backups/db/ \| head -2"` | mtime ≤ 24 часов назад | > 24 часов или пусто |
| **П5** | Health очереди | `ssh liderra "pgrep -fa queue:work; tail -50 app/storage/logs/laravel.log \| grep -ic -e failed -e error"` | `queue:work` процесс активен И ≤ 5 ошибок в последних 50 строках laravel.log | процесс мёртв ИЛИ > 5 ошибок |
| **П6** | nginx config | `ssh liderra "sudo nginx -t"` | `syntax is ok` + `test is successful` | любое иное |
| **П7** | fail2ban активен | `ssh liderra "sudo systemctl is-active fail2ban"` | `active` | `inactive` / `failed` |
| **П8** | Pending миграции | `ssh liderra "cd app && php artisan migrate:status \| grep -c Pending"` | 0 ИЛИ список к выкату согласован с brief'ом | необъявленные pending |

### 4.5. Процедура (5 шагов)

1. Принять brief — что выкатываем.
2. Запустить 8 проверок последовательно (параллельность по SSH не даёт большого выигрыша, sequential проще для отладки).
3. Собрать результаты в таблицу из 8 строк.
4. Применить решающее правило:
   - Все 8 зелёных → **GO** + список smoke-команд для пост-выкатной проверки
   - Хоть одна красная → **NO-GO** + причина + ссылка на квирк memory + что делать чтобы исправить
   - Любая «не смог проверить» (SSH-таймаут, неожиданный формат) → **NO-GO с эскалацией** («нужен человек, агент не угадывает»)
5. Опционально (если brief содержит `--post-smoke`): после выката повторить smoke-проверки (HTTP 200 на главной, миграция применилась, очередь жива).

### 4.6. Модель и инструменты

- **Модель:** Sonnet 4.6
- **Tools:** Bash, Read, Grep
- **Skills:**
  - `superpowers:verification-before-completion` — перед итоговым GO убедиться что все 8 проверок прогнаны (не одна пропущена)

### 4.7. Что зашиваем в system prompt

- 8 точных команд + ожидаемые форматы вывода
- Память о квирках 104-108 (с MEMORY.md цитатами):
  - 104: stale `bootstrap/cache/config.php` переживает .env-фикс
  - 105: scp Windows→Linux кладёт CRLF в .env → sqlite-fallback → 500
  - 106: `queue:work --timeout` default 60s убивает worker сам себя
  - 107: `config:cache` НЕ из-под www-data → кэширует defaults → 500 (24.05 03:46 UTC)
  - 108: NTFS junction для worktree node_modules
- Шаблон отчёта (таблица + вердикт + smoke-команды)
- SSH-настройки (читает из `~/.ssh/config`, никаких паролей в system prompt)

### 4.8. Границы (out of scope)

- Сам выкат не делает (только проверяет готовность). Выкат — главный исполнитель.
- Не трогает базу данных (только smoke-чтение).
- Не меняет конфиги на боевом.
- Не угадывает: если вывод команды не соответствует шаблону — NO-GO с эскалацией, не «возможно нормально».

### 4.9. Риски и митигации

| Риск | Митигация |
|------|-----------|
| Новый квирк, которого нет в его памяти | Любой неожиданный output → автоматически NO-GO + эскалация. Через 1-2 эпизода добавляю в его system prompt. |
| SSH-таймаут / сеть лежит | Жёсткий timeout 30 сек на проверку. Если 2+ проверки таймнули — отчёт «не смог проверить, выкат на свой риск». |
| Что-то не покрыто 8 проверками | Со временем расширяю список. Агент сам границы не двигает. |
| Ложно-положительный GO (агент пропустил проблему) | Я смотрю отчёт перед нажатием. Агент не выкатывает сам — только сообщает. |

### 4.10. Что отдаёт

- Таблица 8 строк с green/red статусом каждой проверки
- Вердикт **GO** или **NO-GO**
- Если NO-GO — конкретная причина + ссылка на квирк memory + что нужно сделать
- Если GO — список smoke-команд для пост-выкатной проверки

---

## 5. Общие архитектурные решения

### 5.1. Где живут определения агентов

Project-local в `.claude/agents/normative-sync.md` и `.claude/agents/prod-deploy-validator.md` — по образцу `.claude/agents/pest-parallel-debugger.md` и `.claude/agents/rls-reviewer.md` (прецеденты узко-специализированных проектных агентов).

### 5.2. Frontmatter каждого агента

```yaml
---
name: <slug>
description: <когда зовётся — для триггер-классификации>
tools: <ограниченный список>
model: claude-sonnet-4-6
---
```

### 5.3. Скилы которые **не** даём ни одному из этих агентов

- `brainstorming`, `writing-plans`, `executing-plans` — это исполнители, не проектировщики
- `test-driven-development`, `frontend-design`, `mcp-builder` — не их scope
- `superpowers:dispatching-parallel-agents` — они листовые, не дирижируют

### 5.4. Subagent-driven git-safety (Pravila §15.1)

Оба агента работают с git (один правит файлы → git diff отдаёт; второй делает SSH но не git). Главный исполнитель ВСЕ ЕЩЁ обязан верифицировать commit-базу (`git rev-parse HEAD`) ПОСЛЕ каждого вызова `normative-sync`-агента, до коммита его diff'а.

### 5.5. Привязка к Brain governance (Pravila §16)

- Stop-hook будет писать routing_decision и для этих агентов (provenance `user_directed_method` — главный исполнитель явно их позвал)
- `task_classification` маппинг (tools/observer-classification-map.json) расширить: `normative_sync` → узел `agent:normative-sync`; `prod_deploy_validation` → узел `agent:prod-deploy-validator`. После добавления — missed-activation детектор будет ловить случаи когда я делаю синк сам вместо вызова агента.

---

## 6. Что вне scope этого спека

- Создание агента «#3 разборщик карты наблюдателя» (отложен — частота 1-2/неделю, ROI ниже)
- Создание агента «off-phase tooling integrator» (отброшен — слишком broad для одного агента)
- Автоматическое добавление в `task_classification` маппинг (это отдельная задача brain governance)
- Замена существующих агентов `pest-parallel-debugger` / `rls-reviewer` (они работают, не трогаем)
- Какие-либо изменения нормативки (Pravila / PSR / Tooling / CLAUDE.md) для регистрации этих агентов — это произойдёт ВО ВРЕМЯ первого использования каждого агента (тогда сами агенты впишут себя в footer-счётчик, классическая dogfooding-проверка)

---

## 7. Открытые вопросы

- **OQ-1:** Должны ли агенты иметь доступ к `mcp__redis__*` / `mcp__laravel-boost__*` для расширенных pre-flight проверок? **Решение по умолчанию:** нет, минимальный tools-set; расширим если понадобится после первой недели использования.
- **OQ-2:** Нужно ли запускать `normative-sync` через TaskOutput с фоновым режимом (агент работает в фоне, я делаю что-то другое)? **Решение по умолчанию:** нет, синхронный вызов (1-2 мин ожидания не критично).
- **OQ-3:** Должен ли `prod-deploy-validator` уметь делать сам бэкап БД если П4 красная? **Решение по умолчанию:** нет, только отчёт. Действия — главный исполнитель.

---

## 8. Прецеденты в проекте

- **`.claude/agents/pest-parallel-debugger.md`** — узко-специализированный диагностический агент для Pest-quirks 72/73/77. Прецедент проектного агента с tools-restriction.
- **`.claude/agents/rls-reviewer.md`** — узко-специализированный review-агент для RLS на миграциях. Прецедент агента с явным «when to invoke».
- **`docs/superpowers/specs/2026-05-19-brain-governance-design.md`** — прецедент спека на инфраструктурное изменение через спек → план → реализация.

---

## 9. Следующий шаг

После согласования этого спека — `superpowers:writing-plans` создаст implementation plan с задачами:

1. Написать `.claude/agents/normative-sync.md` (system prompt + tools + frontmatter)
2. Написать `.claude/agents/prod-deploy-validator.md` (то же)
3. Smoke-тест №1 на dry-run (свежий синк, например post-billing-v2-spec-c)
4. Smoke-тест №2 на dry-run (pre-flight перед следующим выкатом)
5. Расширить `tools/observer-classification-map.json` двумя классификациями
6. Запись в memory `feedback_specialized_agents.md` после первой недели использования (что работает / что нет)