epic-via-subagents

name	epic-via-subagents
description	Конвейер обработки эпика: подготовка → реализация задач через сабагентов → ревью → мерж
depends_on	["run-subagent"]

Обработка эпика через сабагентов

Когда использовать

• Нужно провести эпик от todo до done через команду AI-сабагентов.
• Ты оркестратор процесса: распаковываешь эпик, назначаешь роли, запускаешь сабагентов, контролируешь результат.
• Скилл описывает полный цикл: подготовка веток, запуск сабагентов на реализацию и ревью, мерж подветок, финализация эпика. Конкретные промпты и команды — в каждом шаге.

Git Workflow

master
  └── <epic-branch>            ← создаётся от master
        ├── <task-subbranch-1>  ← от ветки эпика, draft PR → сабагент коммитит → мерж по готовности
        ├── <task-subbranch-2>  ← от ветки эпика, draft PR → сабагент коммитит → мерж по готовности
        └── <task-subbranch-N>  ← ...

Финальный PR: <epic-branch> → master.

⚠️ Критически важно: подветки задач создаются от ветки эпика, а не от master. Ветка эпика содержит весь код, который ещё не влит в master.

Как использовать

Шаг 0: Подготовка

1. Прочитай файл эпика (todo/EPIC-*.todo.md).
2. Убедись, что план реализации содержит задачи с чекбоксами [ ].
3. Если план пуст или неполон — запроси у пользователя уточнение.
4. Сформируй имя ветки эпика по шаблону <type>/<epic-id-kebab-case>.
5. Создай ветку эпика от актуального master.
6. Запиши имя ветки в поле branch файла эпика. Закоммить и запушь.
7. Убедись, что все задачи удовлетворяют Definition of Ready (см. todo/AGENTS.md).

Шаг 1: Выбор следующей задачи

1. Найди первую невыполненную задачу в плане.
2. Прочитай файл задачи.
3. Проверь depends_on — все ли зависимости выполнены.

Шаг 2: Подготовка задачи

1. Определи роль исполнителя.
2. Обнови front matter задачи: assignee, branch, status: in_progress.
3. Добавь секцию «Инструкции для сабагента» перед ## Change History:

## Инструкции для сабагента

