task-via-subagents

name	task-via-subagents
description	Конвейер обработки одиночной задачи: подготовка → реализация через сабагента → self-review → code review → доработка → commit/push → PR → merge.
depends_on	["run-subagent"]

Обработка одиночной задачи через сабагентов

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

• Нужно провести одну задачу от todo до done через команду AI-сабагентов.
• Задача не входит в эпик (или эпик не требует общей ветки).
• Ты оркестратор процесса: подготавливаешь задачу, запускаешь сабагента-исполнителя, контролируешь self-review и code review, коммитишь, создаёшь PR, мержишь.

Git Workflow

main
  └── task/<short-description>    ← создаётся от main
        └── (одна ветка, один PR)

Финальный PR: task/<short-description> → main.

Hotfix: для срочных исправлений используй ветку hotfix/x.y.z-<short-description> от production tag vX.Y.Z, а не от main. База PR — main. Остальной конвейер тот же.

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

Шаг 0: Проверка готовности

1. Прочитай файл задачи (todo/TASK-*.todo.md).
2. Убедись, что задача удовлетворяет Definition of Ready (см. todo/AGENTS.md):
   • Заполнены type, value, complexity, priority, author, created.
   • Есть постановка, контекст, scope, критерии приёмки.
   • depends_on — все зависимости выполнены (файлы зависимых задач лежат в todo/done/).
3. Если задача не готова — остановись, запроси уточнение у пользователя.

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

1. Определи роль исполнителя исходя из сути задачи.
2. Предложи пользователю: кто, какая роль. Формат:

   «Предлагаю взять в работу TASK-... — <Роль>. Подтверждаешь?»

3. Получи подтверждение.
4. Обнови front matter задачи: assignee, status: in_progress.
5. Создай ветку task/<short-description> от актуального main.
6. Запиши имя ветки в поле branch.
7. Закоммить и запушь.

Шаг 2: Реализация

Запусти сабагента-исполнителя через скилл run-subagent.

<role-title> — заголовок роли из поля title файла роли (например, Бэкендер Левша).

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

<role-title>, выполни задачу: todo/<TASK-ID>.todo.md.
Реализуй в текущей ветке task/<short-description>.
Следуй [Конвенциям](../../../../docs/conventions/index.md) проекта.
После реализации запусти проверки: `make check`.
НЕ делай коммит — я сделаю сам.

⚠️ Сабагент НЕ коммитит и НЕ пушит. Тимлид контролирует git.

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

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

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

1. Проверь git status — есть ли незакоммиченные изменения?
2. Оцени прогресс: git diff --stat, vendor/bin/phpunit 2>&1 | tail -5.
3. Перезапусти с уточняющим промптом. Увеличь таймаут.
4. Если после 2 перезапусков задача не завершена — эскалируй пользователю.

Шаг 4: Self-review

🛑 Self-review обязателен. Не пропускай этот шаг.

Запусти сабагента-исполнителя для self-review:

<role-title>, выполни self-review своих изменений в текущей ветке task/<short-description>.
Проверь соответствие задаче: todo/<TASK-ID>.todo.md.
Проверь: полноту реализации, соблюдение конвенций, качество тестов, edge cases.
Если есть замечания — сформулируй конкретные Change Request'ы.
Если всё ок — дай подтверждение.

• Замечаний нет → запускай code review (Шаг 5).
• Есть замечания → вернись к Шаг 2 для доработки, передав замечания в промпте:

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

Затем повтори self-review (Шаг 4).

Шаг 5: Code Review

🛑 Code review обязателен. Не пропускай этот шаг.

1. Определи роль ревьювера исходя из сути изменений.
   • Выбирай ревьювера, компетентного в области задачи.
2. Запусти сабагента-ревьювера:

<reviewer-role-title>, проведи code review изменений в ветке task/<short-description>.
Задача: todo/<TASK-ID>.todo.md.
Проверь: соответствие требованиям задачи, архитектурную чистоту, безопасность,
качество тестов, соблюдение конвенций.
Если есть замечания — сформулируй конкретные Change Request'ы с файлом и строкой.
Если всё ок — дай Approval.
Важно: НЕ исправляй код сам — только укажи замечания.

3. Ревьювер дал Approval → переходи к Шаг 6.
4. Есть замечания → вернись к Шаг 2 для доработки, передав замечания:

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

Затем повтори code review (Шаг 5).

Шаг 6: Коммит, Push, PR

Note: При сабагент-конвейере self-review и code review уже пройдены на Шагах 4–5, до создания PR. Статус review в front matter можно пропустить — задача переводится сразу в done.

🛑 Pre-commit checkpoint — проверь перед коммитом:

• Шаг 4 (Self-review) выполнен — замечаний нет.
• Шаг 5 (Code review) выполнен — Approval получен.
• make check — зелёный.
• Если любой из шагов пропущен — остановись и вернись к пропущенному.

1. Закоммить все изменения (Conventional Commits, см. docs/git-workflow/commits.md).
2. Обнови файл задачи: status: done, pr: '#<NUMBER>'.
3. Перенеси задачу в todo/done/: git mv todo/<TASK-ID>.todo.md todo/done/<TASK-ID>.todo.md.
4. Обнови ссылки в Epic и связанных задачах (если есть).
5. Закоммить и запушь.
6. Создай PR через gh pr create (см. docs/git-workflow/pull-request.md):
   • --base main
   • --label "pi" (или другая метка AI-агента)
   • Body: постановка, изменения, ключевые решения, результаты review, проверки.
7. Отчитайся пользователю: номер PR, краткое саммари.

Шаг 7: Merge и финализация

1. После подтверждения пользователя — мержи PR: gh pr merge <N> --squash --delete-branch.
   • Merge без обхода --admin: PR создаётся от GitHub App (идентичность агента), Approve ставит владелец. Настройка — Идентичность агента.
2. Переключись на main: git checkout main && git pull origin main.
3. Проверь: git status — working tree должен быть чистым.
4. Удали рабочую ветку (если не удалена автоматически).
5. Отчитайся пользователю об итогах и предложи следующую задачу.

Лимиты

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

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

Сложность задачи	Таймаут
C1–C2	600 сек
C3	1200 сек
C4	2400 сек
C5+	3600 сек

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

Ситуация	Действие
Сабагент не завершил задачу	Повтор с уточнением, при неудаче — эскалация
Тесты/Psalm падают	Доработка с указанием ошибок
3 итерации с замечаниями	Эскалация пользователю
Остались незакоммиченные изменения	Тимлид делает коммит сам
Self-review пропущен	🛑 Вернись и выполни. Это не опционально.
Code review пропущен	🛑 Вернись и выполни. Это не опционально.

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

• Задача в статусе done, файл в todo/done/.
• Задача проведена через цикл: подготовка → реализация → self-review → code review → доработки → PR → merge.
• PR слит в main, ветка удалена.