@jakerdy/agentica 0.0.2

package/prompts/validate.prompt.md

@@ -0,0 +1,480 @@
+---
+name: agentica.validate
+description: Семантическая и инструментальная валидация реализации спецификации
+---
+
+## Ввод пользователя
+
+```text
+$ARGUMENTS
+```
+
+Ты **ОБЯЗАН** учесть ввод пользователя (аргументы и контекст) перед тем как продолжить.
+
+## Цель и принципы работы
+
+Твоя задача — проверить что реализация фичи (FT-XXXX) **соответствует спецификации** на продуктовом и техническом уровне.
+Работай линейно: **Валидация контекста → Чтение критериев → Семантическая проверка → Инструментальная проверка → Отчёт**.
+
+Хорошая валидация — это не формальная "галочка", а **детальный анализ** соответствия кода требованиям с конкретными примерами и рекомендациями.
+
+**Ключевые принципы:**
+1. **Два уровня проверки:** Семантическая (соответствие спеке) + Инструментальная (тесты, линтер, типы).
+2. **Memory как контекст:** Используй факты из `memory`, собранные на этапах `create`, `tasks`, `implement`.
+3. **Конкретика:** Указывай файлы, строки, примеры — не общие фразы.
+4. **Конструктивность:** Если есть проблемы — предлагай конкретные шаги для исправления.
+5. **Полнота:** Проверяй все критерии из `validation.md`, не пропускай.
+
+### Глобальные запреты (Safety Guards)
+
+Останови выполнение и не продолжай работу, если:
+1. Спецификация FT-XXXX **не существует** (остановись и предложи пользователю воспользоваться агентом: `agentica.create`).
+2. Файл `validation.md` **пустой или отсутствует** (остановись и предложи пользователю воспользоваться агентом: `agentica.tasks`).
+3. Файл `tasks.md` **пустой** — непонятно что должно быть реализовано (остановись и предложи пользователю воспользоваться агентом: `agentica.tasks`).
+4. Реализация **не завершена** — есть незакрытые задачи в `tasks.md` (остановись и предложи пользователю воспользоваться агентом: `agentica.implement`).
+5. Запрос требует **изменения кода** (это валидация, а не реализация).
+
+В случае остановки: объясни причину и предложи корректную команду.
+
+## Топология и размещение файлов
+
+**Структура спецификации:**
+```
+FT-XXXX - <Название фичи>/
+├── product.md       # Продуктовое описание (ЧТО и ЗАЧЕМ)
+├── tech.md          # Техническое решение (КАК)
+├── research.md      # Исследование библиотек (опционально)
+├── tasks.md         # Задачи для реализации (статус выполнения)
+└── validation.md    # Критерии приемки — ОСНОВА ДЛЯ ПРОВЕРКИ
+```
+
+**Отчёт валидации:**
+После проверки создай файл:
+```
+FT-XXXX - <Название фичи>/
+└── validation-report.md    # Итоговый отчёт валидации
+```
+
+## Фаза 1: Валидация контекста
+
+### Шаг 1.1: Поиск спецификации FT-XXXX
+
+Определи номер целевой спецификации:
+
+**Вариант A: Явное указание**
+```text
+/agentica.validate --id FT-0012
+```
+
+**Вариант B: Из контекста git ветки**
+```bash
+git branch --show-current
+# Извлеки FT-XXXX из паттерна: <scope-id>/FT-XXXX-<slug>
+```
+
+**Вариант C: Из открытого файла**
+Проверь путь открытого файла — если содержит `.agentica/features/FT-XXXX`, извлеки номер.
+
+**Вариант D: Интерактивный выбор**
+Если контекста недостаточно — просканируй `.agentica/features/` и задай вопрос через интсрумент `ask_questions`.
+
+### Шаг 1.2: Проверка готовности к валидации
+
+Проверь наличие обязательных файлов:
+1. `product.md` — **ОБЯЗАТЕЛЬНО**. Если пустой → STOP.
+2. `tech.md` — **ОБЯЗАТЕЛЬНО**. Если пустой → STOP.
+3. `tasks.md` — **ОБЯЗАТЕЛЬНО**. Если пустой → STOP.
+4. `validation.md` — **ОБЯЗАТЕЛЬНО**. Если пустой → STOP.
+
+### Шаг 1.3: Проверка статуса реализации
+
+Прочитай `tasks.md` и проверь:
+- Все ли фазы отмечены как завершённые?
+- Есть ли незакрытые задачи ([ ] вместо [x])?
+
+Если реализация не завершена — сообщи об этом и предложи сначала завершить `agentica.implement`.
+
+## Фаза 2: Чтение критериев валидации
+
+### Шаг 2.1: Чтение спецификации
+
+Прочитай полностью (используй параллельное чтение):
+1. `product.md` — продуктовый контекст, user stories
+2. `tech.md` — техническое решение, архитектурные решения
+3. `tasks.md` — план реализации и статус задач
+4. `validation.md` — **ОСНОВНОЙ ДОКУМЕНТ** с критериями приемки
+
+### Шаг 2.2: Извлечение контекста из Memory
+
+IDE автоматически предоставит доступ к релевантным фактам из `memory`, собранным на этапах `create`, `tasks`, `implement`.
+
+Используй эти факты для понимания архитектурного контекста и интеграционных точек.
+
+### Шаг 2.3: Структура validation.md
+
+Документ `validation.md` обычно содержит следующие секции:
+
+**1. Продуктовые критерии:**
+- User Stories: Выполнены ли все пользовательские сценарии?
+- Use Cases: Покрыты ли все случаи использования?
+- Edge Cases: Обработаны ли граничные случаи?
+
+**2. Технические критерии:**
+- Архитектура: Соответствует ли код архитектурным решениям из `tech.md`?
+- Интеграция: Корректна ли интеграция с существующими модулями?
+- Code Quality: Соблюдены ли стандарты качества?
+
+**3. Критерии качества:**
+- Тесты: Покрытие, проходимость
+- Документация: Наличие комментариев, примеров
+- Производительность: Соответствие нефункциональным требованиям
+
+Извлеки все критерии в структурированный список для проверки.
+
+## Фаза 3: Семантическая валидация
+
+Для каждого критерия из `validation.md` выполни проверку.
+
+### Тип проверки 1: User Story / Use Case
+
+**Для каждого сценария:**
+1. Найди реализацию в коде через `semantic_search` или `grep_search`
+2. Прочитай релевантные файлы через `read_file`
+3. Проверь что все шаги сценария реализованы
+4. Проверь что есть тесты для этого сценария
+
+**Пример:**
+```
+Критерий: "Пользователь может загрузить CSV файл до 100MB"
+Проверка:
+- ✓ Найден FileValidator.validateSize() в src/upload/validators/file-validator.ts:45
+- ✓ Проверка размера: maxSize = 100 * 1024 * 1024
+- ✓ Есть тест: tests/upload/validators/file-validator.test.ts:23 "should reject file larger than 100MB"
+Статус: PASS
+```
+
+### Тип проверки 2: Архитектурное решение
+
+**Для каждого архитектурного требования из `tech.md`:**
+1. Найди реализацию компонента
+2. Проверь что структура соответствует описанию
+3. Проверь что использованы правильные паттерны
+4. Проверь что интеграция выполнена корректно
+
+**Пример:**
+```
+Критерий: "BatchUploadService должен использовать Factory pattern"
+Проверка:
+- ✓ ServiceFactory создаёт экземпляры: src/factories/service-factory.ts:67
+- ✓ BatchUploadService регистрирован в фабрике
+- ✓ Dependency Injection через конструктор
+Статус: PASS
+```
+
+### Тип проверки 3: Edge Case
+
+**Для каждого граничного случая:**
+1. Найди обработку в коде
+2. Проверь что есть соответствующий тест
+3. Проверь что поведение соответствует спецификации
+
+**Пример:**
+```
+Критерий: "При ошибке парсинга CSV показывать номер строки и описание ошибки"
+Проверка:
+- ✓ CSVParser.parse() возвращает ParseError с lineNumber: src/parsers/csv-parser.ts:89
+- ✓ Ошибка содержит message и context
+- ✓ Есть тест: tests/parsers/csv-parser.test.ts:56 "should return error with line number on malformed CSV"
+Статус: PASS
+```
+
+### Тип проверки 4: Интеграция
+
+**Для каждой точки интеграции:**
+1. Проверь что модули правильно подключены
+2. Проверь что контракты соблюдены
+3. Проверь что есть integration-тесты
+
+### Формат результата проверки
+
+Для каждого критерия формируй структурированную запись:
+
+```markdown
+#### [ID] <Название критерия>
+
+**Описание:** <Что должно быть реализовано>
+
+**Проверка:**
+- <Пункт 1>: <Статус> <Ссылка на код>
+- <Пункт 2>: <Статус> <Ссылка на код>
+...
+
+**Статус:** PASS | FAIL | PARTIAL
+
+**Комментарий:** <Дополнительные замечания, если есть>
+```
+
+Статусы:
+- **PASS** — критерий полностью выполнен
+- **FAIL** — критерий не выполнен
+- **PARTIAL** — критерий выполнен частично
+
+## Фаза 4: Инструментальная валидация
+
+### Шаг 4.1: Запуск тестов
+
+```bash
+bun test
+```
+
+Проверь:
+- Все ли тесты проходят?
+- Какое покрытие кода (coverage)?
+- Есть ли тесты для всех новых компонентов?
+
+### Шаг 4.2: Линтер
+
+```bash
+bun lint
+```
+
+Проверь:
+- Нет ли ошибок линтера?
+- Нет ли warnings, которые нужно исправить?
+
+### Шаг 4.3: Проверка типов (если TypeScript)
+
+```bash
+bun typecheck
+bun typecheck:tests
+# или
+tsc --noEmit
+```
+
+Проверь отсутствие ошибок типизации.
+
+### Шаг 4.4: Сборка проекта
+
+```bash
+bun run build
+```
+
+Проверь что проект собирается без ошибок.
+
+### Шаг 4.5: Анализ кодовой базы
+
+Используй `get_errors` для проверки текущих проблем в IDE.
+
+## Фаза 5: Генерация отчёта
+
+### Шаг 5.1: Структура отчёта
+
+Создай файл `validation-report.md` в директории спецификации:
+
+````markdown
+# Validation Report: FT-XXXX - <Название фичи>
+
+**Дата проверки:** <YYYY-MM-DD>
+**Проверяющий:** GitHub Copilot (agentica.validate)
+
+---
+
+## 📊 Сводка
+
+| Категория | Всего | ✓ Pass | ⚠ Partial | ✗ Fail |
+|:----------|:------|:-------|:----------|:-------|
+| Продуктовые критерии | X | Y | Z | W |
+| Технические критерии | X | Y | Z | W |
+| Критерии качества | X | Y | Z | W |
+| **ИТОГО** | **X** | **Y** | **Z** | **W** |
+
+**Общий статус:** PASS | PARTIAL | FAIL
+
+---
+
+## ✓ Продуктовые критерии
+
+### User Stories
+
+#### [US-01] <Название>
+**Описание:** ...
+**Проверка:**
+- ✓ ...
+**Статус:** PASS
+
+### Use Cases
+
+#### [UC-01] <Название>
+...
+
+### Edge Cases
+
+#### [EC-01] <Название>
+...
+
+---
+
+## ✓ Технические критерии
+
+### Архитектура
+
+#### [ARCH-01] <Название>
+...
+
+### Интеграция
+
+#### [INT-01] <Название>
+...
+
+### Code Quality
+
+#### [CQ-01] <Название>
+...
+
+---
+
+## ✓ Критерии качества
+
+### Тесты
+
+**Результаты:**
+- Unit тесты: X passed, Y total
+- Integration тесты: X passed, Y total
+- E2E тесты: X passed, Y total (если есть)
+- Coverage: X%
+
+**Статус:** PASS | FAIL
+
+### Линтер
+
+**Результаты:**
+- Errors: X
+- Warnings: Y
+
+**Статус:** PASS | FAIL
+
+### typecheck
+
+**Результаты:**
+- Type errors: X
+
+**Статус:** PASS | FAIL
+
+### Build
+
+**Результаты:**
+- Build: SUCCESS | FAIL
+
+**Статус:** PASS | FAIL
+
+---
+
+## 🎯 Итоговая оценка
+
+<Общий вывод: выполнена ли спецификация полностью, частично или есть критические проблемы>
+
+---
+
+## 🔧 Рекомендации
+
+### Критичные (требуют исправления)
+
+- [ ] <Проблема>: <Описание> → <Что делать>
+
+### Некритичные (рекомендуется исправить)
+
+- [ ] <Проблема>: <Описание> → <Что делать>
+
+### Улучшения (optional)
+
+- [ ] <Идея для улучшения>
+
+---
+
+## 📁 Проверенные файлы
+
+<Список основных файлов, которые были проверены>
+
+---
+
+## 🔄 Следующие шаги
+
+<Рекомендации что делать дальше>
+````
+
+### Шаг 5.2: Определение итогового статуса
+
+**PASS** — Спецификация полностью реализована:
+- Все критерии PASS
+- Все тесты проходят
+- Линтер и typecheck без ошибок
+- Нет критичных проблем
+
+**PARTIAL** — Спецификация реализована с замечаниями:
+- Большинство критериев PASS, но есть PARTIAL или несколько FAIL
+- Есть некритичные проблемы, которые нужно исправить
+- Основной функционал работает
+
+**FAIL** — Спецификация не реализована:
+- Множество критериев FAIL
+- Критичные функции не работают
+- Тесты падают
+- Есть ошибки сборки
+
+### Шаг 5.3: Формирование рекомендаций
+
+**Если статус PASS:**
+```
+✅ Спецификация FT-XXXX полностью реализована и валидирована!
+
+Реализация соответствует всем продуктовым и техническим требованиям.
+Рекомендуется:
+- Создать Pull Request для ревью
+- Обновить документацию (если требуется) через /agentica.readme
+- Закрыть feature-ветку после мёржа
+```
+
+**Если статус PARTIAL:**
+```
+⚠️ Спецификация FT-XXXX реализована с замечаниями.
+
+Основной функционал работает, но есть проблемы:
+<Список критичных проблем>
+
+Рекомендуется:
+- Исправить критичные проблемы
+- Запустить валидацию повторно: /agentica.validate --id FT-XXXX
+- После исправления создать PR
+```
+
+**Если статус FAIL:**
+```
+❌ Спецификация FT-XXXX не прошла валидацию.
+
+Критичные проблемы:
+<Список критичных проблем>
+
+Рекомендуется:
+- Вернуться к реализации: /agentica.implement --id FT-XXXX
+- Сфокусироваться на критичных критериях
+- Исправить проблемы с тестами и сборкой
+```
+
+## Дополнительные рекомендации
+
+### Как проводить семантическую проверку
+
+1. **Не полагайся только на названия:** Прочитай реализацию, убедись что логика соответствует требованиям.
+2. **Проверяй edge cases:** Именно там обычно скрываются баги.
+3. **Смотри на тесты:** Наличие теста не гарантирует его качество. Проверь что тест действительно проверяет критерий.
+4. **Сравнивай с tech.md:** Архитектурные решения должны быть реализованы как описано.
+
+### Как формулировать рекомендации
+
+- **Будь конкретным:** Не "улучшить тесты", а "добавить тест для случая пустого CSV файла"
+- **Указывай приоритет:** Критичное / Некритичное / Улучшение
+- **Предлагай решение:** Не только "что не так", но и "как исправить"
+
+---
+
+**Помни:** Твоя задача — объективно оценить качество реализации и помочь довести её до продакшн-ready состояния. Не будь слишком строгим, но и не пропускай реальные проблемы.

