@jakerdy/agentica 0.0.2

package/globals/anti-spaghetti.md

@@ -0,0 +1,65 @@
+# Анти-спагетти метод: Единый Code Style Guide
+
+## 1. Структура файла и Визуальное оформление
+- **Принципы:** Код должен быть структурированным сверху вниз. Порядок секций фиксирован, это делает код предсказуемым.
+- **Структура модуля (Strict):**
+    1.  **Импорты**
+    2.  **Константы** — магические числа/строки выносятся сюда.
+    3.  **Интерфейсы/типы** — одноуровневые, без вложенности.
+    4.  **Публичные функции/классы** — экспортируемое API.
+    5.  **Приватные функции/классы** — внутренняя реализация.
+    6.  **Утилитарные функции** — вспомогательные/экспорт в самом конце.
+- **Четкое визуальное разделение:** Помечай группы широким однострочным разделителем-заголовком, чтобы визуально "разрезать" файл.
+    - *Пример:*
+        ```typescript
+        //------------------- Constants ---------------------//
+        //---------------------- Types ----------------------//
+        //------------------- Public API --------------------//
+        //---------------- Order Processor ------------------//
+        //---------------------- Utils ----------------------//
+        ```
+- **Структура класса:** Придерживайся следующей очерёдности (state first):
+    1.  **Приватные поля** (состояние).
+    2.  **Конструктор**.
+    3.  **Публичные свойства** (геттеры/сеттеры).
+    4.  **Публичные методы**.
+    5.  **Приватные методы**.
+    6.  **Утилитарные методы** (статические).
+
+## 2. Типизация и Данные (TypeScript)
+- **Одноуровневые типы:** Создавай на каждый отдельный "объект" свой интерфейс/тип. Разбивай сложные вложенные типы на отдельные алиасы. Это улучшает читаемость и отладку.
+    - *Плохо:* `function process(data: { items: { id: string }[] })`
+    - *Хорошо:* `interface Item { id: string }; interface ProcessData { items: Item[] };`
+- **Избегай дублирования DTO:** Не создавай 10 похожих интерфейсов для передачи одних и тех же данных. Если аргументов много и они повторяются — сгруппируй их в Класс или общий DTO.
+- **Интерфейсы для DTO:** Для всех args-return структур использовать интерфейсы, даже если это всего 2-3 поля.
+- **Прямые типы:** Используй типы напрямую (через импорты), избегай `typeof` или `ISomeType["field"]` в сигнатурах.
+
+## 3. Плоскость (Flatness) и Поток управления
+- **Принцип раннего возврата (Early Return):** Избегай конструкции `else`. Если в блоке `if` происходит `return`, `throw` или `break`, `else` не нужен. Это уменьшает визуальную вложенность.
+- **Запрет на пирамиды:** Вложенные if-ы запрещены. Вычисли флаги по очереди и используй ранний возврат. Макс. 3-4 уровня вложенности — если больше, рефактори.
+- **Распаковка цепочек методов:** Обязательное использование именованных переменных для промежуточных вычислений. Вместо цепочки в 10 этажей (`data.filter().map().reduce()...`) разбивай шаги на переменные:
+    - *Пример:* `const activeItems = ...; const values = ...; const result = ...;`
+- **Императивное >> Функционального:** Если можно написать простой цикл `for/of`, пиши его. Не городи сложные композиции из `reduce`, если это не улучшает читаемость.
+- **Тернарные операторы:** Разрешены только если помещаются в одну строку и не содержат вложенности.
+
+## 4. Простота (Simplicity) и Рефакторинг
+- **Лимиты функции:** Макс. 30-40 строк кода. Функция должна помещаться на экран.
+- **Лимит аргументов:** Не более 4-х аргументов. Если нужно больше — группируйте в объект (DTO) или превращайте функцию в класс.
+- **Превращай мега-функции в классы:** Если функция имеет >100 строк, >5 аргументов или хранит сложное состояние в замыканиях (`let state = ...`), её нужно рефакторить в класс. Поля класса заменят замыкания, а методы — шаги алгоритма.
+- **Единый уровень абстракции:** Внутри одной функции не должны перемешиваться высокоуровневая бизнес-логика и низкоуровневые манипуляции (парсинг JSON и расчет скидки рядом).
+
+## 5. Чистота (Cleanliness) и Инкапсуляция
+- **Defensive programming только на границах:** Проверки `null/undefined` нужны только на входе в публичный API (границы системы). Внутри приватных методов и между внутренними функциями — доверяй типизации TypeScript.
+    - *Принцип:* "Не проверяй дважды". Если `handleUser` уже проверил `user`, то `processUser` не должен проверять его снова.
+- **Инкапсуляция условий:** Запрет на "размазывание" логики. Вместо `if (order.total > 100 && order.user.isPremium)` используй метод модели `if (order.canApplyDiscount())`. Логика принадлежит объекту с данными.
+- **Чистота булевых выражений:** Если условие `if` содержит более 2-х операторов, вынеси его в переменную (`const canAccess = ...`) или метод.
+- **Запрет на мутации:** Функция не должна изменять входные параметры (immutability).
+- **Запрет на Side Effects в геттерах:** Методы `get...` не должны менять состояние объекта или БД.
+
+## 6. Общие запреты и стандарты
+- **Магические значения:** Все числа, строки, таймауты и конфигурации — строго в константы с понятными именами (`const MAX_RETRY = 3`).
+- **Никаких флагов в аргументах:** Если `boolean` аргумент меняет логику функции (ветвление внутри), раздели её на две разные функции.
+- **Обработка ошибок:** Не должно быть методов, целиком завернутых в `try-catch`, кроме верхнего уровня публичного API.
+- **Ограничение длины строки:** Максимум 100–120 символов (нет горизонтальному скроллу).
+- **Мертвый код:** Закомментированный код удаляется безжалостно. Для истории есть Git.
+- **Стрелочные функции:** Вложенные стрелки только для коротких лямбд. Если растет логика — выноси в именованную функцию.

