@jakerdy/agentica 0.0.2

package/stacks/typescript/server/structure.md

@@ -0,0 +1,35 @@
+# Структура проекта
+
+Проект организован следующим образом:
+
+```
+.
+├── .agentica/                         # Документы и артефакты Agentica для этого проекта
+│   ├── templates/                     # Шаблоны для фич/изменений/архитектурных решений
+│   ├── features/                      # Описания фич и контрактов API
+│   ├── changes/                       # Изменения и миграции
+│   ├── architecture/                  # Архитектурные решения (ADR)
+│   ├── product.md                     # Описание сервиса с продуктовой точки зрения
+│   ├── structure.md                   # Этот файл: структура репозитория
+│   └── tech.md                        # Технический стек, принципы и инструменты
+├── .vscode/                           # Настройки VS Code
+├── src/                               # Серверный код (routes, services, db)
+│   ├── index.ts                       # Композиция сервера и запуск
+│   ├── routes/                        # HTTP роуты/handlers
+│   ├── services/                      # Бизнес-логика (use-cases)
+│   ├── db/                            # Доступ к БД, схемы, репозитории
+│   └── ...                            # Middleware, utils, types
+├── tests/                             # Тесты (unit/integration)
+├── scripts/                           # Скрипты (миграции, генерация, деплой)
+├── README.md                          # Документация сервиса
+├── biome.json                         # Линт/форматирование Biome
+├── tsconfig.json                      # Конфигурация TypeScript
+└── package.json                       # Зависимости и скрипты
+```
+
+## Правила структуры
+
+- `routes/` тонкие: валидация + вызов `services/`.
+- `services/` не знает о транспорте (HTTP) и UI.
+- Взаимодействие с БД изолировано в `db/`.
+- Архитектурные решения фиксируются в `.agentica/architecture/`.

package/stacks/typescript/server/tech.md

@@ -0,0 +1,30 @@
+# Technology Stack
+
+В этом разделе описывается технологический стек, используемый в этом проекте, и принципы по подбору библиотек и инструментов.
+
+## Базовые технологии
+- Node.js 20+
+- Bun — рантайм и пакетный менеджер
+- Biome — линтинг и форматирование кода
+- TypeScript — основной язык
+- Bun test — тестирование
+
+## Серверные приложения
+- ElysiaJS — HTTP сервер/роутинг
+- Zod — валидация входных данных
+- Drizzle — доступ к БД и миграции
+- Логи и метрики (опционально): структурированные логи, трассировка
+
+## Non-goals
+- Не смешиваем transport (HTTP) и доменную логику в одном месте.
+- Не делаем "магические" middleware без явной схемы ошибок/логирования.
+
+## Качество и проверки
+- Format: `bun format`
+- Lint: `bun lint`
+- Typecheck: `bun typecheck`
+- Tests: `bun test`
+
+## Зависимости
+- Валидация и схемы должны быть едиными (не смешивать несколько validators).
+- Библиотеки для БД/ORM выбираем так, чтобы миграции были воспроизводимы.

package/stacks/typescript/spa/product.md

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

package/stacks/typescript/spa/structure.md

@@ -0,0 +1,36 @@
+# Структура проекта
+
+Проект организован следующим образом:
+
+```
+.
+├── .agentica/                         # Документы и артефакты Agentica для этого проекта
+│   ├── templates/                     # Шаблоны для фич/изменений/архитектурных решений
+│   ├── features/                      # Описания UI/UX фич и сценариев
+│   ├── changes/                       # Изменения, миграции, заметки по релизам
+│   ├── architecture/                  # Архитектурные решения (ADR)
+│   ├── product.md                     # Описание SPA с продуктовой точки зрения
+│   ├── structure.md                   # Этот файл: структура репозитория
+│   └── tech.md                        # Технический стек, принципы и инструменты
+├── .vscode/                           # Настройки VS Code
+├── public/                            # Статические файлы
+├── src/                               # Исходный код SPA
+│   ├── main.tsx                       # Точка входа (bootstrap UI)
+│   ├── app.tsx                        # Корневой компонент приложения
+│   ├── components/                    # UI компоненты
+│   ├── routes/                        # Страницы/роуты (если используются)
+│   └── ...                            # Stores, utils, types
+├── index.html                         # HTML entrypoint
+├── vite.config.ts                     # Конфигурация Vite
+├── tests/                             # Тесты (unit/e2e), если есть
+├── README.md                          # Документация по запуску и разработке
+├── biome.json                         # Линт/форматирование Biome
+├── tsconfig.json                      # Конфигурация TypeScript
+└── package.json                       # Зависимости и скрипты
+```
+
+## Правила структуры
+
+- `src/main.tsx` — единственная точка bootstrap; не разносить инициализацию по компонентам.
+- UI-компоненты держать в `components/`, страницы/экраны — в `routes/`.
+- Архитектурные решения фиксируются в `.agentica/architecture/`.

