massCode (Agent Skills)

# Точка входа для агента massCode

Отвечай всегда на русском.

massCode — это приложение на Electron + Vue 3 + TypeScript с TailwindCSS v4 в renderer, API-маршрутами на Elysia в main process, markdown vault как основным хранилищем пользовательского контента в v5 и `store.app` / `store.preferences` для локального UI state и настроек.

## Всегда действующие правила

- Следуй YAGNI. Предпочитай минимальную корректную реализацию вместо спекулятивных абстракций.
- Соблюдай границы слоёв: renderer не должен напрямую обращаться к Node.js, filesystem или DB. Используй API или IPC.
- Никогда не хардкодь пользовательские строки. Используй систему локализации.
- Не запускай lint или тесты по всему проекту для локальной задачи. Ограничивай команды затронутыми файлами или директориями.
- После изменений API DTO или routes запускай `pnpm api:generate`.
- После изменений locale-файлов запускай `pnpm i18n:copy`.
- Если задача совпадает по теме с одним из skills ниже, загружай этот skill до внесения изменений.

## Skills

- `.agents/skills/architecture-standards/SKILL.md`
  Используй первым для общих правил репозитория: архитектура, naming, декомпозиция и выбор следующего skill.
- `.agents/skills/vue-renderer-standards/SKILL.md`
  Используй для работы с Vue renderer: `<script setup lang="ts">`, правила auto-import, composables, shared state и renderer-side паттерны.
- `.agents/skills/ui-foundations/SKILL.md`
  Используй для базовых UI-правил: Tailwind v4, typography через `UiText` и согласованных styling decisions для renderer UI.
- `.agents/skills/ui-primitives/SKILL.md`
  Используй для component-level UI работы: `Ui*` components, Shadcn imports, `cn`, `cva`, notifications и правил против переизобретения primitives.
- `.agents/skills/electron-api-and-ipc/SKILL.md`
  Используй для API routes, DTO, IPC handlers, renderer-to-main communication и границ Electron-интеграции.
- `.agents/skills/api-and-typing/SKILL.md`
  Используй для generated API types, DTO-derived renderer typing и решения, когда локальный UI type оправдан, а когда нужно переиспользовать существующие API types.
- `.agents/skills/spaces-architecture/SKILL.md`
  Используй при изменениях, связанных с `code` / `notes` / `math` / `tools`, markdown-space state, sync behavior или `spaces:*` IPC.
- `.agents/skills/i18n/SKILL.md`
  Используй для правил локализации, размещения locale keys, `i18n.t(...)` и требования не хардкодить строки.
- `.agents/skills/documentation-workflow/SKILL.md`
  Используй для добавления или обновления документации, страниц `docs/website/documentation`, sidebar, assets и README-упоминаний фич.
- `.agents/skills/release-notes/SKILL.md`
  Используй для генерации release notes нового релиза в игнорируемый файл `docs/releases/<tag>.md` для вставки в GitHub release: группировка merged PR в user-facing разделы и compare-ссылка.
- `.agents/skills/development-workflow/SKILL.md`
  Используй для repo-specific workflow rules: scoped lint/test команды и обязательные follow-up шаги после изменений source-of-truth файлов.
- `.agents/skills/github-workflow/SKILL.md`
  Используй для massCode git и GitHub workflow: issue, ветки, commits, PR и подготовки к merge.

## Рекомендуемый порядок загрузки

- Широкая или неочевидная задача: начни с `architecture-standards`, затем загрузи профильный skill.
- Renderer UI задача: `architecture-standards` → `vue-renderer-standards` → `ui-foundations` → `ui-primitives`.
- API / IPC / Electron задача: `architecture-standards` → `electron-api-and-ipc`.
- Generated types / renderer typing задача: `architecture-standards` → `api-and-typing`.
- Spaces задача: `architecture-standards` → `spaces-architecture`.
- Задача про текст и локализацию: `i18n`.
- Задача про документацию или README: `documentation-workflow`.
- Задача про release notes нового релиза: `release-notes`.
- Workflow-чувствительная задача: `development-workflow`.
- Задача про git / branch / commit / PR: `github-workflow`.

