# APAW — Automatic Programmers Agent Workflow

**Self-Improving Agent Pipeline** — автономная система из 30+ специализированных ИИ-агентов с автоматической эволюцией промптов, мониторингом выполнения и модульной архитектурой.

Поддерживаемые стеки: **PHP/Laravel/Symfony/WordPress**, **Next.js**, **Vue/Nuxt**, **React**, **Python/Django/FastAPI**, **Go**, **Flutter**, **Node.js/Express**.

---

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

```
APAW/
├── .kilo/                           # KiloCode конфигурация
│   ├── agents/                      # 30 агентов (YAML frontmatter)
│   ├── commands/                    # Workflow команды (/pipeline, /laravel, /nextjs, /vue, etc.)
│   ├── rules/                       # Правила кодирования (атомарные задачи, модульность, токены)
│   ├── skills/                      # Специализированные навыки (PHP, Go, Node, Docker, Gitea)
│   ├── shared/                      # Общие модули (gitea-api, gitea-auth, gitea-commenting, self-evolution)
│   ├── logs/                        # Логи выполнения агентов и fitness-метрики
│   ├── capability-index.yaml        # Индекс возможностей и маршрутизация
│   ├── gitea.jsonc                  # Структура конфигурации Gitea (credentials из env)
│   ├── kilo.jsonc                   # Конфигурация primary агентов
│   └── KILO_SPEC.md                 # Спецификация агентов
├── agent-evolution/                 # Dashboard эволюции агентов
│   ├── index.standalone.html        # Standalone dashboard
│   ├── scripts/                     # Scripts синхронизации
│   ├── data/                        # История изменений
│   └── docker-compose.yml           # Docker запуск
├── scripts/                         # Utility scripts
│   └── agent-stats.ts              # Статистика выполнения агентов
├── AGENTS.md                        # Справка по агентам
├── STRUCTURE.md                     # Структура проекта
└── README.md                        # Этот документ
```

---

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

### Использование с KiloCode

```bash
# Клонировать репозиторий
git clone https://git.softuniq.eu/UniqueSoft/APAW.git

# Скопировать конфигурацию в проект
cp -r APAW/.kilo /your-project/
```

KiloCode автоматически обнаружит `.kilo/` и загрузит всех агентов.

### Запуск Dashboard эволюции

```bash
# Standalone (без Docker)
bun run sync:evolution
open agent-evolution/index.standalone.html

# Или через Docker
cd agent-evolution
docker-compose up -d
# Dashboard доступен на http://localhost:3001
```

### Мониторинг агентов

```bash
# Статистика выполнения за 30 дней
bun run agent:stats

# За последнюю неделю
bun run agent:stats:week

# По конкретному проекту
bun run agent:stats --project UniqueSoft/my-shop
```

---

## Команда агентов (30+)

### Планирование и Анализ

| Агент | Модель | Назначение |
|-------|--------|------------|
| `@orchestrator` | GLM-5 | Главный диспетчер, маршрутизация задач |
| `@requirement-refiner` | GLM-5 | Идеи → User Stories |
| `@history-miner` | Nemotron-3-Super | Поиск дублей в git |
| `@system-analyst` | GLM-5 | Схемы БД, API контракты |
| `@planner` | Nemotron-3-Super | Декомпозиция задач (CoT/ToT) |
| `@capability-analyst` | GLM-5 | Gap analysis |

### Разработка

| Агент | Модель | Назначение |
|-------|--------|------------|
| `@lead-developer` | Qwen3-Coder 480B | Основной код по TDD |
| `@frontend-developer` | Qwen3-Coder 480B | UI компоненты |
| `@backend-developer` | Qwen3-Coder 480B | Node.js/Express APIs |
| `@php-developer` | Qwen3-Coder 480B | PHP/Laravel/Symfony/WordPress |
| `@python-developer` | Qwen3-Coder 480B | Python/Django/FastAPI |
| `@go-developer` | Qwen3-Coder 480B | Go/Gin/Echo APIs |
| `@flutter-developer` | Qwen3-Coder 480B | Flutter mobile apps |
| `@devops-engineer` | Nemotron-3-Super | Docker, K8s, CI/CD |