package/stacks/typescript/spa/tech.md

@@ -0,0 +1,29 @@
+# Technology Stack
+
+В этом разделе описывается технологический стек, используемый в этом проекте, и принципы по подбору библиотек и инструментов.
+
+## Базовые технологии
+- Node.js 20+
+- Bun — рантайм и пакетный менеджер
+- Biome — линтинг и форматирование кода
+- TypeScript — основной язык
+- Tailwind CSS 4 — стилизация
+
+## SPA
+- SolidJS — UI
+- Solid Primitives — утилиты/хуки
+- Vite — сборка и dev-сервер
+
+## Non-goals
+- Не строим дизайн-систему с нуля, если есть готовые примитивы.
+- Не хардкодим окружения/URL внутри компонентов.
+
+## Качество и проверки
+- Format: `bun format`
+- Lint: `bun lint`
+- Typecheck: `bun typecheck`
+- Tests: `bun test`
+
+## Зависимости
+- UI-утилиты — сначала искать в `solid-primitives`, потом добавлять своё.
+- Любая зависимость должна быть совместима с билдом Vite и ESM.

package/templates/architecture/AR-0000 - /320/220/321/200/321/205/320/270/321/202/320/265/320/272/321/202/321/203/321/200/320/260 /321/204/320/270/321/207/320/270 /320/270/320/273/320/270 /320/274/320/276/320/264/321/203/320/273/321/217 XXX.md"

@@ -0,0 +1,136 @@
+# AR-0000 - Архитектура фичи или модуля XXX
+
+Этот документ — «референс идеи» и архитектурных решений на уровне концепций и псевдокода.
+Он не обязан быть привязан к конкретной структуре кода, но должен фиксировать важные предпосылки, границы и механизмы.
+
+## TL;DR (заполняет автор)
+
+**Что строим:** ...
+
+**Зачем:** ...
+
+**Ключевая идея в 1–2 фразы:** ...
+
+
+## Контекст и границы
+
+**Контекст:**
+- В какой системе/продукте живёт модуль/фича: ...
+
+**Границы ответственности:**
+- Что делает: ...
+- Что не делает: ...
+
+**Внешние зависимости/интеграции (если есть):**
+- ...
+
+
+## Цели, качества, принципы
+
+**Цели (3–7):**
+- ...
+
+**Качества (качество системы / quality attributes):**
+- Надёжность: ...
+- Производительность: ...
+- Безопасность: ...
+- Поддерживаемость: ...
+- Наблюдаемость: ...
+
+**Принципы (design principles):**
+- ...
+- ...
+- ...
+
+
+## Обзор решения
+
+Короткое описание архитектуры, основных компонентов и того, как они взаимодействуют.
+
+### Диаграмма (опционально)
+
+```mermaid
+flowchart LR
+	A[Client / Caller] --> B[Module XXX]
+	B --> C[(Storage / External System)]
+```
+
+## Компоненты и механизмы архитектуры
+
+### Компонент 1: ...
+
+Описание компонента 1, его роль в архитектуре и взаимодействие с другими компонентами.
+
+**Ответственность:** ...
+
+**Входы/выходы (концептуально):**
+- Вход: ...
+- Выход: ...
+
+**Инварианты/гарантии:**
+- ...
+
+### Компонент 2: ...
+
+...
+
+### Подход / паттерн: ...
+
+Описание логики реализуемого бизнес-процесса и того как он перекладывается на архитектуру и код. Если есть, то описание паттерна проектирования, который используется для реализации этого процесса.
+
+
+## Потоки данных и сценарии (на уровне идей)
+
+### Сценарий 1 (happy path)
+
+1. ...
+2. ...
+3. ...
+
+### Сценарий 2 (ошибки / деградация)
+
+1. ...
+2. ...
+
+
+## Псевдокод (только значимые детали)
+
+```text
+function main(input):
+	validate(input)
+	state = load_state(...)
+	result = core_algorithm(state, input)
+	persist(result)
+	return result
+```
+
+
+## Компромиссы, альтернативы, риски
+
+**Компромиссы:**
+- ...
+
+**Альтернативы (и почему не выбраны):**
+- ...
+
+**Риски:**
+- ...
+
+
+## Открытые вопросы
+
+- ...
+
+
+## Ресурсы и ссылки
+
+> Для ссылки на ресурс используется синтаксис: [^1], [^2], [^3], ...
+
+- [^1]: ... (ресурс 1)
+- [^2]: ... (ресурс 2)
+- [^3]: ... (ресурс 3)
+
+### Связанные документы (опционально)
+
+- Feature spec: FT-....
+- Change spec: CH-....

