# APAW — Automatic Programmers Agent Workflow

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

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

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

---

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

```
.
├── .claude/                                # Claude Code runtime
│   ├── commands/                           # 14 slash-команд (/project:*)
│   ├── rules/                              # Глобальные правила кодирования
│   └── logs/                               # История оценок агентов
├── .kilo/                                  # KiloCode plugin runtime
│   ├── agents/                             # 25 агентов (YAML frontmatter)
│   ├── commands/                           # 18 workflow команд
│   ├── skills/                             # 34+ специализированных навыка
│   ├── rules/                              # Правила кодирования
│   ├── workflows/                          # Workflow определения
│   ├── capability-index.yaml               # Индекс возможностей агентов
│   └── logs/                               # Логи эффективности
├── src/kilocode/                           # TypeScript API
├── archive/                                # Архив (устаревшие файлы)
├── AGENTS.md                               # Справка по агентам
└── README.md                               # Этот документ
```

---

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

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

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

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

| # | Роль | Модель | Специализация |
|---|------|--------|---------------|
| 5 | **System Analyst** | Qwen3.6-Plus | Создаёт схемы БД, API-контракты |
| 6 | **Product Owner** | Qwen3.6-Plus | Управляет чек-листами в Issues |
| 7 | **Capability Analyst** | GPT-OSS 120B | Gap analysis, рекомендации |
| 8 | **Workflow Architect** | GLM-5 | Создание workflow определений |

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

| # | Роль | Модель | Специализация |
|---|------|--------|---------------|
| 9 | **Lead Developer** | Qwen3-Coder 480B | Пишет основной код по TDD |
| 10 | **Backend Developer** | Qwen3-Coder 480B | Node.js/Express APIs |
| 11 | **Go Developer** | DeepSeek-v3.2 | Go/Gin/Echo APIs, concurrency |
| 12 | **Frontend Dev** | Kimi-k2.5 | UI-компоненты, мультимодальный анализ |
| 13 | **The Fixer** | MiniMax-m2.5 | Итеративно исправляет баги |

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

| # | Роль | Модель | Специализация |
|---|------|--------|---------------|
| 14 | **SDET Engineer** | Qwen3-Coder 480B | TDD Red Phase — пишет падающие тесты |
| 15 | **Code Skeptic** | MiniMax-m2.5 | Adversarial ревью кода |
| 16 | **Performance Engineer** | Nemotron-3-Super | N+1, утечки памяти, блокировки |
| 17 | **Security Auditor** | Kimi-k2.5 | OWASP Top 10, CVE в зависимостях |

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

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

### Блок Е: Когнитивное усиление (Research-Based)

| # | Роль | Паттерн | Специализация |
|---|------|---------|---------------|
| 21 | **Planner** | Chain of Thought / Tree of Thoughts | Декомпозиция сложных задач |
| 22 | **Reflector** | Reflexion | Self-reflection, анализ ошибок |
| 23 | **Memory Manager** | Memory Architecture | Контекст и эпизодическая память |

### Блок Ж: Специализированные

| # | Роль | Модель | Специализация |
|---|------|--------|---------------|
| 24 | **Browser Automation** | Qwen3-Coder 480B | E2E тесты с Playwright |
| 25 | **Visual Tester** | Qwen3-Coder 480B | Visual regression testing |
| 26 | **Markdown Validator** | GLM-5 | Валидация Markdown |

---

## Жизненный цикл задачи (State Machine)

```
[Пользователь]
      │
      ▼
┌─────────────────┐
│ Requirement     │  Вагные идеи → технические чек-листы
│ Refiner         │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ History Miner   │  Проверка дублей в git
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ System Analyst   │  Схемы БД, API-контракты
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ SDET Engineer    │  RED Phase — тесты падают
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Lead Developer   │  GREEN Phase — тесты проходят
└────────┬────────┘
         │
         ▼
┌─────────────────┐     замечания     ┌─────────────┐
│ Code Skeptic     │ ───────────────▶ │ The Fixer   │
└────────┬────────┘                   └──────┬──────┘
         │ approve                          │
         ▼                                  │
┌─────────────────┐                         │
│ Performance      │ ◀───────────────────────┘
│ Engineer         │
└────────┬────────┘
         │ approve
         ▼
┌─────────────────┐
│ Security Auditor │
└────────┬────────┘
         │ approve
         ▼
┌─────────────────┐
│ Release Manager  │  SemVer + Merge
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Evaluator        │  Оценка 1-10
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Prompt Optimizer │  Если оценка < 7
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 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/
```

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

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

```bash
git clone https://git.softuniq.eu/UniqueSoft/APAW.git
cp -r APAW/.claude /path/to/your-project/
cp -r APAW/.kilo /path/to/your-project/
```

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

```bash
# Полный цикл от идеи до релиза:
/project:pipeline добавить JWT авторизацию

# Или пошагово:
/project:refine хочу экспорт в PDF
/project:mine экспорт PDF           # Проверка дублей
/project:analyze экспорт PDF        # User story + acceptance criteria
/project:tests ...                  # TDD Red
/project:implement ...              # TDD Green
```

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