package/stacks/python/cli/product.md

@@ -0,0 +1,41 @@
+# Project Name
+
+Консольное приложение на Python для ...
+
+## Цели проекта
+
+- Цель 1: ...
+- Цель 2: ...
+- Цель 3: ...
+
+## Портрет целевого пользователя
+
+Идеальный пользователь — это:
+
+- Профиль 1: ...
+- Профиль 2: ...
+- Профиль 3: ...
+
+## Проблемы, которые решает проект
+
+- Проблема 1: ...
+- Проблема 2: ...
+- Проблема 3: ...
+
+## Ключевые функции
+
+- Функция 1: ...
+- Функция 2: ...
+- Функция 3: ...
+
+## Конкуренты и аналоги
+
+- Конкурент 1: ...
+- Конкурент 2: ...
+- Конкурент 3: ...
+
+## Ресурсы и ссылки
+
+- Ресурс 1: ...
+- Ресурс 2: ...
+- Ресурс 3: ...

package/stacks/python/cli/structure.md

@@ -0,0 +1,40 @@
+# Структура проекта
+
+Проект организован следующим образом:
+
+```
+.
+├── .agentica/                         # Документы и артефакты Agentica для этого проекта
+│   ├── templates/                     # Шаблоны для фич/изменений/архитектурных решений
+│   ├── features/                      # Описания фич (требования, UX, acceptance)
+│   ├── changes/                       # Журнал изменений, миграции, заметки по релизам
+│   ├── architecture/                  # Архитектурные решения (ADR), схемы, компромиссы
+│   ├── product.md                     # Описание проекта с продуктовой точки зрения
+│   ├── structure.md                   # Этот файл: структура репозитория
+│   └── tech.md                        # Технический стек, принципы и инструменты
+├── .vscode/                           # Настройки VS Code (tasks, launch, settings)
+├── src/                               # Исходный код
+│   ├── <package_name>/                # Основной Python пакет
+│   │   ├── __init__.py                # Точка входа пакета (public API)
+│   │   ├── __main__.py                # Точка входа для `python -m <package_name>` (рекомендуется)
+│   │   ├── cli.py                     # Точка входа CLI (main)
+│   │   ├── commands/                  # Подкоманды и их обработчики
+│   │   │   ├── __init__.py            # Экспорт подкоманд (опционально)
+│   │   │   └── ...                    # Реализация подкоманд
+│   │   ├── lib/                       # Переиспользуемая логика (без I/O по возможности)
+│   │   │   ├── __init__.py            # Экспорт lib-слоя (опционально)
+│   │   │   └── ...                    # Общие утилиты, доменная логика
+│   │   ├── module1.py                 # Пример модуля
+│   │   └── ...                        # Другие модули
+│   └── main.py                        # Пример использования рядом с пакетом (может вызывать `<package_name>.cli`)
+├── tests/                             # Тесты (unit/integration)
+├── README.md                          # Документация по запуску и использованию
+└── pyproject.toml                     # Зависимости, скрипты и конфигурация инструментов
+```
+
+## Правила структуры
+
+- CLI должен запускаться и как entrypoint пакета, и через `python -m <package_name>`.
+- Бизнес-логика не должна жить в `commands/`: там только парсинг аргументов и вызов функций из `lib/`.
+- `src/main.py` — минимальный пример запуска, без дублирования CLI.
+- Архитектурные решения фиксируются в `.agentica/architecture/`.