### Качество

| Агент | Модель | Назначение |
|-------|--------|------------|
| `@sdet-engineer` | Qwen3-Coder 480B | TDD Red Phase |
| `@code-skeptic` | MiniMax-m2.5 | Adversarial ревью |
| `@the-fixer` | MiniMax-m2.5 | Исправление багов |
| `@performance-engineer` | Nemotron-3-Super | N+1, утечки памяти |
| `@security-auditor` | Nemotron-3-Super | OWASP Top 10, CVE |

### Релиз и Метрики

| Агент | Модель | Назначение |
|-------|--------|------------|
| `@release-manager` | GLM-5 | Git Flow, SemVer |
| `@evaluator` | GLM-5 | Оценка агентов 1-10 |
| `@pipeline-judge` | GLM-5 | Объективный fitness score |
| `@prompt-optimizer` | GLM-5 | Улучшение промптов |
| `@product-owner` | GLM-5 | Управление Issues |

### Когнитивное усиление

| Агент | Паттерн | Назначение |
|-------|---------|------------|
| `@reflector` | Reflexion | Анализ ошибок |
| `@memory-manager` | Memory Arch | Управление контекстом |

---

## Pipeline Workflow

```
[Issue в целевом проекте] 
   ↓
[@requirement-refiner] → User Story + Acceptance Criteria
   ↓
[@history-miner] → Проверка дублей
   ↓
[@system-analyst] → Схемы БД, API контракты
   ↓
[@sdet-engineer] → TDD Red Phase (тесты падают)
   ↓
[@lead-developer] / [@php-developer] → TDD Green Phase
   ↓
[@code-skeptic] → Adversarial review
   ↓ (fail)            ↓ (pass)
[@the-fixer]          [@performance-engineer]
   ↓                      ↓
   ─────────────────→ [@security-auditor]
                           ↓
                       [@release-manager]
                           ↓
                       [@evaluator] → Score 1-10
                           ↓ (score ≥ 7)
                       [@pipeline-judge] → Fitness 0.0-1.0
                           ↓
                       fitness ≥ 0.85 → COMPLETED
                       fitness < 0.85 → [@prompt-optimizer] → evolving
```

---

## Критические правила

### Целевой проект (НЕ APAW!)

**Issues создаются в целевом проекте, а НЕ в APAW.** APAW — фреймворк агентов, а не проект по умолчанию.

```bash
# Автоопределение проекта из git remote
TARGET_REPO=$(git remote get-url origin | sed 's:/*$::' | sed -E 's|.*[:/]([^/]+/[^/]+?)(\.git)?$|\1|')
```

### Атомарные задачи (1 действие = 1 задача)

Каждый вызов агента решает ровно ОДНУ атомарную задачу:
- ❌ "Реализуй весь бэкенд интернет-магазина"
- ✅ "Создай модель Product с миграцией"
- ✅ "Добавь POST /api/products endpoint"

### Модульный код

- Максимум 100 строк на файл
- Максимум 30 строк на функцию
- Фичи организованы как независимые модули
- Коммуникация между модулями — только через events/interfaces

### Бюджет токенов

| Размер задачи | Макс. токенов | Пример |
|-------------|-------------|---------|
| Tiny | 2,000 | Исправить опечатку |
| Small | 5,000 | Модель + миграция |
| Medium | 10,000 | API endpoint + тест |
| Large | 20,000 | Сервис с 3 методами |

---

## Конфигурация

### Models (kilo.jsonc)

Primary агенты для UI:
- `orchestrator` — GLM-5 (главный диспетчер)
- `code` — Qwen3-Coder 480B (быстрый код)
- `ask` — GLM-5 (вопросы по коду)
- `plan` — Nemotron-3-Super (планирование)
- `debug` — GLM-5 (диагностика)

