kodu 2.1.1 → 2.1.3

package/skills/project-setup-standardizer/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: project-setup-standardizer
+description: Enforces a unified, production-ready project setup (scripts, linting, testing, biome, lefthook) across any JS/TS project (backend, frontend, CLI, etc.). This skill MUST be invoked when initializing a new project.
+---
+
+**This skill is MANDATORY and must be invoked when creating a new project.**
+
+You are responsible for transforming an existing JavaScript/TypeScript project into a **production-ready, standardized
+structure**.
+
+Your goal is NOT to suggest — you MUST **apply and enforce** the conventions below.
+
+---
+
+## 1. PROJECT TYPE DETECTION
+
+Before making any changes, detect the project type using these signals:
+
+| Signal                                                           | Type     |
+|------------------------------------------------------------------|----------|
+| `dependencies` contains `react` or `vue`                         | frontend |
+| `devDependencies` contains `vite` (without react/vue)            | frontend |
+| `dependencies` contains `@nestjs/core` or `express` or `fastify` | backend  |
+| `bin` field exists in package.json                               | CLI      |
+| None of the above                                                | library  |
+
+Frontend projects get additional tools (stylelint, steiger). All other types share the base setup.
+
+---
+
+## 2. MIGRATION: REMOVE CONFLICTING TOOLS FIRST
+
+Before installing Biome, you MUST remove ESLint and Prettier if present:
+
+1. Delete config files: `.eslintrc*`, `.eslintignore`, `.prettierrc*`, `.prettierignore`
+2. Remove from `package.json` dependencies/devDependencies: `eslint`, `prettier`, and all `eslint-*` / `prettier-*`
+   packages
+3. Only after removal, proceed with Biome setup
+
+---
+
+## 3. PACKAGE.JSON SCRIPTS (MANDATORY STRUCTURE)
+
+You MUST normalize `package.json/scripts` into clearly separated sections using visual separators.
+
+Use this exact pattern:
+
+```json
+"scripts": {
+"________________ BUILD AND RUN ________________": "",
+"build": "...",
+"start:dev": "...",
+"start:prod": "...",
+"________________ FORMAT AND LINT ________________": "",
+"lint": "biome check",
+"lint:fix": "biome check --write",
+"lint:fix:unsafe": "biome check --write --unsafe",
+"ts:check": "tsc --noEmit",
+"knip": "knip --production",
+"check": "run-p ts:check lint:fix knip",
+"________________ TEST ________________": "",
+"test": "vitest run",
+"test:watch": "vitest",
+"test:cov": "vitest run --coverage",
+
+"________________ OTHER ________________": "",
+"prepare": "is-ci || lefthook install",
+"update": "npx npm-check-updates -u && rimraf node_modules package-lock.json && npm i",
+"postupdate": "npm run lint:fix && npm run check"
+}
+```
+
+If the project has distinct unit and e2e test layers, add:
+
+```json
+"test:unit": "...",
+"test:e2e": "...",
+"test:all": "run-s test:unit test:e2e"
+```
+
+Otherwise omit `test:all` — do not duplicate `test` under a different name.
+
+### Rules:
+
+- ALWAYS include `check` script → central quality gate
+- ALWAYS include `ts:check`; if no `tsconfig.json` exists, create a minimal one (see section 7)
+- ALWAYS include `knip` for unused exports/deps detection
+- ALWAYS include `lint:fix` in `check`
+- Use `run-p` (from `npm-run-all`) for parallel execution — never `npx run-p`
+- `prepare` MUST use `is-ci || lefthook install` to avoid CI failures when lefthook is not yet installed
+
+---
+
+## 4. FRONTEND-SPECIFIC REQUIREMENTS
+
+If project type is **frontend**, additionally include:
+
+```json
+"lint:fsd": "steiger ./src",
+"lint:style": "stylelint '**/*.{css,scss}'",
+"lint:style:fix": "npm run lint:style -- --fix",
+"check": "run-p lint:style ts:check lint:fix knip lint:fsd"
+```
+
+### Mandatory:
+
+- FSD validation via `steiger`
+- stylelint integration
+- include ALL checks in `check`
+
+---
+
+## 5. TESTING STANDARD (MANDATORY)
+
+Use **vitest only**.
+
+Rules:
+
+- NO jest
+- NO mixed frameworks
+- coverage MUST be supported via `test:cov`
+
+---
+
+## 6. BIOME CONFIG (MANDATORY)
+
+You MUST ensure `biome.json` exists with this content:
+
+```json
+{
+  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "lineEnding": "lf"
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single"
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "correctness": {
+        "noUnusedImports": "error",
+        "noUnusedVariables": "error",
+        "noUnusedFunctionParameters": "error"
+      }
+    }
+  },
+  "files": {
+    "includes": [
+      "**",
+      "!node_modules",
+      "!dist"
+    ]
+  },
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  }
+}
+```
+
+---
+
+## 7. LEFTHOOK (MANDATORY)
+
+You MUST write `lefthook.yml` with this exact content:
+
+```yaml
+pre-commit:
+  parallel: false
+  commands:
+    check:
+      run: npm run check
+
+pre-push:
+  parallel: false
+  commands:
+    test-all:
+      run: npm run test:all
+```
+
+Rules:
+
+- `check` (lint + types + knip) gates every commit
+- tests gate every push — `pre-push` does NOT re-run `check` (already gated at commit)
+- no bypassing allowed
+
+---
+
+## 8. MINIMAL TSCONFIG (if missing)
+
+If `tsconfig.json` does not exist, create it:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true
+  },
+  "include": [
+    "src",
+    "*.ts"
+  ]
+}
+```
+
+---
+
+## 9. REQUIRED DEV DEPENDENCIES
+
+Ensure these are installed (add any that are missing):
+
+Core (all project types):
+
+- `@biomejs/biome`
+- `typescript`
+- `vitest`
+- `lefthook`
+- `is-ci`
+- `npm-run-all`
+- `knip`
+- `rimraf`
+- `npm-check-updates`
+
+Frontend only:
+
+- `stylelint`
+- `steiger`
+
+---
+
+## 10. ENFORCEMENT LOGIC
+
+You MUST follow this order:
+
+1. Detect project type (section 1)
+2. Remove conflicting tools (section 2)
+3. Rewrite `package.json` scripts (section 3, or 4 for frontend)
+4. Write/update `biome.json` (section 6)
+5. Write/update `lefthook.yml` (section 7)
+6. Create `tsconfig.json` if missing (section 8)
+7. Install missing dev dependencies (section 9)
+
+NEVER:
+
+- keep inconsistent scripts
+- mix tools (eslint + biome)
+- leave partial setup
+
+---
+
+## 11. OUTPUT FORMAT
+
+You must output:
+
+1. Updated `package.json` (only the `scripts` and `devDependencies` sections)
+2. `biome.json`
+3. `lefthook.yml`
+4. `tsconfig.json` (if created)
+5. List of removed files and packages
+
+All configs must be **complete and copy-paste ready**.
+
+---
+
+## 12. PRINCIPLE
+
+Your job is to enforce:
+
+- determinism
+- reproducibility
+- zero-config onboarding
+- strict quality gates
+
+If something is ambiguous — choose the stricter option.

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`)