## Основной стек

- Framework: Vue 3, Composition API, `<script setup lang="ts">`
- Styling: TailwindCSS v4, `tailwind-merge`, `cva`
- UI: локальные `src/renderer/components/ui`, Shadcn поверх `reka-ui`, `lucide-vue-next`
- State: composables, без Pinia/Vuex
- Backend: Electron main, Elysia API, markdown vault для контента и `electron-store` для локального состояния приложения
- Utilities: `@vueuse/core`, `vue-sonner`

---
name: architecture-standards
description: Use when working in massCode and you need repo-wide architecture rules, naming conventions, decomposition boundaries, or guidance on which massCode skill to load next.
---

# Architecture Standards

## Overview

Базовый принцип проекта: **YAGNI и простота прежде всего**. Не усложняй код ради гипотетических сценариев, не строй абстракции без повторяющейся потребности и не размывай границы между renderer, API и main.

## Core Rules

- Соблюдай разделение слоёв:
  - Renderer: только UI, composables, вызовы `api.*` и `ipc.invoke(...)`.
  - API: маршруты Elysia, DTO, orchestration и доступ к сервисам и данным приложения.
  - Main: системные интеграции, IPC handlers, lifecycle и слой данных приложения.
- Data flow по умолчанию: Renderer → API / IPC → service / data layer → response.
- Vue-компоненты называй в `PascalCase`.
- TypeScript-файлы называй в `camelCase`.
- Composables именуй с префиксом `use`, а имя файла должно совпадать с экспортируемой функцией.

## YAGNI Guardrails

Признаки overengineering:

- функция страхуется от кейса, которого реально не существует;
- factory или wrapper используется ровно в одном месте и не скрывает состояние;
- abstraction-for-abstraction без повторяющейся боли;
- константы, паттерны и конфигурации придуманы заранее, а не из реальной потребности.

## Component Decomposition

- Если компонент становится больше примерно `300` строк или держит `3+` несвязанных обязанности, дели его.
- Порядок разбиения:
  1. вынеси константы и статические данные;
  2. вынеси чистые функции в utils, только если это реально переиспользуется;
  3. перемести состояние и эффекты в composable;
  4. разбей шаблон на локальные child components.
- Не держи в `<template>` логику сложнее тернарного оператора.

## Feature Subdirectories

- Если часть домена выросла в отдельный subsystem, группируй локальные компоненты, helpers, tests и fixtures в поддиректорию.
- Внутри поддиректории не повторяй полный родительский префикс в именах файлов.
- Локальные файлы держи рядом с фичей. Shared-код, который нужен нескольким областям, оставляй выше уровнем.

## When to Load Other Skills

- Vue renderer, auto-imports, composables, shared state:
  `vue-renderer-standards`
- визуальная база, typography, renderer styling decisions:
  `ui-foundations`
- `Ui*`, Shadcn, `cn`, `cva`, notifications:
  `ui-primitives`
- API routes, DTO, IPC, Electron boundaries:
  `electron-api-and-ipc`
- generated API types, utility typing, локальные view-model:
  `api-and-typing`
- `code` / `notes` / `math` / `tools`, состояние spaces и их синхронизация:
  `spaces-architecture`
- i18n, locale keys, `i18n.t(...)`:
  `i18n`
- docs website, docs sidebar, скриншоты, README-упоминания фич:
  `documentation-workflow`
- scoped lint/test и follow-up commands:
  `development-workflow`

## Common Mistakes

- Тянуть DB или filesystem knowledge в renderer.
- Раздувать один компонент до “оркестратора всего”.
- Выносить абстракцию до появления второй реальной точки использования.
- Размазывать одну фичу по плоской структуре файлов, когда ей уже нужен локальный subdirectory.
- Придумывать локальные typing-паттерны, хотя для них уже пора иметь отдельный skill.