# AI Agent 24/7 Automation System

Автоматизированная система разработки с использованием AI агентов, которые работают круглосуточно над проектом mnemo_cards.

## Обзор

Система состоит из трех типов агентов:

1. **Planning Agent** - анализирует проект и создает список задач
2. **Development Agent** - читает задачи, пишет код, делает коммиты
3. **Test & Deploy** - тестирует изменения и деплоит на staging

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

```
┌─────────────────────────────────────────────────────────────┐
│                    GitHub/Forgejo Actions                    │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐ │
│  │   Planning   │───▶│ Development  │───▶│ Test/Deploy  │ │
│  │    Agent     │    │    Agent     │    │              │ │
│  └──────────────┘    └──────────────┘    └──────────────┘ │
│         │                   │                    │          │
│         ▼                   ▼                    ▼          │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Cursor CLI (AI Provider)                │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                              │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
              ┌────────────────────────┐
              │  Project Repository    │
              │  - mnemo_cards_web_v2  │
              │  - mnemo_cards_backend │
              │  - mnemo_cards_common  │
              └────────────────────────┘
```

## Компоненты

### 1. Task Management

Файлы состояния для каждого компонента:

```
ai_docs/agent/
├── web_v2/
│   ├── task_list.json      # Список задач
│   └── agent_state.json    # Состояние агента
├── backend/
│   ├── task_list.json
│   └── agent_state.json
├── common/
│   ├── task_list.json
│   └── agent_state.json
└── global_lock.json        # Глобальная блокировка
```

### 2. Python Scripts

Оркестрация и управление агентами:

```
tools/agent/
├── config.py                    # Конфигурация
├── task_manager.py              # Менеджер задач
├── cursor_cli_wrapper.py        # Wrapper для Cursor CLI
├── agent_orchestrator.py        # Главный оркестратор (development)
└── planning_agent.py            # Planning агент
```

### 3. Prompts

Инструкции для агентов:

```
ai_docs/agent/prompts/
├── development_prompt.md        # Инструкции для development агента
└── planning_prompt.md           # Инструкции для planning агента
```

### 4. GitHub Actions Workflows

```
.github/workflows/
├── agent-planning.yml           # Planning workflow
├── agent-development.yml        # Development workflow
└── agent-test-deploy.yml        # Test & Deploy workflow
```

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

### 1. Настройка Forgejo Runner

```bash
# Установка Forgejo Runner
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

# Регистрация runner
# Получите registration token из Forgejo: Settings -> Actions -> Runners
sudo forgejo-runner register --no-interactive \
  --instance https://your-forgejo-instance.com \
  --token YOUR_REGISTRATION_TOKEN \
  --name ai-agent-runner \
  --labels ubuntu-latest:docker://node:16-bullseye

# Запуск runner (или через systemd)
sudo forgejo-runner daemon
```

### 2. Настройка Cursor CLI

```bash
# Установка Cursor CLI (на машине runner или автоматически в workflows)
curl https://cursor.com/install -fsS | bash

# Получение API ключа
# 1. Откройте Cursor
# 2. Settings -> Account -> API Keys
# 3. Create new API key
```

### 3. Настройка Secrets в Forgejo

Добавьте следующие secrets в настройках репозитория:
**Repository Settings -> Secrets and Variables -> Actions**

- `CURSOR_API_KEY` - API ключ от Cursor (обязательно)
- `FORGEJO_TOKEN` - Personal Access Token для Forgejo API (обязательно, scopes: repo, write:issue, write:workflow)
- `CURSOR_MODEL` - Модель AI (опционально, по умолчанию claude-3-5-sonnet-20241022)
- `MAX_ITERATIONS` - Максимум итераций (опционально, по умолчанию 10)
- `MAX_RETRIES` - Максимум попыток (опционально, по умолчанию 3)

### 3. Запуск Planning Agent

1. Перейдите в **Actions** в вашем репозитории
2. Выберите workflow **"AI Agent - Planning"**
3. Нажмите **"Run workflow"**
4. Выберите компонент (web_v2, backend, или common)
5. Нажмите **"Run workflow"**

Planning agent:
- Проанализирует текущее состояние проекта
- Создаст список задач в `ai_docs/agent/{component}/task_list.json`
- Создаст issue с summary
- Автоматически запустит Development Agent

### 4. Проверка настройки