package/templates/change/CH-0000 - /320/230/320/267/320/274/320/265/320/275/320/265/320/275/320/270/320/265 /320/262 /321/204/320/270/321/207/320/265 /320/270/320/273/320/270 /320/274/320/276/320/264/321/203/320/273/320/265 XXX.md"

@@ -0,0 +1,33 @@
+# CH-0000 - Изменение в фиче или модуле XXX
+
+В виду того что ... (краткое описание причины изменения и его контекста), необходимо внести следующие изменения в фичу или модуль XXX:
+
+- ... (краткое описание изменения 1)
+- ... (краткое описание изменения 2)
+- ... (краткое описание изменения 3)
+
+При этом важно учитывать следующие аспекты и ограничения:
+
+- ... (аспект или ограничение 1)
+- ... (аспект или ограничение 2)
+
+## Текущее поведение
+
+Описание текущего поведения фичи или модуля XXX, которое необходимо изменить. Это может включать в себя описание функционала, который не соответствует требованиям, или проблем, которые возникают при использовании текущей реализации.
+
+## Ожидаемое поведение
+
+Описание ожидаемого поведения фичи или модуля XXX после внесения изменений. Лучше всего описать это в виде нескольких предложений на естественном языке,  и приложить Golden-Snippet, который демонстрирует правильное поведение.
+
+## Необходимый контекст и важные файлы проекта
+
+- В итнерфейсе IXXX необходимо ... (описание изменений в интерфейсе, если это применимо)
+- В реализации XXX необходимо ... (описание изменений в реализации, если это применимо)
+- Тесты для XXX необходимо ... (описание изменений в тестах, если это применимо)
+
+## Задачи
+
+- [ ] TSK-0001: ... (описание задачи 1)
+- [ ] TSK-0002: ... (описание задачи 2)
+- [ ] TSK-0003: ... (описание задачи 3)
+- [ ] ...

package/templates/feature/FT-0000 - /320/235/320/260/320/267/320/262/320/260/320/275/320/270/320/265 /321/204/320/270/321/207/320/270 /320/270/320/273/320/270 /320/274/320/276/320/264/321/203/320/273/321/217 XXX/product.md"