Subagent модели определены в `.md` файлах агентов.

### Capability Index (capability-index.yaml)

Карта возможностей для маршрутизации:
- `code_writing` → `lead-developer`
- `code_review` → `code-skeptic`
- `test_writing` → `sdet-engineer`
- `php_web_development` → `php-developer`
- `laravel_development` → `php-developer`
- `wordpress_development` → `php-developer`
- `python_web_development` → `python-developer`
- `django_development` → `python-developer`
- `fastapi_development` → `python-developer`
- `nextjs_development` → `frontend-developer`
- `vue_nuxt_development` → `frontend-developer`
- `security` → `security-auditor`
- и т.д.

---

## Эволюция агентов

Система автоматически отслеживает:
- Изменения моделей
- Оценки производительности
- Fitness score (объективные метрики)
- Рекомендации по улучшению
- Логи выполнения каждого агента

```bash
# Синхронизировать данные
bun run sync:evolution

# Открыть dashboard
bun run evolution:open

# Статистика агентов
bun run agent:stats
```

---

## Skills System

Навыки в `.kilo/skills/`:

### PHP
- `php-laravel-patterns` — Laravel routing, Eloquent, middleware, queues
- `php-symfony-patterns` — Symfony controllers, services, Doctrine
- `php-wordpress-patterns` — WordPress plugins, themes, REST API
- `php-security` — OWASP, CSRF, XSS, SQL injection
- `php-testing` — PHPUnit, Pest, Dusk
- `php-modular-architecture` — Modules, packages, service separation

### Frontend (Next.js / Vue / React)
- `nextjs-patterns` — Next.js 14+ App Router, Server Components, Server Actions, Auth.js
- `vue-nuxt-patterns` — Vue 3 / Nuxt 3 Composition API, Pinia, Nitro, SSR
- `react-patterns` — React 18+ hooks, Context, TanStack Query, React Hook Form

### Python
- `python-django-patterns` — Django models, DRF, services, repositories
- `python-fastapi-patterns` — FastAPI async, Pydantic, SQLAlchemy, dependencies

### Инфраструктура
- `gitea-workflow` — Gitea интеграция (автодетекция проекта)
- `gitea-commenting` — Автоматические комментарии
- `agent-logging` — Логирование выполнения агентов

### Docker / БД
- `docker-compose`, `docker-swarm`, `docker-security`, `docker-monitoring`
- `postgresql-patterns`, `sqlite-patterns`, `clickhouse-patterns`

### Go / Node
- `go-web-patterns`, `go-middleware`, `go-testing`, `go-security`
- `nodejs-express-patterns`, `nodejs-auth-jwt`, `nodejs-security-owasp`

### Тестирование / Анализ
- `web-testing`, `visual-testing`, `playwright`
- `research-cycle`, `planning-patterns`, `task-analysis`
- `quality-controller`, `scoped-labels`

---

## Workflow Commands

| Команда | Назначение |
|---------|------------|
| `/pipeline <issue>` | Полный пайплайн для issue |
| `/laravel` | Laravel приложение |
| `/wordpress` | WordPress сайт/плагин |
| `/feature` | Разработка фичи |
| `/commerce` | E-commerce сайт |
| `/booking` | Бронирование |
| `/blog` | Блог |
| `/hotfix` | Срочное исправление |
| `/status <issue>` | Статус пайплайна |
| `/evolve` | Цикл эволюции |
| `/plan` | Планирование задач |
| `/debug` | Диагностика багов |
| `/ask` | Вопросы по коду |
| `/code` | Быстрый код |
| `/research` | Исследование |

---

## Gitea аутентификация

Все Gitea API вызовы используют централизованную аутентификацию через `.kilo/shared/gitea-auth.md`. **Никогда не хардкодьте credentials в коде.**

