auto-sync: 2026-06-02 21:00:01

tasks/orchestrator/proposal_v1/README.md

@@ -0,0 +1,94 @@
+# Мультиагентная разработка ПО на Openclaw + Plane + Git
+
+**Версия:** 1.0
+**Дата:** 2026-05-04
+**Статус:** проектная спецификация, готова к пилоту
+**База:** `analysis_implementation_options.md` (Вариант А — GitOps + Claude Code subagents + Plane как «витрина»)
+**Источник требований:** `intro.txt` + `add0405.txt`
+
+---
+
+## Зачем этот пакет
+
+Аналитическая записка в `analysis_implementation_options.md` отвечала на вопрос «как делать?» (выбор варианта А из четырёх). Этот пакет отвечает на вопрос «**что именно делать прямо сейчас?**» — превращает рекомендацию в оперативный комплект:
+
+- описанный шаг-в-шаг производственный процесс,
+- каталог артефактов с шаблонами,
+- список Quality Gates с машинно-проверяемыми критериями,
+- роли и системные промпты агентов (под Openclaw / Claude Code),
+- протокол их взаимодействия,
+- интеграцию с Plane и Git,
+- чек-лист запуска.
+
+Цель — состояние, в котором **пользователь только формулирует бизнес-требования**, а аналитика, дизайн, разработка, ревью, тестирование, деплой выполняются агентами с проверяемым результатом на каждом шаге.
+
+---
+
+## TL;DR одним абзацем
+
+Каждая фича в Plane автоматически разворачивается в 7 типовых подзадач (Анализ → Архитектура → Дизайн → Разработка → Code Review → Тестирование → Внедрение). Каждая подзадача обслуживается отдельным агентом-специалистом из Openclaw, который читает контекст из Git (`/docs`, `/CLAUDE.md`, ADR) и пишет туда же свой артефакт. Между подзадачами стоят машинные Quality Gates (CI-проверки): без зелёного QG задача не закрывается, кто бы что ни «считал готовым». Plane — витрина для человека, реальный источник правды — Git.
+
+---
+
+## Структура пакета
+
+| # | Файл | О чём |
+|---|---|---|
+| 0 | [README.md](./README.md) | Этот файл — навигация и TL;DR |
+| 1 | [01_production_process.md](./01_production_process.md) | Производственный процесс: 7 этапов, входы/выходы, диаграмма потока |
+| 2 | [02_repo_structure.md](./02_repo_structure.md) | Канон структуры репозитория, naming convention, шаблоны артефактов |
+| 3 | [03_quality_gates.md](./03_quality_gates.md) | Quality Gates: машинно-проверяемые критерии для каждого этапа |
+| 4 | [04_agents_roles.md](./04_agents_roles.md) | Роли агентов, модели, инструменты, границы ответственности |
+| 5 | [05_agent_system_prompts.md](./05_agent_system_prompts.md) | Готовые системные промпты для Openclaw — копируются в subagent definition |
+| 6 | [06_plane_integration.md](./06_plane_integration.md) | Plane: иерархия, шаблоны, custom fields, webhooks, MCP |
+| 7 | [07_git_workflow.md](./07_git_workflow.md) | Git-flow, лейблы стадий, branch protection, CI, конвенция коммитов |
+| 8 | [08_interaction_protocol.md](./08_interaction_protocol.md) | Протокол взаимодействия: hand-off, формат сообщений, эскалации |
+| 9 | [09_ui_testing.md](./09_ui_testing.md) | Стратегия UI-тестирования: Playwright, visual regression, accessibility |
+| 10 | [10_launch_checklist.md](./10_launch_checklist.md) | Чек-лист запуска: что поднять, какие секреты, последовательность |
+
+---
+
+## Как читать пакет
+
+**Если вы заказчик / постановщик БТ** — достаточно прочесть `01_production_process.md` и раздел «Простым языком» в каждом следующем файле. Технические разделы можно пропустить — их выполняют агенты и инженер DevOps на этапе настройки.
+
+**Если вы инженер, который будет настраивать** — читайте всё подряд, плюс перечитайте `analysis_implementation_options.md` для контекста.
+
+**Если вы агент, читающий это в Git** — после прочтения переходите к своему `SKILL.md` и к `CLAUDE.md` конкретного проекта.
+
+---
+
+## Принципы, на которых построен пакет
+
+1. **Single Source of Truth = Git.** Если чего-то нет в репозитории — этого не существует. Plane не источник правды, а витрина.
+2. **Каждый артефакт машинно-валидируем.** «Согласовать у Иванова» не считается QG. Считается — проверка скрипта или линтера.
+3. **Агент производит, оркестратор закрывает.** Агент не имеет права сам поставить галочку «готово» — это делает CI на основе DoD.
+4. **Ничего лишнего.** Если этап не даёт самостоятельной ценности или его проверка не машинна — он не входит в процесс.
+5. **Эскалация явная.** Когда агент не уверен — он пишет вопрос в Plane и останавливается, а не «угадывает».
+6. **Воспроизводимость сред.** Один Dockerfile, один `docker-compose.yml`, разница только в данных и секретах.
+7. **Тестирование обязательно, включая UI.** Без зелёных тестов (unit + integration + e2e + UI + visual + a11y) задача не закрывается.
+
+---
+
+## Краткий словарь терминов
+
+- **BR (Business Request)** — короткий запрос от заказчика (1–10 строк), с которого всё начинается.
+- **BRD (Business Requirements Document)** — формализованные бизнес-требования (что и зачем).
+- **ТЗ (Техническое задание)** — что именно реализуется, в технических терминах.
+- **ADR (Architecture Decision Record)** — запись об архитектурном решении в формате М. Найгарда.
+- **C4** — модель Саймона Брауна для диаграмм архитектуры (Context / Container / Component / Code).
+- **DoD (Definition of Done)** — машинно-проверяемые критерии завершения подзадачи.
+- **QG (Quality Gate)** — «ворота» между этапами, без прохождения которых движение запрещено.
+- **Subagent** — специализированный агент в Openclaw / Claude Code с собственным system prompt и набором тулов.
+- **MCP (Model Context Protocol)** — протокол подключения инструментов к LLM-агентам (Plane, Git, Playwright и т.д.).
+- **Hand-off** — передача задачи от одного агента следующему через коммит/PR/статус Plane.
+- **Ephemeral preview** — временное изолированное окружение, поднимается на каждый PR и удаляется при merge.
+
+---
+
+## Что делать после прочтения
+
+1. Прочесть весь пакет (≈45 минут вдумчивого чтения).
+2. Открыть `10_launch_checklist.md` и пройти его по пунктам.
+3. Выбрать пилотный проект (рекомендация из `analysis_implementation_options.md`: `fr24-noisemap`).
+4. Запустить первую фичу через процесс end-to-end. Все находки — в backlog улучшений процесса.