75 KiB
75 KiB
Исследование мультиагентных оркестраторов и проект собственного
Дата: 15 марта 2026
Проект: Kin — виртуальная софтверная компания
ЧАСТЬ 1: Анализ Ruflo (ex Claude Flow)
1.1 Общие сведения
- Репо: github.com/ruvnet/ruflo
- Автор: ruvnet (один разработчик)
- Звёзды: ~20K, форки: ~2.3K
- Коммиты: 5,800+, 55 alpha-итераций
- Текущая версия: v3.5.0 (февраль 2026) — первый "стабильный" релиз
- Стек: TypeScript/Node.js, WASM (Rust) для policy engine и embeddings
- Пакеты: @claude-flow/cli, claude-flow, ruflo — все три являются обёртками над @claude-flow/cli
1.2 Архитектура (заявленная)
User → Ruflo CLI/MCP → Router → Swarm → Agents → Memory → LLM Providers
↑ ↓
└──────────────── Learning Loop ←────────────────────────┘
Ключевые компоненты:
- CLI/MCP интерфейс — входная точка, 175+ MCP-тулов
- Router — маршрутизация задач к агентам, автоматический выбор модели (haiku/sonnet/opus)
- Swarm Manager — управление топологией (hierarchical, mesh, ring, star)
- Agent System — 60+ предопределённых агентов в 16 категориях
- Memory — SQLite (.swarm/memory.db), ReasoningBank с hash-based embeddings
- Hive Mind — queen/worker иерархия с "consensus" протоколами
1.3 Что РЕАЛЬНО работает (по issue tracker и коду)
Механизм запуска агентов:
- Ключевая функция:
launchClaudeCodeWithSwarmвsrc/cli/commands/swarm-new.ts - ЧТО ОНА ДЕЛАЕТ: формирует гигантский
swarmPrompt(текстовую строку) и передаёт его вclaudeCLI - ПО СУТИ: это prompt engineering — агенты "существуют" как инструкции в промпте одного Claude Code
- Файлы генерируются прямо в корень проекта (issue #398 — нет контроля output directory)
Критический баг (issue #955):
--claudeфлаг вhive-mind spawnДОКУМЕНТИРОВАН, но НЕ РЕАЛИЗОВАН- Команда спавнит "worker agent" (запись в БД), но НЕ запускает Claude Code
- Флаг молча игнорируется
Memory система:
- SQLite-based, работает
- ReasoningBank использует hash-based embeddings (не требует API) — быстрые, но примитивные
- 2-3ms latency для поиска — это хорошо
- Persistent между сессиями
GUI:
- Web UI на порту 3000 (WebSocket)
- Терминальный эмулятор в браузере
- @liamhelmer/claude-flow-ui — отдельный npm-пакет для UI
1.4 Что МАРКЕТИНГ vs РЕАЛЬНОСТЬ
| Заявлено | Реальность |
|---|---|
| 60+ специализированных агентов | Папки с CLAUDE.md промптами в .agents/skills/, по сути — шаблоны для system prompt |
| Byzantine consensus | Протокол описан, но по issue tracker - не используется в реальных сценариях |
| Neural pattern recognition | Hash-based embeddings + паттерн-матчинг, не нейросеть |
| 127 параллельных агентов (из issue #125) | Это wishlist/epic, не реализация. Реально — один claude процесс с большим промптом |
| Self-learning | Запись success/failure в SQLite + маршрутизация на основе прошлых результатов. Работает, но это не ML |
| WASM SIMD acceleration | Rust-based WASM для embeddings — реально работает, даёт скорость |
| Hive Mind | Queen = координирующий промпт, Workers = записи в БД, НЕ отдельные Claude процессы |
1.5 Что ВЗЯТЬ из Ruflo
Сильные стороны (стоит перенять):
-
MCP-интеграция — агент-оркестратор как MCP-сервер для Claude Code. Это позволяет Claude Code вызывать оркестратор как тулзу, а не наоборот. Элегантно.
-
SQLite memory с namespace — простая, надёжная, persistent. Key-value с namespace (architecture/, bugs/, decisions/) — хороший паттерн.
-
Model routing — автоматический выбор haiku для простых задач, opus для сложных. Экономит деньги.
-
Anti-drift defaults —
topology: hierarchical+maxAgents: 8+strategy: specialized. Маленькие команды с чёткими ролями дрифтят меньше. -
ADR (Architecture Decision Records) — spec-first подход, где архитектура описана в ADR-файлах и агенты обязаны следовать.
-
Hook system — pre-task/post-task хуки для автоматизации (pre: загрузить контекст, post: сохранить результат).
-
Структура .agents/skills/ — каждый агент = директория с CLAUDE.md (system prompt) + tools + config. Модульно, расширяемо.
Слабые стороны (НЕ повторять):
-
Fake parallelism — агенты не являются отдельными процессами. Это один Claude Code с большим промптом, притворяющимся несколькими агентами. ГЛАВНАЯ ПРОБЛЕМА — контекст всё равно один, compaction убивает всех одновременно.
-
Over-engineering — 215 MCP tools, 87 в wiki, byzantine consensus — для одного разработчика это красные флаги. Много surface area, мало глубины.
-
Размытие ответственности пакетов — 3 npm-пакета (@claude-flow/cli, claude-flow, ruflo) — это один и тот же код. Ребрендинг создаёт путаницу.
-
Нет реальной изоляции контекста — это ключевое. Если агент-программист и агент-тестировщик живут в одном контексте, compaction убивает нюансы обоих.
-
Документация как продукт — README и Wiki описывают фичи, которые не реализованы (issue #955). Доверять нельзя.
ЧАСТЬ 2: Анализ других фреймворков (ключевые выводы)
2.1 CrewAI (Python)
- Модель: Role-based crews + Event-driven Flows
- Сильное: Быстрое прототипирование, MCP + A2A поддержка, 44K+ GitHub stars
- Слабое: Ограниченный checkpointing, роли через prompt engineering (не настоящая изоляция)
- Для нас: Flows (event-driven оркестрация поверх crews) — хорошая концепция
2.2 LangGraph (Python)
- Модель: Directed graph с conditional edges, checkpointing
- Сильное: Лучшая в индустрии persistence/state, time-travel debug
- Слабое: Высокий порог входа, привязка к LangChain экосистеме
- Для нас: Концепция checkpointing + graph-based flow
2.3 Claude Agent SDK
- Модель: Tool-use chain с sub-agents
- Сильное: Нативная интеграция с Claude, safety-first
- Слабое: Только Claude модели, лёгкий на оркестрацию
- Для нас: Lifecycle hooks
2.4 Нативные субагенты Claude Code
- Как работают:
claude -p "task" --session-id "id"запускает ОТДЕЛЬНЫЙ процесс - КЛЮЧЕВОЕ: Это РЕАЛЬНАЯ изоляция контекста! Каждый субагент — отдельное контекстное окно
- Ограничение: Нет координации "из коробки", нет shared memory, нет PM-слоя
ЧАСТЬ 3: Архитектура Kin (наш проект)
3.1 Ключевой принцип
Каждый агент = отдельный Claude Code процесс с изолированным контекстом. Compaction в рамках одного агента не убивает нюансы, потому что его контекст маленький и специализированный. PM-агент держит мета-уровень, а не весь код.
3.2 Живая иерархия с динамической маршрутизацией
Не pipeline (A→B→C→D), а живая организация: каждый уровень понимает свою зону ответственности и собирает нужную команду под задачу.
[Ты (Михаил)] ← человеческая речь, свободная форма:
│ "клиент пишет что фильтры глючат на айфоне когда быстро тыкаешь"
│ "нужен агрегатор туров, чтобы парсить предложения"
│ "что у меня горит?"
│ "посмотри что там с NeverDNS, давно не трогали"
▼
[Intake-менеджер] — УМНЫЙ агент (Sonnet), НЕ код на Python.
│ Почему агент, а не код:
│ - Клиент пишет "фильтры глючат на айфоне когда быстро тыкаешь"
│ → код не поймёт нюанс "быстро тыкаешь" = race condition
│ → агент переформулирует для команды
│ - Ты пишешь "посмотри что там с NeverDNS"
│ → это не задача, это запрос на статус + возможно ревью
│ → агент разберётся
│
│ Что делает:
│ 1. Понимает контекст (ты — директор и продажник, клиенты через тебя)
│ 2. Определяет проект, тип задачи, срочность
│ 3. Задаёт уточняющие вопросы если надо
│ 4. Формулирует задачу на языке команды
│ 5. Для простых запросов (статус) — SQL к БД, без агентов
│ 6. Для задач — маршрутизирует к нужному PM проекта
│ 7. Для новых проектов — запускает цепочку research → design → architecture
│
│ Его контекст: список проектов + статусы (из БД, маленький)
│ НЕ знает: код, архитектуру, детали — только "кто чем занимается"
│
├── [PM:vdolipoperek] ── знает проект ГЛУБОКО
│ │ Что знает: модули, tech stack, decisions, грабли, текущий статус
│ │ Что умеет: декомпозировать задачу, выбрать нужных специалистов
│ │ Его контекст: decisions + modules + текущие tasks (из БД)
│ │
│ │ Intake передаёт: "Баг: фильтры поиска не применяются при
│ │ быстром переключении на iOS Safari.
│ │ Источник: жалоба клиента. Приоритет: высокий."
│ │
│ │ PM думает: "фильтры — это модуль search. iOS Safari —
│ │ у нас уже была decision #15 про position:fixed.
│ │ Нужен дебагер на модуль search."
│ │
│ │ ┌─── [Дебагер] ← описание бага + код модуля + decision #15
│ │ │ │ ищет проблему
│ │ │ │ нашёл: "race condition в async фильтре"
│ │ │ ▼
│ │ │ [Тестировщик] ← найденный баг + модуль
│ │ │ │ regression test, подтверждает баг
│ │ │ ▼
│ │ │ [Фронтендер] ← баг + тест + spec модуля
│ │ │ │ фиксит, тест проходит
│ │ │ ▼
│ │ └─── [PM] ← результат. Записывает decision:
│ │ "race condition в SearchFilters — debounce + AbortController"
│ │ → Intake сообщает тебе → ты сообщаешь клиенту
│ │
│ │ Другой пример: "добавить оплату на сайт"
│ │ PM: "новый модуль, нужна полная команда"
│ │
│ │ ┌─── [Маркетолог] ← "платежи на сайте турагентства"
│ │ │ │ исследует: как конкуренты делают checkout,
│ │ │ │ какие conversion-паттерны, trust signals
│ │ │ ▼
│ │ │ [UX-дизайнер] ← research маркетолога + brief
│ │ │ │ проектирует: user flow оплаты, wireframes
│ │ │ ▼
│ │ │ [Архитектор] ← UX flow + brief + все decisions проекта
│ │ │ │ spec: модули, API, БД, интеграция с платёжкой
│ │ │ ▼
│ │ │ [Безопасник] ← spec (PCI DSS для платежей!)
│ │ │ │ security requirements
│ │ │ ▼
│ │ │ [Бэкендер] ← spec + security reqs (параллельно!)
│ │ │ [Фронтендер] ← spec + UX wireframes
│ │ │ ▼
│ │ │ [Ревьюер] + [Тестировщик] + [Безопасник]
│ │ └─── [PM] ← всё готово, decisions обновлены
│ │
├── [PM:sharedbox] ── знает свой проект так же глубоко
│ └── (своя динамическая команда)
│
├── [PM:neverdns] ── знает: готов, в маркетинг-фазе
│ └── (маркетолог, копирайтер, SEO — другая команда!)
│
└── ... (остальные проекты)
[Для НОВЫХ проектов — отдельная цепочка:]
Intake: "нужен агрегатор туров"
│
├── [Бизнес-аналитик] ← хотелки + контекст (турагентство)
│ │ исследует: бизнес-модель, монетизация, целевая аудитория
│ │ может спавнить:
│ │ [Исследователь рынка] ← конкуренты, ниша
│ │ [Исследователь API] ← какие API поставщиков туров есть
│ │ [Исследователь юридики] ← лицензии, договора
│ ▼
├── [UX-дизайнер] ← research + хотелки
│ │ user journey, wireframes ключевых страниц
│ │ смотрит конкурентов, лучшие практики
│ ▼
├── [Маркетолог] ← research + UX
│ │ стратегия продвижения, SEO, механики удержания
│ │ что учесть при разработке для маркетинга
│ ▼
├── [Архитектор] ← research + UX + marketing reqs
│ │ project_blueprint: модули, tech stack, план
│ │ учитывает существующий стек (Vue/Nuxt)
│ ▼
└── Создаётся проект в БД → назначается PM → работа начинается
3.3 Типы задач и маршруты (PM выбирает динамически)
PM проекта — это не тупой маршрутизатор, это агент, который ПОНИМАЕТ задачу. Но чтобы понимал хорошо, ему нужны "шаблоны маршрутов" как подсказки:
# В промпте PM: "ты знаешь эти типы задач и кого вызывать"
routes:
debug:
description: "Найти и исправить баг"
typical_flow:
- debugger: "найди причину, опиши"
- tester: "напиши regression test, подтверди баг"
- developer: "исправь, тест должен пройти"
pm_decides:
- какой модуль затронут (из знания проекта)
- frontend или backend баг
- нужен ли security review (если баг в auth/payments)
feature:
description: "Новая фича"
typical_flow:
- architect: "спроектируй"
- developer: "реализуй" (может быть несколько параллельно)
- reviewer: "проверь"
- tester: "протестируй"
pm_decides:
- масштаб (один компонент или новый модуль)
- нужен ли architect (мелкая фича → сразу developer)
- параллелить ли frontend/backend
refactor:
description: "Рефакторинг существующего кода"
typical_flow:
- architect: "оцени scope, предложи план"
- developer: "рефактори по плану"
- tester: "прогони существующие тесты"
pm_decides:
- затрагивает ли другие модули
- нужна ли миграция данных
security_audit:
description: "Проверка безопасности"
typical_flow:
- security: "проверь по OWASP"
- developer: "исправь найденное"
- security: "подтверди исправления"
new_project:
description: "Создание нового проекта с нуля"
typical_flow:
- analyst: "исследуй рынок, конкурентов, API"
- architect: "спроектируй на основе исследования"
- pm: "декомпозируй blueprint на задачи"
- # далее — обычные feature/debug задачи
hotfix:
description: "Срочное исправление в продакшене"
typical_flow:
- debugger: "найди причину"
- developer: "минимальный fix"
- tester: "smoke test"
constraints:
- максимум 1 час
- минимум изменений
- deploy сразу
3.4 Пул специалистов (агенты-рабочие)
Рабочие агенты — НЕ фиксированный набор. Это пул ролей, из которых PM собирает команду под задачу. Каждый — отдельный Claude Code процесс.
specialists:
# ═══════════════════════════════════════════════
# ИССЛЕДОВАНИЯ И АНАЛИТИКА
# ═══════════════════════════════════════════════
business_analyst:
prompt: prompts/business_analyst.md
context: "задание + бизнес-контекст проекта"
tools: [WebSearch, WebFetch, Read, Write]
model: opus # стратегические решения
description: >
Бизнес-аналитик. Исследует бизнес-модель, монетизацию, целевую
аудиторию, юридические аспекты. Может спавнить исследователей.
market_researcher:
prompt: prompts/market_researcher.md
context: "тема исследования + рамки"
tools: [WebSearch, WebFetch, Write]
model: sonnet
description: >
Исследователь рынка. Конкуренты, ниша, тренды, ценообразование.
Подчинённый аналитика — копает конкретную тему.
tech_researcher:
prompt: prompts/tech_researcher.md
context: "что исследовать + ограничения"
tools: [WebSearch, WebFetch, Read, Write]
model: sonnet
description: >
Технический исследователь. API поставщиков, библиотеки,
интеграции, бенчмарки. Знает где искать доки, changelog, issues.
# ═══════════════════════════════════════════════
# ДИЗАЙН И UX
# ═══════════════════════════════════════════════
ux_designer:
prompt: prompts/ux_designer.md
context: "brief + research + примеры конкурентов"
tools: [WebSearch, WebFetch, Read, Write]
model: opus # UX-решения критичны для продукта
description: >
UX-дизайнер. User journey, wireframes (текстовые/Mermaid),
information architecture, interaction patterns.
Смотрит на конкурентов, лучшие практики, accessibility.
ui_designer:
prompt: prompts/ui_designer.md
context: "wireframes + style guide проекта"
tools: [Read, Write]
model: sonnet
description: >
UI-дизайнер. Визуальный дизайн, компонентная система,
типографика, цвета, spacing. Описывает на уровне CSS tokens.
# ═══════════════════════════════════════════════
# МАРКЕТИНГ И КОНТЕНТ
# ═══════════════════════════════════════════════
marketer:
prompt: prompts/marketer.md
context: "research + продукт + целевая аудитория"
tools: [WebSearch, WebFetch, Read, Write]
model: sonnet
description: >
Маркетолог. Стратегия продвижения, SEO-требования для разработки,
conversion-паттерны, A/B тест гипотезы, trust signals.
Знает исследования по поведению пользователей.
Даёт требования разработчикам: что учесть в коде для маркетинга.
copywriter:
prompt: prompts/copywriter.md
context: "brief + tone of voice + целевая аудитория"
tools: [Read, Write]
model: sonnet
description: >
Копирайтер. Тексты для UI (кнопки, заголовки, ошибки),
лендинги, описания, meta-теги. Знает русский и английский.
seo_specialist:
prompt: prompts/seo_specialist.md
context: "сайт + ниша + текущие метрики (если есть)"
tools: [WebSearch, WebFetch, Read, Write, Bash]
model: sonnet
description: >
SEO-специалист. Техническое SEO, структура URL, meta-теги,
schema.org разметка, Core Web Vitals, sitemap.
Даёт конкретные требования фронтендеру и бэкендеру.
# ═══════════════════════════════════════════════
# ПРОЕКТИРОВАНИЕ
# ═══════════════════════════════════════════════
architect:
prompt: prompts/architect.md
context: "brief + ВСЕ decisions проекта + tech_stack + research (если есть)"
tools: [Read, Write]
model: opus # критические решения — максимум мозгов
description: >
Системный архитектор. Проектирует архитектуру, модули, API,
схему БД, интеграции. Выдаёт implementation spec.
Не пишет код — пишет спецификации.
db_architect:
prompt: prompts/db_architect.md
context: "spec + текущая схема БД"
tools: [Read, Write]
model: opus
description: >
Архитектор БД. Схема, миграции, индексы, нормализация.
Когда SQLite хватит, когда переходить на PostgreSQL.
# ═══════════════════════════════════════════════
# РАЗРАБОТКА
# ═══════════════════════════════════════════════
frontend_dev:
prompt: prompts/frontend_dev.md
context: "spec модуля + wireframes + relevant decisions (gotchas)"
tools: [Read, Write, Edit, Bash]
model: sonnet
working_dir: "{project_path}"
description: >
Фронтендер. Vue/Nuxt/React, CSS, анимации, responsive.
Работает в директории проекта.
backend_dev:
prompt: prompts/backend_dev.md
context: "spec модуля + API contracts + relevant decisions"
tools: [Read, Write, Edit, Bash]
model: sonnet
working_dir: "{project_path}"
description: >
Бэкендер. Node.js/Python, API, интеграции, бизнес-логика.
fullstack_dev:
prompt: prompts/fullstack_dev.md
context: "spec модуля + relevant decisions"
tools: [Read, Write, Edit, Bash]
model: sonnet
working_dir: "{project_path}"
description: >
Фулстекер. Для мелких задач, где нет смысла делить.
# ═══════════════════════════════════════════════
# КАЧЕСТВО
# ═══════════════════════════════════════════════
debugger:
prompt: prompts/debugger.md
context: "описание бага + код модуля + логи (если есть)"
tools: [Read, Bash, Write] # НЕТ Edit! Дебагер ищет, не чинит.
model: opus # дебаг требует глубокого reasoning
description: >
Дебагер. Ищет причину бага, описывает root cause, НЕ исправляет.
Предлагает решение, но не трогает код.
reviewer:
prompt: prompts/reviewer.md
context: "код + spec + conventions проекта"
tools: [Read] # ТОЛЬКО чтение! Ревьюер не правит.
model: sonnet
description: >
Ревьюер. Code review: соответствие spec, качество, паттерны,
naming, edge cases. Только читает, не правит.
tester:
prompt: prompts/tester.md
context: "код + spec"
tools: [Read, Write, Edit, Bash]
model: sonnet
working_dir: "{project_path}"
description: >
Тестировщик. Unit, integration, e2e тесты. Гоняет, ищет edge cases.
qa_analyst:
prompt: prompts/qa_analyst.md
context: "spec + UX flow + текущие тесты"
tools: [Read, Write]
model: sonnet
description: >
QA-аналитик. Тест-планы, тест-кейсы, acceptance criteria.
Не пишет код тестов — описывает ЧТО тестировать.
# ═══════════════════════════════════════════════
# ИНФРАСТРУКТУРА И БЕЗОПАСНОСТЬ
# ═══════════════════════════════════════════════
sysadmin:
prompt: prompts/sysadmin.md
context: "инфраструктура проекта + текущий стек"
tools: [Read, Write, Edit, Bash]
model: sonnet
description: >
Сисадмин. Docker, nginx, CI/CD, мониторинг, бэкапы.
Знает когда SQLite хватит и когда нужен PostgreSQL.
Настраивает фаерволы, SSL, деплой. Ставит пакеты/модули.
devops:
prompt: prompts/devops.md
context: "инфраструктура + pipeline + tech stack"
tools: [Read, Write, Edit, Bash]
model: sonnet
description: >
DevOps. CI/CD pipeline, автодеплой, blue-green, rollback.
Docker Compose, GitHub Actions / Forgejo CI.
security:
prompt: prompts/security.md
context: "код + security-relevant decisions"
tools: [Read, Bash]
model: opus # безопасность — не экономим
description: >
Безопасник. OWASP, CVE, auth, injection, secrets, dependencies.
Проверяет фаерволы, ставит ограничения. Знает актуальные уязвимости.
# ═══════════════════════════════════════════════
# ЮРИДИЧЕСКАЯ ПОДДЕРЖКА
# ═══════════════════════════════════════════════
legal:
prompt: prompts/legal.md
context: "описание задачи/модуля + юрисдикция + тип бизнеса"
tools: [WebSearch, WebFetch, Read, Write]
model: opus # юридические решения критичны
description: >
Юрист. Анализирует задачу с точки зрения законности:
- Можно ли так делать? (ЗоЗПП, 152-ФЗ, 54-ФЗ, GDPR...)
- Что нужно сделать чтобы было можно? (оферта, согласие, лицензия)
- Какие документы нужны? (политика конфиденциальности, договор)
- Какие риски? (штрафы, блокировки, претензии)
НЕ заменяет настоящего юриста — даёт направление и чеклист.
PM вызывает когда: коммерция, персональные данные, платежи,
пользовательский контент, трансграничные операции.
PM НЕ вызывает когда: внутренний инструмент без юрлица.
legal_researcher:
prompt: prompts/legal_researcher.md
context: "юридический вопрос + юрисдикция"
tools: [WebSearch, WebFetch, Read, Write]
model: sonnet
description: >
Юридический исследователь. Ищет актуальные нормативные акты,
судебную практику, разъяснения регуляторов.
Подчинённый юриста — копает конкретный вопрос.
# ═══════════════════════════════════════════════
# САППОРТ И ОБРАТНАЯ СВЯЗЬ
# ═══════════════════════════════════════════════
support:
prompt: prompts/support.md
context: "описание продукта + FAQ + known issues + decisions (gotchas)"
tools: [Read, Write]
model: sonnet
description: >
Саппорт-агент. Общается с пользователем (через тебя или напрямую).
Задаёт правильные вопросы, собирает анамнез:
- Что именно не работает? На каком устройстве/браузере?
- Воспроизводится ли стабильно? Когда началось?
- Скриншот/видео?
Формирует структурированный тикет для PM.
НЕ обещает сроки, НЕ принимает решения, НЕ выполняет просьбы.
support_guard:
prompt: prompts/support_guard.md
context: "бизнес-правила проекта + security policies"
tools: [Read]
model: sonnet
description: >
Фильтр саппорта (безопасник обратной связи).
Проверяет ВСЕ входящие от клиентов перед тем как они попадут в систему:
- "Дайте мне данные других пользователей" → REJECT + лог
- "Сделайте скидку 90%" → REJECT (не в компетенции системы)
- "Удалите мой аккаунт" → ESCALATE to human (Михаил решает)
- "Кнопка не работает" → PASS to support → PM
Классифицирует: bug / feature_request / question / abuse / escalate
3.4a Саппорт: от ручного к автоматическому (эволюция)
=== ФАЗА 1: Саппорт через тебя (сейчас) ===
[Клиент] → пишет тебе в WhatsApp/Telegram
│
▼
[Ты] → пересказываешь Intake-менеджеру:
│ "клиент пишет что фильтры глючат на айфоне"
▼
[Intake] → формулирует → [PM проекта] → команда работает
│
▼
[PM] → результат → [Intake] → тебе → ты отвечаешь клиенту
=== ФАЗА 2: Саппорт-агент общается с тобой (скоро) ===
[Клиент] → пишет тебе
│
▼
[Ты] → копируешь сообщение клиента в kin:
│ kin support vdol "текст клиента"
▼
[Support] → задаёт тебе уточняющие вопросы:
│ "Спросите клиента: на каком устройстве? В каком браузере?
│ Воспроизводится ли если обновить страницу?"
▼
[Ты] → спрашиваешь клиента → добавляешь ответы
▼
[Support] → формирует тикет → [Support Guard проверяет] → [PM]
│
▼
[PM] → результат → [Support] формулирует ответ клиенту
→ "Мы нашли и исправили проблему с фильтрами.
Обновите страницу — должно работать."
▼
[Ты] → отправляешь клиенту (можешь отредактировать)
=== ФАЗА 3: Telegram-бот для клиентов (перспектива) ===
[Клиент] → пишет в Telegram-бот проекта напрямую
│
▼
[Support Guard] → фильтрует:
│ abuse/manipulation → BLOCK + лог для тебя
│ escalation → NOTIFY тебя
│ нормальный запрос → PASS
▼
[Support Bot] → общается с клиентом:
│ задаёт вопросы, собирает анамнез, показывает FAQ
│ если FAQ решает проблему → закрывает
│ если нет → формирует тикет
▼
[PM] → принимает тикет, запускает команду
▼
[PM] → результат → [Support Bot] → отвечает клиенту
│
│ ВСЕ ответы клиентам проходят через Support Guard:
│ - не раскрывает внутреннюю архитектуру
│ - не обещает невозможное
│ - не подтверждает уязвимости
│ - вежливо, в стиле бренда
▼
[Ты] → получаешь summary: "Клиент X обратился с багом Y,
команда исправила, клиент получил ответ Z"
(можешь вмешаться в любой момент)
=== ФАЗА 4: Проект живёт сам (далёкая перспектива) ===
[Клиенты] → боты → [Support] → [PM] → [Команда] → [Deploy]
│ │
▼ ▼
[Аналитика использования] [Автодеплой фиксов]
│
▼
[Маркетолог] → "конверсия упала на 5% на странице X"
→ [PM] → [UX-дизайнер] → [Фронтендер] → [A/B тест]
[Ты] = стратегическое управление + финальное approve на крупные изменения
Таблицы для саппорта (добавить в БД):
-- Тикеты от пользователей
CREATE TABLE support_tickets (
id INTEGER PRIMARY KEY AUTOINCREMENT,
project_id TEXT NOT NULL REFERENCES projects(id),
source TEXT NOT NULL, -- 'manual', 'telegram_bot', 'email'
client_id TEXT, -- идентификатор клиента (telegram id, email...)
client_message TEXT NOT NULL, -- исходное сообщение клиента
classification TEXT, -- 'bug', 'feature_request', 'question', 'abuse', 'escalate'
guard_result TEXT, -- 'pass', 'reject', 'escalate'
guard_reason TEXT, -- почему отклонено/эскалировано
anamnesis JSON, -- собранная информация (устройство, шаги, скриншоты)
task_id TEXT REFERENCES tasks(id), -- связанная задача (если создана)
response TEXT, -- ответ клиенту
response_approved BOOLEAN DEFAULT FALSE, -- ты одобрил ответ?
status TEXT DEFAULT 'new', -- new, collecting_info, in_progress, resolved, rejected
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
resolved_at DATETIME
);
-- Настройки бота для каждого проекта
CREATE TABLE support_bot_config (
project_id TEXT PRIMARY KEY REFERENCES projects(id),
telegram_bot_token TEXT, -- токен Telegram-бота (encrypted)
welcome_message TEXT, -- приветствие
faq JSON, -- часто задаваемые вопросы
auto_reply BOOLEAN DEFAULT FALSE, -- автоматически отвечать клиентам?
require_approval BOOLEAN DEFAULT TRUE, -- требовать одобрение ответов?
brand_voice TEXT, -- стиль общения ("формальный", "дружелюбный")
forbidden_topics JSON, -- что нельзя обсуждать с клиентами
escalation_keywords JSON -- триггеры для эскалации к тебе
);
CREATE INDEX idx_tickets_project ON support_tickets(project_id, status);
CREATE INDEX idx_tickets_client ON support_tickets(client_id);
Итого: ~24 специализации в 9 отделах:
| Отдел | Роли | PM вызывает когда |
|---|---|---|
| Исследования | business_analyst, market_researcher, tech_researcher | Новый проект, новый модуль, выбор технологии |
| Дизайн | ux_designer, ui_designer | Новый модуль, редизайн, улучшение UX |
| Маркетинг | marketer, copywriter, seo_specialist | Запуск, лендинги, SEO, контент |
| Проектирование | architect, db_architect | Новый модуль, рефакторинг, масштабирование |
| Разработка | frontend_dev, backend_dev, fullstack_dev | Реализация |
| Качество | debugger, reviewer, tester, qa_analyst | Баги, ревью, тесты |
| Инфраструктура | sysadmin, devops, security | Деплой, CI/CD, безопасность |
| Юридическая | legal, legal_researcher | Коммерция, ПД, платежи, оферты, лицензии |
| Саппорт | support, support_guard | Обратная связь от клиентов |
PM не вызывает всех — он собирает команду под задачу:
- Мелкий баг от клиента: support → PM → debugger → tester → frontend_dev
- Новый модуль с платежами: legal → marketer → ux → architect → security → devs → review
- Новый коммерческий проект: analyst → researchers → legal → ux → marketer → architect
- Внутренний инструмент: architect → fullstack_dev → tester (без юриста и маркетолога)
Разделение прав (КРИТИЧНО):
- Исследователи/аналитики: WebSearch + Read + Write (документы). Не трогают код.
- Дизайнеры: Read + Write (спеки, wireframes). Не трогают код.
- Маркетологи: WebSearch + Read + Write. Не трогают код — дают требования.
- Архитектор: Read + Write (спеки). Не пишет код.
- Дебагер: Read + Bash. Ищет, НЕ правит.
- Ревьюер: ТОЛЬКО Read. Не трогает.
- Разработчики: полный доступ, но только к своему модулю.
- Сисадмин/DevOps: полный доступ к инфраструктуре.
- Безопасник: Read + Bash. Не правит — выдаёт требования.
- Саппорт: Read + Write (тикеты). Не трогает код, не принимает решений.
- Support Guard: ТОЛЬКО Read. Фильтр — пропускает/блокирует/эскалирует.
3.5 Протокол обмена между агентами
Агенты общаются ТОЛЬКО через структурированные артефакты в БД. Никакого shared context. Каждый артефакт — JSON файл + запись в tasks.
Универсальный формат передачи:
{
"task_id": "VDOL-042",
"from_role": "pm",
"to_role": "debugger",
"type": "debug_request",
"payload": {
"bug_description": "Фильтры поиска не применяются при быстром переключении",
"module": "search",
"affected_files": [
"src/components/search/SearchFilters.vue",
"src/composables/useSearch.ts",
"src/api/search.ts"
],
"known_context": [
"Фильтры используют async API вызовы",
"Раньше был похожий баг с debounce (decision #15)"
],
"reproduction_steps": "Быстро кликнуть 3 разных фильтра подряд"
}
}
PM формирует payload, подтягивая из decisions:
# context_builder собирает для дебагера
context = {
"task": db.get_task("VDOL-042"),
"module_files": git.list_files("src/components/search/"),
"relevant_decisions": db.get_decisions(
project_id="vdol",
category="search",
types=["gotcha", "workaround"]
),
"recent_bugs": db.get_tasks(
project_id="vdol",
module="search",
status="done",
type="debug",
limit=5
)
}
3.6 Коммуникация между рабочими агентами
Рабочие агенты могут "общаться", но не напрямую — через PM как посредника, или через артефакты в файловой системе:
[Дебагер] → пишет debug_report.json → [PM читает]
PM решает: "нужен фронтендер для фикса"
[PM] → формирует fix_request.json (debug_report + spec) → [Фронтендер]
[Фронтендер] → правит код → [Тестировщик] запускает тесты
[Тестировщик] → test_result.json → [PM]
PM решает: "тесты прошли, закрываю задачу" или "фейл, обратно фронтендеру"
НО: для скорости можно разрешить прямую цепочку без PM:
# PM заранее описывает pipeline
kin run VDOL-042 --pipeline "debugger → tester → frontend_dev → tester"
# Каждый агент передаёт результат следующему через файл
# PM получает только финальный результат + все промежуточные в логах
3.7 Механизм запуска (как это работает технически)
# Сценарий 1: ты пишешь в Telegram
"продебажь фильтры в vdolipoperek"
# Диспетчер (Python):
# 1. Парсит: проект=vdol, тип=debug, что=фильтры
# 2. Запускает PM проекта:
claude -p "$(cat prompts/pm.md)
ПРОЕКТ: vdolipoperek
TECH STACK: Vue 3, TypeScript, Nuxt
ТЕКУЩИЕ DECISIONS:
$(kin decisions vdol --category search --format brief)
ЗАДАЧА: продебажь фильтры — не применяются при быстром переключении
ДОСТУПНЫЕ СПЕЦИАЛИСТЫ: debugger, frontend_dev, backend_dev, tester, reviewer, security
ШАБЛОНЫ МАРШРУТОВ: $(cat routes.yaml)
Декомпозируй задачу и верни JSON с pipeline." \
--session-id "pm-vdol-$(date +%s)" \
--output-format json
# PM возвращает:
{
"task_id": "VDOL-043",
"pipeline": [
{"role": "debugger", "module": "search", "brief": "..."},
{"role": "tester", "depends_on": "debugger", "brief": "regression test"},
{"role": "frontend_dev", "depends_on": "tester", "brief": "fix"},
{"role": "tester", "depends_on": "frontend_dev", "brief": "verify fix"}
],
"decisions_to_load": [15, 23] # PM знает какие decisions релевантны
}
# Runner исполняет pipeline:
for step in pipeline:
context = context_builder.build(step.role, step.module, step.decisions)
result = claude_run(step.role, context, project_path)
save_result(step, result)
if not result.success:
escalate_to_pm(step, result) # PM решает что делать
# Сценарий 2: новый проект
"нужен агрегатор туров, чтобы парсить предложения и показывать клиентам"
# Диспетчер определяет: тип=new_project
# Запускает Аналитика (БЕЗ PM, потому что проекта ещё нет):
claude -p "$(cat prompts/analyst.md)
Исследуй тему: агрегатор туров для турагентства.
Контекст: существующий сайт vdolipoperek.com (Vue/Nuxt).
Нужно: конкуренты, доступные API поставщиков туров, ценообразование,
технические ограничения. Верни market_research.json" \
--session-id "analyst-new-$(date +%s)" \
--tools WebSearch,WebFetch,Write
# Аналитик может спавнить исследователей:
# - "исследователь API" — ищет API TUI, Pegas, Anex...
# - "исследователь конкурентов" — анализирует level.travel, onlinetours...
# После: Архитектор получает research + хотелки:
claude -p "$(cat prompts/architect.md)
ИССЛЕДОВАНИЕ: $(cat market_research.json)
ХОТЕЛКИ: агрегатор туров, парсинг предложений, отображение клиентам
СУЩЕСТВУЮЩИЙ СТЕК: Vue 3, Nuxt, Node.js
Спроектируй project_blueprint.json" \
--session-id "arch-new-$(date +%s)"
# Blueprint → создаётся проект в БД → назначается PM → работа начинается
3.5 State Management
SQLite база — мультипроектная с рождения:
-- Проекты (центральный реестр)
CREATE TABLE projects (
id TEXT PRIMARY KEY, -- 'vdol', 'sharedbox', 'neverdns', 'barsik', 'askai'
name TEXT NOT NULL, -- 'В долю поперёк', 'SharedBox', 'NeverDNS'
path TEXT NOT NULL, -- ~/projects/mailbox, ~/projects/vdolipoperek
tech_stack JSON, -- ["vue3", "typescript", "nuxt"]
status TEXT DEFAULT 'active', -- active, paused, maintenance, ready
priority INTEGER DEFAULT 5, -- 1=критический, 10=когда-нибудь
pm_prompt TEXT, -- путь к кастомному промпту PM для этого проекта
claude_md_path TEXT, -- путь к CLAUDE.md проекта
forgejo_repo TEXT, -- owner/repo для синхронизации issues
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
-- Задачи (привязаны к проекту)
CREATE TABLE tasks (
id TEXT PRIMARY KEY, -- VDOL-042, SB-015, NDNS-003
project_id TEXT NOT NULL REFERENCES projects(id),
title TEXT NOT NULL,
status TEXT DEFAULT 'pending', -- pending, decomposed, in_progress, review, done, blocked
priority INTEGER DEFAULT 5,
assigned_role TEXT, -- architect, developer, reviewer, tester, security
parent_task_id TEXT REFERENCES tasks(id), -- для подзадач
brief JSON, -- Task Brief от PM
spec JSON, -- Implementation Spec от архитектора
review JSON, -- Review Result
test_result JSON, -- Test Result
security_result JSON, -- Security Check Result
forgejo_issue_id INTEGER, -- связка с Forgejo issue
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
-- Решения и грабли (КЛЮЧЕВАЯ ТАБЛИЦА — то что теряется при compaction)
-- Это ВНЕШНЯЯ ПАМЯТЬ PM-агента для каждого проекта
CREATE TABLE decisions (
id INTEGER PRIMARY KEY AUTOINCREMENT,
project_id TEXT NOT NULL REFERENCES projects(id),
task_id TEXT REFERENCES tasks(id), -- может быть NULL для общепроектных решений
type TEXT NOT NULL, -- 'decision', 'gotcha', 'workaround', 'rejected_approach', 'convention'
category TEXT, -- 'architecture', 'ui', 'api', 'security', 'devops', 'performance'
title TEXT NOT NULL,
description TEXT NOT NULL,
tags JSON, -- ["ios-safari", "css", "bottom-sheet"] для поиска
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
-- Логи агентов (для дебага, обучения и cost tracking)
CREATE TABLE agent_logs (
id INTEGER PRIMARY KEY AUTOINCREMENT,
project_id TEXT NOT NULL REFERENCES projects(id),
task_id TEXT REFERENCES tasks(id),
agent_role TEXT NOT NULL, -- pm, analyst, architect, debugger, frontend_dev, etc.
session_id TEXT, -- claude --session-id
action TEXT NOT NULL, -- 'decompose', 'implement', 'review', 'test', 'fix', 'research'
input_summary TEXT, -- что получил (краткое описание, не полный текст)
output_summary TEXT, -- что выдал
tokens_used INTEGER,
model TEXT, -- haiku, sonnet, opus
cost_usd REAL, -- стоимость вызова
success BOOLEAN,
error_message TEXT,
duration_seconds INTEGER,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
-- Модули проекта (PM знает структуру)
-- Это "карта" проекта для PM: он знает какие модули есть и кого вызвать
CREATE TABLE modules (
id INTEGER PRIMARY KEY AUTOINCREMENT,
project_id TEXT NOT NULL REFERENCES projects(id),
name TEXT NOT NULL, -- 'search', 'auth', 'payments', 'ui-kit'
type TEXT NOT NULL, -- 'frontend', 'backend', 'shared', 'infra'
path TEXT NOT NULL, -- 'src/components/search/', 'src/api/search.ts'
description TEXT, -- 'Поиск и фильтрация туров'
owner_role TEXT, -- 'frontend_dev', 'backend_dev' — кого вызывать
dependencies JSON, -- ["auth", "api-client"] — зависимости между модулями
UNIQUE(project_id, name)
);
-- Pipelines (история запусков — для обучения и повторного использования)
CREATE TABLE pipelines (
id INTEGER PRIMARY KEY AUTOINCREMENT,
task_id TEXT NOT NULL REFERENCES tasks(id),
project_id TEXT NOT NULL REFERENCES projects(id),
route_type TEXT NOT NULL, -- 'debug', 'feature', 'refactor', 'hotfix', 'new_project'
steps JSON NOT NULL, -- pipeline JSON от PM
status TEXT DEFAULT 'running', -- running, completed, failed, cancelled
total_cost_usd REAL,
total_tokens INTEGER,
total_duration_seconds INTEGER,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
completed_at DATETIME
);
-- Кросс-проектные зависимости и связи
CREATE TABLE project_links (
id INTEGER PRIMARY KEY AUTOINCREMENT,
from_project TEXT NOT NULL REFERENCES projects(id),
to_project TEXT NOT NULL REFERENCES projects(id),
type TEXT NOT NULL, -- 'depends_on', 'shares_component', 'blocks'
description TEXT,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
-- Индексы для быстрого доступа PM-агентов
CREATE INDEX idx_tasks_project_status ON tasks(project_id, status);
CREATE INDEX idx_decisions_project ON decisions(project_id);
CREATE INDEX idx_decisions_tags ON decisions(tags); -- для JSON-поиска по тегам
CREATE INDEX idx_agent_logs_project ON agent_logs(project_id, created_at);
CREATE INDEX idx_agent_logs_cost ON agent_logs(project_id, cost_usd);
3.6 Контекст-билдер (КЛЮЧЕВОЙ КОМПОНЕНТ)
Перед запуском любого агента, система собирает контекст из БД:
kin run VDOL-042
│
▼
[context-builder]
│
├── Читает task VDOL-042 из tasks table → brief, spec
├── Читает decisions WHERE project_id='vdol' → релевантные грабли
│ (фильтрует по category и tags, не грузит ВСЕ решения)
├── Читает projects WHERE id='vdol' → tech_stack, claude_md_path
├── Формирует МИНИМАЛЬНЫЙ контекст для конкретной роли:
│
│ Для архитектора: brief + ALL decisions (он должен знать историю)
│ Для программиста: spec + decisions WHERE category IN ('gotcha','workaround')
│ Для ревьюера: spec + код + decisions WHERE type='convention'
│ Для тестировщика: spec + код (минимум)
│ Для безопасника: код + security conventions
│
└── Запускает claude -p с собранным контекстом
Это решает проблему "раздувшихся CLAUDE.md": контекст собирается динамически и фильтруется по роли.
3.7 Meta-PM: обзор всех проектов
Meta-PM — самый "тупой" но самый полезный агент. Он работает с VIEW-запросами к БД:
-- "Что горит?" — для Meta-PM
SELECT p.name, p.priority, p.status,
COUNT(CASE WHEN t.status = 'blocked' THEN 1 END) as blocked_tasks,
COUNT(CASE WHEN t.status = 'in_progress' THEN 1 END) as active_tasks,
COUNT(CASE WHEN t.status = 'pending' THEN 1 END) as pending_tasks,
MAX(t.updated_at) as last_activity
FROM projects p
LEFT JOIN tasks t ON t.project_id = p.id
WHERE p.status = 'active'
GROUP BY p.id
ORDER BY p.priority ASC, blocked_tasks DESC;
-- "Сколько трачу?" — cost tracking
SELECT p.name,
SUM(al.cost_usd) as total_cost,
SUM(al.tokens_used) as total_tokens,
COUNT(*) as agent_calls
FROM agent_logs al
JOIN projects p ON p.id = al.project_id
WHERE al.created_at > datetime('now', '-7 days')
GROUP BY p.id
ORDER BY total_cost DESC;
3.8 Компоненты
kin/
├── core/
│ ├── db.py -- SQLite init, migrations
│ ├── models.py -- Projects, Tasks, Decisions, Modules, Pipelines
│ ├── context_builder.py -- формирование контекста ПО РОЛИ из БД
│ └── api.py -- REST API для GUI (FastAPI, читает ту же SQLite)
│
├── agents/
│ ├── prompts/ -- ~24 промпта (pm.md, architect.md, debugger.md...)
│ ├── routes.yaml -- шаблоны маршрутов (debug, feature, refactor...)
│ ├── specialists.yaml -- пул ролей с tools, model, context rules
│ └── runner.py -- запуск claude -p, pipeline executor
│
├── cli/
│ └── main.py
│ # kin status — все проекты одним взглядом
│ # kin run VDOL-043 — PM декомпозирует + pipeline
│ # kin run VDOL-043 --dry-run — показать pipeline без запуска
│ # kin ask "что горит?" — Intake отвечает
│ # kin support vdol "текст" — тикет от клиента
│ # kin cost --last 7d — расходы
│ # kin new-project "агрегатор" — analyst → architect → PM
│
├── web/ -- GUI (Vue 3 + TypeScript — твой стек!)
│ ├── src/
│ │ ├── views/
│ │ │ ├── Dashboard.vue -- обзор всех проектов
│ │ │ ├── ProjectView.vue -- один проект: задачи, модули, decisions
│ │ │ ├── PipelineView.vue -- pipeline задачи: кто работает, где блокер
│ │ │ ├── CostView.vue -- расходы по проектам и задачам
│ │ │ └── SupportView.vue -- тикеты от клиентов
│ │ ├── components/
│ │ │ ├── ProjectCard.vue -- карточка проекта со статусом
│ │ │ ├── PipelineGraph.vue -- визуализация pipeline (граф агентов)
│ │ │ ├── AgentStatus.vue -- статус агента (idle/working/done/error)
│ │ │ ├── DecisionsList.vue -- decisions проекта с поиском по тегам
│ │ │ └── LiveLog.vue -- real-time лог текущего pipeline
│ │ └── App.vue
│ └── package.json
│
├── integrations/
│ ├── telegram_bot.py -- бот-интерфейс (для тебя + клиентские боты)
│ └── forgejo_sync.py -- двусторонняя синхронизация issues ↔ tasks
│
├── config/
│ └── projects.yaml -- начальная конфигурация проектов
│
└── kin.db -- SQLite база (единственный source of truth)
3.9 GUI: что нужно видеть
Dashboard (главный экран):
┌─────────────────────────────────────────────────────────────┐
│ Kin Dashboard Cost: $47/week │
├─────────────────────────────────────────────────────────────┤
│ │
│ 🔴 vdolipoperek 3 active 1 blocked $12/week │
│ └─ VDOL-043: debug фильтров [████░░] debugger → tester │
│ └─ VDOL-044: mobile bottom-sheet [██████] done ✓ │
│ └─ VDOL-045: оплата [░░░░░░] blocked: ждёт юриста │
│ │
│ 🟡 sharedbox 1 active $8/week │
│ └─ SB-016: multi-tenant isolation [██░░░░] architect │
│ │
│ 🟢 neverdns 0 active $0/week │
│ └─ маркетинг-фаза, ждёт контент │
│ │
│ 🟢 barsik 1 active $5/week │
│ └─ BARS-007: RAG pipeline [████░░] backend_dev │
│ │
│ ⚪ askai 0 active $0/week │
│ ⚪ ddfo 0 active $0/week │
│ ⚪ stopleak 0 active $0/week │
│ │
│ ─── Support ─── │
│ 2 новых тикета (vdolipoperek) │
│ 1 ожидает твоего approve │
│ │
└─────────────────────────────────────────────────────────────┘
Pipeline View (конкретная задача):
┌─────────────────────────────────────────────────────────────┐
│ VDOL-043: Debug фильтров поиска Status: in_progress│
│ Priority: high Cost: $1.82 Duration: 12 min │
├─────────────────────────────────────────────────────────────┤
│ │
│ [PM] ──────► [Debugger] ──────► [Tester] ──────► [Frontend]│
│ ✓ 0.3s ✓ $0.45 ● working ○ pending│
│ decomposed found: writing │
│ pipeline race condition regression │
│ in useSearch.ts test │
│ │
│ Decisions добавлены: │
│ #47: "race condition в async фильтре — AbortController" │
│ │
│ ─── Live Log ─── │
│ 12:04:32 [tester] Запущен: session tst-VDOL043-1710... │
│ 12:04:33 [tester] Читает: src/composables/useSearch.ts │
│ 12:04:45 [tester] Пишет: tests/search.filter.spec.ts │
│ 12:05:01 [tester] Bash: npm run test -- search.filter │
│ │
└─────────────────────────────────────────────────────────────┘
Почему Vue 3: это твой стек, ты на нём строишь vdolipoperek. GUI Kin — это тоже проект, который Kin может помогать разрабатывать. Meta-moment: Kin строит свой собственный GUI.
Архитектура GUI:
[kin.db] ← SQLite (source of truth)
│
├── [core/api.py] ← FastAPI, REST endpoints
│ GET /projects — список проектов со статусами
│ GET /projects/{id} — детали проекта + задачи + modules
│ GET /tasks/{id} — задача + pipeline + agent logs
│ GET /tasks/{id}/live — SSE stream для live log
│ GET /pipelines/{id} — граф pipeline с статусами
│ GET /decisions?project=X — decisions с фильтрами
│ GET /support/tickets — тикеты от клиентов
│ GET /cost?period=7d — расходы
│ POST /tasks — создать задачу
│ POST /tasks/{id}/run — запустить pipeline
│ POST /support/approve/{id} — одобрить ответ клиенту
│
└── [web/] ← Vue 3 + TypeScript, Vite
Подключается к API
SSE для live обновлений pipeline
Responsive (работает с MacBook и с телефона)
Ключевое: GUI читает ту же SQLite что и CLI/runner. Нет отдельной базы для GUI, нет sync проблем. runner.py пишет в kin.db → API читает → Vue показывает. Real-time через SSE (Server-Sent Events) — runner пишет лог → API стримит → Vue обновляет.
3.10 Интеграция с существующей инфраструктурой
- Forgejo: Двусторонний sync — issue создано в Forgejo → task в kin, task завершён → issue закрыт. Forgejo остаётся UI для ручного просмотра.
- Obsidian: Decisions из БД экспортируются как .md в vault. Kanban-доска читает задачи. Направление: kin → Obsidian (read-only зеркало).
- Telegram бот: Основной мобильный интерфейс. Свободная форма: "продебажь фильтры в vdolipoperek" → dispatcher парсит → PM → pipeline.
- Mac Mini M4 Pro: Основной хост. Агенты запускаются как процессы на нём.
- MacBook: Через SSH + Telegram бот. Или Syncthing синхронизирует kin.db (receive-only на MacBook).
- CLAUDE.md per project: Минимальный (30 строк), содержит ТОЛЬКО: "tech stack", "coding conventions", "ссылка на kin для контекста". Decisions НЕ дублируются.
3.10 Ключевые отличия от Ruflo
| Аспект | Ruflo | Kin |
|---|---|---|
| Мультипроектность | Нет | Intake + Project PMs |
| Полнота команды | Только dev | ~22 роли: research, design, marketing, dev, QA, ops, support |
| Маршрутизация | Фиксированная | PM динамически собирает команду |
| Изоляция | Один промпт | Каждый агент = отдельный процесс |
| Обратная связь | Нет | Support → Guard → PM → команда → ответ клиенту |
| Клиентские боты | Нет | Telegram per project (перспектива) |
ЧАСТЬ 4: План действий
Фаза 1: Фундамент + один проект (2-3 дня)
- SQLite схема (все таблицы включая support)
- context-builder, runner.py, pipeline executor
- Intake-агент, PM, routes.yaml, specialists.yaml
- Базовые промпты: architect, frontend_dev, debugger, tester, reviewer
- CLI + тест на vdolipoperek.com
Фаза 2: Полная команда ~22 роли (2-3 дня)
- Все промпты, разделение прав
- Тест полной цепочки marketer → ux → architect → dev → review
Фаза 3: Все 10 проектов (1-2 дня)
Фаза 4: Telegram интеграция (1-2 дня)
Фаза 5: Саппорт + Support Guard (1-2 дня)
Фаза 6: Forgejo + Obsidian sync (1 день)
Фаза 7: Боевой прогон на vdolipoperek (1-2 недели)
Фаза 8: Клиентские Telegram-боты (перспектива)
Фаза 9: Самоподдерживающиеся проекты (далёкая перспектива)
ЧАСТЬ 5: Критические ограничения реализации
5.1 Запрет блокирующего time.sleep в pipeline execution thread
Корень бага KIN-145. Pipeline агентов выполняется в отдельном потоке (ThreadPoolExecutor или threading.Thread). Этот поток является единственным для всего пайплайна задачи. Любой блокирующий вызов внутри него блокирует весь runner-процесс на время сна.
Механизм каскадного падения:
runner.pyвызываетmerge_worktree(worktree_path, p_path, max_retries=3, retry_delay_s=15)(старый баг)- При git-конфликте
merge_worktreeвызываетtime.sleep(15)трижды → 45 секунд блокировки - Родительский web-сервер (FastAPI) теряет ответ от воркера
_check_parent_alive()во всех других пайплайнах видитESRCH(процесс недоступен) или таймаут- Все in-flight пайплайны помечаются как
failed→ массовое падение всех задач во всех проектах
Почему retry для git-конфликтов бессмысленен: Git merge conflict — детерминированная ошибка. Конфликт возник потому что два ветки расходятся в одном месте файла. Повторная попытка через 15 секунд не изменит содержимое файлов и снова завершится конфликтом. Retry тут не помогает, только блокирует.
Допустимые альтернативы в зависимости от контекста:
async-задержка (asyncio.sleep) — если код работает в async-окружении- отдельный поток (
threading.Thread) — если нужен polling или retry с задержкой - отказ от retry — для детерминированных ошибок (git merge conflict, validation error)
Event.wait(timeout)— если нужно ждать внешнего события без CPU spin
Правило:
time.sleep()вagents/ЗАПРЕЩЁН без исключений. Вcore/разрешён только в файлах с явным daemon-thread или retry-контекстом: —core/watchdog.py(daemon-поток, отдельный от pipeline) —core/worktree.py(retry-delay, вызывается только с явными kwargs, не из runner.py)
Static regression guard: tests/test_kin_fix_025_regression.py сканирует agents/ и core/
на наличие time.sleep — любой новый вызов вне allowlist ломает тест.
Заметки
Архитектура: Изоляция контекста через процессы. Decisions = внешняя память PM. PM тупой/памятливый, workers умные/забывчивые. context-builder фильтрует по роли. ~22 роли = полная софтверная компания.
Бизнес: Полнота > скорость. Продукт = коммерческий, не поделка. Саппорт замыкает цикл. Support Guard критичен. В перспективе проекты живут сами.
Техника: Python, SQLite (source of truth), cost tracking встроен, Forgejo sync, Obsidian read-only.
Из Ruflo взять: MCP, SQLite memory, model routing, ADR, hooks. НЕ брать: fake parallelism, over-engineering.