docs: update README with full APAW pipeline documentation

- Add complete agent table with models and specializations - Add State Machine workflow diagram - Add installation instructions - Add PromptOps versioning explanation - Add efficiency scoring documentation
2026-04-01 14:50:01 -04:00
parent dc1f040d9e
commit 238964abf6
1 changed files with 206 additions and 26 deletions
--- a/README.md
+++ b/README.md
@@ -1,33 +1,213 @@
-# KiloCode Agent Pipeline
+# APAW — Automatic Programmers Agent Workflow

-This repository contains the complete configuration and system prompts for the KiloCode 14-agent autonomous IT office pipeline.
+**KiloCode Agent Pipeline** — полная конфигурация автономного ИТ-офиса из 14 специализированных ИИ-агентов для плагина KiloCode (VS Code).

-## Structure
+Система спроектирована как **Self-Healing Repository**: агенты автоматически анализируют Issues в Gitea, пишут код, тестируют, проводят ревью и деплоят, не переписывая одно и то же дважды благодаря встроенной памяти коммитов.

- `.kilocodemodes` - Main configuration file for Agent Manager
- `.kilocode/agents/` - System prompts for all 14 roles
- `.kilocode/rules/` - Global coding rules
- `.kilocode/logs/` - Evaluation logs
- `packages/opencode/src/kilocode/agent-manager/` - TypeScript integration scripts
+---

-## Agents
+## Структура репозитория

-1. **Requirement Refiner** (Kimi-k2-thinking)
-2. **Orchestrator** (GLM-5)
-3. **History Miner** (Gemini-3-Flash)
-4. **System Analyst** (GPT-OSS 120B)
-5. **Product Owner** (Qwen3.5 122B)
-6. **Lead Developer** (DeepSeek-v3.2)
-7. **Frontend Dev** (Kimi-k2.5)
-8. **The Fixer** (MiniMax-m2.7)
-9. **SDET Engineer** (Qwen3-Coder-Next)
-10. **Code Skeptic** (GPT-OSS 120B)
-11. **Performance Engineer** (Nemotron-3-Super)
-12. **Security Auditor** (GLM-4.7)
-13. **Release Manager** (Devstral-2 123B)
-14. **Performance Evaluator** (GPT-o3)
-15. **Prompt Optimizer** (Claude 4.5)
+```
+.
+├── .kilocodemodes                          # Конфигурация режимов для KiloCode
+├── .kilocode/
+│   ├── agents/                             # Системные промпты (личности агентов)
+│   │   ├── requirement-refiner.md          # Агент 1: Уточнитель требований
+│   │   ├── orchestrator.md                 # Агент 2: Оркестратор (мозг системы)
+│   │   ├── history-miner.md                # Агент 3: Архивариус Git-истории
+│   │   ├── system-analyst.md               # Агент 4: Системный аналитик
+│   │   ├── product-owner.md                # Агент 5: Менеджер чек-листов
+│   │   ├── lead-dev.md                     # Агент 6: Ведущий разработчик
+│   │   ├── frontend-dev.md                 # Агент 7: Frontend-разработчик
+│   │   ├── the-fixer.md                    # Агент 8: Итеративный исправитель
+│   │   ├── sdet-engineer.md                # Агент 9: Инженер по тестированию (TDD)
+│   │   ├── code-skeptic.md                 # Агент 10: Критик кода
+│   │   ├── performance-engineer.md         # Агент 11: Инженер производительности
+│   │   ├── security-auditor.md             # Агент 12: Аудитор безопасности
+│   │   ├── release-manager.md              # Агент 13: Менеджер релизов
+│   │   ├── evaluator.md                    # Агент 14: Оценщик эффективности
+│   │   └── prompt-optimizer.md             # Агент 15: Оптимизатор промптов
+│   ├── rules/
+│   │   └── global.md                       # Глобальные правила для всех агентов
+│   └── logs/
+│       └── efficiency_score.json           # История оценок эффективности агентов
+└── packages/
+    └── opencode/
+        └── src/
+            └── kilocode/
+                └── agent-manager/          # TypeScript-интеграция с KiloCode
+                    ├── index.ts            # Загрузчик конфигурации агентов
+                    ├── workflow.ts         # State Machine пайплайна
+                    ├── router.ts           # Маршрутизатор между агентами
+                    ├── prompt-loader.ts    # Динамическая загрузка промптов
+                    ├── git-ops.ts          # Git-операции (история, коммиты)
+                    ├── evaluator.ts        # Логика оценки эффективности
+                    └── types.ts            # TypeScript-типы системы
+```

-## Workflow
+---

