APAW/README.md

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:*)
│   │   ├── pipeline.md                     # Полный цикл одной командой
│   │   ├── orchestrate.md                  # Диспетчер
│   │   ├── refine.md                       # Уточнение требований
│   │   ├── mine.md                         # Поиск дублей в git
│   │   ├── analyze.md                      # Системный дизайн
│   │   ├── tests.md                        # TDD red phase
│   │   ├── implement.md                    # TDD green phase
│   │   ├── skeptic.md                      # Adversarial ревью
│   │   ├── perf.md                         # Анализ производительности
│   │   ├── fix.md                          # Исправление проблем
│   │   ├── security.md                     # Аудит безопасности
│   │   ├── release.md                      # Менеджер релизов
│   │   ├── evaluate.md                     # Оценка агентов
│   │   └── optimize-prompts.md             # PromptOps авто-улучшение
│   ├── rules/
│   │   └── global.md                       # Глобальные правила кодирования
│   └── logs/
│       └── efficiency_score.json           # История оценок агентов
├── .kilo/                                  # KiloCode plugin runtime (@kilocode/plugin)
│   ├── agents/                             # 25 агентов (YAML frontmatter)
│   │   ├── orchestrator.md                 # Диспетчер
│   │   ├── requirement-refiner.md          # Уточнитель требований
│   │   ├── history-miner.md                # Архивариус Git
│   │   ├── system-analyst.md               # Системный аналитик
│   │   ├── product-owner.md                # Менеджер задач
│   │   ├── lead-developer.md               # Ведущий разработчик
│   │   ├── frontend-developer.md           # Frontend
│   │   ├── backend-developer.md            # Backend (Node.js)
│   │   ├── go-developer.md                 # Backend (Go)
│   │   ├── the-fixer.md                    # Исправитель
│   │   ├── sdet-engineer.md                # Тестирование TDD
│   │   ├── code-skeptic.md                 # Критик кода
│   │   ├── performance-engineer.md         # Производительность
│   │   ├── security-auditor.md             # Безопасность
│   │   ├── release-manager.md              # Релизы
│   │   ├── evaluator.md                    # Оценщик
│   │   ├── prompt-optimizer.md             # PromptOps
│   │   ├── capability-analyst.md           # Анализ возможностей
│   │   ├── agent-architect.md              # Архитектор агентов
│   │   ├── workflow-architect.md           # Архитектор workflows
│   │   ├── planner.md                      # Планировщик (CoT/ToT)
│   │   ├── reflector.md                    # Рефлексия
│   │   ├── memory-manager.md               # Управление памятью
│   │   └── ...
│   ├── commands/                           # Workflow команды (18 файлов)
│   ├── skills/                             # Специализированные навыки (34+)
│   │   ├── nodejs-*                        # Node.js навыки
│   │   ├── go-*                            # Go навыки
│   │   ├── gitea-*                         # Gitea интеграция
│   │   └── ...
│   ├── rules/                              # Правила кодирования
│   ├── workflows/                          # Workflow определения
│   ├── capability-index.yaml               # Индекс возможностей
│   └── logs/                               # Логи
├── src/
│   └── kilocode/                           # TypeScript API
│       ├── index.ts
│       └── ...
├── archive/                                # Архив (устаревшие файлы)
├── AGENTS.md                               # Справка по агентам
└── README.md                              # Этот документ

. ├── 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) │ │ ├── capability-analyst.md # Анализ возможностей │ │ ├── agent-architect.md # Архитектор агентов │ │ ├── workflow-architect.md # Архитектор workflows │ │ ├── planner.md # Планировщик (CoT/ToT) │ │ ├── reflector.md # Рефлексия │ │ └── memory-manager.md # Управление памятью │ ├── commands/ # Workflow команды (18 файлов) │ ├── skills/ # 34+ специализированных навыков │ │ ├── nodejs- # Node.js навыки (8) │ │ ├── go-* # Go навыки (8) │ │ ├── gitea-* # Gitea интеграция │ │ └── ... │ ├── rules/ # Правила кодирования │ │ ├── nodejs.md # Node.js правила │ │ ├── go.md # Go правила │ │ ├── agent-patterns.md # Паттерны агентов │ │ └── ... │ ├── workflows/ # Workflow определения │ ├── capability-index.yaml # Индекс возможностей агентов │ └── logs/ # Логи эффективности ├── src/ │ └── kilocode/ # TypeScript API ├── archive/ # Архив (устаревшие файлы) ├── AGENTS.md # Справка по агентам └── README.md # Этот документ

---

## Состав команды (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 и т.д.

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

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/

Копирует .claude/ и .kilo/ в целевой проект. Команды доступны как /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
@BackendDeveloper	Node.js/Express APIs and database	ollama-cloud/qwen3-coder:480b
@GoDeveloper	Go/Gin/Echo APIs and concurrency	ollama-cloud/deepseek-v3.2
@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
@CapabilityAnalyst	Gap analysis and recommendations	ollama-cloud/gpt-oss:120b
@WorkflowArchitect	Creates workflow definitions	ollama-cloud/glm-5
@Planner	Task decomposition (CoT/ToT)	ollama-cloud/gpt-oss:120b
@Reflector	Self-reflection and lesson extraction	ollama-cloud/gpt-oss:120b
@MemoryManager	Memory systems and context retrieval	ollama-cloud/gpt-oss:120b
@MarkdownValidator	Validates Markdown formatting	ollama-cloud/glm-5
@BrowserAutomation	E2E browser testing with Playwright	ollama-cloud/qwen3-coder:480b
@VisualTester	Visual regression testing	ollama-cloud/qwen3-coder:480b

Cognitive Enhancement Agents (Research-Based)

Agent	Pattern	Role
@Planner	Chain of Thought / Tree of Thoughts	Task decomposition
@Reflector	Reflexion	Self-reflection and mistake analysis
@MemoryManager	Memory Architecture	Context and episodic memory

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

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

Агент	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 плагин)

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

KiloCode автоматически обнаружит .kilo/ и загрузит все агенты. Начните с Requirement Refiner, введя описание задачи на естественном языке.

---

PromptOps: Эволюция промптов через Git

Все системные промпты хранятся в .kilo/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

---

Оценка эффективности

Файл .kilo/logs/efficiency_score.json хранит историю оценок по каждому Issue:

{
  "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 для работы с пайплайном:

Установка

bun install
bun run build

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

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 интеграция

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)

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

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 для аналитики.

---

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

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

---

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

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