# APAW — Automatic Programmers Agent Workflow

**Dual-runtime Agent Pipeline** — полная конфигурация автономного ИТ-офиса из 13+ специализированных ИИ-агентов.

Поддерживает два runtime:
- **KiloCode** (VS Code плагин) — через `.kilo/agent/` (`@kilocode/plugin` формат)
- **Claude Code** (CLI / VS Code extension) — через `.claude/commands/`

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

---

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

```
.
├── install-apaw.sh                         # Установщик в любой проект (bash)
├── .claude/                                # Claude Code runtime
│   ├── commands/                           # 13 slash-команд (/project:*)
│   │   ├── pipeline.md                     # Полный цикл одной командой
│   │   ├── orchestrate.md                  # Диспетчер (Sonnet)
│   │   ├── refine.md                       # Уточнение требований (Sonnet)
│   │   ├── mine.md                         # Поиск дублей в git (Haiku)
│   │   ├── analyze.md                      # Системный дизайн (Opus)
│   │   ├── tests.md                        # TDD red phase (Sonnet)
│   │   ├── implement.md                    # TDD green phase (Opus)
│   │   ├── skeptic.md                      # Adversarial ревью (Sonnet)
│   │   ├── perf.md                         # Анализ производительности (Sonnet)
│   │   ├── fix.md                          # Исправление проблем (Sonnet)
│   │   ├── security.md                     # Аудит безопасности (Opus)
│   │   ├── release.md                      # Менеджер релизов (Sonnet)
│   │   ├── evaluate.md                     # Оценка агентов (Haiku)
│   │   └── optimize-prompts.md             # PromptOps авто-улучшение (Opus)
│   ├── rules/
│   │   └── global.md                       # Глобальные правила кодирования
│   └── logs/
│       └── efficiency_score.json           # История оценок агентов
├── .kilo/                                  # KiloCode plugin runtime (@kilocode/plugin)
│   ├── agent/                              # 19 агентов в формате plugin (YAML frontmatter)
│   │   ├── orchestrator.md                 # Диспетчер (GLM-5)
│   │   ├── requirement-refiner.md          # Уточнитель требований (Kimi-k2-thinking)
│   │   ├── history-miner.md                # Архивариус Git (Gemini-3-Flash)
│   │   ├── system-analyst.md               # Системный аналитик (GPT-OSS 120B)
│   │   ├── product-owner.md                # Менеджер задач (Qwen3.5 122B)
│   │   ├── lead-developer.md               # Ведущий разработчик (DeepSeek-v3.2)
│   │   ├── frontend-developer.md           # Frontend (Kimi-k2.5)
│   │   ├── the-fixer.md                    # Исправитель (MiniMax-m2.7)
│   │   ├── sdet-engineer.md                # Тестирование TDD (Qwen3-Coder-Next)
│   │   ├── code-skeptic.md                 # Критик кода (GPT-OSS 120B)
│   │   ├── performance-engineer.md         # Производительность (Nemotron-3-Super)
│   │   ├── security-auditor.md             # Безопасность (GLM-4.7)
│   │   ├── release-manager.md              # Релизы (Devstral-2 123B)
│   │   ├── evaluator.md                    # Оценщик (GPT-o3)
│   │   ├── prompt-optimizer.md             # PromptOps (Claude 4.5)
│   │   ├── ask.md                          # Knowledge agent (Gemini-3-Flash)
│   │   ├── code.md                         # Quick coder (DeepSeek-v3.2)
│   │   ├── debug.md                        # Диагностика (MiniMax-m2.7)
│   │   └── plan.md                         # Стратег (GPT-OSS 120B)
│   ├── package.json                        # @kilocode/plugin dependency
│   └── node_modules/                       # Plugin runtime
├── .kilocode/
│   ├── agents/                             # Устаревший формат (заменён .kilo/agent/)
│   ├── rules/
│   │   └── global.md                       # Глобальные правила
│   └── logs/
│       └── efficiency_score.json           # История оценок
├── src/
│   └── kilocode/
│       ├── index.ts                    # Точка входа модуля
│       └── agent-manager/              # TypeScript-интеграция с KiloCode
│           ├── index.ts                 # Загрузчик конфигурации агентов
│           ├── workflow.ts              # State Machine пайплайна
│           ├── router.ts                # Маршрутизатор между агентами
│           ├── prompt-loader.ts         # Динамическая загрузка промптов
│           ├── git-ops.ts               # Git-операции (история, коммиты)
│           ├── evaluator.ts             # Логика оценки эффективности
│           ├── gitea-client.ts          # Gitea API для логирования
│           ├── pipeline-runner.ts       # Оркестратор пайплайна
│           └── types.ts                 # TypeScript-типы системы
```