Создайте тестовый workflow или проверьте:

```bash
# Проверьте что runner запущен
sudo systemctl status forgejo-runner

# Проверьте secrets через Forgejo UI
# Repository -> Settings -> Secrets and Variables -> Actions

# Проверьте что .github/workflows/ содержит файлы
ls -la .github/workflows/
```

### 5. Запуск Development Agent

Development agent запускается автоматически после Planning Agent, или можно запустить вручную:

1. Actions -> **"AI Agent - Development"**
2. Run workflow -> выбрать компонент
3. Agent начнет работу над задачами

**Примечание**: Убедитесь что Forgejo Runner запущен и online перед запуском workflows!

## Как это работает

### Planning Agent Workflow

1. **Анализ**: Читает `tasks.md`, `workflow_state.md`, текущий `task_list.json`
2. **Генерация**: Использует Cursor CLI для создания нового task list
3. **Валидация**: Проверяет корректность JSON и структуры задач
4. **Коммит**: Сохраняет task_list.json в репозиторий
5. **Запуск**: Триггерит Development Agent

### Development Agent Workflow

1. **Инициализация**: Загружает task list и agent state
2. **Выбор задачи**: Берет следующую pending задачу по приоритету
3. **Блокировка**: Проверяет, нужна ли глобальная блокировка
4. **Выполнение**: 
   - Использует Cursor CLI для написания кода
   - Запускает линтер
   - Запускает тесты
   - Делает коммит с описанием изменений
5. **Обновление**: Обновляет статус задачи и agent state
6. **Повтор**: Берет следующую задачу или завершается

### Test & Deploy Workflow

1. **Триггер**: Автоматически запускается после коммитов
2. **Обнаружение**: Определяет, какие компоненты изменились
3. **Тестирование**: 
   - Запускает flutter/dart analyze
   - Запускает тесты
   - Собирает coverage
4. **Результат**: 
   - ✅ Если тесты прошли - готово к деплою
   - ❌ Если тесты не прошли - создает issue

## Multi-Agent Support

Система поддерживает параллельную работу нескольких агентов:

```bash
# Агент 1: работает над web_v2
Actions -> Planning -> web_v2
  └─> Development -> web_v2

# Агент 2: одновременно работает над backend
Actions -> Planning -> backend
  └─> Development -> backend
```

### Координация агентов

- **Per-component locking**: Каждый агент блокирует только свой компонент
- **Global lock**: Если задача модифицирует `mnemo_cards_common`, берется глобальная блокировка
- **Conflict resolution**: Перед коммитом делается git pull --rebase

## Мониторинг и отладка

### Просмотр состояния агента

```bash
# Web v2
cat ai_docs/agent/web_v2/agent_state.json

# Backend
cat ai_docs/agent/backend/agent_state.json
```

### Просмотр текущих задач

```bash
# Web v2
cat ai_docs/agent/web_v2/task_list.json

# Backend
cat ai_docs/agent/backend/task_list.json
```

### Логи workflow

1. Actions -> выберите workflow run
2. Посмотрите логи каждого step
3. В summary будет краткий отчет

### Ручной запуск на локальной машине

```bash
# Установите переменные окружения
export CURSOR_API_KEY="your-key-here"
export PROJECT_ROOT="/path/to/mnemo_cards"

# Planning agent
python tools/agent/planning_agent.py web_v2

# Development agent
python tools/agent/agent_orchestrator.py web_v2
```

## Ограничения и safety

### Автоматические ограничения

- **Max iterations**: 10 итераций за один запуск
- **Timeout**: 6 часов на workflow run
- **Max retries**: 3 попытки на задачу
- **Stale lock**: Блокировка считается устаревшей через 2 часа

### Что агенты НЕ могут делать

❌ Удалять .git директорию  
❌ Force push  
❌ Модифицировать production secrets  
❌ Деплоить на production (только staging)  
❌ Удалять файлы без причины  

### Безопасность

- Все коммиты проверяются через Test workflow
- Агенты не имеют доступа к production secrets
- Изменения можно ревьюить через Git history
- Можно откатить любой коммит

## Troubleshooting

### Агент не запускается

1. Проверьте, что `CURSOR_API_KEY` настроен в Secrets
2. Проверьте, что Cursor CLI установлен (в логах workflow)
3. Проверьте, что task_list.json существует и валиден

### Тесты не проходят

