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

2026-10-21 23:02:35 +03:00
9 changed files with 158 additions and 183 deletions
@@ -1,30 +0,0 @@
---
-name: Epic
-about: Большая задача/эпик — используйте для крупных фич и релизов
-labels: epic
---
-
-# Заголовок epica
-
-Опишите цель эпика, scope и критерии приёма.
-
-## Описание
-
-(Кратко опишите проблему/цель)
-
-## Критерии приёма (GIVEN / WHEN / THEN)
-
- GIVEN ...
- WHEN ...
- THEN ...
-
-## Артефакты
-
- OpenAPI spec (если есть)
- Proposed image tag
- Доп. доки
-
-## Дополнительно
-
-Предполагаемые owners: @backend, @devops, @qa
-Оценка: (story points)
@@ -1,16 +0,0 @@
---
-name: Release Request
-about: Запрос на релиз
-labels: release
---
-
-# Release Request
-
-Версия: 
-Image tag:
-Список PRs/links:
-CI status link:
-Test report link:
-
-Релиз в staging: [ ]
-Релиз в prod: [ ] (требует TechLead approval)
@@ -1,18 +0,0 @@
---
-name: Task
-about: Конкретная задача
-labels: task
---
-
-# Заголовок задачи
-
-Описание:
-
-Acceptance criteria:
- GIVEN
- WHEN
- THEN
-
-Owner: @
-Estimate (SP):
-Priority: low/medium/high
@@ -1,28 +0,0 @@
-# Labels for project
- name: epic
-  color: ffbf00
-  description: large feature or project
- name: backend
-  color: 0e8a16
-  description: backend related work
- name: frontend
-  color: 1d76db
-  description: frontend related work
- name: devops
-  color: e99695
-  description: infra / deployment
- name: qa
-  color: cfd3d7
-  description: testing
- name: task
-  color: ededed
-  description: generic task
- name: blocker
-  color: b60205
-  description: blocking issue
- name: release
-  color: 5319e7
-  description: release request
- name: hotfix
-  color: fbca04
-  description: urgent hotfix
@@ -1,13 +0,0 @@
-# PR Title
-
-Описание изменений:
-
-Checklist:
- [ ] CI green
- [ ] Unit tests passed
- [ ] Integration tests (mock) passed
- [ ] Coverage >= 70%
- [ ] Security scan: no high/critical findings
- [ ] Assigned reviewer(s)
-
-Ссылки на связанные issue:
@@ -1,7 +0,0 @@
-# CODEOWNERS file
-# Format: path @owner
-
-/backend/ @backend
-/frontend/ @frontend
-/devops/ @devops
-/tests/ @qa
@@ -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
+```
@@ -1,45 +0,0 @@
-# TechLead agent payload for Hermes import
-id: techlead
-persona: "TechLead‑bot проекта VPN Gateway"
-responsibilities:
-  - Руководство архитектурой и принятие релизов
-  - Декомпозиция эпиков, утверждение DoD
-  - Назначение владельцев и приоритизация задач
-  - Эскалация blocker'ов и контроль качества
-triggers:
-  - epic_created
-  - release_request
-  - blocker_over_48h
-inputs:
-  - epic_description
-  - backlog_status
-  - ci_status
-  - test_reports
-outputs:
-  - decomposed_issues
-  - release_checklist
-  - comments_on_issues_prs
-allowed_actions:
-  - create_issue
-  - update_issue
-  - add_comment
-  - set_labels
-  - assign_users
-decision_rules:
-  merge_requirements: "CI == green AND coverage >= 70% AND security_scan == low/none AND >=1 code review"
-  hotfix: "manual TechLead approval required (tag: hotfix-bypass)"
-  deploy_prod: "only after TechLead approval + smoke tests green"
-escalation:
-  delay_hours: 48
-  action: "create issue 'escalation', mention owners, propose meeting within 24h"
-required_permissions:
-  - repo: issues write
-  - repo: pull_request comment
-  - ci: read_artifacts
-observability:
-  - action_log: /var/log/hermes/techlead_actions.log
-  - metrics: [epic_to_release_days, dod_compliance_rate, escalations_count]
-config:
-  COVERAGE_THRESHOLD: 70
-  ESCALATION_DELAY_HOURS: 48
-  TECHLEAD_LOG: /var/log/hermes/techlead_actions.log
@@ -1,26 +0,0 @@
-#!/usr/bin/env bash
-# Start TechLead Hermes agent in tmux session
-set -euo pipefail
-
-TECHLEAD_LOG=${TECHLEAD_LOG:-/var/log/hermes/techlead_actions.log}
-COVERAGE_THRESHOLD=${COVERAGE_THRESHOLD:-70}
-ESCALATION_DELAY_HOURS=${ESCALATION_DELAY_HOURS:-48}
-TMUX_SESSION=${TMUX_SESSION:-techlead}
-PROFILE=${HERMES_PROFILE:-default}
-
-mkdir -p "$(dirname "$TECHLEAD_LOG")"
-
-# Start tmux session with hermes interactive chat
-if ! tmux has-session -t "$TMUX_SESSION" 2>/dev/null; then
-  tmux new-session -d -s "$TMUX_SESSION" "hermes --profile $PROFILE chat"
-  sleep 2
-  # Send initial system instruction
-  tmux send-keys -t "$TMUX_SESSION" "You are TechLead-bot. Load persona from /workspace/exports/techlead_payload.yaml and start monitoring issues with label 'epic'." C-m
-  tmux send-keys -t "$TMUX_SESSION" "COVERAGE_THRESHOLD=$COVERAGE_THRESHOLD ESCALATION_DELAY_HOURS=$ESCALATION_DELAY_HOURS TECHLEAD_LOG=$TECHLEAD_LOG" C-m
-  echo "Started tmux session '$TMUX_SESSION' with TechLead agent."
-else
-  echo "Tmux session '$TMUX_SESSION' already exists. Attach with: tmux attach -t $TMUX_SESSION"
-fi
-
-# One-shot alternative (no tmux):
-# hermes --profile $PROFILE chat -q "You are TechLead-bot. Load persona from /workspace/exports/techlead_payload.yaml and decompose epic: ..."