---

## Состав команды (14 агентов)

### Блок А: Вход и Планирование

| # | Роль | Модель | Специализация |
|---|------|--------|---------------|
| 1 | **Requirement Refiner** | Kimi-k2-thinking | Транслирует задачи в строгие технические чек-листы |
| 2 | **Orchestrator** | GLM-5 | Главный диспетчер, управляет State Machine |
| 3 | **History Miner** | GPT-OSS 20B | Сканирует git log, предотвращает дублирование работы |

### Блок Б: Проектирование

| # | Роль | Модель | Специализация |
|---|------|--------|---------------|
| 4 | **System Analyst** | Qwen3.6-Plus (Free) | Создаёт схемы БД, TypeScript-интерфейсы и API-контракты |
| 5 | **Product Owner** | Qwen3.6-Plus (Free) | Управляет чек-листами в Issues и статусными лейблами |

### Блок В: Производство

| # | Роль | Модель | Специализация |
|---|------|--------|---------------|
| 6 | **Lead Developer** | Qwen3-Coder 480B | Пишет основной код (Go / Node.js) по TDD-спецификации |
| 7 | **Frontend Dev** | Kimi-k2.5 | UI-компоненты, мультимодальный анализ скриншотов |
| 8 | **The Fixer** | MiniMax-m2.5 | Итеративно исправляет баги после тестов и ревью |

### Блок Г: Контроль Качества

| # | Роль | Модель | Специализация |
|---|------|--------|---------------|
| 9 | **SDET Engineer** | Qwen3-Coder 480B | Пишет падающие тесты до реализации (TDD Red Phase) |
| 10 | **Code Skeptic** | MiniMax-m2.5 | Ищет race conditions, уязвимости, логические дыры |
| 11 | **Performance Engineer** | Nemotron-3-Super | Проверяет на N+1, утечки памяти, блокировки event loop |
| 12 | **Security Auditor** | Kimi-k2.5 | OWASP Top 10, SQL-инъекции, XSS, CVE в зависимостях |

### Блок Д: Релиз и Самообучение

| # | Роль | Модель | Специализация |
|---|------|--------|---------------|
| 13 | **Release Manager** | Qwen3-Coder 480B | SemVer, Git Flow, мердж только при Green Build |
| 14 | **Performance Evaluator** | GPT-OSS 120B | Оценивает эффективность каждого агента по шкале 1-10 |
| 15 | **Prompt Optimizer** | Qwen3.6-Plus (Free) | Анализирует ошибки и переписывает системные промпты |

---

