From b84b9f91f628dfab5c955f01731f06bfa81333b8 Mon Sep 17 00:00:00 2001 From: Markov Date: Sun, 15 Feb 2026 12:26:58 +0100 Subject: [PATCH] docs: comprehensive project vision and workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Full workflow: Discovery → Planning → Execution → Review → Deploy - UI layout mockup - Agent roles and types - CLI integration problem analysis - Task/subtask hierarchy for context preservation --- IDEAS.md | 352 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 250 insertions(+), 102 deletions(-) diff --git a/IDEAS.md b/IDEAS.md index c689d64..d24e382 100644 --- a/IDEAS.md +++ b/IDEAS.md @@ -1,9 +1,43 @@ # Team Board — Идеи и концепция -## Суть +## Суть проекта -Веб-платформа где AI-агенты работают как команда над проектами. -Человек видит всё: задачи, переписку, код. Полная прозрачность. +**Team Board** — платформа для управления командой AI-агентов, работающих над проектами. + +**Ключевая идея:** Несколько AI-агентов работают как команда разработчиков. Человек видит всё: задачи, код, переписку. Полная прозрачность. + +--- + +## Проблема, которую решаем + +Один универсальный AI-ассистент: +- Контекст переполняется при разных задачах +- Сложно параллельно вести несколько направлений +- Нет специализации — один промпт на всё + +**Решение:** Команда специализированных агентов, каждый со своей ролью и контекстом. + +--- + +## Архитектура + +### Микросервисы (Python + FastAPI) + +| Сервис | Описание | +|--------|----------| +| Gateway | API Gateway, аутентификация | +| Projects | Проекты, Git интеграция | +| Tasks | Задачи, канбан, подзадачи | +| Agents | Управление AI агентами | +| Chat | Чаты проектов | + +### Frontend (Next.js) + +Web UI для управления всем. + +### Database + +PostgreSQL (существующий на сервере). --- @@ -15,10 +49,10 @@ ├──────────────┬─────────────────────────────────────────────────────┤ │ │ Project Alpha [Settings] │ │ PROJECTS │─────────────────────────────────────────────────────│ -│ │ 💬 Chat ▼ │ +│ │ 💬 Chat ▼ (сворачиваемый) │ │ ○ Alpha │ ┌──────────────────────────────────────────────┐ │ │ ● Beta │ │ Agent-1: Закоммитил фикс для issue #42 │ │ -│ ○ Gamma │ │ Agent-2: Проверил, всё ок. Можно мержить. │ │ +│ ○ Gamma │ │ Agent-2: Проверил, всё ок │ │ │ │ │ You: Мержите │ │ │ [+ New] │ └──────────────────────────────────────────────┘ │ │ │─────────────────────────────────────────────────────│ @@ -37,136 +71,250 @@ --- -## Проекты +## Workflow: от идеи до деплоя -Каждый проект содержит: -- **Git репозиторий** (Gitea интеграция) -- **Канбан доска** с задачами -- **Чат** для обсуждений -- **Назначенные агенты** +### Фаза 1: Инициация проекта + +**Точки входа:** +- Через главного агента (Марков) в Telegram +- Через Web UI — кнопка "New Project" +- Через любого агента + +**Результат:** Создаётся черновик проекта, открывается Discovery Chat. + +--- + +### Фаза 2: Discovery (Обсуждение) + +**Участники:** Человек + Lead Agent + +**Цель:** Превратить размытую идею в чёткое ТЗ + +**Что делает Lead Agent:** +1. Задаёт уточняющие вопросы +2. Предлагает варианты реализации +3. Указывает на риски +4. Формирует структуру + +**Артефакты:** +- `BRIEF.md` — краткое описание проекта +- `REQUIREMENTS.md` — функциональные требования +- `ARCHITECTURE.md` — техническое решение + +**Выход из фазы:** Человек подтверждает "Да, делаем так" + +--- + +### Фаза 3: Planning (Декомпозиция) + +**Кто делает:** Lead Agent (или человек вручную) + +**Процесс:** +``` +REQUIREMENTS.md → Декомпозиция → Epic → Tasks → Subtasks +``` + +**Пример:** +``` +Epic: "Модуль авторизации" +├── Task: "Модель пользователя" +│ ├── Subtask: "Схема БД" +│ ├── Subtask: "SQLAlchemy модель" +│ └── Subtask: "Миграция" +├── Task: "API эндпоинты" +│ ├── Subtask: "POST /auth/register" +│ ├── Subtask: "POST /auth/login" +│ └── Subtask: "Tests" +└── Task: "Интеграция с frontend" +``` + +--- + +### Фаза 4: Execution (Разработка) + +**Как агенты берут задачи:** + +| Модель | Описание | +|--------|----------| +| **Pull** | Агент сам выбирает задачу по специализации | +| **Push** | Lead Agent назначает задачи | +| **Гибрид** | Критичные — назначаются, остальные — свободный выбор | + +**Процесс работы агента:** +1. Взял задачу → "In Progress" +2. Читает контекст (Brief, Requirements, связанные задачи) +3. Работает (код, тесты, документация) +4. Коммитит в feature branch +5. Создаёт подзадачу "Review" → другому агенту +6. Ревью и итерации +7. Merge в main + +--- + +### Фаза 5: Review & QA + +**Принцип:** Никакой код не идёт в main без ревью. + +**Кто ревьюит:** +- Другой агент (не автор) +- Специальный "Reviewer" агент +- Человек (для критичного) + +**Автоматизация:** +- CI/CD запускает тесты +- Линтеры +- Security checks + +**Escalation:** 3 итерации ревью без согласия → эскалация к Lead/Human. + +--- + +### Фаза 6: Deploy + +1. Integration тесты +2. Staging deploy +3. Human approval (опционально) +4. Production deploy --- ## Задачи и подзадачи -**Принцип:** Подзадачи внутри задачи — не теряем контекст. +**Ключевой принцип:** Подзадачи внутри задачи — контекст НЕ теряется. ``` Task: "Реализовать API авторизации" -├── Subtask: "Написать модели" → Agent-1 -│ └── Status: Done -├── Subtask: "Code review" → Agent-2 -│ └── Status: Done (approved) -├── Subtask: "Написать тесты" → Agent-1 -│ └── Status: In Progress -└── Subtask: "Final review" → Agent-2 - └── Status: Waiting +├── Subtask: "Написать модели" → Agent-1 ✓ +├── Subtask: "Code review" → Agent-2 ✓ +├── Subtask: "Написать тесты" → Agent-1 (in progress) +└── Subtask: "Final review" → Agent-2 (waiting) ``` -Когда агент работает над подзадачей — он видит всю задачу и все предыдущие подзадачи. +Когда агент работает над подзадачей — видит всё дерево + историю. --- -## Агенты +## Роли агентов -Типы агентов: -- **OpenClaw instance** — полноценный агент с инструментами -- **Claude API** — через API напрямую -- **Codex** — OpenAI Codex -- **Gemini** — Google -- **Custom** — любой через API +| Роль | Обязанности | +|------|-------------| +| **Lead/Analyst** | Discovery, Planning, Coordination | +| **Developer** | Код, тесты | +| **Reviewer** | Code review, QA | +| **DevOps** | CI/CD, Deploy | +| **Documenter** | Документация | + +--- + +## Типы агентов + +| Тип | Описание | +|-----|----------| +| **OpenClaw** | Полноценный агент с инструментами | +| **Claude API** | Прямой вызов API | +| **Claude Code CLI** | Через CLI (без траты API токенов) | +| **Codex** | OpenAI | +| **Gemini** | Google | +| **Custom** | Любой через API | + +--- + +## Проблема: CLI Integration + +**Задача:** Использовать Claude Code CLI (авторизован через Max подписку) без траты API токенов. + +**Варианты решения:** + +### 1. Headless Mode (если поддерживается) +```bash +claude --message "prompt" --output result.txt +``` + +### 2. PTY Automation +```python +import pexpect +child = pexpect.spawn('claude') +child.sendline('Write a function...') +response = child.before +``` + +### 3. Session Bridge +``` +Team Board → Agent Service → PTY Bridge → Claude CLI в tmux +``` + +### 4. MCP Integration +Если CLI поддерживает Model Context Protocol. + +### 5. Гибридный подход +- Простые задачи → API (дёшево) +- Кодинг → CLI +- Роутинг по типу задачи + +**Требуется исследование:** Проверить возможности `claude` CLI. + +--- + +## Прозрачность + +**Всё видно в Web UI:** +- Статус задач +- Кто над чем работает +- Коммиты +- Переписка в задачах +- Метрики + +**Уведомления:** +- Задача застряла +- Нужно решение человека +- Deploy готов + +--- + +## Настройки проекта -Конфигурация агента: ```yaml -name: "Claude-Coder" -provider: anthropic -model: claude-sonnet-4-20250514 -role: "Backend разработчик" -capabilities: - - code - - review - - git +Project: + name: "My Project" + git_enabled: true # default: true + git_url: "https://..." + lead_agent_id: "markov" # можно переназначить + agents: ["claude", "codex"] ``` --- -## Чат проекта +## Инфраструктура (уже есть) -- Сворачиваемая панель над канбаном -- Участники: человек + агенты -- Агенты пишут о прогрессе -- Человек даёт указания -- История сохраняется +- **PostgreSQL** — БД +- **Thoth** — STT/TTS сервис +- **Authentik** — SSO +- **Nginx + certbot** — домены +- **Gitea** — Git хостинг +- **OpenClaw (Марков)** — главный агент --- -## Workflow +## Открытые вопросы -1. Человек создаёт задачу -2. Назначает агента (или агент сам берёт) -3. Агент работает, создаёт подзадачи если нужно -4. Передаёт на ревью другому агенту (подзадача) -5. Ревьюер комментирует / апрувит -6. Фиксы если нужны (подзадача) -7. Задача закрывается - -Всё логируется. Человек может вмешаться на любом этапе. - ---- - -## API для агентов - -``` -GET /api/tasks/available — доступные задачи -POST /api/tasks/{id}/take — взять задачу -POST /api/tasks/{id}/subtask — создать подзадачу -POST /api/tasks/{id}/complete — завершить -POST /api/tasks/{id}/comment — комментарий -POST /api/chat/{project}/send — написать в чат -GET /api/git/{project}/status — статус репозитория -POST /api/git/{project}/commit — закоммитить -``` - ---- - -## База данных - -``` -projects -├── id, name, git_url, created_at - -tasks -├── id, project_id, parent_id (для подзадач) -├── title, description, status -├── assigned_agent_id -├── created_at, updated_at - -agents -├── id, name, provider, model -├── config (JSON), status - -messages (чат) -├── id, project_id, agent_id/user_id -├── content, timestamp -``` +1. Как интегрировать CLI-агентов (Claude Code, Cline)? +2. Workspace для агентов — общий или изолированный? +3. Реалтайм прогресс работы агента? +4. Лимиты: макс агентов, макс задач? +5. Биллинг/учёт использования API? --- ## Приоритеты реализации 1. [ ] Базовый UI: проекты, доска -2. [ ] Tasks service: CRUD задач -3. [ ] Agents service: регистрация агентов -4. [ ] Подзадачи и назначения -5. [ ] Chat service -6. [ ] Git интеграция +2. [ ] Tasks Service: CRUD, подзадачи +3. [ ] Agents Service: регистрация +4. [ ] Chat Service +5. [ ] Git интеграция +6. [ ] CLI Bridge для Claude Code 7. [ ] Подключение реальных агентов --- -## Открытые вопросы - -1. Как агент "работает"? Поллинг задач или вебхуки? -2. Workspace для агентов — общий или изолированный? -3. Как показывать прогресс работы агента в реалтайме? -4. Лимиты: макс агентов, макс задач? +*Документ для обсуждения. Финальная архитектура — отдельно.*