-The pipeline follows a strict state machine managed by the Orchestrator, moving from requirements refinement through design, implementation, testing, review, and release, with a built-in self-improvement loop via the Evaluator and Prompt Optimizer.
+## Состав команды (14 агентов)
+
+### Блок А: Вход и Планирование
+
+| # | Роль | Модель | Специализация |
+|---|------|--------|---------------|
+| 1 | **Requirement Refiner** | Kimi-k2-thinking | Транслирует задачи в строгие технические чек-листы |
+| 2 | **Orchestrator** | GLM-5 | Главный диспетчер, управляет State Machine |
+| 3 | **History Miner** | Gemini-3-Flash | Сканирует git log, предотвращает дублирование работы |
+
+### Блок Б: Проектирование
+
+| # | Роль | Модель | Специализация |
+|---|------|--------|---------------|
+| 4 | **System Analyst** | GPT-OSS 120B | Создаёт схемы БД, TypeScript-интерфейсы и API-контракты |
+| 5 | **Product Owner** | Qwen3.5 122B | Управляет чек-листами в Issues и статусными лейблами |
+
+### Блок В: Производство
+
+| # | Роль | Модель | Специализация |
+|---|------|--------|---------------|
+| 6 | **Lead Developer** | DeepSeek-v3.2 | Пишет основной код (Go / Node.js) по TDD-спецификации |
+| 7 | **Frontend Dev** | Kimi-k2.5 | UI-компоненты, мультимодальный анализ скриншотов |
+| 8 | **The Fixer** | MiniMax-m2.7 | Итеративно исправляет баги после тестов и ревью |
+
+### Блок Г: Контроль Качества
+
+| # | Роль | Модель | Специализация |
+|---|------|--------|---------------|
+| 9 | **SDET Engineer** | Qwen3-Coder-Next | Пишет падающие тесты до реализации (TDD Red Phase) |
+| 10 | **Code Skeptic** | GPT-OSS 120B | Ищет race conditions, уязвимости, логические дыры |
+| 11 | **Performance Engineer** | Nemotron-3-Super | Проверяет на N+1, утечки памяти, блокировки event loop |
+| 12 | **Security Auditor** | GLM-4.7 | OWASP Top 10, SQL-инъекции, XSS, CVE в зависимостях |
+
+### Блок Д: Релиз и Самообучение
+
+| # | Роль | Модель | Специализация |
+|---|------|--------|---------------|
+| 13 | **Release Manager** | Devstral-2 123B | SemVer, Git Flow, мердж только при Green Build |
+| 14 | **Performance Evaluator** | GPT-o3 | Оценивает эффективность каждого агента по шкале 1-10 |
+| 15 | **Prompt Optimizer** | Claude 4.5 | Анализирует ошибки и переписывает системные промпты |
+
+---
+
+## Жизненный цикл задачи (State Machine)
+
+```
+[Пользователь] -> Requirement Refiner -> Orchestrator
+                                              |
+                    +-------------------------+
+                    v                         v
+             History Miner            (если дубль -> закрыть)
+                    |
+                    v
+             System Analyst
+                    |
+                    v
+             SDET Engineer (Red Phase: тесты падают)
+                    |
+                    v
+             Lead Developer (Green Phase: тесты проходят)
+                    |
+                    v
+             Code Skeptic ---- замечания ---> The Fixer --+
+                    |                                      |
+                    +--------------------------------------+
+                    | (Approve)
+                    v
+             Performance Engineer -- проблемы -> The Fixer
+                    | (OK)
+                    v
+             Security Auditor -- уязвимости -> The Fixer
+                    | (OK)
+                    v
+             Release Manager (SemVer + Merge)
+                    |
+                    v
+             Performance Evaluator (оценка 1-10)
+                    |
+                    v
+             Prompt Optimizer (если оценка < 7 -> улучшить промпт)
+                    |
+                    v
+             Product Owner (закрывает Issue)
+```
+
+---
+
+## Установка и использование
+
+### 1. Скопируйте файлы в ваш проект
+
+```bash
+git clone https://git.softuniq.eu/UniqueSoft/APAW.git
+cp -r APAW/.kilocode /your-project/
+cp APAW/.kilocodemodes /your-project/
+```
+
+### 2. Откройте проект в VS Code с установленным KiloCode
+
+KiloCode автоматически обнаружит файл `.kilocodemodes` и загрузит все 14 режимов агентов.
+
+### 3. Выберите режим в KiloCode
+
+В выпадающем меню выбора режима появятся все агенты. Начните с **Requirement Refiner**, введя описание задачи на естественном языке.
+
+---
+
+## PromptOps: Эволюция промптов через Git
+
+Все системные промпты хранятся в `.kilocode/agents/` и версионируются через Git:
+
+- **Отслеживать эволюцию** — `git diff` покажет изменения, сделанные Prompt Optimizer
+- **Откатывать изменения** — `git checkout` вернёт предыдущую версию промпта
+- **Анализировать обучение** — частые коммиты в промпт означают, что агент требует доработки
+
+Пример коммита от Prompt Optimizer:
+
+```
+chore(ai-brain): optimize Lead Dev prompt based on Issue #142 failures
+
+- Added: "Always check type compatibility in index.d.ts before implementation"
+- Reason: 4 fix iterations due to TypeScript interface mismatches
+```
+
+---
+
+## Оценка эффективности
+
+Файл `.kilocode/logs/efficiency_score.json` хранит историю оценок по каждому Issue:
+
+```json
+{
+  "version": "1.0",
+  "history": [
+    {
+      "issue": 142,
+      "date": "2026-03-31T10:30:00Z",
+      "agents": {
+        "requirement-refiner": 8,
+        "lead-developer": 6,
+        "code-skeptic": 9
+      },
+      "iterations": 3,
+      "duration_hours": 2.5
+    }
+  ]
+}
+```
+
+---
+
+## Технический стек
+
+- **Оркестрация**: Node.js / TypeScript (Agent Manager)
+- **Интеграция**: KiloCode VS Code Extension
+- **Версионирование**: Gitea + Git Flow
+- **Язык разработки**: Go / Node.js (основные проекты)
+- **Тестирование**: TDD (Red-Green-Refactor)
+
+---
+
+*Разработано в рамках проекта APAW (Automatic Programmers Agent Workflow) — 2026*