## Жизненный цикл задачи (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)
```

---

## Установка и использование

### Вариант A: Claude Code (рекомендуется)

#### Глобальная установка — команды работают во ВСЕХ проектах

```bash
git clone https://git.softuniq.eu/UniqueSoft/APAW.git
mkdir -p ~/.claude/commands ~/.claude/rules
cp APAW/.claude/commands/*.md ~/.claude/commands/
cp APAW/.claude/rules/global.md ~/.claude/rules/
# Заменить /project: на /user: во внутренних ссылках:
sed -i 's|/project:|/user:|g' ~/.claude/commands/*.md
```

После этого в **любом проекте** доступны команды `/user:pipeline`, `/user:refine` и т.д.

#### Установка в конкретный проект

```bash
git clone https://git.softuniq.eu/UniqueSoft/APAW.git
./APAW/install-apaw.sh /path/to/your-project
```

Скрипт создаёт `.claude/` в целевом проекте. Команды доступны как `/project:*`.

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

```
# Полный цикл от идеи до релиза:
/project:pipeline добавить эндпоинт авторизации через JWT
# или глобально (после глобальной установки):
/user:pipeline добавить эндпоинт авторизации через JWT

# Или пошагово:
/project:refine хочу кнопку экспорта в PDF
/project:mine экспорт PDF
/project:analyze экспорт PDF — user story + acceptance criteria
/project:tests ...
/project:implement ...
```

#### Таблица команд

| Команда | Агент | Модель | Назначение |
|---------|-------|--------|-----------|
| `/project:pipeline` | Pipeline Runner | Sonnet | Весь цикл одной командой |
| `/project:orchestrate` | Orchestrator | Sonnet | Маршрутизация по состоянию |
| `/project:refine` | Requirement Refiner | Sonnet | Вагные идеи → чеклист |
| `/project:mine` | History Miner | **Haiku** | Поиск дублей в git |
| `/project:analyze` | System Analyst | **Opus** | Схемы БД, API-контракты |
| `/project:tests` | SDET Engineer | Sonnet | TDD — пишет падающие тесты |
| `/project:implement` | Lead Developer | **Opus** | TDD — делает тесты зелёными |
| `/project:skeptic` | Code Skeptic | Sonnet | Adversarial ревью кода |
| `/project:perf` | Performance Engineer | Sonnet | N+1, утечки, блокировки |
| `/project:fix` | The Fixer | Sonnet | Точечные исправления |
| `/project:security` | Security Auditor | **Opus** | OWASP Top 10, CVE |
| `/project:release` | Release Manager | Sonnet | SemVer, gate-check, тег |
| `/project:evaluate` | Evaluator | **Haiku** | Оценка агентов 1–10 |
| `/project:optimize-prompts` | Prompt Optimizer | **Opus** | PromptOps авто-улучшение |

> Haiku = быстро и дёшево. Opus = максимальное качество. Sonnet = баланс.

---

## KiloCode Commands (Quick Actions)

| Command | Description | Model |
|---------|-------------|-------|
| `/plan` | Creates detailed task plans | ollama-cloud/qwen3-coder:480b |
| `/ask` | Answers codebase questions | openai/qwen3-32b |
| `/debug` | Analyzes and fixes bugs | ollama-cloud/gpt-oss:20b |
| `/code` | Quick code generation | ollama-cloud/qwen3-coder:480b |

## KiloCode Pipeline Agents

| Agent | Role | Model |
|-------|------|-------|
| `@RequirementRefiner` | Converts vague ideas to strict User Stories | ollama-cloud/kimi-k2-thinking |
| `@HistoryMiner` | Finds duplicates and past solutions in git | ollama-cloud/gpt-oss:20b |
| `@SystemAnalyst` | Designs technical specifications | qwen/qwen3.6-plus:free |
| `@SDETEngineer` | Writes tests following TDD | ollama-cloud/qwen3-coder:480b |
| `@LeadDeveloper` | Primary code writer | ollama-cloud/qwen3-coder:480b |
| `@FrontendDeveloper` | UI implementation with multimodal | ollama-cloud/kimi-k2.5 |
| `@CodeSkeptic` | Adversarial code reviewer | ollama-cloud/minimax-m2.5 |
| `@TheFixer` | Iteratively fixes bugs | ollama-cloud/minimax-m2.5 |
| `@PerformanceEngineer` | Reviews for performance issues | ollama-cloud/nemotron-3-super |
| `@SecurityAuditor` | Scans for vulnerabilities | ollama-cloud/kimi-k2.5 |
| `@ReleaseManager` | Git operations and deployments | ollama-cloud/qwen3-coder:480b |
| `@Evaluator` | Scores agent effectiveness | ollama-cloud/gpt-oss:120b |
| `@PromptOptimizer` | Improves agent prompts | qwen/qwen3.6-plus:free |
| `@ProductOwner` | Manages issue checklists | qwen/qwen3.6-plus:free |
| `@Orchestrator` | Routes tasks between agents | ollama-cloud/glm-5 |
| `@AgentArchitect` | Manages agent network per Kilo.ai spec | qwen/qwen3.6-plus:free |

> **Note:** For AgentArchitect, use `subagent_type: "system-analyst"` with prompt "You are Agent Architect..." (workaround for unsupported agent-architect type).

## Конфигурация разрешений агентов

Все агенты настроены для автономной работы без запросов разрешений на каждое действие:

| Агент | read | edit | write | bash | glob | grep | task |
|-------|------|------|-------|------|------|------|------|
| **orchestrator** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 15 subagents |
| **lead-developer** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | code-skeptic |
| **frontend-developer** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | deny |
| **sdet-engineer** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | lead-developer |
| **the-fixer** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | code-skeptic, orchestrator |
| **code-skeptic** | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ | the-fixer, performance-eng |
| **performance-engineer** | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ | the-fixer, security-auditor |
| **security-auditor** | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ | the-fixer, release-manager |
| **evaluator** | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | prompt-optimizer, product-owner |
| **requirement-refiner** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | history-miner, system-analyst |
| **history-miner** | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ | deny |
| **system-analyst** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | deny |
| **product-owner** | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | deny |
| **release-manager** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | evaluator |
| **prompt-optimizer** | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | deny |
| **agent-architect** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | deny |

**Категории разрешений:**
- **Code Writers** (lead-developer, frontend-developer, sdet-engineer, the-fixer) — полный доступ для написания кода
- **Reviewers** (code-skeptic, performance-engineer, security-auditor, evaluator) — только чтение, без редактирования
- **Analysts** (requirement-refiner, history-miner, system-analyst, product-owner) — чтение + создание спецификаций
- **Release Manager** — полный доступ для git-операций
- **Configurators** (prompt-optimizer, agent-architect) — полный доступ для редактирования конфигураций



---

### Вариант B: KiloCode (VS Code плагин)

```bash
git clone https://git.softuniq.eu/UniqueSoft/APAW.git
cp -r APAW/.kilocode /your-project/
cp APAW/.kilocodemodes /your-project/
```

KiloCode автоматически обнаружит `.kilocodemodes` и загрузит все режимы агентов.
Начните с **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
    }
  ]
}
```

---

## KiloCode Workflows Integration

Проект интегрирован с **KiloCode Workflows** (slash commands):

### Доступные команды

| Команда | Описание | Пример |
|---------|----------|--------|
| `/pipeline <issue>` | Запуск полного пайплайна | `/pipeline 42` |
| `/status <issue>` | Проверка статуса пайплайна | `/status 42` |
| `/evaluate <issue>` | Генерация отчёта эффективности | `/evaluate 42` |
| `/plan` | Создание детального плана | `/plan feature X` |
| `/ask` | Вопросы по кодовой базе | `/ask how does auth work` |
| `/debug` | Анализ и исправление багов | `/debug error in login` |
| `/code` | Быстрая генерация кода | `/code add validation` |

### Как использовать Pipeline

1. Откройте проект в VS Code с плагином KiloCode
2. Создайте Issue в Gitea
3. Введите `/pipeline <номер-issue>` в чате KiloCode
4. Пайплайн автоматически:
   - Получит контекст Issue
   - Проверит дубликаты в git
   - Маршрутизирует через агентов по статусу
   - Логирует прогресс в комментарии Gitea
   - Сгенерирует итоговый отчёт

### Workflow файлы

| Файл | Назначение |
|------|------------|
| `.kilo/commands/pipeline.md` | Основной workflow пайплайна |
| `.kilo/commands/status.md` | Проверка статуса |
| `.kilo/commands/evaluate.md` | Оценка эффективности |
| `.kilo/agents/*.md` | Определения агентов (subagents) |
| `.kilo/rules/*.md` | Правила кодирования |
| `.kilo/skills/gitea/` | Gitea integration skill |

### Прямой вызов агентов

Агентов можно вызывать напрямую через `@mention`:

```
@lead-developer implement authentication flow
@code-skeptic review the auth module
@security-auditor check for vulnerabilities
```

---

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

- **Оркестрация**: Node.js / TypeScript (Agent Manager)
- **Интеграция**: KiloCode VS Code Extension / Claude Code
- **Версионирование**: Gitea + Git Flow
- **Язык разработки**: TypeScript / Node.js / Go
- **Тестирование**: TDD (Red-Green-Refactor)

---

## Agent Manager API

Новый модуль `src/kilocode/` предоставляет программный API для работы с пайплайном:

### Установка

```bash
bun install
bun run build
```

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

```typescript
import { 
  PipelineRunner, 
  GiteaClient, 
  decideRouting,
  WORKFLOW_GRAPH,
  type AgentRole,
  type IssueStatus 
} from './src/kilocode/index.js'

// Инициализация пайплайна
const runner = await createPipelineRunner({
  giteaToken: process.env.GITEA_TOKEN,
  giteaApiUrl: 'https://git.softuniq.eu/api/v1',
  efficiencyThreshold: 7,
  autoLog: true
})

// Запуск пайплайна для Issue
const result = await runner.run({
  issueNumber: 42,
  files: ['src/auth.ts', 'src/user.ts'],
  testResults: { passed: 5, failed: 0 }
})

// Определение следующего агента
const decision = decideRouting({
  status: 'implementing',
  labels: ['status: implemented'],
  checklists: { completed: 3, total: 5 },
  comments: [],
  files: ['src/auth.ts']
})

console.log(decision.nextAgent) // 'code-skeptic'
```

### Gitea интеграция

```typescript
const client = new GiteaClient({
  apiUrl: 'https://git.softuniq.eu/api/v1',
  token: process.env.GITEA_TOKEN
})

client.setRepository('UniqueSoft', 'APAW')

// Получить Issue
const issue = await client.getIssue(42)

// Установить статус
await client.setStatus(42, 'implementing')

// Добавить комментарий
await client.createComment(42, {
  body: '## ✅ Implementation Complete\n\nAll tests passed.'
})

// Закрыть Issue
await client.closeIssue(42)
```

### Логирование эффективности

```typescript
await runner.logEvaluation(42, [
  { agent: 'lead-developer', score: 8, notes: 'Clean implementation' },
  { agent: 'code-skeptic', score: 7, notes: 'Found 2 minor issues' },
  { agent: 'the-fixer', score: 9, notes: 'Fixed issues quickly', iterations: 1 }
], 2, 1.5)
```

---

## Self-Improving Pipeline

Система автоматически логирует эффективность каждого агента в Gitea Issues:

1. **Pipeline Runner** запускается для каждой задачи
2. Каждый агент логирует свой прогресс в комментарии Issue
3. **Evaluator** оценивает эффективность агентов (1-10)
4. **Prompt Optimizer** получает агентов с низкими оценками (<7)
5. Промпты автоматически улучшаются на основе анализа

Журнал эффективности сохраняется в `.kilo/logs/efficiency_score.json` для аналитики.

---

## Переменные окружения

```bash
# Gitea API
GITEA_API_URL=https://git.softuniq.eu/api/v1
GITEA_TOKEN=your-token-here
```

---

## Удаление дубликатов

Если в проекте есть старые файлы в `packages/opencode/`, выполните:

```bash
sudo rm -rf packages/opencode/src/kilocode/
```

Код интегрирован в `src/kilocode/`.

---

*Разработано в рамках проекта APAW (Automatic Programmers Agent Workflow) — 2026*