@@ -0,0 +1,121 @@
+# FT-0000 - Продуктовое описание - Название фичи или модуля XXX
+
+Этот документ нужен, чтобы разработчик быстро понял «общую картину» фичи/модуля: зачем это делается, для кого, где границы и как выглядит успех.
+
+Верхнюю часть заполняет пользователь (1–2 экрана текста). Ниже агент детализирует в User Stories, требования и тест-кейсы.
+
+
+## Краткое описание (заполняет пользователь)
+
+**Что строим (1–3 предложения):**
+- ...
+
+**Почему сейчас / проблема:**
+- ...
+
+**Ценность:**
+- Для пользователя: ...
+- Для бизнеса: ...
+
+
+## Цели и границы (заполняет пользователь)
+
+**Цели (3–7 буллетов):**
+- ...
+
+**Не цели (что точно не делаем):**
+- ...
+
+**Входит в объём (scope):**
+- ...
+
+**Не входит в объём (out of scope):**
+- ...
+
+
+## Пользователи и сценарий (заполняет пользователь)
+
+**Кто пользуется (роли/персоны):**
+- Основной пользователь: ...
+- Вторичный пользователь: ...
+
+**Ключевой пользовательский сценарий (happy path, 5–10 шагов):**
+1. ...
+2. ...
+3. ...
+
+**Краевые случаи (top-5):**
+- ...
+
+
+## Ограничения и зависимости (заполняет пользователь)
+
+**Ограничения:**
+- Продуктовые/UX: ...
+- Технические/платформенные: ...
+- Безопасность/комплаенс (если актуально): ...
+
+**Зависимости и интеграции (если есть):**
+- Системы/модули: ...
+- Внешние сервисы: ...
+
+
+## Критерии успеха (заполняет пользователь)
+
+**Как поймём, что фича успешна (измеримо, если возможно):**
+- ...
+
+**Критерии готовности (Definition of Done на уровне фичи):**
+- ...
+
+
+## Риски и открытые вопросы (заполняет пользователь)
+
+**Риски:**
+- ...
+
+**Открытые вопросы:**
+- ...
+
+
+---
+
+## Детализация (заполняет агент)
+
+Задача этой секции — разложить верхнеуровневое описание на User Stories, функциональные требования, тест-кейсы и критерии приёмки.
+
+## User Stories
+
+### US-0001 - Как ... (роль пользователя), я хочу ... (желание), чтобы ... (ценность).
+
+Описание первой пользовательской истории, которая описывает потребности и ожидания пользователей от фичи или модуля XXX.
+
+#### Функциональные требования для US-0001
+
+- <список функциональных требований, которые должны быть реализованы для удовлетворения потребностей, описанных в US-0001>
+- FR-0001: ... (описание функционального требования 1)
+- FR-0002: ... (описание функционального требования 2)
+
+#### Тест-кейсы для US-0001
+
+**Integration - тесты**
+- <верхнеуровневый список тестов, которые проверяют взаимодействие этой фичи или модуля с другими компонентами системы>
+- INT-0001: ... (описание тест-кейса 1)
+- INT-0002: ... (описание тест-кейса 2)
+
+**End-to-end - тесты**
+- <верхнеуровневый список тестов, которые проверяют полный пользовательский сценарий с использованием этой фичи или модуля>
+- E2E-0001: ... (описание тест-кейса 1)
+- E2E-0002: ... (описание тест-кейса 2)
+
+#### Критерии приемки для US-0001
+
+1. **Дано** <входная потребность>, **Когда** <действие пользователя>, **Тогда** <ожидаемый результат>.
+2. **Дано** <входная потребность>, **Когда** <действие пользователя>, **Тогда** <ожидаемый результат>.
+3. ...
+
+
+### US-0002 - Как ... (роль пользователя), я хочу ... (желание), чтобы ... (ценность).
+
+...
+

package/templates/feature/FT-0000 - /320/235/320/260/320/267/320/262/320/260/320/275/320/270/320/265 /321/204/320/270/321/207/320/270 /320/270/320/273/320/270 /320/274/320/276/320/264/321/203/320/273/321/217 XXX/tasks.md"

@@ -0,0 +1,38 @@
+# FT-0000 - Список задач - Название фичи или модуля XXX
+
+Документы:
+- [Продуктовое описание - Название фичи или модуля XXX](../product.md)
+- [Тех-задание фичи или модуля XXX](../tech.md)
+- [Чек-лист для валидации фичи или модуля XXX](../validation.md)
+
+---
+
+Фазы реализации:
+
+- Фаза 1: Инициализация и планирование
+- Фаза 2: Разработка базового функционала и утилит
+- Фаза 3: Реализация бизнес-логики и интеграция с другими компонентами
+- Фаза 4: Тестирование, отладка и оптимизация
+- Фаза 5: Валилдация реализации на соответствие качественным критериям и требованиям
+- Фаза 6: Подготовка к релизу и выпуск фичи или модуля XXX
+
+---
+
+# Фаза 1: Инициализация и планирование
+
+- [ ] TSK-1-001: Создать директории и файлы для фичи или модуля XXX
+- [ ] TSK-1-002: Определить основные интерфейсы и контракты для фичи или модуля XXX
+- [ ] ...
+
+
+# Фаза 2: Разработка базового функционала и утилит
+
+- [ ] TSK-2-001: Реализовать базовые функции и утилиты для фичи или модуля XXX
+- [ ] ...
+
+# Фаза 3: Реализация бизнес-логики и интеграция с другими компонентами
+
+...
+
+
+# Фаза N: ...

package/templates/feature/FT-0000 - /320/235/320/260/320/267/320/262/320/260/320/275/320/270/320/265 /321/204/320/270/321/207/320/270 /320/270/320/273/320/270 /320/274/320/276/320/264/321/203/320/273/321/217 XXX/tech.md"