| Команда | Назначение |
|---------|-----------|
| `/project:pipeline` | Весь цикл одной командой |
| `/project:refine` | Идеи → чеклист |
| `/project:mine` | Поиск дублей в git |
| `/project:analyze` | Схемы БД, API-контракты |
| `/project:tests` | TDD — падающие тесты |
| `/project:implement` | TDD — реализация |
| `/project:skeptic` | Adversarial ревью |
| `/project:perf` | N+1, утечки, блокировки |
| `/project:fix` | Точечные исправления |
| `/project:security` | OWASP Top 10, CVE |
| `/project:release` | SemVer, gate-check, тег |
| `/project:evaluate` | Оценка агентов 1-10 |

---

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

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

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

---

## KiloCode Pipeline Agents

| Agent | Role | Model |
|-------|------|-------|
| `@RequirementRefiner` | Converts ideas to User Stories | ollama-cloud/kimi-k2-thinking |
| `@HistoryMiner` | Finds duplicates in git | ollama-cloud/gpt-oss:20b |
| `@SystemAnalyst` | Technical specifications | qwen/qwen3.6-plus:free |
| `@SDETEngineer` | TDD tests | ollama-cloud/qwen3-coder:480b |
| `@LeadDeveloper` | Primary code writer | ollama-cloud/qwen3-coder:480b |
| `@FrontendDeveloper` | UI implementation | ollama-cloud/kimi-k2.5 |
| `@BackendDeveloper` | Node.js/Express APIs | ollama-cloud/qwen3-coder:480b |
| `@GoDeveloper` | Go/Gin/Echo APIs | ollama-cloud/deepseek-v3.2 |
| `@CodeSkeptic` | Adversarial reviewer | ollama-cloud/minimax-m2.5 |
| `@TheFixer` | Bug fixes | ollama-cloud/minimax-m2.5 |
| `@PerformanceEngineer` | Performance review | ollama-cloud/nemotron-3-super |
| `@SecurityAuditor` | Vulnerability scan | ollama-cloud/kimi-k2.5 |
| `@ReleaseManager` | Git operations | ollama-cloud/qwen3-coder:480b |
| `@Evaluator` | Effectiveness scoring | ollama-cloud/gpt-oss:120b |
| `@PromptOptimizer` | Prompt improvements | qwen/qwen3.6-plus:free |
| `@ProductOwner` | Issue management | qwen/qwen3.6-plus:free |
| `@Orchestrator` | Task routing | ollama-cloud/glm-5 |
| `@Planner` | Task decomposition | ollama-cloud/gpt-oss:120b |
| `@Reflector` | Self-reflection | ollama-cloud/gpt-oss:120b |
| `@MemoryManager` | Context management | ollama-cloud/gpt-oss:120b |

---

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

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

---

## Agent Manager API

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

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

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

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

const runner = await createPipelineRunner({
  giteaToken: process.env.GITEA_TOKEN,
  giteaApiUrl: 'https://git.softuniq.eu/api/v1'
})

const result = await runner.run({
  issueNumber: 42,
  files: ['src/auth.ts']
})
```

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

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

const issue = await client.getIssue(42)
await client.setStatus(42, 'implementing')
await client.createComment(42, {
  body: '## ✅ Implementation Complete'
})
```

---

## Skills System

Система навыков в `.kilo/skills/` обеспечивает специализацию агентов:

### Backend Development

| Skill | Technology |
|-------|------------|
| `nodejs-express-patterns` | Express.js routing, middleware |
| `nodejs-auth-jwt` | JWT authentication |
| `nodejs-db-patterns` | Database operations |
| `nodejs-security-owasp` | Security best practices |
| `go-web-patterns` | Gin/Echo web framework |
| `go-db-patterns` | GORM/sqlx patterns |
| `go-concurrency` | Goroutines, channels |
| `go-modules` | Go modules management |

### Integration & Workflow

| Skill | Purpose |
|-------|---------|
| `gitea-commenting` | Gitea API integration |
| `gitea-workflow` | Workflow execution |
| `research-cycle` | Self-improvement cycle |
| `planning-patterns` | Task decomposition |

---

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

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

---

## PromptOps: Эволюция промптов

Все промпты хранятся в `.kilo/agents/` и версионируются через Git:

- **Отслеживать эволюцию** — `git diff` покажет изменения
- **Откатывать изменения** — `git checkout` вернёт предыдущую версию
- **Анализировать обучение** — частые коммиты означают необходимость доработки

---

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

| Layer | Technology |
|-------|------------|
| Runtime | Node.js / TypeScript |
| Integration | KiloCode VS Code Extension / Claude Code |
| Version Control | Gitea + Git Flow |
| Languages | TypeScript / Node.js / Go |
| Testing | TDD (Red-Green-Refactor) |

---

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