📋 Техническое задание: Агент-Архитектор (Architect Agent)

[xdevrobot]

🎯 Цель задачи

Реализовать нового агента /architect, который не выполняет задачи напрямую, а выступает в роли менеджера-оркестратора: ставит подзадачи, контролирует их выполнение, проверяет результаты, мержит изменения в отдельную ветку и формирует финальный Pull Request для человеческого ревью.

📌 Ссылка на оригинальную задачу: link-assistant/hive-mind#935

---

🧠 Концепция работы агента

┌─────────────────────────────────────────┐
│  🔹 Агент-Архитектор получает 1 задачу  │
│  (ссылка на GitHub Issue)               │
└─────────────────┬───────────────────────┘
                  ▼
┌─────────────────────────────────────────┐
│  🔹 Декомпозиция:                       │
│  • Разбивает задачу на N подзадач       │
│  • Создаёт под-используя --split-by     │
│  • Назначает метки (--label)            │
└─────────────────┬───────────────────────┘
                  ▼
┌─────────────────────────────────────────┐
│  🔹 Параллельное выполнение:            │
│  • Запускает /solve для каждой подзадачи│
│  • Использует общую ветку --base-branch│
│  • Мониторит статус через --watch       │
└─────────────────┬───────────────────────┘
                  ▼
┌─────────────────────────────────────────┐
│  🔹 Валидация и мерж:                   │
│  • Проверяет готовность каждого PR      │
│  • Выносит вердикт: approve / changes   │
│  • Мержит в feature-ветку при --minimum-approvals │
└─────────────────┬───────────────────────┘
                  ▼
┌─────────────────────────────────────────┐
│  🔹 Финальная интеграция:               │
│  • Проверяет согласованность решений    │
│  • При необходимости создаёт доп. задачи│
│  • Формирует единый итоговый PR         │
│  • Предоставляет на человеческое ревью  │
└─────────────────────────────────────────┘

---

⚙️ Конфигурация команды

/architect <issue-url> [options]

Опция	Значение по умолчанию	Описание
--depth	1	Глубина рекурсивной декомпозиции (1 = один уровень подзадач)
--split-by	2	На сколько подзадач делить одну задачу на каждом уровне
--label	"help wanted"	Метка для автоматически создаваемых подзадач
--minimum-approvals	1	Минимальное количество аппрувов для автоматического мержа под-PR
--orchestrate	false	Режим оркестрации: автоматический запуск /solve без зависимости от /hive
--base-branch	(из задачи)	Ветка, в которую мержатся все подзадачи
--use-base-issue-branch	false	Использовать ветку родительской задачи как базовую для подзадач
--auto-use-base-issue-branch	false	Автоматически определять и использовать ветку родителя
--watch	false	Режим постоянного мониторинга без перезапуска команды

---

🔄 Жизненный цикл задачи

1️⃣ Инициализация

• Архитектор получает ссылку на главную задачу
• Анализирует описание, метки, приоритет
• Определяет тип задачи: feature / bug / task / won't fix

2️⃣ Декомпозиция

• Генерирует план выполнения
• Создаёт подзадачи через GitHub API с меткой --label
• Для каждой подзадачи:
  • Указывает связь с родительской задачей
  • Назначает ветку --base-branch (общая для всех подзадач уровня)

3️⃣ Оркестрация выполнения

• Запускает /solve <sub-issue-url> --base-branch <branch> --orchestrate
• Отслеживает статус через Telegram-уведомления [#380]
• При завершении подзадачи:
  • Проверяет качество кода через review.mjs
  • Выносит вердикт через gh pr review --approve или --request-changes

4️⃣ Интеграция

• После мержа всех подзадач одного уровня:
  • Анализирует согласованность изменений
  • При конфликтах/несоответствиях создаёт корректирующие подзадачи
  • При рекурсии (--depth > 1) переходит на следующий уровень

5️⃣ Финализация

• Когда все подзадачи закрыты и мержнуты:
  • Создаёт финальный PR в основную ветку репозитория
  • Добавляет сводное описание: что сделано, какие подзадачи решены
  • Назначает ревьюверов, оставляет задачу на человеческое утверждение

---

🧩 Зависимости и предварительные требования

Перед реализацией необходимо убедиться, что реализованы:

Задача	Статус	Описание
#380	✅	Уведомления в Telegram о завершении сессии
#1193	⏳	Оркестратор CLI-команда
--base-branch в /solve	✅	Корректная работа с целевой веткой
--watch режим в /solve	⚠️	Мониторинг без перезапуска
Поддержка подзадач в GitHub	✅	Связь issue через parent/sub-issue

---

🗂️ Предлагаемая структура кода

src/
├── commands/
│   └── architect.mjs          # Основная логика команды /architect
├── agents/
│   ├── architect/
│   │   ├── planner.js         # Декомпозиция задач
│   │   ├── orchestrator.js    # Запуск и мониторинг подзадач
│   │   ├── validator.js       # Проверка результатов и ревью
│   │   └── integrator.js      # Финальный мерж и создание PR
│   └── shared/
│       ├── task-graph.js      # Граф зависимостей задач
│       └── branch-manager.js  # Управление ветками
├── utils/
│   ├── github-api.js          # Обёртка над GitHub API
│   └── pr-utils.js            # Утилиты для работы с PR
└── config/
    └── architect-defaults.js  # Значения по умолчанию для опций

---

🧪 Критерии приемки (Acceptance Criteria)

• Архитектор корректно создаёт подзадачи с указанными параметрами (--split-by, --label)
• Все подзадачи выполняются в параллельных воркерах через /solve --orchestrate
• Архитектор отслеживает завершение подзадач через Telegram-уведомления или polling GitHub API
• Автоматическое ревью под-PR с возможностью approve / request changes через gh CLI
• Мерж под-PR происходит только после достижения --minimum-approvals
• Все изменения подзадач одного уровня мержатся в единую feature-ветку (не в main)
• При --depth > 1 процесс декомпозиции рекурсивно повторяется для подзадач
• Финальный PR содержит сводку всех изменений и ссылается на все закрытые подзадачи
• Архитектор корректно обрабатывает ошибки: падение подзадачи, конфликт мержа, таймаут
• Поддерживается режим --watch для долгосрочных задач без перезапуска

---

🚀 План реализации (по этапам)

Этап 1: Прототип (MVP)

• Реализовать базовую команду /architect с парсингом аргументов
• Интеграция с GitHub API для создания подзадач
• Запуск /solve для одной подзадачи в тестовом режиме

Этап 2: Оркестрация

• Параллельный запуск нескольких воркеров
• Мониторинг статуса подзадач (polling + Telegram webhooks)
• Базовая валидация результатов

Этап 3: Ревью и мерж

• Интеграция с gh CLI для автоматического ревью PR
• Логика автоматического мержа при выполнении условий
• Обработка конфликтов и запросов на изменения

Этап 4: Рекурсия и финализация

• Поддержка --depth > 1
• Создание финального сводного PR
• Генерация отчёта о выполненной работе

Этап 5: Стабилизация

• Обработка ошибок и edge-cases
• Логирование и дебаг-информация
• Документация и примеры использования

---

🔗 Ссылки и ресурсы

• 📄 Оригинал задачи: link-assistant/hive-mind#935
• 🧪 PoC параллельного выполнения: Krol-X/NiceMusicLibrary#2
• 📚 Документация Hive Mind: xdevrobot/hive-mind
• 🤖 Telegram Bot API: core.telegram.org/bots/api
• 🛠️ GitHub CLI: cli.github.com