From b95db7c7d68470f5992045ce5e9e804295be492d Mon Sep 17 00:00:00 2001 From: johnfrum1234 Date: Sun, 15 Mar 2026 13:40:58 +0200 Subject: [PATCH] bootstrap: vdol project loaded with real data --- agent-orchestrator-research.md | 1291 ++++++++++++++++++++++++++++++++ 1 file changed, 1291 insertions(+) create mode 100644 agent-orchestrator-research.md diff --git a/agent-orchestrator-research.md b/agent-orchestrator-research.md new file mode 100644 index 0000000..8d7aff2 --- /dev/null +++ b/agent-orchestrator-research.md @@ -0,0 +1,1291 @@ +# Исследование мультиагентных оркестраторов и проект собственного + +## Дата: 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` (текстовую строку) и передаёт его в `claude` CLI +- ПО СУТИ: это 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 + +**Сильные стороны (стоит перенять):** + +1. **MCP-интеграция** — агент-оркестратор как MCP-сервер для Claude Code. Это позволяет Claude Code вызывать оркестратор как тулзу, а не наоборот. Элегантно. + +2. **SQLite memory с namespace** — простая, надёжная, persistent. Key-value с namespace (architecture/, bugs/, decisions/) — хороший паттерн. + +3. **Model routing** — автоматический выбор haiku для простых задач, opus для сложных. Экономит деньги. + +4. **Anti-drift defaults** — `topology: hierarchical` + `maxAgents: 8` + `strategy: specialized`. Маленькие команды с чёткими ролями дрифтят меньше. + +5. **ADR (Architecture Decision Records)** — spec-first подход, где архитектура описана в ADR-файлах и агенты обязаны следовать. + +6. **Hook system** — pre-task/post-task хуки для автоматизации (pre: загрузить контекст, post: сохранить результат). + +7. **Структура .agents/skills/** — каждый агент = директория с CLAUDE.md (system prompt) + tools + config. Модульно, расширяемо. + +**Слабые стороны (НЕ повторять):** + +1. **Fake parallelism** — агенты не являются отдельными процессами. Это один Claude Code с большим промптом, притворяющимся несколькими агентами. ГЛАВНАЯ ПРОБЛЕМА — контекст всё равно один, compaction убивает всех одновременно. + +2. **Over-engineering** — 215 MCP tools, 87 в wiki, byzantine consensus — для одного разработчика это красные флаги. Много surface area, мало глубины. + +3. **Размытие ответственности пакетов** — 3 npm-пакета (@claude-flow/cli, claude-flow, ruflo) — это один и тот же код. Ребрендинг создаёт путаницу. + +4. **Нет реальной изоляции контекста** — это ключевое. Если агент-программист и агент-тестировщик живут в одном контексте, compaction убивает нюансы обоих. + +5. **Документация как продукт** — 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 проекта — это не тупой маршрутизатор, это агент, который ПОНИМАЕТ задачу. +Но чтобы понимал хорошо, ему нужны "шаблоны маршрутов" как подсказки: + +```yaml +# В промпте 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 процесс. + +```yaml +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 на крупные изменения +``` + +**Таблицы для саппорта (добавить в БД):** + +```sql +-- Тикеты от пользователей +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. + +**Универсальный формат передачи:** +```json +{ + "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:** +```python +# 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 Механизм запуска (как это работает технически) + +```bash +# Сценарий 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 решает что делать +``` + +```bash +# Сценарий 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 база — мультипроектная с рождения:** + +```sql +-- Проекты (центральный реестр) +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-запросами к БД: + +```sql +-- "Что горит?" — для 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: Самоподдерживающиеся проекты (далёкая перспектива) + +--- + +## Заметки + +**Архитектура:** Изоляция контекста через процессы. 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.