package/globals/lang-python.md

@@ -0,0 +1,105 @@
+# Python Specifics
+
+## Naming
+
+| Тип символа              | `Casing`       | PEP                                                                            |
+| ------------------------ | -------------- | ------------------------------------------------------------------------------ |
+| Класс, Exception         | `PascalCase`   | [PEP 8](https://peps.python.org/pep-0008/#class-names)                         |
+| Функция, метод           | `snake_case`   | [PEP 8](https://peps.python.org/pep-0008/#function-and-variable-names)         |
+| Переменная, аргумент     | `snake_case`   | [PEP 8](https://peps.python.org/pep-0008/#function-and-variable-names)         |
+| Константа (module-level) | `ALL_CAPS`     | [PEP 8](https://peps.python.org/pep-0008/#constants)                           |
+| Приватный атрибут/метод  | `_snake_case`  | [PEP 8](https://peps.python.org/pep-0008/#method-names-and-instance-variables) |
+| Name mangling            | `__snake_case` | [PEP 8](https://peps.python.org/pep-0008/#method-names-and-instance-variables) |
+| Модуль, пакет            | `snake_case`   | [PEP 8](https://peps.python.org/pep-0008/#package-and-module-names)            |
+| Type variable            | `PascalCase`   | [PEP 8](https://peps.python.org/pep-0008/#type-variable-names)                 |
+
+## Декомпозиция модулей
+
+Не стоит писать супер большие модули с множеством классов. По возможности:
+- Один публичный класс = один модуль (файл)
+- Связанные функции группируй в отдельные модули
+- Используй `__init__.py` для удобного публичного API пакета
+- Приватные helper-функции можно оставлять в том же модуле с префиксом `_`
+
+В частности, выноси в отдельные модули:
+- Модели данных (dataclasses, Pydantic models)
+- Бизнес-логику и сервисы
+- Утилиты и helpers
+- Типы и протоколы (interfaces)
+- Константы и конфигурацию
+
+## Скрипты
+
+- Форматирование Ruff: `uv run ruff format`
+- Линт Ruff: `uv run ruff check`
+- Автофикс линта: `uv run ruff check --fix`
+- Проверка типов mypy: `uv run mypy .`
+- Запуск всех тестов: `uv run pytest`
+- Запуск тестов с покрытием: `uv run pytest --cov`
+- Не запускай утилиты через `pip`, используй `uv` и скрипты выше. Если нужны дополнительные команды, добавь их в `pyproject.toml` секцию `[tool.uv.scripts]`.
+
+## pyproject.toml и зависимости
+
+- Добавляй зависимости только через `uv add <package>`.
+- Добавляй dev-зависимости через `uv add --dev <package>`.
+- Удаляй зависимости только через `uv remove <package>`.
+- **Не** редактируй `pyproject.toml` вручную для зависимостей.
+- Используй `uv sync` для синхронизации окружения.
+- Для production-зависимостей НЕ используй `--dev`.
+
+## Типизация
+
+Следуй [PEP 484](https://peps.python.org/pep-0484/) (Type Hints):
+
+```python
+# Хорошо:
+def process_items(items: list[str], count: int) -> dict[str, int]:
+    result: dict[str, int] = {}
+    return result
+
+# Плохо (без type hints):
+def process_items(items, count):
+    result = {}
+    return result
+```
+
+- Используй современный синтаксис типов (Python 3.10+): `list[str]` вместо `List[str]`
+- Для опциональных значений: `str | None` вместо `Optional[str]`
+- Используй `typing.Protocol` для структурной типизации (duck typing)
+- Избегай `Any` — используй `object`, `typing.Protocol` или generic types
+
+## Docstrings
+
+Следуй [PEP 257](https://peps.python.org/pep-0257/) и Google/NumPy стилю:
+
+```python
+def calculate_total(items: list[float], tax_rate: float) -> float:
+    """Calculate total price including tax.
+    
+    Args:
+        items: List of item prices
+        tax_rate: Tax rate as decimal (e.g., 0.15 for 15%)
+    
+    Returns:
+        Total price with tax applied
+        
+    Raises:
+        ValueError: If tax_rate is negative
+    """
+    if tax_rate < 0:
+        raise ValueError("Tax rate cannot be negative")
+    return sum(items) * (1 + tax_rate)
+```
+
+## Общие обязательные принципы
+
+- **Типизация**: всегда используй type hints для публичного API ([PEP 484](https://peps.python.org/pep-0484/))
+- **Обработка ошибок**: выбрасывай конкретные исключения, не используй голый `except:`
+- **Imports**: следуй порядку [PEP 8](https://peps.python.org/pep-0008/#imports) (stdlib → third-party → local), используй `ruff` для автосортировки
+- **Immutability**: предпочитай неизменяемые структуры данных (tuples, frozenset, dataclasses с `frozen=True`)
+- **Context managers**: используй `with` для работы с ресурсами (файлы, соединения, locks)
+- **Dataclasses**: используй `@dataclass` вместо ручного `__init__` для data containers
+- **Pathlib**: используй `pathlib.Path` вместо `os.path` для работы с путями
+- **f-strings**: используй f-strings для форматирования строк вместо `.format()` или `%`
+- **List comprehensions**: предпочитай comprehensions вместо `map()`/`filter()` для простых случаев
+- **Dependency Injection**: передавай зависимости через аргументы конструктора/функций (важно для тестируемости)

package/globals/lang-typescript.md

@@ -0,0 +1,61 @@
+# Typescript Specifics
+
+## Naming
+
+| Тип символа               | `Casing`         |
+| ------------------------- | ---------------- |
+| Класс, Enum               | `PascalCase`     |
+| Интерфейс                 | `IPascalCase`    |
+| Поле интерфейса/класса    | `snake_case`     |
+| Метод                     | `PascalCase`     |
+| Компонент                 | `PascalCase`     |
+| Функция                   | `camelCase`      |
+| Аргумент                  | `snake_case`     |
+| Переменная                | `snake_case`     |
+| Ключ Enum'а               | `PascalCase`     |
+| Строковое значение Enum'а | `snake_case`     |
+| Константа                 | `ALL_CAPS`       |
+| Папка/Файл                | `snake_case.ext` |
+
+## Декомпозиция компонентов
+
+Не стоит писать супер глубокие компоненты, по возможности, все "атомарные", и все те кусочки JSX которым можно дать название нужно выносить в отдельный компонент, даже если он не будет повторно использоваться за пределами этого конкретного модуля.
+
+В частности:
+- Элементы списка
+- Содержимое карточек
+- Секции сложных Layout'ов
+- ...
+
+## Скрипты
+- Форматирование Biome: `bun format`
+- Линт Biome: `bun lint`
+- Проверка типов проекта: `bun typecheck`
+- Проверка типов тестов: `bun typecheck:tests`
+- Запуск всех тестов: `bun test`
+- Не запускай утилиты через `bunx <tool>`, используй скрипты выше. Если их нет, добавь новый скрипт в `package.json`.
+
+## package.json и зависимости
+- Добавляй зависимости только через `bun add <package>`.
+- Удаляй зависимости только через `bun remove <package>`.
+- **Не** редактируй `package.json` вручную для зависимостей.
+- Добавляй зависимости в правильный workspace-пакет.
+- Не добавляй расширение `.js` к импортам, если это не требуется. Все внутренние импорты пакетов не должны содержать `.js`.
+
+## ES6 `this` binding
+
+В тех случаях когда код написан в классе, и нужно передать колбек в виде метода, следует передавать стрелочную функцию:
+
+```typescript
+// Хорошо:
+handle.addEventListener("onclick", (e) => this.BeginDrag(e))
+
+// Плохо:
+handle.addEventListener("onclick", this.BeginDrag.bind(this))
+```
+## Общие обязательные приципы
+- Интерфейсы: префикс `I` (например, `IUser`, `IProjectConfig`). Названия файлов для интерфейсов не должны содержать `I` (например, `user.ts`, а не `IUser.ts`).
+- Типизация: избегай `any` (используй `unknown` или введи интерфейс/тип).
+- Обработка ошибок: выбрасывай только подклассы `Error`.
+- Внедрение зависимостей: предпочитай DI через аргументы конструктора/фабрик (важно для тестируемости).
+- Архитектура расширения: держи бизнес-логику в **extension host**; webviews не должны превращаться во второй бэкенд.

package/globals/use-agentica.md

@@ -0,0 +1,127 @@
+## Agentica Framework: Гид для Агентов
+
+Этот проект использует **Agentica** - фреймворк для spec-driven разработки. Твоя задача — работать **внутри спецификаций**, а не в обход них.
+
+### Где искать контекст
+
+**1. Структура директории `.agentica/`**
+
+Проверяй ОБА уровня:
+- **Корень проекта** `.agentica/` - глобальный контекст (шаблоны, промпты, общие стандарты)
+- **Корень пакета** `.agentica/` - локальные спеки и контекст конкретного пакета
+
+**Корневой уровень** (`.agentica/` в корне проекта):
+```
+.agentica/
+├── prompts/          # Воркфлоу агентов (init, create, implement, validate)
+├── templates/        # Шаблоны спек (feature, change, architecture)
+├── product.md        # Глобальное продуктовое видение
+├── structure.md      # Структура и организация репозитория
+├── tech.md           # Глобальный тех-стек и стандарты
+└── status.md         # Статус интеграции
+```
+
+**Уровень пакета** (`.agentica/` в каждом пакете/скоупе):
+```
+packages/my-package/.agentica/
+├── features/         # Спеки FT-XXXX (новая функциональность)
+├── changes/          # Спеки CH-XXXX (изменения существующего кода)
+├── architecture/     # Спеки AR-XXXX (архитектурные решения и паттерны)
+├── product.md        # Назначение и домен пакета
+├── structure.md      # Файловая структура пакета
+├── tech.md           # Стек и паттерны конкретного пакета
+└── status.md         # Отслеживание интеграции пакета
+```
+
+**2. Система Memory**
+
+IDE автоматически предоставляет доступ к фактам, сохранённым на предыдущих этапах спеки (`create`, `tasks`). Эти факты помечены тегами по фичам/скоупам:
+
+- `@<scope>/FT-XXXX--existing-modules` - Существующие модули и их назначение
+- `@<scope>/FT-XXXX--patterns` - Используемые паттерны проектирования
+- `@<scope>/FT-XXXX--libraries` - Подключённые библиотеки и API
+- `@<scope>/FT-XXXX--integration-points` - Точки, где модули соединяются
+- `@<scope>/FT-XXXX--dependencies` - Граф зависимостей
+
+**Доверяй этим фактам** - они содержат исследованный контекст о кодовой базе. Используй их, чтобы избежать дублирования кода и следовать существующей архитектуре.
+
+### Как найти информацию
+
+**Перед написанием любого кода:**
+1. Прочитай `product.md` (уровень пакета) - пойми домен и назначение
+2. Прочитай `structure.md` (уровень пакета) - узнай, где должны быть файлы
+3. Прочитай `tech.md` (уровень пакета И корня) - следуй стандартам
+4. Проверь факты в memory - используй существующие паттерны и модули
+5. Прочитай связанные спеки в `features/`, `changes/`, `architecture/` - учись на похожих работах
+
+**При реализации спеки (FT-XXXX или CH-XXXX):**
+1. **ВСЕГДА** читай полную спеку сначала: `product.md`, `tech.md`, `tasks.md`, `validation.md`
+2. Проверь, существует ли `research.md` - он может содержать решения по библиотекам
+3. Просканируй соседние спеки в `features/` - они могут использовать те же паттерны
+4. Ищи документы AR-XXXX, относящиеся к твоему домену - они определяют архитектуру
+
+**Если застрял или неясно:**
+- Перечитай `tech.md` - решение может быть уже определено
+- Ищи похожий код через `semantic_search` с конкретными терминами
+- Проверь memory на наличие связанных паттернов
+- НЕ УГАДЫВАЙ - задавай уточняющие вопросы
+
+### Критические правила
+
+**1. Оставайся внутри спеки**
+- Твоя задача — реализовать то, что **уже решено** в спеке
+- НЕ добавляй "улучшения" или "хотелки", не упомянутые в задачах
+- Если спека неясна - спрашивай, не предполагай
+
+**2. Останавливайся при переполнении контекста**
+- Если ты читаешь слишком много файлов и контекст кажется "тяжёлым" - ОСТАНАВЛИВАЙСЯ
+- Попроси пользователя:
+  - Сузить скоуп
+  - Разбить задачу на более мелкие спеки
+  - Создать нормальную спеку через `/agentica.create` или `/agentica.architect`
+
+**3. Читай соседние спеки**
+- Перед созданием похожего кода проверь другие FT-XXXX в том же пакете
+- Переиспользуй паттерны, не изобретай заново
+- Консистентность > новизна
+
+**4. Следуй процессу**
+Каждый воркфлоу Agentica имеет определённые шаги (init → create → tasks → implement → validate). Если пользователь просит сделать что-то масштабное:
+- Проверь, существует ли связанная спека
+- Если спеки нет - рекомендуй сначала использовать `/agentica.create`
+- Не пиши большие фичи "фристайлом" без спеки
+
+### Рекомендации для пользователя
+
+Если пользователь просит большие изменения в "обычном" режиме (без воркфлоу Agentica):
+```
+⚠️  Похоже на существенное изменение. Рекомендую использовать воркфлоу Agentica:
+
+1. Создай спеку: `/agentica.create --name <название-фичи>`
+2. Распланируй задачи: `/agentica.tasks --id FT-XXXX`
+3. Реализуй: `/agentica.implement --id FT-XXXX`
+4. Валидируй: `/agentica.validate --id FT-XXXX`
+
+Это обеспечит:
+- Правильное планирование архитектуры
+- Поэтапную реализацию с тестами
+- Покрытие всех edge cases
+- Лучшее качество и поддерживаемость кода
+```
+
+### Быстрая справка
+
+| Мне нужно...                     | Смотри в...                          |
+| :------------------------------- | :----------------------------------- |
+| Понять назначение проекта        | Root `.agentica/product.md`          |
+| Узнать, где должны быть файлы    | Package `.agentica/structure.md`     |
+| Следовать стандартам кода        | `.agentica/tech.md` (оба уровня)     |
+| Посмотреть архитектурные решения | Package `.agentica/architecture/`    |
+| Проверить похожие фичи           | Package `.agentica/features/`        |
+| Понять прошлые изменения         | Package `.agentica/changes/`         |
+| Найти существующие паттерны      | Факты Memory + похожие спеки         |
+| Изучить воркфлоу                 | Root `.agentica/prompts/*.prompt.md` |
+
+---
+
+**Помни:** Agentica - это **планируемая разработка**. Если тебя просят сделать что-то большое без спеки - рекомендуй сначала создать её. Спеки экономят время и дают лучший код.

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@jakerdy/agentica",
+  "version": "0.0.2",
+  "description": "Spec-driven framework for agent coding with developer-first approach",
+  "keywords": [
+    "ai",
+    "agents",
+    "llm",
+    "spec-driven",
+    "code-generation",
+    "architecture",
+    "cli",
+    "developer-tools"
+  ],
+  "author": "Jak Erdy",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jakerdy/agentica.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jakerdy/agentica/issues"
+  },
+  "homepage": "https://github.com/jakerdy/agentica#readme",
+  "module": "src/index.ts",
+  "main": "dist/cli.js",
+  "type": "module",
+  "bin": {
+    "agentica": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "prompts",
+    "templates",
+    "stacks",
+    "globals",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun run build.ts",
+    "prepublishOnly": "bun run build"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5",
+    "@types/bun": "latest"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3"
+  }
+}