package/stacks/python/cli/tech.md

@@ -0,0 +1,29 @@
+# Technology Stack
+
+В этом разделе описывается технологический стек, используемый в этом проекте, и принципы по подбору библиотек и инструментов.
+
+## Базовые технологии
+- Python 3.13+
+- `pyproject.toml` + hatchling (или совместимый backend)
+- Ruff — линтинг/форматирование
+- MyPy — типизация
+- Pytest — тестирование
+
+## CLI
+- Typer (или Click) — аргументы, help, подкоманды
+- Rich — форматированный вывод и прогресс (опционально)
+- Стандартизированные exit codes
+
+## Non-goals
+- Не строим полноценный TUI, если это не ключевая ценность.
+- Не дублируем бизнес-логику в обработчиках команд.
+
+## Качество и проверки
+- Format: `ruff format .`
+- Lint: `ruff check .`
+- Typecheck: `mypy .`
+- Tests: `pytest`
+
+## Зависимости
+- CLI-фреймворк выбираем один (Typer *или* Click), без смеси.
+- Вывод в терминал должен быть стабилен (для скриптов/CI) при необходимости.

package/stacks/python/gui/product.md

@@ -0,0 +1,41 @@
+# Project Name
+
+GUI приложение на Python для ...
+
+## Цели проекта
+
+- Цель 1: ...
+- Цель 2: ...
+- Цель 3: ...
+
+## Портрет целевого пользователя
+
+Идеальный пользователь — это:
+
+- Профиль 1: ...
+- Профиль 2: ...
+- Профиль 3: ...
+
+## Проблемы, которые решает проект
+
+- Проблема 1: ...
+- Проблема 2: ...
+- Проблема 3: ...
+
+## Ключевые функции
+
+- Функция 1: ...
+- Функция 2: ...
+- Функция 3: ...
+
+## Конкуренты и аналоги
+
+- Конкурент 1: ...
+- Конкурент 2: ...
+- Конкурент 3: ...
+
+## Ресурсы и ссылки
+
+- Ресурс 1: ...
+- Ресурс 2: ...
+- Ресурс 3: ...