### Порядок резолва

1. **`GITEA_TOKEN`** env var → используется напрямую (предпочтительно)
2. **`GITEA_USER` + `GITEA_PASS`** → создание временного токена через Basic Auth
3. **`.env` файл** → чтение переменных из .env
4. **Ошибка `ValueError`** → если credentials отсутствуют (не silent fail)

### Конфигурация

| Переменная | Обязательна | Описание |
|------------|-------------|----------|
| `GITEA_API_URL` | Нет | API URL (default: `https://git.softuniq.eu/api/v1`) |
| `GITEA_TOKEN` | Предпочтительно | API токен |
| `GITEA_USER` | Fallback | Username для Basic Auth |
| `GITEA_PASS` | Fallback | Password для Basic Auth |
| `GITEA_TARGET_REPO` | Нет | Переопределение проекта |

### .env шаблон

```bash
# .env (НИКОГДА не коммитьте этот файл!)
GITEA_API_URL=https://git.softuniq.eu/api/v1
GITEA_TOKEN=your-api-token-here
# GITEA_USER=your-username
# GITEA_PASS=your-password
# GITEA_TARGET_REPO=Owner/RepoName
```

См. `.kilo/gitea.jsonc` — структура конфигурации, `.kilo/shared/gitea-auth.md` — функции аутентификации.

---

## Мониторинг выполнения

Каждый вызов агента логируется в `.kilo/logs/agent-executions.jsonl`:

```jsonl
{"ts":"2026-04-18T14:00:00Z","agent":"php-developer","issue":42,"project":"UniqueSoft/my-shop","task":"Create Product model","subtask_type":"model_creation","duration_ms":45000,"tokens_used":8500,"status":"success","files":["app/Models/Product.php"],"score":8,"next_agent":"code-skeptic"}
```

```bash
# Статистика агентов
bun run agent:stats

# За неделю
bun run agent:stats:week

# По проекту
bun run agent:stats:project --project UniqueSoft/my-shop
```

---

## Технический стек

| Layer | Technology |
|-------|------------|
| Runtime | TypeScript / Node.js / Bun |
| Agent Runtime | KiloCode VS Code Extension |
| Version Control | Gitea + Git Flow |
| Languages | TypeScript / PHP / Python / Go / Dart |
| Testing | TDD (Red-Green-Refactor), PHPUnit, Pest |
| Containerization | Docker / Docker Compose |

---

## Статус проекта

✅ Production Ready  
✅ 30 агентов  
✅ Self-improving pipeline с fitness scoring  
✅ Gitea интеграция с автодетекцией проекта  
✅ Agent Evolution Dashboard  
✅ Мониторинг выполнения агентов  
✅ PHP/Laravel/Symfony/WordPress поддержка  
✅ Next.js / Vue/Nuxt / React поддержка  
✅ Python/Django/FastAPI поддержка  
✅ Атомарные задачи и модульная архитектура  
🆕 **v2026-05-07 — Evolution Round: Kilo Code Release Sync**  
- 🔒 **Subagent Cascade Prevention** — `task[*]=deny` + `task[subagent]=deny` для всех агентов  
- 🛡️ **Bash Hardening** — разрешённый allowlist, `ask` по умолчанию  
- 📦 **Session Persistence** — checkpoint после каждой фазы, `.kilo/logs/checkpoints/{issue}-{phase}.json`  
- 🌳 **Worktree Isolation** — агенты работают в отдельных git worktree без затрагивания `dev`  
- 🧠 **Per-Agent Reasoning** — `reasoning_effort` (`xhigh`/`high`/`medium`/`low`) для каждого агента  
- 🐳 **MCP Cleanup** — `--rm` для Docker MCP, orphaned process cleanup  
- ✅ **Config Validation** — валидация `kilo.jsonc` перед стартом pipeline  

---

*APAW (Automatic Programmers Agent Workflow) — 2026*