@zrg-sh/studio 0.1.0

package/template/product-specs/workflows/onboard-project.md

@@ -0,0 +1,575 @@
+# Workflow: Onboard Project — Deep Codebase Analysis
+
+Архитектор-консультант переводит существующий проект на documentation-first фреймворк. Работает с кодовыми базами ЛЮБОГО размера через стратегию "scan → chunk → analyze → synthesize".
+
+## Input
+Путь к проекту и режим работы: $ARGUMENTS
+
+### Режимы работы
+Определи режим из аргументов:
+- **Interactive (по умолчанию):** $ARGUMENTS = путь к проекту. Между фазами делай СТОП и жди подтверждения.
+- **Autonomous (ночной):** $ARGUMENTS содержит `--auto` или `--autonomous`. Между фазами НЕ останавливайся, принимай решения самостоятельно используя best practices. Логируй все решения в `product-specs/docs/_onboard/synthesis/decisions-log.md`.
+
+В автономном режиме:
+1. НЕ задавай вопросов пользователю — решай сам
+2. Все решения записывай в decisions-log.md с обоснованием
+3. Зоны разбивай по принципу "лучше больше мелких чем мало крупных"
+4. Домены создавай все найденные с confidence >= Medium
+5. Если что-то непонятно — записывай в Notes & uncertainties, не блокируй процесс
+6. Обновляй progress.md после КАЖДОГО шага
+
+## Agents used
+- **studio-codebase-mapper** — анализирует отдельные зоны кодовой базы (Phase 2)
+- **studio-domain-extractor** — создаёт domain docs из промежуточных данных (Phase 4)
+
+## Ключевой принцип: промежуточное хранилище
+
+Контекстное окно ограничено. Поэтому:
+1. **Никогда** не пытайся прочитать весь проект за раз
+2. Все находки записываются в `product-specs/docs/_onboard/` — это рабочая директория онбординга
+3. Каждая зона анализируется отдельным sub-agent (studio-codebase-mapper)
+4. Синтез происходит из файлов в `_onboard/`, а не из кода напрямую
+5. После завершения `_onboard/` остаётся как артефакт (можно удалить позже)
+
+```
+docs/_onboard/
+├── 00-codebase-map.md        → структура + стек + статистика
+├── 01-zones.md               → карта зон для анализа
+├── zones/                    → промежуточные находки по зонам
+│   ├── zone-auth.md
+│   ├── zone-api.md
+│   ├── zone-models.md
+│   └── ...
+├── 02-domain-hypotheses.md   → гипотезы доменов (синтез из зон)
+├── 03-entity-registry.md     → все найденные сущности
+├── 04-event-registry.md      → все найденные события
+├── 05-api-surface.md         → все найденные API endpoints
+├── 06-integration-map.md     → внешние зависимости и интеграции
+├── 07-context-stack.md       → стек и архитектурные паттерны
+└── synthesis/                → финальный синтез
+    ├── domain-plan.md        → план доменов (утверждённый пользователем)
+    ├── decisions-log.md      → решения (автономный режим)
+    └── progress.md           → прогресс онбординга
+```
+
+---
+
+## Phase 0: Bootstrap
+
+### Step 0.1: Создай рабочую директорию
+```bash
+mkdir -p product-specs/docs/_onboard/zones product-specs/docs/_onboard/synthesis
+```
+
+### Step 0.2: Создай decisions log (для автономного режима)
+Если режим autonomous — создай `product-specs/docs/_onboard/synthesis/decisions-log.md`:
+```markdown
+# Autonomous Decisions Log
+
+Все решения, принятые автоматически в ночном режиме.
+
+| # | Phase | Decision | Rationale | Confidence |
+|---|-------|----------|-----------|------------|
+```
+
+### Step 0.3: Создай progress tracker
+Запиши в `product-specs/docs/_onboard/synthesis/progress.md`:
+```markdown
+# Onboarding Progress
+
+## Status: Phase 0 — Bootstrap
+## Project: $ARGUMENTS
+## Started: [date]
+
+### Phases
+- [x] Phase 0: Bootstrap
+- [ ] Phase 1: Codebase Map
+- [ ] Phase 2: Zone Analysis
+- [ ] Phase 3: Synthesis
+- [ ] Phase 4: Domain Creation
+- [ ] Phase 5: Contexts & PRDCTs
+- [ ] Phase 6: Validation
+
+### Zone Analysis Progress
+| Zone | Status | Findings file |
+|------|--------|---------------|
+```
+
+Этот файл обновляется после каждого шага. Если сессия прервётся — следующая сессия читает progress.md и продолжает с места остановки.
+
+---
+
+## Phase 1: Codebase Map (высокоуровневый обзор)
+
+Цель: понять размер, стек, и определить зоны для глубокого анализа. НЕ читай содержимое файлов — только структуру.
+
+### Step 1.1: Статистика проекта
+```bash
+# Размер проекта
+find $ARGUMENTS -type f -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.java" | grep -v node_modules | grep -v .git | grep -v dist | grep -v build | wc -l
+
+# Строки кода по типам файлов
+find $ARGUMENTS -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.py" -o -name "*.go" \) | grep -v node_modules | grep -v .git | xargs wc -l 2>/dev/null | tail -1
+
+# Структура верхнего уровня
+find $ARGUMENTS -maxdepth 2 -type d | grep -v node_modules | grep -v .git | grep -v dist | sort
+```
+
+### Step 1.2: Определи стек
+Прочитай ТОЛЬКО конфиг-файлы (они маленькие):
+- `package.json` (только dependencies секцию)
+- `docker-compose.yml`
+- `.env.example`
+- `tsconfig.json` / `go.mod` / `requirements.txt`
+- CI config (`.github/workflows/`, `.gitlab-ci.yml`)
+
+### Step 1.3: Определи зоны
+Раздели кодовую базу на **зоны** — логически изолированные части для анализа. Каждая зона должна помещаться в контекст одного sub-agent (~500 файлов max).
+
+Стратегия разбиения (в порядке приоритета):
+1. **По сервисам** (если monorepo/microservices): каждый сервис = зона
+2. **По модулям/features** (если modular monolith): каждый модуль = зона
+3. **По слоям** (если layered): models, controllers, services, utils = отдельные зоны
+4. **По размеру** (fallback): группы по ~200-300 файлов
+
+Для КАЖДОЙ зоны определи:
+- Имя (kebab-case)
+- Путь(и) в проекте
+- Примерное количество файлов
+- Что искать (модели? API? события? UI?)
+
+### Step 1.4: Запиши Codebase Map
+Запиши в `product-specs/docs/_onboard/00-codebase-map.md`:
+```markdown
+# Codebase Map
+
+## Project: [name]
+## Date: [date]
+
+## Stats
+- Total source files: [N]
+- Total LOC: [N]
+- Languages: [list]
+
+## Stack
+- Language: [X]
+- Backend framework: [X]
+- Frontend framework: [X]
+- Database: [X]
+- ORM: [X]
+- Message broker: [X]
+- Cache: [X]
+- CI/CD: [X]
+
+## Directory Structure
+[tree вывод]
+
+## Infrastructure
+[из docker-compose, env, CI]
+```
+
+### Step 1.5: Запиши карту зон
+Запиши в `product-specs/docs/_onboard/01-zones.md`:
+```markdown
+# Zone Map
+
+## Zones for analysis
+
+| # | Zone | Path(s) | Files (~) | Focus |
+|---|------|---------|-----------|-------|
+| 1 | zone-models | src/models/, src/entities/ | ~50 | Entities, schemas, types |
+| 2 | zone-api | src/controllers/, src/routes/ | ~80 | API endpoints, validation |
+| ... | ... | ... | ... | ... |
+
+## Analysis order
+1. zone-models (фундамент: сущности)
+2. zone-api (API surface)
+3. zone-services (бизнес-логика)
+4. zone-events (события, async)
+5. zone-frontend (UI, если есть)
+```
+
+**Interactive:** СТОП. Покажи пользователю codebase map и карту зон. Спроси:
+1. "Правильно ли я разбил проект? Нужно ли добавить/убрать/объединить зоны?"
+2. "Есть ли зоны которые можно пропустить?"
+
+**Autonomous:** Не останавливайся. Запиши в decisions-log: "Определил N зон, разбивка по [стратегия]. Confidence: [X]." Продолжай.
+
+Обнови progress.md: Phase 1 done.
+
+---
+
+## Phase 2: Zone Analysis (глубокое чтение кода по частям)
+
+Цель: прочитать ВСЮ кодовую базу по зонам, извлечь знания, записать в промежуточные файлы.
+
+### Для КАЖДОЙ зоны выполни:
+
+#### Step 2.1: Запусти studio-codebase-mapper agent для зоны
+Для каждой зоны запускай отдельный studio-codebase-mapper agent. Передай агенту:
+- Имя зоны
+- Путь(и) зоны
+- Фокус анализа
+- Релевантный контекст из product-specs/docs/_onboard/00-codebase-map.md
+
+Agent должен:
+1. Прочитать ВСЕ файлы в указанных путях (используя Glob + Read)
+2. Найти и записать:
+
+**Entities/Models:**
+- Имя, поля, типы
+- Relations (FK, references)
+- Enums/статусы (кандидаты в state machines)
+- Constraints/validation
+
+**Business Rules:**
+- Валидации (что проверяется, когда)
+- Guards/middleware (кто имеет доступ)
+- Условная логика (if/switch по бизнес-состояниям)
+
+**Events:**
+- Event names, producers, consumers
+- Payload structure
+- Async vs sync
+
+**API Endpoints:**
+- Method, path, handler
+- Request/response types
+- Auth requirements
+- Error codes
+
+**Dependencies:**
+- Imports из ДРУГИХ зон (потенциальные интеграции между доменами)
+- Внешние API calls
+- Database queries (какие таблицы читает/пишет)
+
+**Patterns:**
+- Repository/Service/Controller
+- Event sourcing / CQRS
+- State machines
+- Saga/orchestration patterns
+
+Результат записывается в `product-specs/docs/_onboard/zones/[zone-name].md`.
+
+#### Step 2.2: Проверь результат
+После завершения studio-codebase-mapper:
+1. Прочитай `product-specs/docs/_onboard/zones/[zone-name].md`
+2. Проверь что файл не пустой и содержит конкретные находки
+3. Если зона оказалась слишком большой (agent не прочитал всё):
+   - Раздели зону на подзоны
+   - Добавь подзоны в `01-zones.md`
+   - Запусти studio-codebase-mapper для каждой подзоны
+
+#### Step 2.3: Обнови прогресс
+После каждой зоны обнови `product-specs/docs/_onboard/synthesis/progress.md` — отметь зону как done.
+
+### Параллельный запуск
+Если зоны независимы — запускай до 3 studio-codebase-mapper agents параллельно для ускорения. Зависимые зоны (zone-services зависит от zone-models) — последовательно.
+
+### Шаблон zone файла
+
+Каждый `product-specs/docs/_onboard/zones/zone-*.md` должен следовать структуре:
+
+```markdown
+# Zone: [name]
+## Path(s): [paths]
+## Analyzed: [date]
+## Files read: [count]
+
+## Entities found
+| Entity | File | Fields | Relations | Status enum |
+|--------|------|--------|-----------|-------------|
+
+## Business rules found
+| Rule | File:Line | Description | Validation type |
+|------|-----------|-------------|-----------------|
+
+## Events found
+| Event | Producer file | Consumer file(s) | Payload | Sync/Async |
+|-------|--------------|-------------------|---------|------------|
+
+## API endpoints found
+| Method | Path | Handler file | Auth | Request type | Response type |
+|--------|------|-------------|------|-------------|---------------|
+
+## Cross-zone dependencies
+| This zone imports | From zone | Type (model/service/util) |
+|-------------------|-----------|--------------------------|
+
+## Patterns observed
+- [pattern]: [where and how used]
+
+## Domain hypotheses
+Из анализа этой зоны, эти файлы могут принадлежать доменам:
+| File/Entity | Hypothesized domain | Confidence | Evidence |
+|-------------|-------------------|------------|----------|
+
+## Notes & uncertainties
+- [что не удалось понять, что требует уточнения у человека]
+```
+
+**Interactive:** СТОП после всех зон. Покажи сводку: сколько зон проанализировано, сколько entities/events/endpoints найдено суммарно. Спроси есть ли пропущенные зоны.
+
+**Autonomous:** Запиши сводку в progress.md и продолжай к Phase 3.
+
+---
+
+## Phase 3: Synthesis (агрегация из зон в единую картину)
+
+Цель: прочитать ВСЕ zone-файлы (НЕ код!) и собрать единую картину.
+
+### Step 3.1: Собери реестр сущностей
+Прочитай ВСЕ `product-specs/docs/_onboard/zones/zone-*.md`. Извлеки все entities. Запиши в `product-specs/docs/_onboard/03-entity-registry.md`:
+```markdown
+# Entity Registry
+| Entity | Source zone | File | Fields count | Relations | Status enum | Hypothesized domain |
+```
+Дедупликация: если одна сущность встречается в нескольких зонах — объединяй, отмечай "shared".
+
+### Step 3.2: Собери реестр событий
+Из всех zone-файлов. Запиши в `product-specs/docs/_onboard/04-event-registry.md`:
+```markdown
+# Event Registry
+| Event | Producer zone | Consumer zone(s) | Payload | Domain boundary? |
+```
+Пометь события между зонами как "domain boundary candidates" — они указывают на границы доменов.
+
+### Step 3.3: Собери API surface
+Из всех zone-файлов. Запиши в `product-specs/docs/_onboard/05-api-surface.md`:
+```markdown
+# API Surface
+| Method | Path | Zone | Auth | Domain? |
+```
+
+### Step 3.4: Собери карту интеграций
+Из cross-zone dependencies всех зон. Запиши в `product-specs/docs/_onboard/06-integration-map.md`:
+```markdown
+# Integration Map
+
+## Internal dependencies (between zones)
+| From | To | Type | Indicates |
+```
+Нарисуй Mermaid graph зависимостей между зонами.
+
+### Step 3.5: Определи стек и паттерны
+Из patterns всех зон. Запиши в `product-specs/docs/_onboard/07-context-stack.md`:
+```markdown
+# Stack & Architecture Patterns
+## Observed patterns
+## Frameworks & libraries used
+## Testing infrastructure
+## CI/CD pipeline
+```
+
+### Step 3.6: Сформулируй гипотезы доменов
+Это ключевой шаг. На основе:
+- Entity registry (группировка сущностей)
+- Event registry (boundaries = events между зонами)
+- Integration map (слабо связанные кластеры)
+- Domain hypotheses из каждой зоны
+
+Запиши в `product-specs/docs/_onboard/02-domain-hypotheses.md`:
+```markdown
+# Domain Hypotheses
+
+## Methodology
+Домены определены на основе:
+1. Кластеризации сущностей по связям
+2. Границ событий (events между зонами)
+3. API namespace groups
+4. Cross-zone dependency analysis
+
+## Hypothesized domains
+
+### Domain: [name]
+- **Responsibility:** что делает этот домен
+- **Core entities:** [list] (из entity registry)
+- **Events produced:** [list] (из event registry)
+- **Events consumed:** [list]
+- **API endpoints:** [list] (из API surface)
+- **Source zones:** [list] — из каких зон собран
+- **Source files:** [key files]
+- **Confidence:** High / Medium / Low
+- **Evidence:** [почему считаем это отдельным доменом]
+- **Open questions:** [что непонятно]
+
+### Domain: [name]
+...
+
+## Domain relationship diagram
+[Mermaid graph: домены, стрелки = events/dependencies]
+
+## Entities not assigned to any domain
+| Entity | Source | Reason |
+```
+
+**Interactive:** СТОП. Покажи пользователю гипотезы доменов с evidence, diagram, не-распределённые entities. Спроси:
+- "Правильно ли определены домены?"
+- "Какие 3-5 создать первыми?"
+- "Есть ли implicit домены которых нет в коде?"
+
+**Autonomous:** Создай все домены с confidence >= Medium. Запиши в decisions-log: какие домены создаёшь и почему, какие пропустил (Low confidence). Приоритет: домены с наибольшим количеством entities.
+
+Запиши подтверждённый/автоматический план в `product-specs/docs/_onboard/synthesis/domain-plan.md`.
+
+---
+
+## Phase 4: Domain Creation (из промежуточных файлов, не из кода)
+
+Цель: создать domain docs из entity/event/api registries + zone files.
+
+### Для КАЖДОГО подтверждённого домена:
+
+#### Step 4.1: Собери контекст
+Прочитай ТОЛЬКО:
+- `product-specs/docs/_onboard/synthesis/domain-plan.md` (какие entities/events в этом домене)
+- Конкретные zone-файлы указанные в "Source zones"
+- Entity registry (строки для этого домена)
+- Event registry (строки для этого домена)
+
+НЕ читай код напрямую — все знания уже в zone-файлах.
+
+#### Step 4.2: Создай домен через studio-domain-extractor
+Запусти studio-domain-extractor agent для каждого домена. Agent получает:
+- Имя домена и responsibility из domain-plan.md
+- Релевантные zone-файлы
+- Entity registry (строки для этого домена)
+- Event registry (строки для этого домена)
+
+Agent создаёт полную структуру домена в `product-specs/docs/domains/[name]/`:
+1. Копирует шаблоны: `cp product-specs/docs/domains/_template/* product-specs/docs/domains/[name]/`
+2. Заполняет каждый файл из промежуточных данных:
+   - README.md — из domain hypothesis description
+   - ubiquitous-language.md — из entity names, field names, event names
+   - aggregates.md — из entities + relations + status enums → state machine
+   - business-rules.md — из business rules в zone-файлах
+   - events.md — из event registry
+   - invariants.md — из validation rules + DB constraints в zone-файлах
+   - integrations.md — из cross-zone dependencies + API endpoints
+   - ownership.md — оставь TBD, спросить пользователя
+
+Правила:
+- Заголовки на English, содержимое на Russian
+- YAML frontmatter обязателен
+- Используй Mermaid для state machines и ER diagrams
+- НЕ копируй код — описывай бизнес-логику своими словами
+- Domain docs содержат ТОЛЬКО бизнес-знание, НЕ реализацию
+
+#### Step 4.3: Обнови meta-документы
+После создания всех доменов:
+1. Обнови `product-specs/docs/_meta/domain-map.md` — добавь все новые домены и связи
+2. Обнови `product-specs/docs/_meta/capability-map.md`
+3. Обнови `product-specs/docs/_meta/glossary.md`
+
+**Interactive:** СТОП. Покажи созданные домены, количество файлов, completeness. Спроси подтверждение.
+
+**Autonomous:** Запиши в decisions-log: "[N] доменов создано, completeness [X]%". Продолжай.
+
+---
+
+## Phase 5: Contexts & Baseline PRDCTs
+
+### Step 5.1: Заполни контексты
+Прочитай `product-specs/docs/_onboard/07-context-stack.md` и заполни `product-specs/docs/contexts/`:
+
+**Backend:** architecture.md, service-map.md, data-ownership.md, async-flows.md, integration-patterns.md
+**Frontend:** architecture.md, routing.md, state-management.md, permissions-model.md
+**QA:** test-strategy.md, quality-gates.md
+**Analytics:** event-taxonomy.md
+
+Заполняй ТОЛЬКО из промежуточных файлов `_onboard/`. НЕ заполняй файл если данных нет.
+
+### Step 5.2: Создай ретроспективные PRDCT
+Для топ 3-5 ключевых фич (определяются из крупнейших entity clusters):
+
+1. Определи PRDCT-ID
+2. Создай облегчённый change package:
+   - `metadata.yaml` — status: done, retroactive: true
+   - `change-draft.md` — что и зачем
+   - `01-discovery.md` — актёры, основной сценарий
+   - `02-product-spec.md` — AC (фактическое поведение)
+   - `03-domain-impact.md` — затронутые домены
+   - `index.md`, `release-notes.md`
+3. 04-08 НЕ заполняй — избыточно для ретроспективных PRDCT
+
+> [!warning] Лимит: максимум 5 ретроспективных PRDCT
+
+---
+
+## Phase 6: Validation
+
+### Step 6.1: Проверь домены
+Для каждого домена:
+- [ ] Все 8 файлов существуют и не placeholder
+- [ ] ubiquitous-language не конфликтует между доменами
+- [ ] invariants корректны
+- [ ] events имеют producer И consumers
+
+### Step 6.2: Проверь целостность
+- [ ] Все entities из registry распределены по доменам
+- [ ] Все events из registry описаны в domain events
+- [ ] API surface покрыт доменами
+
+### Step 6.3: Итоговый отчёт
+
+```markdown
+## Onboarding Report
+
+### Project: [name]
+### Duration: [phases completed]
+
+### Codebase analyzed
+- Files scanned: [N]
+- Zones analyzed: [N]
+- LOC processed: [N]
+
+### Domains created
+| Domain | Entities | Events | Invariants | Completeness |
+|--------|----------|--------|------------|-------------|
+
+### Contexts filled
+| Context | Files filled | Files skipped |
+
+### Retrospective PRDCTs
+| PRDCT | Title | Domains |
+
+### Knowledge captured
+- Entities documented: [N]
+- Events documented: [N]
+- Business rules extracted: [N]
+- API endpoints mapped: [N]
+
+### Known gaps
+- [что НЕ удалось извлечь из кода]
+- [что требует уточнения с людьми]
+
+### Recommended next steps
+1. Проверить ubiquitous language с domain experts
+2. Дополнить business rules которые в головах (не в коде)
+3. Создать ADR для ключевых архитектурных решений
+4. `/review PRDCT-XXXX` для каждого ретроспективного PRDCT
+5. Удалить `product-specs/docs/_onboard/` когда больше не нужен
+```
+
+---
+
+## Resume protocol
+
+Если сессия прервалась:
+
+1. Прочитай `product-specs/docs/_onboard/synthesis/progress.md`
+2. Определи текущую фазу и шаг
+3. Прочитай готовые промежуточные файлы
+4. Продолжи с точки остановки
+
+Для пользователя: "Я вижу что онбординг начат ранее. Фаза [X] завершена, зоны [list] проанализированы. Продолжаю с [следующий шаг]."
+
+---
+
+## Tone
+Методичный архитектор-консультант:
+- Никогда не торопится
+- Предпочитает записать находку в файл, чем держать в голове
+- Показывает промежуточные результаты и ждёт подтверждения
+- Честно говорит "этой зоны не хватило, нужна ещё одна итерация"
+- Рекурсивно дробит то что не помещается в контекст