mnemo_cards/ai_docs/AGENT_SYSTEM_SUMMARY.md

# AI Agent 24/7 Automation System - Summary

## Что создано

Полноценная система автоматизированной разработки с использованием AI агентов для Forgejo.

## Архитектура

```
┌─────────────────────────────────────────┐
│      Forgejo Actions (Workflows)        │
├─────────────────────────────────────────┤
│                                         │
│  Planning Agent → Development Agent     │
│        ↓               ↓                │
│    Task List    →   Code Changes        │
│                        ↓                │
│                  Test & Deploy          │
│                                         │
└─────────────────────────────────────────┘
         ↓
    Cursor CLI (AI Provider)
         ↓
    Claude Sonnet 4.5
```

## Созданные файлы

### 📁 Workflows (3 файла)

1. **`.github/workflows/agent-planning.yml`**
   - Запускается вручную (workflow_dispatch)
   - Анализирует проект
   - Создает task_list.json
   - Создает issue с summary
   - Триггерит development workflow

2. **`.github/workflows/agent-development.yml`**
   - Читает задачи из task_list.json
   - Использует Cursor CLI для написания кода
   - Запускает тесты
   - Делает коммиты
   - Цикл до завершения всех задач (макс 10 итераций, 6 часов)

3. **`.github/workflows/agent-test-deploy.yml`**
   - Триггерится автоматически после push
   - Определяет измененные компоненты
   - Запускает analyze + tests для каждого
   - Готовит к деплою если тесты прошли
   - Создает issue если тесты не прошли

### 🐍 Python Scripts (5 файлов)

1. **`tools/agent/config.py`** (124 строки)
   - Конфигурация для каждого компонента
   - Пути к файлам состояния
   - Команды для тестов/линтера/сборки

2. **`tools/agent/task_manager.py`** (334 строки)
   - Класс `Task` - представление задачи
   - Класс `AgentState` - состояние агента
   - Класс `TaskManager` - работа с задачами и состоянием
   - Класс `GlobalLock` - глобальная блокировка для shared resources

3. **`tools/agent/cursor_cli_wrapper.py`** (300 строк)
   - Wrapper для Cursor CLI
   - Парсинг stream-json output
   - Отслеживание прогресса (tool calls, files modified)
   - Обработка ошибок

4. **`tools/agent/agent_orchestrator.py`** (423 строки)
   - Главный оркестратор development цикла
   - Чтение задач
   - Выполнение через Cursor CLI
   - Запуск тестов
   - Создание коммитов
   - Обработка ретраев

5. **`tools/agent/planning_agent.py`** (334 строки)
   - Planning агент
   - Анализ текущего состояния проекта
   - Генерация task_list.json через Cursor CLI
   - Валидация JSON
   - Коммит task list

### 📝 Prompts (2 файла)

1. **`ai_docs/agent/prompts/development_prompt.md`** (~400 строк)
   - Инструкции для development агента
   - Code standards (Clean Architecture, yx_state)
   - Примеры кода
   - Testing guidelines
   - DO/DON'T список

2. **`ai_docs/agent/prompts/planning_prompt.md`** (~300 строк)
   - Инструкции для planning агента
   - Формат task list
   - Priority guidelines
   - Acceptance criteria examples
   - Task ordering strategy

### 📊 State Files (7 файлов)

1. **`ai_docs/agent/web_v2/task_list.json`** - задачи для web_v2
2. **`ai_docs/agent/web_v2/agent_state.json`** - состояние агента web_v2
3. **`ai_docs/agent/backend/task_list.json`** - задачи для backend
4. **`ai_docs/agent/backend/agent_state.json`** - состояние агента backend
5. **`ai_docs/agent/common/task_list.json`** - задачи для common
6. **`ai_docs/agent/common/agent_state.json`** - состояние агента common
7. **`ai_docs/agent/global_lock.json`** - глобальная блокировка

### 📚 Documentation (4 файла)

1. **`ai_docs/agent/README.md`** (~600 строк)
   - Полная документация системы
   - Архитектура
   - Как работают агенты
   - Multi-agent support
   - Мониторинг и отладка
   - Best practices
   - Примеры использования

2. **`ai_docs/agent/CONFIGURATION.md`** (~500 строк)
   - Детальная конфигурация для Forgejo
   - Настройка Forgejo Runner
   - Настройка secrets
   - Cursor CLI setup
   - Troubleshooting
   - Мониторинг
   - Security best practices

3. **`ai_docs/agent/FORGEJO_SETUP.md`** (~400 строк)
   - Пошаговая инструкция на 15-30 минут
   - Настройка Forgejo Actions
   - Установка runner
   - Создание secrets
   - Первый запуск
   - Checklist проверки

4. **`ai_docs/agent/QUICKSTART.md`** (~200 строк)
   - Быстрый старт за 5 минут
   - Основные команды
   - Структура проекта
   - Troubleshooting
   - Советы

## Ключевые особенности

### ✅ Multi-Agent Support

