docs: add team workflow guide — how to work with dev agent profiles

2026-10-21 23:02:35 +03:00
parent f7936fa882
commit 6cdccc85c5
1 changed files with 158 additions and 0 deletions
@@ -0,0 +1,158 @@
+# awg-dash: Руководство по работе с командой разработки
+
+> Команда состоит из 5 агентов Hermes с изолированными профилями.
+> Репозиторий: `embeddevio/awg-dash` (Gitea)
+> MCP сервер: `http://127.0.0.1:8100/mcp`
+
+---
+
+## 1. Роли
+
+| Роль | Профиль | Запуск | Ответственность |
+|------|---------|--------|-----------------|
+| **TechLead** | `techlead-agent` | `hermes --profile techlead-agent chat` | Архитектура, декомпозиция эпиков, контроль качества, мерж, релизы |
+| **Backend** | `backend-engineer` | `hermes --profile backend-engineer chat` | REST API, бизнес-логика, модели, unit-тесты |
+| **Frontend** | `frontend-engineer` | `hermes --profile frontend-engineer chat` | UI/UX, дашборды, e2e-тесты |
+| **QA** | `qa-engineer` | `hermes --profile qa-engineer chat` | Тест-планы, автотесты, регресс, security |
+| **DevOps** | `devops` | `hermes --profile devops chat` | CI/CD, Docker, деплой, мониторинг |
+
+Маршрутизация: при создании issue с лейблом `backend`/`frontend`/`qa`/`devops`/`epic` Hermes направляет задачу соответствующему профилю автоматически.
+
+---
+
+## 2. Быстрый старт
+
+```bash
+# Запустить TechLead агента (отвечает за архитектуру и координацию)
+tmux new-session -d -s techlead 'hermes --profile techlead-agent chat'
+
+# Подключиться к сессии
+tmux attach -t techlead
+
+# Когда нужен бэкенд — запустить в другом окне
+tmux new-session -d -s backend 'hermes --profile backend-engineer chat'
+
+# Остальные профили по мере необходимости
+tmux new-session -d -s frontend 'hermes --profile frontend-engineer chat'
+tmux new-session -d -s qa 'hermes --profile qa-engineer chat'
+tmux new-session -d -s devops 'hermes --profile devops chat'
+```
+
+---
+
+## 3. Процесс разработки
+
+```
+TechLead: Эпик → Subtasks with AC
+    ├── Backend: API + тесты → PR
+    ├── Frontend: UI компоненты → PR
+    ├── QA: Тест-план → e2e → Review PRs
+    ├── DevOps: CI/CD + деплой в staging
+    └── TechLead: Code Review → Merge (если все gates зелёные)
+```
+
+### 3.1 Эпик (создаёт TechLead)
+
+1. Зайти в профиль TechLead: `hermes --profile techlead-agent chat`
+2. Дать задачу. Агент создаст issue с лейблом `epic`.
+3. В теле issue — GIVEN/WHEN/THEN acceptance criteria.
+4. Агент создаст задачи-потомки с лейблами ролей.
+
+**ID лейблов (использовать числа, не строки):**
+
+| ID | Лейбл |
+|----|-------|
+| 1 | `epic` |
+| 2 | `backend` |
+| 3 | `frontend` |
+| 4 | `devops` |
+| 5 | `qa` |
+| 6 | `blocker` |
+| 7 | `release` |
+| 8 | `hotfix` |
+
+### 3.2 Разработка (Backend / Frontend)
+
+1. Зайти в профиль (`hermes --profile backend-engineer chat`).
+2. Сообщить номер issue — агент сам прочитает задачу.
+3. Агент создаёт ветку `feat/N-slug`, пишет код, тесты, открывает PR.
+4. **Важно:** агент не сливает PR. Только TechLead мержит.
+
+### 3.3 QA
+
+1. Зайти в профиль QA: `hermes --profile qa-engineer chat`
+2. Попросить проверить PR #N. Агент прочитает diff, напишет тест-план, выполнит тесты.
+3. Результат — комментарий на PR с pass/fail.
+
+### 3.4 DevOps
+
+1. Зайти в профиль DevOps: `hermes --profile devops chat`
+2. Сообщить о мерже — агент собирает образ, деплоит в staging.
+
+### 3.5 Code Review и Merge (TechLead)
+
+**Gate для мержа:**
+- [ ] CI зелёный (lint + тесты)
+- [ ] coverage ≥ 70%
+- [ ] Security scan — low/none
+- [ ] QA approve
+- [ ] Хотя бы 1 review от владельца роли
+
+**Gate для релиза:**
+- [ ] Все задачи эпика закрыты
+- [ ] Regression pass
+- [ ] Smoke tests green
+- [ ] Документация обновлена
+
+---
+
+## 4. Labels reference
+
+Можно установить лейбл через Gitea MCP:
+
+```
+issue_write(method='add_labels', owner='embeddevio', repo='awg-dash',
+  issue_number=N, labels=[2])  # backend
+```
+
+---
+
+## 5. Создание задачи вручную
+
+```python
+# Через MCP инструмент
+mcp__gitea__issue_write(
+  method='create',
+  owner='embeddevio',
+  repo='awg-dash',
+  title='Frontend: status indicator',
+  body='**AC:** GIVEN tunnel active WHEN page loads THEN green indicator shown',
+  labels=[3]  # frontend
+)
+```
+
+---
+
+## 6. Правила для всех
+
+- Все операции с репозиторием — только через MCP (не curl, не shell git).
+- Никто не пушит в `main` напрямую.
+- Никто не сливает свой PR (кроме TechLead после прохождения gates).
+- PR #1 (TechLead bootstrap) — не мержить, это шаблоны и конфиги.
+- Если задача кажется непонятной — агент откроет issue с уточняющими вопросами.
+- Критическая проблема → лейбл `blocker` → TechLead подключается.
+
+---
+
+## 7. Переключение между профилями
+
+```bash
+# Из текущей сессии можно выйти (/exit) и зайти в другой профиль
+# Или через отдельный tmux:
+
+tmux new-session -d -s backend 'hermes --profile backend-engineer chat'
+tmux attach -t backend
+
+# Просмотр запущенных сессий агентов
+tmux ls
+```