@kudusov.takhir/ba-toolkit 1.2.0

package/README.ru.md

@@ -0,0 +1,846 @@
+<div align="center">
+
+# 📋 BA Toolkit
+
+<strong>AI-конвейер для бизнес-аналитика</strong><br>
+От брифа проекта до передачи в разработку — 21 навык, полностью структурированный пайплайн
+
+[🇺🇸 English](README.md) · 🇷🇺 **Русский**
+
+<img src="https://img.shields.io/badge/skills-21-blue" alt="Skills">
+<img src="https://img.shields.io/badge/domains-9-green" alt="Domains">
+<img src="https://img.shields.io/badge/format-Markdown-orange" alt="Format">
+<img src="https://img.shields.io/badge/language-auto--detect-purple" alt="Language">
+<img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="License">
+
+<img src="https://img.shields.io/badge/Claude_Code-✓-6C5CE7" alt="Claude Code">
+<img src="https://img.shields.io/badge/Codex_CLI-✓-00D26A" alt="Codex CLI">
+<img src="https://img.shields.io/badge/Gemini_CLI-✓-4285F4" alt="Gemini CLI">
+<img src="https://img.shields.io/badge/Cursor-convert-F5A623" alt="Cursor">
+<img src="https://img.shields.io/badge/Windsurf-convert-1ABCFE" alt="Windsurf">
+
+</div>
+
+---
+
+## Содержание
+
+- [Что это?](#-что-это)
+  - [Для кого это?](#для-кого-это)
+  - [Почему не просто промптить напрямую?](#почему-не-просто-промптить-chatgpt--claude-напрямую)
+- [Совместимость с платформами](#-совместимость-с-платформами)
+- [Пайплайн](#-пайплайн)
+- [Поддержка доменов](#-поддержка-доменов)
+- [Как работает каждый навык](#-как-работает-каждый-навык)
+- [Установка](#-установка)
+  - [Вариант A: Claude Code](#вариант-a-claude-code-cli--рекомендуется)
+  - [Вариант B: OpenAI Codex CLI](#вариант-b-openai-codex-cli)
+  - [Вариант C: Google Gemini CLI](#вариант-c-google-gemini-cli)
+  - [Вариант D: Cursor, Windsurf, Aider](#вариант-d-cursor-windsurf-aider)
+  - [Начало нового проекта](#начало-нового-проекта)
+  - [Обновление BA Toolkit](#обновление-ba-toolkit)
+- [Структура репозитория](#-структура-репозитория)
+- [Система кросс-ссылок](#-система-кросс-ссылок)
+- [Минимально жизнеспособный пайплайн](#-минимально-жизнеспособный-пайплайн)
+- [Быстрый старт](#-быстрый-старт)
+- [Как выглядит результат](#️-как-выглядит-результат)
+- [Руководство по использованию](#-руководство-по-использованию)
+  - [1. Начало проекта](#1-начало-проекта)
+  - [2. Движение по пайплайну](#2-движение-по-пайплайну)
+  - [3. Использование /clarify](#3-использование-clarify)
+  - [4. Использование /analyze](#4-использование-analyze)
+  - [5. Использование /trace](#5-использование-trace)
+  - [6. Разбиение крупных элементов](#6-разбиение-крупных-элементов)
+  - [7. Работа с несколькими проектами](#7-работа-с-несколькими-проектами)
+  - [8. Решение проблем](#8-решение-проблем)
+  - [9. AGENTS.md — постоянный контекст проекта](#9-agentsmd--постоянный-контекст-проекта)
+- [FAQ](#-faq)
+- [Вклад в проект](#-вклад-в-проект)
+- [Добавление нового домена](#-добавление-нового-домена)
+- [История изменений](CHANGELOG.md)
+- [Лицензия](#-лицензия)
+
+---
+
+## 🎯 Что это?
+
+BA Toolkit — это набор из **21 взаимосвязанного навыка**, которые превращают вашего AI-агента в бизнес-аналитика. Вы проходите по структурированному пайплайну — от высокоуровневого брифа проекта до пакета передачи в разработку — и получаете полный набор артефактов требований, готовый для инженерной команды.
+
+Каждый навык **читает результаты предыдущих шагов**, поддерживает кросс-ссылки между артефактами (FR → US → UC → AC → NFR → Сущности → ADR → API → Экраны → Сценарии) и адаптируется под домен вашего проекта.
+
+**Артефакты генерируются на том языке, на котором вы пишете.** Спросите на английском — получите документы на английском. Спросите на русском, испанском или любом другом языке — результат последует за языком запроса.
+
+### Для кого это?
+
+- **Разработчики**, создающие продукт без выделенного BA — получите структурированные требования до написания кода.
+- **Продакт-менеджеры**, которым нужна формальная документация (SRS, AC, NFR), но хочется производить её быстрее.
+- **Бизнес-аналитики**, использующие AI для ускорения создания артефактов и сокращения ручного кросс-ссылочного контроля.
+- **Основатели стартапов**, превращающие идею в спецификацию, готовую для команды разработки или презентации инвесторам.
+
+### Почему не просто промптить ChatGPT / Claude напрямую?
+
+| | Одноразовый промпт | BA Toolkit |
+|--|-----------------|-----------|
+| Структура | Одноразово; нет памяти между сообщениями | 11 взаимосвязанных артефактов, каждый читает все предыдущие |
+| Покрытие | Легко пропустить NFR, крайние случаи, модель данных | Структурированное интервью + чек-листы предотвращают пробелы |
+| Трассируемость | Отсутствует | Цепочка FR → US → AC → API → WF через `/trace` |
+| Контроль качества | Эпизодический | `/clarify` и `/analyze` с градацией CRITICAL/HIGH |
+| Доменные знания | Общие | Встроенные референсы по 9 доменам (iGaming, Fintech, SaaS, E-commerce, Healthcare, Logistics, On-demand, Social/Media, Real Estate) |
+| Передача в разработку | Текст в чате | До 11 Markdown-файлов, готовых для Jira, Spec Kit или команды разработки |
+
+---
+
+## 🤖 Совместимость с платформами
+
+BA Toolkit использует открытую **спецификацию Agent Skills** (формат SKILL.md), опубликованную Anthropic в декабре 2025 года и принятую на нескольких платформах.
+
+| Платформа | Поддержка | Установка |
+|----------|:-------:|-------------|
+| **Claude Code** | ✅ Нативная | `cp -r skills/ .claude/skills/ba-toolkit/` |
+| **OpenAI Codex CLI** | ✅ Нативная | `cp -r skills/ ~/.codex/skills/ba-toolkit/` |
+| **Gemini CLI** | ✅ Нативная | Скопируйте всё дерево `skills/` в `~/.gemini/skills/ba-toolkit/` (пользовательская) или `.gemini/skills/ba-toolkit/` (проектная) |
+| **Cursor** | 🔄 Конверсия | SKILL.md → правила `.mdc` в `.cursor/rules/` |
+| **Windsurf** | 🔄 Конверсия | SKILL.md → правила в `.windsurf/rules/` |
+| **Aider** | 🔄 Конверсия | SKILL.md → файл conventions |
+
+> 💡 Платформы с отметкой **Нативная** читают SKILL.md как есть. Платформы с отметкой **Конверсия** требуют одноразовой конвертации формата — содержимое одинаковое, различается только формат файла. Конвертацию можно автоматизировать через инструменты вроде [convert.sh](https://github.com/alirezarezvani/claude-skills/blob/main/scripts/convert.sh).
+
+### Определение окружения
+
+Навыки не хардкодят платформо-специфичные пути. Вместо этого они ссылаются на `references/environment.md`, где содержится логика определения выходной директории для каждой платформы. По умолчанию артефакты сохраняются в текущей рабочей директории.
+
+Чтобы настроить под свою конфигурацию, отредактируйте `skills/references/environment.md` — все навыки автоматически подхватят изменения.
+
+---
+
+## 🔗 Пайплайн
+
+```
+📐 /principles (опционально)
+        │
+        ▼
+📄 /brief → 📑 /srs → 📝 /stories → 🔄 /usecases → ✅ /ac → ⚡ /nfr → 🗃️ /datadict → 🔬 /research → 🔌 /apicontract → 🖼️ /wireframes → 🧪 /scenarios → 📦 /handoff
+                           │
+                           └──→ 🔍 /trace    (доступно после /stories)
+
+🔎 /clarify [focus]  — доступно на любом шаге, для любого артефакта
+📊 /analyze          — доступно на любом шаге после /srs
+```
+
+| # | Команда | Что генерирует | Файл результата |
+|:---:|---------|-------------------|-------------|
+| 0 | `/principles` | 📐 Принципы проекта — язык, ID-конвенции, DoR, правила трассируемости, базовые NFR | `00_principles_{slug}.md` |
+| 1 | `/brief` | 📄 Бриф проекта — цели, аудитория, стейкхолдеры, риски | `01_brief_{slug}.md` |
+| 2 | `/srs` | 📑 Спецификация требований (IEEE 830) | `02_srs_{slug}.md` |
+| 3 | `/stories` | 📝 User Stories, сгруппированные по эпикам | `03_stories_{slug}.md` |
+| 4 | `/usecases` | 🔄 Use Cases с основным/альтернативным/исключительным потоками | `04_usecases_{slug}.md` |
+| 5 | `/ac` | ✅ Критерии приёмки (Given/When/Then) | `05_ac_{slug}.md` |
+| 6 | `/nfr` | ⚡ Нефункциональные требования с метриками | `06_nfr_{slug}.md` |
+| 7 | `/datadict` | 🗃️ Словарь данных — сущности, типы, ограничения | `07_datadict_{slug}.md` |
+| 7a | `/research` | 🔬 Технологическое исследование — ADR, карта интеграций, решения по хранению данных | `07a_research_{slug}.md` |
+| 8 | `/apicontract` | 🔌 API-контракт — эндпоинты, схемы, ошибки | `08_apicontract_{slug}.md` |
+| 9 | `/wireframes` | 🖼️ Текстовые описания вайрфреймов | `09_wireframes_{slug}.md` |
+| 10 | `/scenarios` | 🧪 Сквозные валидационные сценарии — пользовательские пути, связывающие US, AC, WF, API | `10_scenarios_{slug}.md` |
+| 11 | `/handoff` | 📦 Пакет передачи в разработку — инвентарь артефактов, объём MVP, открытые пункты | `11_handoff_{slug}.md` |
+| — | `/trace` | 🔍 Матрица трассируемости + пробелы покрытия | `00_trace_{slug}.md` |
+| — | `/clarify [focus]` | 🔎 Целевое разрешение неоднозначностей для любого артефакта | _(обновляет существующий артефакт)_ |
+| — | `/analyze` | 📊 Отчёт о качестве по всем артефактам с таблицей серьёзности | `00_analyze_{slug}.md` |
+| — | `/estimate` | 📏 Оценка трудозатрат — Фибоначчи SP, T-shirt размеры или человеко-дни | `00_estimate_{slug}.md` |
+| — | `/glossary` | 📖 Единый глоссарий проекта с детекцией терминологического дрифта | `00_glossary_{slug}.md` |
+| — | `/export [format]` | 📤 Экспорт User Stories в Jira / GitHub Issues / Linear / CSV | `export_{slug}_{format}.json` / `.csv` |
+| — | `/risk` | ⚠️ Реестр рисков — матрица вероятность × влияние, митигация по каждому риску | `00_risks_{slug}.md` |
+| — | `/sprint` | 🗓️ План спринтов — истории, сгруппированные по velocity и capacity с целями спринтов | `00_sprint_{slug}.md` |
+
+> 💡 **Slug** проекта (например, `dragon-fortune`) задаётся на шаге `/brief` и автоматически переиспользуется во всех файлах.
+
+---
+
+## 🌍 Поддержка доменов
+
+По умолчанию пайплайн **доменно-агностичен**. На этапе `/brief` вы выбираете домен — и каждый последующий навык загружает доменно-специфичные вопросы интервью, обязательные сущности, категории NFR и термины глоссария.
+
+| Домен | Покрываемые отрасли |
+|--------|-------------------|
+| 🎰 **iGaming** | Онлайн-слоты, ставки на спорт, казино-лобби, Telegram Mini Apps, промо-механики |
+| 🏦 **Fintech** | Необанки, платёжные системы, криптобиржи, инвестиционные платформы, P2P-кредитование |
+| ☁️ **SaaS** | B2B-платформы, CRM, аналитика, маркетплейсы, EdTech, HRTech |
+| 🛒 **E-commerce** | B2C-магазины, B2B-каталоги, мульти-вендорные маркетплейсы, D2C-бренды, цифровые товары |
+| 🏥 **Healthcare** | Телемедицина, портал пациента, EHR/EMR, управление клиникой, приложения для ментального здоровья |
+| 🚚 **Logistics** | Доставка "последней мили", управление курьерами, отслеживание грузов, WMS, управление автопарком |
+| 🔧 **On-demand** | Райд-хейлинг, домашние услуги, маркетплейсы задач, красота, репетиторство, уход за питомцами |
+| 📱 **Social / Media** | Соцсети, платформы для криейторов, форумы сообществ, рассылки, короткое видео |
+| 🏠 **Real Estate** | Порталы недвижимости, CRM агентств, управление арендой, property management, ипотечные инструменты |
+| ✏️ **Custom** | Любой другой домен — работает с общими вопросами интервью |
+
+> ➕ **Добавление нового домена** = создание одного Markdown-файла в `skills/references/domains/`. См. раздел [Добавление нового домена](#-добавление-нового-домена) ниже.
+
+---
+
+## 🔄 Как работает каждый навык
+
+Большинство навыков пайплайна следуют этому циклу:
+
+```
+┌─────────────┐      ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  1. Команда │────▶│ 2. Контекст │────▶│ 3. Интервью │────▶│ 4. Генерация│
+│   /brief    │      │  Загрузка   │     │ 3-7 вопросов│     │   Markdown  │
+│   /srs ...  │      │  предыдущих │     │ за раунд,   │     │ артефакт +  │
+│             │      │ артефактов +│     │  2-4 раунда │     │   резюме    │
+│             │      │  домена +   │     │             │     │             │
+│             │      │  принципов  │     │             │     │             │
+└─────────────┘      └─────────────┘     └─────────────┘     └──────┬──────┘
+                                                                    │
+                                                                    ▼
+                                                             ┌─────────────┐
+                                                             │5. Доработка │
+                                                             │             │
+                                                             │ /clarify    │
+                                                             │ /revise     │
+                                                             │ /expand     │
+                                                             │ /split      │
+                                                             │ /validate   │
+                                                             │ /done ──────┼──▶ Следующий шаг
+                                                             └─────────────┘
+```
+
+> `/handoff`, `/trace` и `/analyze` пропускают шаг 3 — они извлекают всю информацию из существующих артефактов автоматически, без интервью.
+
+### Подкоманды
+
+| Команда | Что делает |
+|---------|-------------|
+| `/clarify [focus]` | Целевой проход по неоднозначностям — выявляет размытые термины, отсутствующие метрики, противоречивые правила |
+| `/revise [section]` | Переписать конкретный раздел с вашими правками |
+| `/expand [section]` | Добавить больше деталей в раздел |
+| `/split [element]` | Разбить крупный элемент на более мелкие (например, большую user story) |
+| `/validate` | Проверить полноту, согласованность и соответствие предыдущим артефактам |
+| `/analyze` | Отчёт о качестве по всем артефактам: дубликаты, пробелы покрытия, терминологический дрифт, невалидные ссылки |
+| `/done` | Зафиналить текущий артефакт и перейти к следующему шагу пайплайна |
+
+---
+
+## 📦 Установка
+
+### 🚀 Самый простой способ: через npm (без клонирования)
+
+```bash
+# Одноразовая настройка проекта — ничего не устанавливать, просто запустить:
+npx ba-toolkit init
+npx ba-toolkit install --for claude-code
+
+# Или установить глобально и переиспользовать для всех проектов:
+npm install -g ba-toolkit
+ba-toolkit install --for claude-code --global
+```
+
+Поддерживаемые агенты: `claude-code`, `codex`, `gemini`, `cursor`, `windsurf`. Установка для Cursor и Windsurf автоматически конвертирует `SKILL.md` в формат правил `.mdc`. Используйте `--dry-run`, чтобы посмотреть результат без записи файлов.
+
+Запустите `ba-toolkit --help` для полного списка команд CLI. У npm-пакета **нулевые рантайм-зависимости** — нужен только Node.js ≥ 18.
+
+---
+
+### Вариант A: Claude Code CLI ✨ Ручная установка
+
+```bash
+# Клонирование и копирование директории skills (включает доменные референсы)
+git clone https://github.com/TakhirKudusov/ba-toolkit.git
+cp -r ba-toolkit/skills/ /path/to/project/.claude/skills/ba-toolkit/
+```
+
+Или установить глобально:
+
+```bash
+cp -r ba-toolkit/skills/ ~/.claude/skills/ba-toolkit/
+```
+
+Сохраняйте полное дерево: папки навыков (`brief/`, `srs/`, …) должны оставаться вместе с `references/` в одной родительской директории.
+
+### Вариант B: OpenAI Codex CLI
+
+Навыки загружаются из `$CODEX_HOME/skills` (по умолчанию `~/.codex/skills`). Копируйте **всю** директорию `skills/` как один каталог, чтобы общий `references/` оставался рядом с каждым навыком:
+
+```bash
+cp -r ba-toolkit/skills/ ~/.codex/skills/ba-toolkit/
+```
+
+Если вы используете кастомный Codex home, задайте `CODEX_HOME` и копируйте под `$CODEX_HOME/skills/ba-toolkit/`.
+
+### Вариант C: Google Gemini CLI
+
+Та же схема, что и для Codex: одна директория, содержащая все подпапки навыков **и** `references/`:
+
+```bash
+# Пользовательская (для всех проектов)
+cp -r ba-toolkit/skills/ ~/.gemini/skills/ba-toolkit/
+
+# Или только для проекта (в корне репозитория)
+cp -r ba-toolkit/skills/ /path/to/project/.gemini/skills/ba-toolkit/
+```
+
+После копирования перезагрузите CLI.
+
+### Вариант D: Cursor, Windsurf, Aider
+
+Эти платформы используют собственный формат правил вместо SKILL.md. Сначала конвертируйте, затем копируйте:
+
+```bash
+# Вариант 1: используйте community-конвертер
+# https://github.com/alirezarezvani/claude-skills/blob/main/scripts/convert.sh
+./convert.sh --tool cursor --target /path/to/project
+./convert.sh --tool windsurf --target /path/to/project
+
+# Вариант 2: попросите вашего AI-агента
+# "Convert all SKILL.md files in skills/ to Cursor .mdc rule format"
+```
+
+**Cursor (детали):** правила проекта располагаются в [`.cursor/rules/`](https://cursor.com/docs/rules) как файлы `.mdc`. Каждое правило — это Markdown с **YAML-фронтматтером** сверху (например, `description`, опциональный `globs` для паттернов файлов и `alwaysApply`, когда правило должно применяться в каждом Agent-чате). Просто переименовать `SKILL.md` в `.mdc` недостаточно — нужен этот метаданный блок. [Cursor CLI](https://cursor.com/docs/cli/using) использует ту же конфигурацию `.cursor/rules`, что и редактор, и также может читать `AGENTS.md` / `CLAUDE.md` в корне репозитория наряду с правилами.
+
+### Начало нового проекта
+
+Запустите скрипт-инициализатор, чтобы создать папку результатов и стартовый `AGENTS.md` одним шагом:
+
+```bash
+# macOS / Linux
+bash init.sh
+
+# Windows PowerShell
+.\init.ps1
+```
+
+Скрипт спросит slug проекта, название и домен, затем создаст `output/{slug}/` и `AGENTS.md` с полной таблицей статуса пайплайна. После этого откройте вашего AI-ассистента и запустите `/brief`.
+
+---
+
+### Обновление BA Toolkit
+
+Когда выходит новая версия, подтяните последние изменения и пересоберите директорию `skills/` в месте установки:
+
+```bash
+cd ba-toolkit
+git pull
+
+# Claude Code — на уровне проекта
+cp -r skills/ /path/to/project/.claude/skills/ba-toolkit/
+
+# Claude Code — глобально
+cp -r skills/ ~/.claude/skills/ba-toolkit/
+
+# Codex CLI
+cp -r skills/ ~/.codex/skills/ba-toolkit/
+
+# Gemini CLI (пользовательская установка)
+cp -r skills/ ~/.gemini/skills/ba-toolkit/
+```
+
+
+Ранее сгенерированные файлы артефактов (`01_brief_*.md`, `02_srs_*.md` и т. д.) обновлением не затрагиваются — они остаются точно такими, какими вы их оставили.
+
+---
+
+## 📁 Структура репозитория
+
+```
+ba-toolkit/
+│
+├── skills/                        # 🧠 Исходные файлы SKILL.md (устанавливайте эту директорию)
+│   ├── ac/SKILL.md                #    Шаг 5: Критерии приёмки
+│   ├── apicontract/SKILL.md       #    Шаг 8: API-контракт
+│   ├── brief/SKILL.md             #    Шаг 1: Бриф проекта
+│   ├── datadict/SKILL.md          #    Шаг 7: Словарь данных
+│   ├── nfr/SKILL.md               #    Шаг 6: Нефункциональные требования
+│   ├── srs/SKILL.md               #    Шаг 2: Требования (SRS)
+│   ├── stories/SKILL.md           #    Шаг 3: User Stories
+│   ├── principles/SKILL.md        #    Шаг 0 (опционально): Принципы проекта
+│   ├── trace/SKILL.md             #    Кросс-сквозной: Матрица трассируемости
+│   ├── clarify/SKILL.md           #    Кросс-сквозной: Целевое разрешение неоднозначностей
+│   ├── analyze/SKILL.md           #    Кросс-сквозной: Отчёт о качестве по артефактам
+│   ├── usecases/SKILL.md          #    Шаг 4: Use Cases
+│   ├── wireframes/SKILL.md        #    Шаг 9: Описания вайрфреймов
+│   ├── research/SKILL.md          #    Шаг 7a (опционально): Технологическое исследование и ADR
+│   ├── scenarios/SKILL.md         #    Шаг 10 (опционально): Сквозные валидационные сценарии
+│   ├── handoff/SKILL.md           #    Шаг 11 (опционально): Пакет передачи в разработку
+│   ├── estimate/SKILL.md          #    Утилита: Оценка трудозатрат (SP / T-shirt / человеко-дни)
+│   ├── glossary/SKILL.md          #    Утилита: Единый глоссарий проекта
+│   ├── export/SKILL.md            #    Утилита: Экспорт в Jira / GitHub Issues / Linear / CSV
+│   ├── risk/SKILL.md              #    Утилита: Реестр рисков (матрица вероятность × влияние)
+│   ├── sprint/SKILL.md            #    Утилита: План спринтов (группировка по velocity)
+│   └── references/
+│       ├── environment.md         #    🖥️ Платформо-специфичные пути вывода
+│       ├── closing-message.md     #    📋 Шаблон завершающего сообщения (используется всеми навыками)
+│       ├── prerequisites.md       #    ✅ Чек-листы предварительных условий по шагам
+│       ├── templates/             #    📄 Базовые шаблоны артефактов с плейсхолдерами [TOKEN]
+│       │   ├── README.md
+│       │   ├── principles-template.md
+│       │   ├── brief-template.md
+│       │   ├── srs-template.md
+│       │   ├── stories-template.md
+│       │   ├── usecases-template.md
+│       │   ├── ac-template.md
+│       │   ├── nfr-template.md
+│       │   ├── datadict-template.md
+│       │   ├── research-template.md
+│       │   ├── apicontract-template.md
+│       │   ├── wireframes-template.md
+│       │   ├── scenarios-template.md
+│       │   ├── trace-template.md
+│       │   ├── analyze-template.md
+│       │   └── handoff-template.md
+│       └── domains/
+│           ├── igaming.md         #    🎰 Доменные знания iGaming
+│           ├── fintech.md         #    🏦 Доменные знания Fintech
+│           ├── saas.md            #    ☁️ Доменные знания SaaS
+│           ├── ecommerce.md       #    🛒 Доменные знания E-commerce
+│           ├── healthcare.md      #    🏥 Доменные знания Healthcare / MedTech
+│           ├── logistics.md       #    🚚 Доменные знания Logistics / Delivery
+│           ├── on-demand.md       #    🔧 Доменные знания On-demand / Services
+│           ├── social-media.md    #    📱 Доменные знания Social / Media
+│           └── real-estate.md     #    🏠 Доменные знания Real Estate
+│
+├── example/
+│   └── dragon-fortune/            # 📚 Полный пример проекта (iGaming Telegram Mini App)
+│
+├── bin/
+│   └── ba-toolkit.js              # 🧰 Точка входа npm CLI (нулевые рантайм-зависимости)
+├── package.json                   # 📦 Манифест npm-пакета (для `npx ba-toolkit`)
+├── init.ps1                       # 🚀 Инициализатор проекта (Windows PowerShell)
+├── init.sh                        # 🚀 Инициализатор проекта (macOS / Linux bash)
+├── CHANGELOG.md                   # 📋 История версий
+├── COMMANDS.md                    # 📜 Шпаргалка по всем командам
+├── LICENSE                        # Текст лицензии MIT
+├── README.md                      # English version
+├── README.ru.md                   # Русская версия
+├── .gitignore
+└── .github/
+    ├── workflows/
+    │   ├── validate.yml           # ✅ CI: валидация артефактов и файлов навыков на PR
+    │   └── release.yml            # 🚀 CD: создание GitHub Release при пуше тега версии
+    └── scripts/
+        └── validate_artifacts.py  # Python-валидатор, используемый в CI
+```
+
+> 💡 **`skills/`** — это директория, которую вы устанавливаете: копируйте её как единое целое, чтобы `references/` оставался рядом со всеми папками навыков.
+
+---
+
+## 🔗 Система кросс-ссылок
+
+Каждый артефакт ссылается на своих предшественников. Эта цепочка обеспечивает полную трассируемость от бизнес-целей до спецификаций экранов:
+
+```
+FR-001 (SRS)
+  └── US-001 (Stories)
+        └── UC-001 (Use Cases)
+              └── AC-001-01 (Критерии приёмки)
+                    │
+                  NFR-003 (Нефункциональные требования)
+                    │
+                  User, Bet (Словарь данных)
+                    │
+                  ADR-002 (Research — техническое решение, продиктованное этой сущностью)
+                    │
+                  POST /bets (API-контракт)
+                    │
+                  WF-005 (Вайрфреймы)
+                    │
+                  SC-003 (Валидационный сценарий — сквозной путь)
+```
+
+Команда `/trace` строит **полную матрицу** этих ссылок и подсвечивает непокрытые FR, истории без AC, "осиротевшие" сущности и эндпоинты, а также процент покрытия по каждому типу артефакта. Команда `/analyze` добавляет находки с градацией серьёзности: дубликаты, неоднозначные термины, терминологический дрифт и невалидные ссылки.
+
+---
+
+## ⚡ Минимально жизнеспособный пайплайн
+
+Не каждому проекту нужен весь набор из 21 навыка. Два распространённых пути:
+
+**Lean** (самый быстрый путь до handoff — 9 шагов):
+```
+/brief → /srs → /stories → /ac → /nfr → /datadict → /apicontract → /wireframes → /handoff
+```
+
+**Full** (полная трассируемость и контроль качества — 15 шагов):
+```
+/principles → /brief → /srs → /stories → /usecases → /ac → /nfr → /datadict
+           → /research → /apicontract → /wireframes → /scenarios
+           → /trace → /analyze → /handoff
+```
+
+Используйте `/clarify` на любом шаге, чтобы разрешить неоднозначности перед переходом дальше.
+
+**Оценки времени** (приблизительные, зависят от сложности проекта и глубины интервью):
+
+| Шаг | Lean pipeline | Full pipeline |
+|------|:---:|:---:|
+| `/principles` | — | 5–10 мин |
+| `/brief` | 15–25 мин | 20–35 мин |
+| `/srs` | 25–40 мин | 30–50 мин |
+| `/stories` | 20–30 мин | 25–40 мин |
+| `/usecases` | — | 20–35 мин |
+| `/ac` | 20–35 мин | 25–40 мин |
+| `/nfr` | 15–20 мин | 15–25 мин |
+| `/datadict` | 15–25 мин | 20–30 мин |
+| `/research` | — | 15–25 мин |
+| `/apicontract` | 20–35 мин | 25–40 мин |
+| `/wireframes` | 25–40 мин | 30–50 мин |
+| `/scenarios` | — | 15–25 мин |
+| `/trace` + `/analyze` | — | 10–15 мин |
+| `/handoff` | 5–10 мин | 5–10 мин |
+| **Итого** | **~3–4 часа** | **~5–8 часов** |
+
+---
+
+## 🚀 Быстрый старт
+
+```
+# Опционально: определить конвенции перед стартом
+Вы:      /principles
+Агент:   На каком языке генерировать артефакты? Какая серьёзность блокирует /done?
+Вы:      Русский, блокировать только на CRITICAL
+Агент:   [генерирует 00_principles_dragon-fortune.md — применяется всеми последующими навыками]
+
+Вы:      /brief
+Агент:   В каком домене ваш проект? (iGaming, Fintech, SaaS, другой?)
+Вы:      iGaming — онлайн-слот как Telegram Mini App
+Агент:   [задаёт 5-6 целевых вопросов о целях, аудитории, ограничениях...]
+Вы:      [отвечаете]
+Агент:   [генерирует 01_brief_dragon-fortune.md]
+         Артефакт сохранён: 01_brief_dragon-fortune.md
+         Покрыто: 4 бизнес-цели, 3 стейкхолдера, 6 рисков.
+         Следующий шаг: /srs
+
+Вы:      /done
+Агент:   Бриф зафиналирован. Следующий шаг: /srs
+
+Вы:      /srs
+Агент:   [читает бриф, спрашивает про роли, интеграции, бизнес-правила...]
+...
+```
+
+Повторяйте для каждого шага. В любой момент после `/srs` запустите `/clarify [focus]`, чтобы разрешить неоднозначности в текущем артефакте, или `/analyze` — для полного кросс-артефактного отчёта о качестве. После `/stories` запустите `/trace`, чтобы проверить покрытие трассируемости.
+
+---
+
+## 🗂️ Как выглядит результат
+
+Полный пример проекта — **Dragon Fortune** (iGaming Telegram Mini App) — включён в [`example/dragon-fortune/`](example/dragon-fortune/). Все 15 артефактов реалистичные, связаны кросс-ссылками и сгенерированы прогоном полного пайплайна BA Toolkit.
+
+| Артефакт | Файл |
+|---------|------|
+| Принципы проекта | [`00_principles_dragon-fortune.md`](example/dragon-fortune/00_principles_dragon-fortune.md) |
+| Бриф проекта | [`01_brief_dragon-fortune.md`](example/dragon-fortune/01_brief_dragon-fortune.md) |
+| Требования (SRS) | [`02_srs_dragon-fortune.md`](example/dragon-fortune/02_srs_dragon-fortune.md) |
+| User Stories | [`03_stories_dragon-fortune.md`](example/dragon-fortune/03_stories_dragon-fortune.md) |
+| Use Cases | [`04_usecases_dragon-fortune.md`](example/dragon-fortune/04_usecases_dragon-fortune.md) |
+| Критерии приёмки | [`05_ac_dragon-fortune.md`](example/dragon-fortune/05_ac_dragon-fortune.md) |
+| Нефункциональные требования | [`06_nfr_dragon-fortune.md`](example/dragon-fortune/06_nfr_dragon-fortune.md) |
+| Словарь данных | [`07_datadict_dragon-fortune.md`](example/dragon-fortune/07_datadict_dragon-fortune.md) |
+| Технологическое исследование | [`07a_research_dragon-fortune.md`](example/dragon-fortune/07a_research_dragon-fortune.md) |
+| API-контракт | [`08_apicontract_dragon-fortune.md`](example/dragon-fortune/08_apicontract_dragon-fortune.md) |
+| Вайрфреймы | [`09_wireframes_dragon-fortune.md`](example/dragon-fortune/09_wireframes_dragon-fortune.md) |
+| Валидационные сценарии | [`10_scenarios_dragon-fortune.md`](example/dragon-fortune/10_scenarios_dragon-fortune.md) |
+| Пакет передачи в разработку | [`11_handoff_dragon-fortune.md`](example/dragon-fortune/11_handoff_dragon-fortune.md) |
+| Реестр рисков | [`00_risks_dragon-fortune.md`](example/dragon-fortune/00_risks_dragon-fortune.md) |
+| План спринтов | [`00_sprint_dragon-fortune.md`](example/dragon-fortune/00_sprint_dragon-fortune.md) |
+
+> Пример демонстрирует полную трассируемость: FR → US → UC → AC → NFR → Сущность → ADR → API → WF → Сценарий, плюс реестр рисков и план спринтов.
+
+---
+
+## 📖 Руководство по использованию
+
+### 1. Начало проекта
+
+Запустите первую команду, и агент возьмёт управление на себя — он загрузит доменные референсы, задаст вопросы и сгенерирует артефакт. Вы никогда не редактируете файлы SKILL.md напрямую.
+
+```
+Вы:      /brief
+Агент:   В каком домене ваш проект? (iGaming, Fintech, SaaS, другой?)
+Вы:      Fintech — мобильное приложение необанка
+Агент:   Отлично. Задам несколько вопросов.
+         1. Какая основная бизнес-цель — привлечение новых пользователей, рост использования карт или что-то другое?
+         2. На какую географию и валюту ориентировано приложение?
+         3. Есть ли существующие банки-партнёры или приложение будет standalone-продуктом?
+Вы:      [отвечаете на все три]
+Агент:   Ещё пара вопросов...
+         [1-2 раунда]
+Агент:   [генерирует 01_brief_neobank-app.md]
+
+         Артефакт сохранён: 01_brief_neobank-app.md
+         Покрыто: 3 бизнес-цели, 5 стейкхолдеров, 4 риска.
+         Slug зафиксирован для этого пайплайна: neobank-app
+
+         Доступно: /clarify · /revise · /expand · /validate · /done
+         Следующий шаг: /srs
+```
+
+**Slug** (`neobank-app`) выводится из названия проекта на шаге `/brief` и используется как суффикс для каждого последующего файла: `02_srs_neobank-app.md`, `03_stories_neobank-app.md` и т. д.
+
+---
+
+### 2. Движение по пайплайну
+
+После просмотра сгенерированного артефакта либо доработайте его, либо зафиналите:
+
+```
+# Не устраивает раздел — переписать его
+Вы:      /revise section 3
+Агент:   [спрашивает, что изменить, переписывает раздел 3, сохраняет файл]
+
+# Нужны детали
+Вы:      /expand section 7
+Агент:   [добавляет детали в раздел 7]
+
+# Всё устраивает — перейти к следующему шагу
+Вы:      /done
+Агент:   Бриф зафиналирован. Артефакт сохранён.
+         Следующий шаг: /srs
+```
+
+Каждый шаг автоматически читает результаты всех предыдущих шагов. Вам не нужно вставлять или ссылаться на предыдущие файлы — агент находит их по slug в выходной директории.
+
+---
+
+### 3. Использование /clarify
+
+Запускайте `/clarify` после генерации любого артефакта, чтобы выявить неоднозначности перед переходом дальше. Это быстрее, чем обнаружить проблему через три шага.
+
+```
+Вы:      /clarify
+Агент:   Найдено 4 неоднозначности в 02_srs_neobank-app.md:
+
+         1. [FR-003] "Система должна отвечать быстро" — какое целевое время отклика в мс?
+         2. [FR-011] Роль "Admin" используется, но не определена в разделе 2.2 — это то же, что "Compliance Officer"?
+         3. [NFR-001] "Высокая доступность" — какой числовой целевой SLA (%)?
+         4. [FR-019 vs FR-024] Оба описывают конвертацию валют — это одна и та же фича?
+
+Вы:      1. Под 200мс на p95. 2. Нет, Admin — отдельная внутренняя роль. 3. 99.9%. 4. Да, слить.
+Агент:   [обновляет FR-003, добавляет Admin в роли, добавляет 99.9% в NFR-001, сливает FR-019 и FR-024]
+         Обновлено: 02_srs_neobank-app.md — 4 неоднозначности разрешены.
+```
+
+Можно также сфокусироваться на конкретной области:
+
+```
+Вы:      /clarify security
+Вы:      /clarify FR-015
+```
+
+---
+
+### 4. Использование /analyze
+
+Запускайте `/analyze` в любой момент после `/srs`, чтобы получить кросс-артефактный отчёт о качестве. В отличие от `/trace` (который проверяет ссылки), `/analyze` также ловит дубликаты, неоднозначный язык и терминологический дрифт.
+
+```
+Вы:      /analyze
+Агент:   [читает все существующие артефакты]
+
+         Артефакт сохранён: 00_analyze_neobank-app.md
+
+         Finding Report:
+         | ID | Category      | Severity | Location          | Summary                          | Recommendation        |
+         |----|---------------|----------|-------------------|----------------------------------|-----------------------|
+         | A1 | Coverage Gap  | CRITICAL | srs:FR-008        | Нет связанной user story         | Создать US или удалить|
+         | A2 | Ambiguity     | HIGH     | nfr:NFR-004       | "Масштабируемый" без метрики     | Добавить целевой RPS  |
+         | A3 | Terminology   | HIGH     | srs + stories     | Дрифт "Wallet" vs "Balance"      | Стандартизировать в глоссарии |
+         | A4 | Duplication   | MEDIUM   | srs:FR-012,FR-017 | Почти-дубликат требований логина | Слить                 |
+
+         Общее покрытие: FR→US 87% · US→AC 94%
+         CRITICAL: 1 · HIGH: 2 · MEDIUM: 1
+
+         Топ-действия: исправить A1 через /stories, исправить A2 через /clarify NFR-004, исправить A3 через /revise glossary
+```
+
+**Градация серьёзности:**
+
+| Серьёзность | Значение | Действие |
+|----------|---------|--------|
+| CRITICAL | Нарушает целостность пайплайна — отсутствует обязательная ссылка, несуществующий ID | Исправить до `/done` |
+| HIGH | Значительный риск качества — отсутствующая метрика, дрифт ключевого термина | Исправить до handoff |
+| MEDIUM | Опасение качества, не блокирует | Задокументировать или отложить |
+| LOW | Стилистическое предложение | Опционально |
+
+Запустите `/analyze` повторно после исправлений, чтобы отследить прогресс.
+
+---
+
+### 5. Использование /trace
+
+Запускайте `/trace` после `/stories`, чтобы проверить покрытие трассируемости. Он строит полную матрицу FR → US → UC → AC → ...
+
+```
+Вы:      /trace
+Агент:   [генерирует 00_trace_neobank-app.md]
+
+         Coverage Summary:
+         FR → US:       24/27 (89%) — FR-008, FR-019, FR-022 не покрыты
+         US → AC:       41/41 (100%) ✓
+         Entity → FR:   18/20 (90%) — Transaction, AuditLog не привязаны
+
+         Рекомендации:
+         — Создать user stories для FR-008, FR-019, FR-022 или удалить их из SRS
+         — Привязать Transaction и AuditLog к соответствующим FR в /datadict
+```
+
+Запустите `/trace` снова после исправления пробелов — он перечитает все артефакты и пересчитает матрицу.
+
+---
+
+### 6. Разбиение крупных элементов
+
+Если user story или требование слишком широкое, разбейте его:
+
+```
+Вы:      /split US-014
+Агент:   US-014 покрывает 4 отдельных действия. Предлагаемое разбиение:
+         — US-014a: Игрок просматривает историю транзакций (read-only)
+         — US-014b: Игрок фильтрует транзакции по дате и типу
+         — US-014c: Игрок экспортирует транзакции в PDF
+         — US-014d: Игрок оспаривает транзакцию
+
+         Применить разбиение?
+Вы:      Да, но объедини 014a и 014b
+Агент:   [переписывает US-014 как две истории: US-014 и US-014b]
+```
+
+---
+
+### 7. Работа с несколькими проектами
+
+Каждый проект получает свой slug и свой набор файлов. Если вы работаете с несколькими проектами в одной директории, запустите `/principles` первым для каждого и установите `output mode: subfolder` — файлы будут автоматически организованы по подпапкам `{slug}/`.
+
+Если вы начинаете новый проект без смены выходной директории, агент обнаружит существующие файлы `01_brief_*.md` и предупредит вас перед перезаписью.
+
+---
+
+### 8. Решение проблем
+
+**Агент говорит, что не может найти бриф / SRS / предыдущий артефакт:**
+Навык ищет файлы, соответствующие маске `01_brief_*.md` в выходной директории. Если файл сохранён в другом месте, либо переместите его, либо укажите агенту полный путь.
+
+**Артефакт сгенерирован не на том языке:**
+Запустите `/principles` и явно укажите язык артефактов. Затем перезапустите текущий шаг — все последующие навыки будут использовать язык из `00_principles_{slug}.md`.
+
+**Нужно переделать шаг с нуля:**
+Запустите команду снова (например, `/srs`). Агент предупредит, что `02_srs_{slug}.md` уже существует, и предложит перезаписать или создать новую версию.
+
+**Не загружается доменный референс:**
+Проверьте, что `skills/references/domains/{domain}.md` существует, и что имя домена в брифе точно совпадает (`igaming`, `fintech`, `saas`, `ecommerce`, `healthcare`, `logistics`, `on-demand`, `social-media` или `real-estate` — в нижнем регистре с дефисами).
+
+**`/analyze` сообщает о находках, которые вы уже исправили:**
+Запустите `/analyze` снова — он всегда перечитывает все артефакты заново. Кэшированные результаты не используются.
+
+---
+
+### 9. AGENTS.md — постоянный контекст проекта
+
+После завершения `/brief` агент создаёт или обновляет `AGENTS.md` в корне вашего проекта. В этом файле хранится slug проекта, домен, ключевые ограничения, пути к артефактам и текущий этап пайплайна.
+
+```markdown
+# BA Toolkit — Project Context
+
+**Project:** Dragon Fortune
+**Slug:** dragon-fortune
+**Domain:** iGaming
+**Language:** English
+**Pipeline stage:** Brief complete
+
+## Artifacts
+- `/outputs/01_brief_dragon-fortune.md` — Project Brief
+
+## Key context
+- **Business goal:** Telegram Mini App slot for CIS markets, 50k MAU in 6 months
+- **Key constraints:** Telegram API limits, AML/KYC compliance, certified RTP
+
+## Next step
+Run /srs to generate the Requirements Specification.
+```
+
+`AGENTS.md` обновляется снова после `/srs` — добавляются роли, интеграции и количество FR. Любой AI-агент (Claude Code, Codex, Gemini CLI), прочитавший этот файл, поймёт контекст проекта без повторного чтения всех артефактов — полезно при возобновлении работы в новой сессии.
+
+---
+
+## ❓ FAQ
+
+**Нужны ли все 21 навык?**
+Нет. Lean-пайплайн (`/brief → /srs → /stories → /ac → /nfr → /datadict → /apicontract → /wireframes → /handoff`) покрывает основы за ~3–4 часа. Добавляйте `/usecases`, `/research`, `/scenarios`, `/trace` и `/analyze`, когда нужно более глубокое покрытие.
+
+**Можно ли использовать на любом языке?**
+Да. Агент определяет язык вашего первого сообщения и генерирует все артефакты на этом языке. Задайте его явно через `/principles`, если хотите зафиксировать язык независимо от языка разговора.
+
+**Работает ли офлайн / без интернета?**
+Да. Все навыки — это локальные Markdown-файлы. Единственная сетевая зависимость — ваш AI-агент (Claude Code, Codex CLI и т. д.). Ни один компонент BA Toolkit не обращается к внешним API.
+
+**Мой домен — не iGaming, не Fintech и не SaaS. Я всё равно могу использовать BA Toolkit?**
+Да. Выберите "Custom" на шаге `/brief`, и навыки будут использовать общие вопросы интервью. Можно добавить свой домен за 30 минут, создав один Markdown-файл — см. раздел [Добавление нового домена](#-добавление-нового-домена).
+
+**Можно ли вернуться и отредактировать предыдущий артефакт?**
+Да. Запустите `/revise [section]` на любом шаге, либо вызовите команду навыка заново (например, `/srs`), чтобы перегенерировать с нуля. Агент предупредит перед перезаписью. Последующие навыки автоматически прочтут обновлённую версию.
+
+**Работает ли с более мелкими / быстрыми моделями?**
+Структурированный Markdown-формат и явные кросс-ссылки помогают небольшим моделям оставаться в контексте. Для лучших результатов используйте модель с окном контекста не менее 32k токенов — поздние шаги пайплайна загружают несколько крупных артефактов одновременно.
+
+**Как обновить BA Toolkit после выхода новой версии?**
+См. инструкции по обновлению в разделе [Установка](#-установка) выше.
+
+---
+
+## 🤝 Вклад в проект
+
+Вклады приветствуются. Наиболее полезные дополнения:
+
+**Новые домены** (максимальное влияние, без кода):
+Создайте `skills/references/domains/{domain}.md` по шаблону из раздела [Добавление нового домена](#-добавление-нового-домена). Откройте PR с файлом и кратким описанием домена.
+
+**Улучшения навыков:**
+Редактируйте соответствующий `skills/{name}/SKILL.md`. Сохраняйте обратную совместимость — избегайте переименования секций или изменения имён выходных файлов, так как другие навыки от них зависят.
+
+**Отчёты о багах:**
+Откройте GitHub issue с указанием: имени навыка, запущенной команды, используемого агента/платформы и того, что произошло vs что ожидалось.
+
+**Правила:**
+- Один PR на один домен или навык.
+- Протестируйте навык сквозным прогоном перед отправкой (запустите полную команду, проверьте выходной файл).
+- Сохраняйте стиль согласованным с существующими навыками: формальный, нейтральный, без эмодзи в теле артефакта, язык следует вводу пользователя.
+
+---
+
+<h2 id="-добавление-нового-домена">➕ Добавление нового домена</h2>
+
+Создайте `skills/references/domains/{domain}.md` по следующей структуре:
+
+```markdown
+# Domain Reference: {Name}
+
+## 1. /brief — Project Brief
+### Domain-specific interview questions
+### Typical business goals
+### Typical risks
+
+## 2. /srs — Requirements Specification
+### Domain-specific interview questions
+### Typical functional areas
+
+## 3. /stories — User Stories
+### Domain-specific interview questions
+### Typical epics
+
+## 4. /usecases — Use Cases
+## 5. /ac — Acceptance Criteria
+## 6. /nfr — Non-functional Requirements
+## 7. /datadict — Data Dictionary
+## 8. /apicontract — API Contract
+## 9. /wireframes — Wireframe Descriptions
+
+## Domain Glossary
+| Term | Definition |
+|------|-----------|
+```
+
+Каждый навык загружает **только свою секцию** из файла референса — это эффективно расходует контекст.
+
+---
+
+## 📄 Лицензия
+
+MIT — используйте свободно, модифицируйте, распространяйте. Полный текст см. в [LICENSE](LICENSE).