kodu 2.1.2 → 2.1.3

package/skills/start/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: start
+description: Единая точка входа для разработки продукта с нуля. Определяет текущее состояние проекта, объясняет что происходит на каждом шаге и вызывает нужные скиллы вместо пользователя. Запускай первым — этот скилл управляет всем. Другие скиллы (doc-gen, tech-blueprint, implement-project и т.д.) вызывать напрямую не нужно.
+license: MIT
+compatibility: opencode
+metadata:
+  level: multi
+  output: docs/ + prototype/ + blueprint/ + projects/
+---
+
+## Назначение
+
+Этот скилл — **единственный**, с которым нужно взаимодействовать. Он ведёт через весь конвейер разработки, вызывая остальные скиллы в нужный момент:
+
+```
+[1] Документация   →  doc-gen              → docs/<name>/
+[2] Прототип       →  litefront-prototype  → prototype/         (рекомендуется, не обязателен)
+[3] ТЗ             →  tech-blueprint       → blueprint/<name>/3_TECH_BLUEPRINT/
+[4] Реализация     →  implement-project    → projects/<name>/
+```
+
+Каждый этап создаёт артефакты для следующего. Не нужно знать как работают другие скиллы.
+
+---
+
+## При первом запуске
+
+1. Определить состояние проекта (см. «Определение состояния»)
+2. Если ни одного проекта нет → объяснить конвейер, спросить название и описание идеи
+3. Если проект найден → показать статус и предложить продолжить
+
+**Объяснение для нового пользователя (сказать один раз в начале):**
+
+> Разработка продукта проходит 4 этапа:
+>
+> **1. Документация** — опишем продукт: зачем, для кого, из чего состоит.
+> Результат: VISION.md (цели) + SPEC.md (требования и сценарии).
+>
+> **2. Прототип** — создадим кликабельный UI-макет. Все данные симулируются,
+> бэкенд не нужен. Помогает проверить UX до написания кода.
+>
+> **3. Техническое задание** — спроектируем базу данных, GraphQL API
+> и архитектуру фронтенда и бэкенда. 5 документов.
+>
+> **4. Реализация** — напишем полный рабочий проект с тестами.
+>
+> Перед переходом к каждому следующему этапу я буду ждать вашего «продолжить».
+
+---
+
+## Структура workspace
+
+```
+docs/<ИмяПроекта>/                    ← [Этап 1] продуктовая документация
+├── INDEX.md
+├── 1_PRODUCT_VISION/VISION.md
+└── 2_PRODUCT_SPEC/SPEC.md
+
+prototype/                             ← [Этап 2] UI-прототип (общий для всех проектов)
+└── src/...
+
+blueprint/<ИмяПроекта>/               ← [Этап 3] техническое задание
+└── 3_TECH_BLUEPRINT/
+    ├── IMPLEMENTATION_GUIDE.md
+    ├── DATABASE_MODEL.md
+    ├── API_CONTRACTS.md
+    ├── ARCHITECTURE.md
+    └── TESTING_PLAN.md
+
+projects/<ИмяПроекта>/                ← [Этап 4] реализация
+├── backend/
+└── frontend/
+```
+
+---
+
+## Определение состояния проекта
+
+Проверить наличие файлов (bash):
+
+```bash
+# Stage 1 завершён:
+test -f docs/<name>/2_PRODUCT_SPEC/SPEC.md
+
+# Stage 2 завершён:
+test -d prototype/src
+
+# Stage 3 создан (файлы есть):
+test -f blueprint/<name>/3_TECH_BLUEPRINT/IMPLEMENTATION_GUIDE.md
+
+# Stage 3 валиден (запустить и посмотреть на exit code):
+python3 ~/.config/opencode/skills/tech-blueprint/scripts/blueprint_validator.py \
+  validate "<name>" --output ./blueprint
+
+# Stage 4 завершён:
+test -d projects/<name>/backend/src && test -d projects/<name>/frontend/src
+```
+
+**Несколько проектов:** если в `docs/` найдено более одной папки — показать список и спросить с каким работаем.
+
+**Консистентность:** если `docs/<name>/SPEC.md` новее чем `blueprint/<name>/3_TECH_BLUEPRINT/DATABASE_MODEL.md` — предупредить:
+> ⚠️ SPEC.md изменялся после создания ТЗ. Рекомендуется пересоздать ТЗ командой «пересоздать ТЗ».
+
+---
+
+## Формат вывода статуса
+
+При запросе «статус» / «где мы» / «прогресс»:
+
+```
+## Проект: <ИмяПроекта>
+
+| Этап | Статус | Детали |
+|------|--------|--------|
+| 1. Документация   | ✅ Готово      | docs/<name>/SPEC.md |
+| 2. Прототип       | ✅ Готово      | prototype/src/ |
+| 3. ТЗ             | ⚠️ Нужны правки | blueprint_validator: 2 ошибки |
+| 4. Реализация     | ⏳ Не начата   | — |
+
+➡️ Следующий шаг: исправить ошибки ТЗ → сказать «валидируй» → затем «продолжить».
+```
+
+Статусы: `✅ Готово` / `⚠️ Нужны правки` / `🔄 В процессе` / `⏳ Не начато`
+
+---
+
+## Этап 1: Документация (doc-gen)
+
+**Сказать перед запуском:**
+> Начинаем с описания продукта. Я буду задавать вопросы — чем точнее вы опишете
+> идею, тем точнее получится документ. Обычно занимает 5-10 минут диалога.
+
+**Действие:** запустить скилл `doc-gen`
+(`~/.config/opencode/skills/doc-gen/SKILL.md`)
+
+Выходные документы должны лежать в `docs/<ИмяПроекта>/`.
+
+**После завершения — показать краткое резюме:**
+```
+✅ Документация создана: docs/<name>/
+
+Ключевые сущности (из SPEC.md §Сущности): <список>
+Ключевые операции: <3-5 операций>
+Страницы: <список>
+Роли пользователей: <список>
+```
+
+**Ворота ревью — ждать подтверждения:**
+> Прочитайте docs/<name>/2_PRODUCT_SPEC/SPEC.md.
+> Все ли сущности и операции описаны верно?
+> - Нужны правки → опишите что изменить, я обновлю
+> - Всё верно → скажите **«продолжить»**
+
+---
+
+## Этап 2: Прототип (litefront-prototype) — рекомендуется
+
+**Сказать перед запуском:**
+> Создадим кликабельный UI-прототип — все страницы будут работать,
+> но данные симулируются (без реального бэкенда).
+> Поможет визуально проверить SPEC.md и уточнить UX до написания кода.
+>
+> Этот этап можно пропустить — скажите **«пропустить»**, тогда ТЗ
+> будет создаваться только по тексту SPEC.md.
+
+**Действие:** запустить скилл `litefront-prototype`
+(`~/.config/opencode/skills/litefront-prototype/SKILL.md`)
+
+**После завершения:**
+```
+✅ Прототип создан: prototype/
+
+Запуск: cd prototype && npm run start:dev  →  http://localhost:3000
+
+Реализованные страницы: <список из прототипа>
+```
+
+**Ворота ревью — ждать подтверждения:**
+> Запустите прототип и проверьте все страницы и переходы.
+> - Нужны изменения в UI → опишите, обновлю прототип
+> - Нужно уточнить SPEC.md → скажите **«назад к документации»**
+> - Всё верно → скажите **«продолжить»**
+
+---
+
+## Этап 3: Техническое задание (tech-blueprint)
+
+**Сказать перед запуском:**
+> Создаём 5 технических документов — точное описание как будет построен проект:
+> - **DATABASE_MODEL.md** — схема БД (Prisma ORM, PostgreSQL)
+> - **API_CONTRACTS.md** — GraphQL API: операции, типы, права доступа
+> - **ARCHITECTURE.md** — NestJS-модули и FSD-слайсы фронтенда
+> - **TESTING_PLAN.md** — конкретные тест-сценарии
+> - **IMPLEMENTATION_GUIDE.md** — руководство разработчика: стек, что уже готово, команды
+>
+> После генерации документы автоматически проверяются валидатором на 9 критериев.
+
+**Действие:** запустить скилл `tech-blueprint`
+(`~/.config/opencode/skills/tech-blueprint/SKILL.md`)
+
+**После завершения — запустить валидатор:**
+```bash
+python3 ~/.config/opencode/skills/tech-blueprint/scripts/blueprint_validator.py \
+  validate "<name>" --output ./blueprint
+```
+
+Если есть ошибки → **исправить перед тем как показывать пользователю** (не переходить к следующему этапу с ошибками).
+
+**После успешной валидации — показать резюме:**
+```
+✅ ТЗ создано и валидно: blueprint/<name>/3_TECH_BLUEPRINT/
+
+Prisma-модели: <список>
+GraphQL-операции по доменам:
+  <Домен 1>: query1, mutation1
+  <Домен 2>: query2, mutation2
+NestJS-модули для реализации: <список>
+Новые FSD-слайсы: <список (без boilerplate-слайсов)>
+```
+
+**Ворота ревью — ждать подтверждения:**
+> Просмотрите ТЗ, особенно DATABASE_MODEL.md и API_CONTRACTS.md.
+> - Хотите изменить → правьте файлы в blueprint/<name>/3_TECH_BLUEPRINT/ и скажите **«валидируй»**
+> - Хотите полностью пересоздать → скажите **«пересоздать ТЗ»**
+> - Всё верно → скажите **«продолжить»**
+
+---
+
+## Этап 4: Реализация (implement-project)
+
+**Сказать перед запуском:**
+> Финальный и самый длительный этап — полная реализация по утверждённому ТЗ.
+> По завершении:
+> - projects/<name>/backend/ — работающий NestJS API
+> - projects/<name>/frontend/ — React SPA
+> - все тесты из TESTING_PLAN.md реализованы
+> - npm run check && npm run test:all зелёные в обоих проектах
+
+**Финальная проверка перед запуском:**
+- [ ] SPEC.md утверждён пользователем
+- [ ] Прототип просмотрен (или явно пропущен)
+- [ ] ТЗ прошло валидацию без ошибок (`blueprint_validator.py` → exit 0)
+
+Если хотя бы один пункт не выполнен → предупредить и спросить подтверждение:
+> ⚠️ Рекомендую сначала устранить [проблему]. Продолжить всё равно? («да» / «нет»)
+
+**Действие:** запустить скилл `implement-project`
+(`~/.config/opencode/skills/implement-project/SKILL.md`)
+
+**После завершения:**
+```
+🎉 Проект реализован!
+
+Запуск бэкенда:
+  cd projects/<name>/backend && npm run start:dev
+
+Запуск фронтенда:
+  cd projects/<name>/frontend && npm run start:dev
+
+Все проверки: npm run check && npm run test:all → ✅
+
+Что дальше:
+  1. Настроить OIDC-провайдер (Logto/Keycloak) в .env обоих проектов
+  2. Поднять PostgreSQL + Redis (docker compose up -d)
+  3. npm run db:migrations:apply
+```
+
+---
+
+## Все распознаваемые команды
+
+| Команда | Действие |
+|---------|---------|
+| «начать», «старт», «новый проект» | Определить состояние → начать или продолжить |
+| «статус», «где мы», «прогресс» | Таблица состояния всех 4 этапов |
+| «продолжить», «go», «следующий шаг» | Выполнить следующий незавершённый этап |
+| «пропустить» | Пропустить прототип (только для этапа 2) |
+| «назад к документации» | Повторно запустить doc-gen |
+| «пересоздать прототип» | Повторно запустить litefront-prototype |
+| «пересоздать ТЗ» | Повторно запустить tech-blueprint |
+| «валидируй», «проверь ТЗ» | Запустить blueprint_validator → показать результат |
+| «покажи документы» | Перечислить все созданные файлы с путями |
+| «как запустить» | Команды запуска для текущего состояния проекта |
+| «что такое [скилл]» | Объяснить назначение конкретного скилла |
+| «помощь», «help» | Показать эту таблицу |
+
+---
+
+## Обработка ошибок
+
+**Документация не отражает идею:**
+→ Описание правок от пользователя → обновить SPEC.md → показать что изменилось
+
+**Прототип не запускается:**
+→ `cd prototype && npm install && npm run start:dev` → показать полный текст ошибки
+
+**Ошибки blueprint_validator:**
+→ Показать каждую ошибку + объяснение → исправить автоматически где возможно → повторить валидацию
+
+**SPEC.md обновлён после создания ТЗ:**
+→ Предупредить об устаревании → предложить «пересоздать ТЗ»
+
+**Тесты не проходят:**
+→ Показать failing tests → предложить исправить → повторить `npm run test:all`
+
+**Незнакомый вопрос пользователя:**
+→ Ответить в контексте текущего этапа + подсказать следующий шаг
+
+---
+
+## Ключевые принципы поведения
+
+1. **Никогда не переходить к следующему этапу без явного «продолжить»** — всегда ждать
+2. **Объяснять ЧТО и ЗАЧЕМ** перед каждым действием — один абзац, без лишних деталей
+3. **Показывать прогресс**: «Этап 2 из 4 — Прототип» в начале каждого блока
+4. **При ошибке — не продолжать**: исправить → проверить → только потом вперёд
+5. **Краткие резюме**: 5-10 пунктов ключевых сущностей/операций — не пересказывать документ целиком
+6. **Один вопрос за раз** — не перегружать пользователя опросником
+7. **Помнить об ограничениях boilerplate** — не предлагать реализовывать уже готовое (`Profile`, `features/auth`, `pages/404`)