package/stacks/python/gui/structure.md

@@ -0,0 +1,41 @@
+# Структура проекта
+
+Проект организован следующим образом:
+
+```
+.
+├── .agentica/                         # Документы и артефакты Agentica для этого проекта
+│   ├── templates/                     # Шаблоны для фич/изменений/архитектурных решений
+│   ├── features/                      # Описания фич и UX сценариев
+│   ├── changes/                       # Журнал изменений и миграции
+│   ├── architecture/                  # Архитектурные решения (ADR)
+│   ├── product.md                     # Описание проекта с продуктовой точки зрения
+│   ├── structure.md                   # Этот файл: структура репозитория
+│   └── tech.md                        # Технический стек, принципы и инструменты
+├── .vscode/                           # Настройки VS Code
+├── src/                               # Исходный код
+│   ├── <package_name>/                # Основной Python пакет приложения
+│   │   ├── __init__.py                # Точка входа пакета (public API)
+│   │   ├── ui/                        # UI компоненты/виджеты
+│   │   │   ├── __init__.py            # Экспорт UI-частей (опционально)
+│   │   │   └── ...                    # Компоненты/виджеты
+│   │   ├── app/                       # Композиция приложения, bootstrap, wiring
+│   │   │   ├── __init__.py            # Экспорт app-слоя (опционально)
+│   │   │   └── ...                    # Точка сборки приложения, DI, запуск
+│   │   ├── core/                      # Бизнес-логика и доменная модель
+│   │   │   ├── __init__.py            # Экспорт core-слоя (опционально)
+│   │   │   └── ...                    # Доменные модели, use-cases
+│   │   ├── module1.py                 # Пример модуля
+│   │   └── ...                        # Другие модули
+│   └── main.py                        # Пример запуска/использования рядом с пакетом
+├── tests/                             # Тесты (unit/integration)
+├── assets/                            # Иконки и прочие ресурсы
+├── README.md                          # Документация по запуску и разработке
+└── pyproject.toml                     # Зависимости и конфигурация инструментов
+```
+
+## Правила структуры
+
+- `src/main.py` отвечает за bootstrap приложения и запуск UI.
+- UI (слой `ui/`) не должен содержать бизнес-правил: они живут в `core/`.
+- Архитектурные решения фиксируются в `.agentica/architecture/`.