- Параллельная работа нескольких агентов
- Каждый агент работает над своим компонентом (web_v2, backend, common)
- Per-component locking
- Global lock для shared resources (mnemo_cards_common)

### ✅ Cursor CLI Integration

- Использует Cursor CLI вместо прямых API вызовов
- Автоматическая оптимизация контекста
- Уважает .cursorrules
- Stream-json для отслеживания прогресса

### ✅ Forgejo Native

- Полностью адаптировано под Forgejo
- Используется Forgejo API для issues и workflow triggers
- Работает с Forgejo Runner
- Без зависимостей от GitHub

### ✅ Safety & Limits

- Максимум 10 итераций за запуск
- Timeout 6 часов
- Максимум 3 ретрая для задачи
- Автоматический git pull перед коммитом
- Stale lock detection (2 часа)

### ✅ Autonomous Operation

- Агенты работают полностью автономно
- Не требуют вмешательства человека
- Автоматический retry при ошибках
- Создание issues при критических ошибках

## Workflow процесс

### Planning Agent

1. **Trigger**: Вручную через UI или API
2. **Input**: tasks.md, workflow_state.md, agent_state.json
3. **Process**: 
   - Cursor CLI анализирует проект
   - Генерирует task_list.json
4. **Output**: 
   - Обновленный task_list.json
   - GitHub issue с summary
   - Триггер development workflow

### Development Agent

1. **Trigger**: Автоматически после planning или вручную
2. **Input**: task_list.json
3. **Process**:
   - Цикл по задачам (по приоритету)
   - Для каждой задачи:
     - Cursor CLI пишет код
     - Запускаются тесты
     - При успехе: коммит + next task
     - При ошибке: retry до 3 раз
4. **Output**:
   - Git commits с изменениями
   - Обновленный agent_state.json
   - Issues для failed tasks

### Test & Deploy

1. **Trigger**: Автоматически после push
2. **Input**: Git diff
3. **Process**:
   - Определить измененные компоненты
   - Для каждого: analyze + test
4. **Output**:
   - Test reports
   - Deployment (если тесты прошли)
   - Issues (если тесты не прошли)

## Требования

### Обязательные

- **Forgejo**: 1.20+ с Actions
- **Forgejo Runner**: установлен и запущен
- **Cursor**: активная подписка + API key
- **Python**: 3.8+
- **Flutter**: 3.24.0+ (для web_v2)
- **Dart**: 3.0+ (для backend/common)

### Secrets

- `CURSOR_API_KEY` - API ключ от Cursor
- `FORGEJO_TOKEN` - Personal Access Token для Forgejo

## Быстрый старт

### 1. Установите Runner

```bash
wget https://code.forgejo.org/forgejo/runner/releases/download/v3.3.0/forgejo-runner-3.3.0-linux-amd64
sudo mv forgejo-runner-3.3.0-linux-amd64 /usr/local/bin/forgejo-runner
sudo chmod +x /usr/local/bin/forgejo-runner
sudo forgejo-runner register --instance https://your-forgejo.com --token TOKEN
sudo forgejo-runner daemon
```

### 2. Добавьте Secrets

Repository -> Settings -> Secrets and Variables -> Actions

- `CURSOR_API_KEY`
- `FORGEJO_TOKEN`

### 3. Запустите Planning

Actions -> AI Agent - Planning -> Run workflow -> web_v2

**Готово!** Агент начнет работу.

## Документация

- **Быстрый старт**: [QUICKSTART.md](./ai_docs/agent/QUICKSTART.md)
- **Полная настройка**: [FORGEJO_SETUP.md](./ai_docs/agent/FORGEJO_SETUP.md)
- **Конфигурация**: [CONFIGURATION.md](./ai_docs/agent/CONFIGURATION.md)
- **Документация**: [README.md](./ai_docs/agent/README.md)

## Статистика

- **Всего файлов**: 21
- **Python код**: ~1500 строк
- **Workflows**: ~500 строк
- **Prompts**: ~700 строк
- **Documentation**: ~1700 строк
- **Общий объем**: ~4400 строк кода и документации

## Возможности расширения

### В будущем можно добавить:

- [ ] Telegram уведомления о прогрессе
- [ ] Dashboard для мониторинга
- [ ] Автоматические расписания (cron triggers)
- [ ] Metrics и аналитика (сколько задач выполнено, время и т.д.)
- [ ] Интеграция с CI/CD для автодеплоя
- [ ] A/B тестирование разных AI моделей
- [ ] Система приоритетов на основе бизнес-метрик
- [ ] Автоматический rollback при критических ошибках

## Лицензия

Использует:
- **Cursor CLI**: Коммерческая лицензия Cursor
- **Forgejo**: MIT License
- **Остальной код**: Собственная разработка для проекта mnemo_cards

---

**Создано**: 2025-11-20  
**Версия**: 1.0  
**Powered by**: Cursor CLI + Claude Sonnet 4.5 + Forgejo Actions