**Ветка:** <task-subbranch> (уже создана и активна)
**PR:** уже создан (draft) из <task-subbranch> в <epic-branch> — [PR #<PR_NUMBER>](<PR_LINK>)

### Порядок действий
1. Переключись в ветку `<task-subbranch>`: `git checkout <task-subbranch>`
2. Реализуй задачу согласно описанию.
3. Следуй [Конвенциям](../../../../docs/conventions/index.md) проекта.
4. Делай промежуточные коммиты после каждого логического этапа.
5. После реализации запусти проверки: `make check`.
6. Сделай `git push`.
7. Переведи PR из draft в ready: `gh pr ready <PR_NUMBER>`.

4. Создай подветку от ветки эпика, закоммить файл задачи и сделай git push.
5. Создай draft PR из подветки в ветку эпика.
6. Обнови секцию инструкций в задаче: впиши реальный [<PR_NUMBER>](<PR_LINK>). Закоммить и сделай git push.

Шаг 3: Реализация и правки

Запусти сабагента-исполнителя.

<role-title> — заголовок роли из поля title файла роли (например, Бэкендер Левша). Файл роли передаётся через -r, путь в промпте не нужен.

Пример промпта на реализацию:

<role-title>, выполни задачу: todo/<TASK-ID>.todo.md.
Следуй инструкциям из секции 'Инструкции для сабагента' в файле задачи.

Для доработки по замечаниям ревьювера:

<role-title>, доработай задачу: todo/<TASK-ID>.todo.md по замечаниям ревьювера:
<суть замечаний>

[PR #<PR_NUMBER>](<PR_LINK>) уже существует, после правок закоммить и сделай `git push`.

Шаг 4: Анализ результата

Успех → self-review (Шаг 5). Ошибка → перезапусти с уточнением или эскалируй.

Если агент завершён по таймауту:

1. Проверь git status — есть ли незакоммиченные изменения?
2. Оцени прогресс: git diff --stat, make check 2>&1 | tail -20.
3. Сделай WIP-коммит: git add -A && git commit -m "WIP: <TASK-ID>" && git push.
4. Перезапусти с уточняющим промптом. Увеличь таймаут.
5. Если после 2 перезапусков задача не завершена — эскалируй пользователю.

Шаг 5: Self-review

Попроси ту же роль проверить своё решение. Запусти сабагента.

⚠️ Self-review обязателен для любого типа задач — код, документация, конфигурация, исследование. Исполнитель проверяет полноту и качество своей работы на соответствие критериям приёмки задачи.

Пример промпта:

<role-title>, выполни ревью своих изменений в PR [PR #<PR_NUMBER>](<PR_LINK>).
Проверь соответствие задаче: todo/<TASK-ID>.todo.md.

Если замечаний нет → запускай внешнее ревью (Шаг 6). Если есть замечания → вернись к Шаг 3 для доработки.

Шаг 6: Ревью

⚠️ Ревью обязательно для любого типа задач — код, документация, конфигурация, исследование. Выбор ревьювера зависит от сути изменений, а не от наличия кода.

1. Определи роли ревьюверов. Один из них — автор задачи (ревьювит последним). Остальных выбирай по сути изменений.
2. Запускай последовательно сабагента для каждого ревьювера. Пример промпта:

<reviewer-role-title>, выполни ревью [PR #<PR_NUMBER>](<PR_LINK>) из <task-subbranch> в <epic-branch>.
Проверь соответствие задаче: todo/<TASK-ID>.todo.md.

• Если есть замечания — выполни Шаг 3 для доработки, затем повтори ревью этой роли.

3. Повтори пункт 2 для каждого ревьювера.
4. Если все ревьюверы дали апрув → переходи к Шаг 8.

Шаг 7: Мерж PR сабагента в ветку эпика

🛑 Pre-merge checkpoint — проверь перед мержем:

• Шаг 5 (Self-review) выполнен — замечаний нет.
• Шаг 6 (Ревью) выполнен — все ревьюверы дали апрув.
• Если любой из шагов пропущен — остановись и вернись к пропущенному.

1. Убедись, что сабагент запушил код и перевёл PR в ready.
2. Обнови файл задачи (status: done, pr: <ссылка>).
3. Отметь задачу в плане эпика: [x].
4. Перенеси задачу в todo/done/.
5. Обнови ссылки в эпике и связанных задачах.
6. Закоммить и сделай git push.
7. Смержи PR.
8. Удали подветку задачи.
9. Переходи к следующей задаче (Шаг 1).

Шаг 8: Финализация эпика

Когда все задачи эпика выполнены:

1. Убедись, что все Must Have требования в эпике закрыты.
2. Запусти финальные проверки: make check.
3. Создай финальный PR из ветки эпика в master.
4. Обнови файл эпика: status: done, pr: <ссылка на финальный PR>.
5. Отчитайся пользователю. Пример отчёта:

Эпик: <EPIC-ID> — <название>
Финальный PR: [PR #<N>](<URL>)

Критические моменты:
- <таймаут сабагента на задаче X, потребовалось 2 перезапуска>
- <ревьювер выявил проблему с архитектурой, потребовалась доработка>
- <задача Y заблокирована зависимостью, выполнена после TASK-Z>

Лимиты

Лимит	Значение
Итерации реализация → ревью → доработка	3
Перезапуски сабагента при ошибке/таймауте	2
Исчерпание лимитов	Эскалация пользователю

Таймауты сабагентов

watch-subagent.sh принимает три таймаута: -s (soft), -m (hard), -t (stall).

Soft-timeout (-s) и Hard-timeout (-m)

Сложность задачи	-s (soft)	-m (hard)
C1–C2	600 сек	auto (1200)
C3	1200 сек	auto (2400)
C4	2400 сек	4800 сек
C5+	3600 сек	7200 сек

-m можно не указывать для C1–C3: скрипт автоматически вычислит max(soft*2, 1200). Для C4+ указывай -m явно, чтобы избежать слишком раннего хард-килла.

Stall-timeout (-t)

Stall-timeout — время без единого JSONL-события, после которого агент считается зависшим. Срабатывает только если процесс реально простаивает (idle): если он активен (грузит CPU/IO — ретраит, ожидание ответа), stall не убивает, а ждёт до hard-timeout (см. WATCH_STALL_RESPECT_LIVENESS в SKILL run-subagent). По умолчанию 120 сек. Этого достаточно для реализации (C1–C3), но недостаточно для ревью: ревьювер читает много файлов, модель «думает» дольше между tool call'ами.

Тип задачи	-t (stall)
Реализация	120 сек
Self-review	180 сек
Ревью	300 сек

Пример запуска ревью:

scripts/watch-subagent.sh -s 600 -t 300 -o text,files -r docs/agents/roles/team/code_reviewer_backend_puaro.ru.md <<'PROMPT'
<prompt>
PROMPT

Обработка ошибок

Ситуация	Действие
Сабагент не завершил задачу	Повтор с уточнением, при неудаче — эскалация
Проверки падают (make check)	Доработка с указанием ошибок
3 итерации с замечаниями	Эскалация пользователю
Конфликт слияния	Решить конфликт, перезапустить сабагента
Задача заблокирована	Следующая задача, вернуться после разблокировки
Сабагент не закоммитил	Оркестратор делает коммит сам
Файл задачи не виден на подветке	Проверить, что задача закоммичена в эпик-ветку до создания подветки

Ожидаемый результат

• Все задачи эпика в статусе done, файлы в todo/done/.
• Каждая задача проведена через цикл: подготовка → реализация → self-review → ревью → доработки → мерж.
• Финальный PR из ветки эпика в master создан.