1. Агент попробует исправить 3 раза
2. После 3 попыток создается issue
3. Агент переходит к следующей задаче

### Агент "завис"

1. Agent state показывает "in_progress" более 2 часов
2. Запустите новый workflow - он сбросит состояние
3. Или вручную отредактируйте agent_state.json

### Конфликты коммитов

1. Агент делает `git pull --rebase` перед коммитом
2. Если конфликт - задача помечается skipped
3. Planning agent переназначит задачу позже

## Best Practices

### Для человека-разработчика

1. ✅ Обновляйте `tasks.md` с новыми фичами
2. ✅ Ревьюите коммиты от агентов
3. ✅ Запускайте Planning Agent раз в неделю
4. ❌ Не редактируйте task_list.json вручную (используйте tasks.md)
5. ❌ Не коммитьте в те же файлы, над которыми работает агент

### Для Planning Agent

- Создавайте задачи на 2-8 часов работы
- Разбивайте большие фичи на подзадачи
- Указывайте четкие acceptance criteria
- Правильно выставляйте dependencies

### Для Development Agent

- Всегда пишите тесты
- Следуйте существующим паттернам кода
- Не оставляйте TODOs
- Делайте атомарные коммиты

## Примеры использования

### Сценарий 1: Добавление новой фичи

1. Добавьте описание фичи в `mnemo_cards_web_v2/tasks.md`
2. Запустите Planning Agent для web_v2
3. Planning Agent создаст задачи
4. Development Agent автоматически начнет работу
5. Мониторьте прогресс в Actions
6. Ревьюйте коммиты от агента

### Сценарий 2: Исправление багов

1. Создайте issue с описанием бага
2. Запустите Planning Agent
3. Planning Agent добавит задачу в task list
4. Development Agent исправит баг
5. Test workflow проверит, что баг исправлен

### Сценарий 3: Рефакторинг

1. Опишите план рефакторинга в tasks.md
2. Запустите Planning Agent
3. Agent создаст задачи для рефакторинга
4. Development Agent выполнит рефакторинг поэтапно
5. Все тесты должны продолжать проходить

## Особенности Forgejo

### Отличия от GitHub Actions

1. **API endpoints**: Используется Forgejo API вместо GitHub API
2. **Actions**: Некоторые GitHub Actions могут не работать, используются альтернативы
3. **Secrets**: Настраиваются через Forgejo UI (Settings -> Secrets and Variables -> Actions)
4. **Runner**: Требует установки и настройки Forgejo Runner
5. **Workflows**: Синтаксис совместим, но используется `.github/workflows/` (не `.forgejo/workflows/`)

### Forgejo API для триггера workflows

```bash
# Trigger Planning Agent
curl -X POST \
  "https://your-forgejo.com/api/v1/repos/user/repo/actions/workflows/agent-planning.yml/dispatches" \
  -H "Authorization: token YOUR_FORGEJO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ref":"master","inputs":{"component":"web_v2"}}'

# Trigger Development Agent
curl -X POST \
  "https://your-forgejo.com/api/v1/repos/user/repo/actions/workflows/agent-development.yml/dispatches" \
  -H "Authorization: token YOUR_FORGEJO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ref":"master","inputs":{"component":"web_v2"}}'
```

### Создание Issues через API

```bash
# Create issue
curl -X POST \
  "https://your-forgejo.com/api/v1/repos/user/repo/issues" \
  -H "Authorization: token YOUR_FORGEJO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Issue title","body":"Issue body","labels":["ai-agent"]}'
```

## Дополнительная информация

- [Конфигурация](./CONFIGURATION.md) - детальная настройка системы для Forgejo
- [Forgejo Actions Docs](https://forgejo.org/docs/latest/user/actions/) - документация Forgejo Actions
- [Cursor CLI Docs](https://cursor.com/docs/cli/headless) - документация Cursor CLI
- [Development Prompt](./prompts/development_prompt.md) - инструкции для разработки
- [Planning Prompt](./prompts/planning_prompt.md) - инструкции для планирования

## Контакты и поддержка

При проблемах:
1. Проверьте логи в Actions
2. Посмотрите agent_state.json
3. Создайте issue с тегом `ai-agent`

---

**Версия:** 1.0  
**Дата:** 2025-11-20  
**Powered by:** Cursor CLI + Claude Sonnet 4.5