@@ -0,0 +1,155 @@
+# FT-0000 - Название фичи или модуля XXX
+
+Этот документ фиксирует технический план и «интерфейс реализации» фичи/модуля: какие сущности, контракты, алгоритмы и ограничения должны быть воплощены в коде.
+
+Верхнюю часть заполняет пользователь (технические предпочтения/ограничения/план). Ниже агент формирует исчерпывающую спецификацию контрактов и сигнатур под TypeScript.
+
+
+## Технический план (заполняет пользователь)
+
+**Кратко (1–3 предложения):**
+- ...
+
+**Целевая среда и ограничения:**
+- Runtime (Node/Bun/Browser): ...
+- TypeScript target/module: ...
+- Ограничения по совместимости/версии: ...
+
+**Архитектурный набросок:**
+- Куда встраиваемся (модуль/пакет/слой): ...
+- Границы ответственности (что делает/не делает модуль): ...
+- Основные зависимости/интеграции: ...
+
+**Предпочитаемые подходы и библиотеки:**
+- Валидация/схемы (например, zod): ...
+- DI/IoC (если нужно): ...
+- Логирование/трассировка: ...
+- Хранилище/HTTP/CLI (если актуально): ...
+
+**Организация кода (ожидаемая структура):**
+- Папки/модули: ...
+- Публичный API (какие экспорты должны быть доступны): ...
+
+**Ключевые алгоритмы/процессы (списком):**
+1. ...
+2. ...
+
+**Ошибки и контракты отказов:**
+- Какие ошибки ожидаем (категории/коды): ...
+- Что возвращаем/кидаем наружу (ошибка vs result): ...
+
+**Нефункциональные требования:**
+- Производительность/лимиты: ...
+- Безопасность (валидация, доступы, секреты): ...
+- Наблюдаемость (логи/метрики): ...
+
+
+---
+
+## Спецификация реализации (заполняет агент)
+
+Эта секция — формальная спецификация для генерации/реализации кода. Она должна быть достаточно точной, чтобы реализация не требовала значимых изменений публичных контрактов.
+
+### Термины и глоссарий (опционально)
+
+- Term1: ...
+
+### Публичное API модуля
+
+- Экспортируемые функции/классы: ...
+- События/хуки (если есть): ...
+
+### Модели данных и схемы
+
+- Входные структуры: ...
+- Выходные структуры: ...
+- Внутренние структуры: ...
+
+### Основные интерфейсы и контракты
+
+- `IInterfaceXXX`: описание интерфейса, который будет реализован фичей или модулем XXX.
+- `ClassXXX`: описание класса, который реализует `IInterfaceXXX` и предоставляет публичный API.
+
+### Логика и алгоритмы
+
+Логика работы фичи или модуля XXX строится на основе ... (краткое описание основных алгоритмов, которые реализует фича или модуль XXX, и их взаимодействия между собой).
+
+#### Бизнес-процесс 001
+
+Описание бизнес-процесса 001, который реализует фича или модуль XXX.
+Это может включать в себя описание входных данных, шагов обработки и ожидаемых результатов.
+
+#### Алгоритм 001 для бизнес-процесса 001
+
+Описание алгоритма 001, который используется для реализации бизнес-процесса 001.
+Это может включать в себя описание основных шагов алгоритма, его сложности и оптимизаций.
+
+...
+
+### Интерфейсы, контракты и классы (формально)
+
+### IInterfaceXXX
+
+Описание интерфейса IInterfaceXXX, его методов, параметров и возвращаемых значений.
+
+```typescript
+
+import { z } from 'zod';
+
+const schema = z.object({
+  ...
+});
+
+export type IInterfaceXXX = z.infer<typeof schema>;
+
+```
+
+### ClassXXX
+
+Описание класса ClassXXX, его методов, параметров и возвращаемых значений.
+
+```typescript
+
+import { z } from 'zod';
+
+const schema = z.object({
+  ...
+});
+
+export type IClassXXXInit = z.infer<typeof schema>;
+
+export class ClassXXX implements IInterfaceXXX {
+
+  constructor(init: IClassXXXInit) {
+    ...
+  }
+
+  /**
+   * Описание метода Method1, его параметров и возвращаемого значения.
+   * @param x - описание параметра x
+    * @returns описание возвращаемого значения
+   */
+  Method1(x: Type): ReturnType;
+
+  ...
+
+}
+
+```
+
+### 2.7 Ошибки
+
+- Перечень доменных ошибок: ...
+- Формат ошибок (name/code/cause): ...
+- Что является retryable/terminal: ...
+
+### 2.8 Конфигурация
+
+- Какие env/config нужны: ...
+- Дефолты и валидация конфигурации: ...
+
+### 2.9 Тестовая стратегия (на уровне реализации)
+
+- Unit: что тестируем (списком): ...
+- Integration: что тестируем (границы/моки): ...
+- E2E: маппинг на User Stories: ...