@jetrabbits/agentic 0.0.1

package/areas/software/data-engineering/workflows/new-model.md

@@ -0,0 +1,71 @@
+---
+name: new-model
+type: workflow
+trigger: /new-model
+description: Scaffold a complete dbt model with SQL, documentation, tests, and lineage from requirements to validated output.
+inputs:
+  - model_name
+  - layer
+  - source_table
+outputs:
+  - dbt_model_sql
+  - yaml_documentation
+  - validated_model
+roles:
+  - pm
+  - team-lead
+  - developer
+  - qa
+execution:
+  initiator: pm
+related-rules:
+  - schema-management.md
+  - pipeline-integrity.md
+  - data-governance.md
+uses-skills:
+  - data-modeling
+  - dbt-patterns
+  - quality-checks
+quality-gates:
+  - dbt compile passes with no errors
+  - standard tests pass (unique/not_null on PK, relationships on FKs)
+  - model documented with column descriptions
+---
+
+## Steps
+
+### 1. Requirements Gathering — `@pm`
+- **Input:** model request
+- **Actions:** confirm model name (snake_case), target layer (staging / intermediate / mart), source table, business purpose, and key metrics or grain
+- **Output:** confirmed model spec
+- **Done when:** spec unambiguous; `@team-lead` briefed
+
+### 2. Model Design — `@team-lead`
+- **Input:** confirmed model spec
+- **Actions:** determine grain and primary key; identify required joins and business logic; specify standard tests (unique, not_null, relationships, recency for time-series); review lineage impact using `/lineage-trace` if modifying shared tables
+- **Output:** design note with grain, PK, test list, lineage notes
+- **Done when:** design approved; no lineage conflicts
+
+### 3. SQL & YAML Implementation — `@developer`
+- **Input:** design note
+- **Actions:**
+  - staging: SELECT with column renaming, type casting, deduplication
+  - intermediate: business logic JOIN template
+  - mart: fact/dimension template with surrogate key and audit columns
+  - generate YAML docs: model description, auto-detected columns, standard tests
+- **Output:** `models/<layer>/<model_name>.sql` + `<model_name>.yml`
+- **Done when:** SQL implemented; YAML complete with all columns described
+
+### 4. Validation — `@qa`
+- **Input:** model files
+- **Actions:** `dbt compile --select <model_name>`; `dbt test --select <model_name> --empty`; compare compiled SQL against design; verify tests are sufficient for the grain and business rules
+- **Output:** validation report; compiled SQL preview
+- **Done when:** `dbt compile` and `dbt test` pass; `@qa` confirms test coverage adequate
+
+### 5. Review & Merge — `@team-lead`
+- **Input:** validated model
+- **Actions:** review SQL logic, naming conventions, documentation completeness; approve or return with blocking feedback
+- **Done when:** `@team-lead` approves; PR merged
+
+## Exit
+Passing dbt tests + complete YAML docs + `@team-lead` approval = model production-ready.

package/areas/software/data-engineering/workflows/schema-migration.md

@@ -0,0 +1,67 @@
+---
+name: schema-migration
+type: workflow
+trigger: /schema-migration
+description: Execute a data warehouse schema migration safely with downstream impact management and expand/contract when needed.
+inputs:
+  - table_name
+  - change_type
+outputs:
+  - migrated_schema
+  - downstream_notification
+roles:
+  - developer
+  - team-lead
+  - qa
+execution:
+  initiator: team-lead
+related-rules:
+  - schema-management.md
+  - pipeline-integrity.md
+  - data-governance.md
+uses-skills:
+  - data-modeling
+  - lineage-governance
+quality-gates:
+  - non-breaking changes confirmed or expand/contract plan approved
+  - all dbt tests pass post-migration
+  - downstream owners notified with 5-business-day notice for breaking changes
+---
+
+## Steps
+
+### 1. Change Classification — `@team-lead`
+- **Input:** table name, change type (rename-column / add-column / change-type / drop-column)
+- **Actions:** classify as non-breaking (add nullable column → proceed to Step 3) or breaking (requires full impact assessment)
+- **Output:** classification decision
+- **Done when:** classification confirmed
+
+### 2. Impact Assessment — `@developer` (breaking changes only)
+- **Input:** breaking change classification
+- **Actions:** run `/lineage-trace` to identify all affected downstream models and dashboards; notify downstream owners with minimum 5-business-day notice
+- **Output:** impact report with affected asset list; notification sent
+- **Done when:** all downstream owners acknowledged
+
+### 3. Migration Strategy — `@team-lead`
+- **Input:** confirmed change + impact report
+- **Actions:** define migration phases:
+  - column rename: Phase 1 add new column + populate from old; Phase 2 migrate downstream; Phase 3 mark old deprecated; Phase 4 (30 days later) drop old
+  - type change: use CAST-safe intermediate column
+  - drop: only after all references removed
+- **Output:** migration strategy doc with phase timeline
+- **Done when:** strategy approved; `@developer` can implement
+
+### 4. Execute Migration — `@developer`
+- **Input:** approved strategy
+- **Actions:** generate and review migration SQL; run in staging first; validate with dbt tests in staging; execute in production in off-peak window
+- **Output:** migration applied to production
+- **Done when:** migration runs without error; no rollback triggered
+
+### 5. Verify & Document — `@qa`
+- **Input:** migrated production schema
+- **Actions:** confirm all dbt tests pass post-migration; update YAML docs and data catalog; announce completion to downstream owners
+- **Output:** `validation_report.md`; catalog updated; owners notified
+- **Done when:** all tests green; documentation current
+
+## Exit
+Post-migration tests green + catalog updated + owners notified = migration complete.

package/areas/software/frontend/AGENTS.md

@@ -0,0 +1,60 @@
+# Frontend — guidance index
+
+## What this area covers
+
+UI and component development: component architecture, accessibility (WCAG AA), performance budgets, state management, API integration, CSS architecture, visual regression, and bundle analysis.
+
+## Guidance chain
+
+1. Project `.agent/` baseline (`AGENTS.md` + `.agent/*`)
+2. `software/general/rules/*` — always active
+3. `frontend/rules/*` — load all for this spec
+4. `frontend/skills/*/SKILL.md` — load only the skill matching the current task
+5. `frontend/workflows/*` — load the workflow matching the triggered command
+
+## Inherited from general
+
+- SDLC roles and quality gates
+- Git workflow, CI, linting / formatting, code style
+- Shared delivery and code review workflows
+
+## Frontend-specific constraints
+
+- WCAG AA compliance is a baseline requirement, not an enhancement — accessibility defects are P0.
+- Performance budgets must be defined before implementing new features with significant asset load.
+- No component ships without documented states: loading, empty, error, success, permission-denied.
+
+## Spec map
+
+```text
+frontend/
+├── rules/
+│   ├── accessibility.md    ← WCAG AA requirements, ARIA patterns, keyboard navigation
+│   ├── architecture.md     ← component hierarchy, coupling, folder structure
+│   ├── performance.md      ← Core Web Vitals budgets, lazy loading, asset optimization
+│   └── quality.md          ← snapshot stability, coverage thresholds, PR review criteria
+├── skills/
+│   ├── a11y-audit/SKILL.md           ← axe, Lighthouse, screen reader testing patterns
+│   ├── api-integration/SKILL.md      ← data fetching, error boundaries, loading states
+│   ├── component-design/SKILL.md     ← composition, props contracts, Storybook patterns
+│   ├── css-architecture/SKILL.md     ← utility-first, design tokens, style isolation
+│   ├── error-handling/SKILL.md       ← error boundaries, fallback UI, user messaging
+│   ├── performance-tuning/SKILL.md   ← bundle splitting, image optimization, CWV analysis
+│   ├── state-management/SKILL.md     ← local vs server state, caching, optimistic UI
+│   └── testing-patterns/SKILL.md     ← component tests, mocking, visual regression
+├── workflows/
+│   ├── a11y-fix.md              ← /a11y-fix
+│   ├── bundle-analyze.md        ← /bundle-analyze
+│   ├── release-prep.md          ← /release-prep
+│   ├── scaffold-component.md    ← /scaffold-component
+│   └── visual-regression.md     ← /visual-regression
+└── prompts/
+    └── *.md
+```
+
+## Discovery patterns
+
+- `rules/*.md`
+- `skills/*/SKILL.md`
+- `workflows/*.md`
+- `prompts/*.md`

package/areas/software/frontend/PROMPTS.md

@@ -0,0 +1,32 @@
+# PROMPTS: frontend
+
+Use these prompts with `AGENTS.md` from the same directory.
+
+## 1) Initialize agent behavior
+
+```text
+Read `frontend/AGENTS.md` and adopt its rules, skills loading strategy, and workflows as hard constraints.
+List the active rules and the selected workflow before implementation.
+```
+
+## 2) Implement a feature
+
+```text
+Using `frontend/AGENTS.md`, implement: <feature description>.
+Before coding: provide architecture notes, risk list, and test plan.
+After coding: run checks and report exact commands and results.
+```
+
+## 3) Incident / debug mode
+
+```text
+Using `frontend/AGENTS.md`, run incident triage for: <incident summary>.
+Return root cause hypotheses, validation steps, fix plan, and rollback plan.
+```
+
+## 4) Release readiness
+
+```text
+Using `frontend/AGENTS.md`, prepare release checklist for: <release scope>.
+Include quality gates, security gates, performance gates, and deployment validation.
+```

package/areas/software/frontend/prompts/a11y-fix.md

@@ -0,0 +1,75 @@
+---
+workflow: a11y-fix
+---
+
+# Prompt: `/a11y-fix`
+
+Use when: resolving accessibility issues found in a WCAG audit or accessibility testing tool.
+
+---
+
+## Example 1 — Audit findings batch fix
+
+**EN:**
+```
+/a11y-fix
+
+Target: /checkout route (all 3 steps)
+Audit tool: axe-core via jest-axe + manual keyboard testing
+Findings:
+  - [Critical] Step 2 payment form: credit card number input has no label (axe: label-content-name-mismatch)
+  - [Critical] Error messages appear visually but not announced by screen reader
+  - [Serious] "Continue" button disabled state not conveyed to AT (missing aria-disabled)
+  - [Moderate] Focus order on mobile: jumps from address field to order summary (skips city/zip)
+Designer decisions needed: error message copy (ARIA live region wording)
+```
+
+**RU:**
+```
+/a11y-fix
+
+Цель: маршрут /checkout (все 3 шага)
+Инструмент аудита: axe-core через jest-axe + ручное тестирование клавиатурой
+Находки:
+  - [Critical] Шаг 2 форма оплаты: поле номера карты без label (axe: label-content-name-mismatch)
+  - [Critical] Сообщения об ошибках отображаются визуально, но не объявляются screen reader'ом
+  - [Serious] Состояние disabled кнопки "Продолжить" не передаётся AT (отсутствует aria-disabled)
+  - [Moderate] Порядок фокуса на мобильном: перескакивает с поля адреса на сводку заказа (пропускает city/zip)
+Решения дизайнера нужны: текст сообщений об ошибках (формулировка ARIA live region)
+```
+
+---
+
+## Example 2 — Component-level screen reader remediation
+
+**EN:**
+```
+/a11y-fix
+
+Target: AccountSecurityModal component used on /settings/security
+Audit inputs:
+- VoiceOver on Safari cannot identify the modal title
+- Escape key closes the modal visually but focus is not returned to the trigger button
+- Password strength meter changes color only; no textual announcement for screen readers
+Acceptance criteria:
+- dialog has correct aria-labelledby / aria-describedby wiring
+- focus trap works with Tab / Shift+Tab and returns focus to the trigger on close
+- strength updates are announced in an aria-live region without duplicate chatter
+Output: implementation plan, component patch, test updates, and final WCAG criterion mapping
+```
+
+**RU:**
+```
+/a11y-fix
+
+Цель: компонент AccountSecurityModal, используемый на /settings/security
+Входные данные аудита:
+- VoiceOver в Safari не может определить заголовок модального окна
+- Escape визуально закрывает модалку, но фокус не возвращается на кнопку-триггер
+- Индикатор сложности пароля меняет только цвет; нет текстового объявления для screen reader
+Критерии приёмки:
+- у dialog корректно настроены aria-labelledby / aria-describedby
+- focus trap работает с Tab / Shift+Tab и возвращает фокус на триггер при закрытии
+- обновления strength объявляются через aria-live без дублирующего шума
+Результат: план реализации, патч компонента, обновления тестов и финальная привязка к критериям WCAG
+```

package/areas/software/frontend/prompts/bundle-analyze.md

@@ -0,0 +1,75 @@
+---
+workflow: bundle-analyze
+---
+
+# Prompt: `/bundle-analyze`
+
+Use when: investigating bundle size regressions or optimizing for performance budgets.
+
+---
+
+## Example 1 — Regression investigation
+
+**EN:**
+```
+/bundle-analyze
+
+Build artifacts: dist/ (webpack build)
+Baseline: performance-budget.json (main branch)
+Detected: main bundle +87KB after merging PR #203
+PR added: recharts library for new dashboard charts
+Budget: main bundle < 250KB gzipped (currently 337KB)
+Goal: identify the culprit and options (tree-shake, lazy-load charts, or alternative library)
+```
+
+**RU:**
+```
+/bundle-analyze
+
+Артефакты сборки: dist/ (webpack build)
+Baseline: performance-budget.json (ветка main)
+Обнаружено: main bundle +87KB после мержа PR #203
+PR добавил: библиотеку recharts для новых графиков dashboard
+Бюджет: main bundle < 250KB gzipped (сейчас 337KB)
+Цель: определить виновника и варианты решения (tree-shake, lazy-load графиков, или альтернативная библиотека)
+```
+
+---
+
+## Example 2 — Route-level split strategy before release
+
+**EN:**
+```
+/bundle-analyze
+
+App: customer portal (Vite + React)
+Problem: /reports route initial JS payload is 1.1MB uncompressed and blocks Lighthouse performance score
+Suspected contributors:
+- monaco-editor loaded on initial route even though only used in one tab
+- shared vendor chunk includes all chart adapters and locale data
+- PDF export library imported in top-level page component
+Budget target: first-load JS for /reports < 350KB gzipped
+Need:
+1. chunk breakdown by route and dependency
+2. quick wins vs larger refactor suggestions
+3. recommendation whether to lazy-load monaco/PDF export and split locale packs
+Output: bundle diff report, prioritized optimization backlog, and estimate of savings per action
+```
+
+**RU:**
+```
+/bundle-analyze
+
+Приложение: customer portal (Vite + React)
+Проблема: initial JS payload маршрута /reports = 1.1MB без сжатия и он блокирует Lighthouse performance score
+Подозреваемые источники:
+- monaco-editor загружается на старте маршрута, хотя используется только в одной вкладке
+- shared vendor chunk включает все chart adapters и locale data
+- библиотека PDF export импортируется в top-level page component
+Целевой бюджет: first-load JS для /reports < 350KB gzipped
+Нужно:
+1. разбивка chunk'ов по маршруту и зависимостям
+2. быстрые выигрыши vs предложения для более крупного рефакторинга
+3. рекомендация, нужно ли lazy-load monaco/PDF export и разделять locale packs
+Результат: bundle diff report, приоритизированный optimization backlog и оценка экономии на каждое действие
+```

package/areas/software/frontend/prompts/release-prep.md

@@ -0,0 +1,83 @@
+---
+workflow: release-prep
+---
+
+# Prompt: `/release-prep`
+
+Use when: preparing a frontend release with coordinated quality, performance, and stakeholder sign-off.
+
+---
+
+## Example 1 — Planned release
+
+**EN:**
+```
+/release-prep
+
+Release: v2.8.0
+Scope: 3 new features (dark mode, notification center, dashboard redesign)
+Target version: 2.8.0
+Success criteria:
+- Lighthouse performance score >= 85 on key pages
+- Zero new WCAG A violations
+- All regression tests pass
+- Bundle size within budget (< 300KB gzipped main)
+Known risk: notification center uses WebSocket - first time in the app
+Release notes audience: end users (non-technical)
+```
+
+**RU:**
+```
+/release-prep
+
+Релиз: v2.8.0
+Скоуп: 3 новые фичи (dark mode, центр уведомлений, редизайн dashboard)
+Целевая версия: 2.8.0
+Критерии успеха:
+- Lighthouse performance score >= 85 на ключевых страницах
+- Ноль новых WCAG A нарушений
+- Все regression tests проходят
+- Размер bundle в рамках бюджета (< 300KB gzipped main)
+Известный риск: центр уведомлений использует WebSocket - первый раз в приложении
+Аудитория release notes: конечные пользователи (нетехнические)
+```
+
+---
+
+## Example 2 — Hotfix release with rollback pressure
+
+**EN:**
+```
+/release-prep
+
+Release: v2.8.1-hotfix
+Scope: fix checkout address form regression introduced in v2.8.0
+Observed impact: 18% of mobile Safari users cannot submit checkout after postal code autofill
+Constraints:
+- ship within 4 hours
+- keep rollback path to v2.8.0 build artifact
+- only changed routes /checkout and /order-confirmation require focused visual regression review
+Checks still required:
+- smoke test on staging with Safari + Chrome mobile emulation
+- confirm no new bundle regression on checkout chunk
+- verify analytics event checkout_submit still fires exactly once
+Output: go/no-go recommendation, rollback trigger list, and customer-facing release note for support team
+```
+
+**RU:**
+```
+/release-prep
+
+Релиз: v2.8.1-hotfix
+Скоуп: исправление регрессии формы адреса на checkout, внесённой в v2.8.0
+Наблюдаемое влияние: 18% пользователей mobile Safari не могут отправить checkout после автозаполнения postal code
+Ограничения:
+- выпустить за 4 часа
+- сохранить путь отката к build artifact версии v2.8.0
+- только изменённые маршруты /checkout и /order-confirmation требуют focused visual regression review
+Проверки, которые всё равно обязательны:
+- smoke test на staging с Safari + Chrome mobile emulation
+- подтвердить отсутствие новой bundle-регрессии в checkout chunk
+- проверить, что analytics event checkout_submit всё ещё срабатывает ровно один раз
+Результат: рекомендация go/no-go, список rollback trigger'ов и customer-facing release note для команды поддержки
+```

package/areas/software/frontend/prompts/scaffold-component.md

@@ -0,0 +1,69 @@
+---
+workflow: scaffold-component
+---
+
+# Prompt: `/scaffold-component`
+
+Use when: creating a new reusable UI component from scratch.
+
+---
+
+## Example 1 — Form component with validation
+
+**EN:**
+```
+/scaffold-component "DateRangePicker"
+
+Purpose: allow users to select a start and end date for filtering reports
+Design system: Tailwind + shadcn/ui; use existing Calendar primitive
+States: default, focused, filled, error (invalid range: end before start), disabled
+Accessibility: keyboard navigation (Arrow keys in calendar), screen reader announces selected range
+API:
+  - value?: { from: Date; to?: Date }
+  - onChange: (range: { from: Date; to?: Date }) => void
+  - minDate?: Date; maxDate?: Date
+  - error?: string
+Consumer context: used in Reports filter bar, works with react-hook-form
+```
+
+**RU:**
+```
+/scaffold-component "DateRangePicker"
+
+Назначение: позволяет пользователям выбрать диапазон дат для фильтрации отчётов
+Дизайн система: Tailwind + shadcn/ui; использовать существующий Calendar primitive
+Состояния: default, focused, filled, error (невалидный диапазон: end раньше start), disabled
+Доступность: навигация клавиатурой (стрелки в календаре), screen reader объявляет выбранный диапазон
+API:
+  - value?: { from: Date; to?: Date }
+  - onChange: (range: { from: Date; to?: Date }) => void
+  - minDate?: Date; maxDate?: Date
+  - error?: string
+Контекст: используется в Reports filter bar, совместим с react-hook-form
+```
+
+---
+
+## Example 2 — Display component
+
+**EN:**
+```
+/scaffold-component "StatusBadge"
+
+Purpose: display entity status with color-coded visual (order status, user role, etc.)
+States: pending (yellow), active (green), cancelled (red), archived (gray)
+Props: status: string; size?: 'sm' | 'md'
+No interactive state — purely visual
+Must work in both light and dark mode (use CSS custom properties)
+```
+
+**RU:**
+```
+/scaffold-component "StatusBadge"
+
+Назначение: отображение статуса сущности с цветовой кодировкой (статус заказа, роль пользователя и т.д.)
+Состояния: pending (жёлтый), active (зелёный), cancelled (красный), archived (серый)
+Props: status: string; size?: 'sm' | 'md'
+Интерактивных состояний нет — только визуальный компонент
+Должен работать в light и dark режиме (использовать CSS custom properties)
+```

package/areas/software/frontend/prompts/visual-regression.md

@@ -0,0 +1,73 @@
+---
+workflow: visual-regression
+---
+
+# Prompt: `/visual-regression`
+
+Use when: detecting unintended UI changes before merging a PR or releasing.
+
+---
+
+## Example 1 — PR visual diff review
+
+**EN:**
+```
+/visual-regression
+
+Scope: components changed in PR #156 (Button, Card, Modal)
+Baseline: main branch snapshots (Percy baseline)
+Changed: updated design tokens (spacing +4px, border-radius change)
+Expected diffs: all Button, Card sizes will have slightly more padding - intentional
+Unexpected diffs to catch: any text overflow, icon misalignment, broken dark mode
+Designer must review: all diffs before baseline is updated
+```
+
+**RU:**
+```
+/visual-regression
+
+Скоуп: компоненты изменённые в PR #156 (Button, Card, Modal)
+Baseline: снапшоты ветки main (Percy baseline)
+Изменено: обновлены design tokens (spacing +4px, изменение border-radius)
+Ожидаемые diff: все размеры Button, Card будут иметь немного больше отступов - намеренно
+Неожиданные diff для обнаружения: любое переполнение текста, смещение иконок, сломанный dark mode
+Дизайнер должен проверить: все diff перед обновлением baseline
+```
+
+---
+
+## Example 2 — Release candidate route sweep
+
+**EN:**
+```
+/visual-regression
+
+Scope: release candidate v4.3.0 on routes /pricing, /signup, /checkout, /account/billing
+Baseline source: Chromatic snapshots from main after design system token freeze
+Recent changes:
+- pricing cards switched to responsive CSS grid
+- signup flow moved validation messages from inline text to floating summary panel
+- checkout uses a new sticky order summary on tablet widths
+Acceptance criteria:
+- no overlap or clipping in EN + DE locales
+- loading and error states reviewed in light and dark themes
+- approved intentional diffs documented before updating the baseline
+Output: visual diff report grouped by route, list of blocker diffs, and approved baseline updates with designer sign-off
+```
+
+**RU:**
+```
+/visual-regression
+
+Скоуп: release candidate v4.3.0 для маршрутов /pricing, /signup, /checkout, /account/billing
+Источник baseline: Chromatic snapshots из main после заморозки design system token'ов
+Недавние изменения:
+- pricing cards переведены на responsive CSS grid
+- signup flow перенёс validation messages из inline текста в floating summary panel
+- checkout использует новый sticky order summary на tablet-ширинах
+Критерии приёмки:
+- отсутствие overlap или clipping в локалях EN + DE
+- loading и error состояния проверены в light и dark themes
+- все намеренные diff'ы задокументированы до обновления baseline
+Результат: visual diff report, сгруппированный по маршрутам, список blocker diff'ов и approved baseline updates с sign-off от дизайнера
+```

package/areas/software/frontend/rules/accessibility.md

@@ -0,0 +1,16 @@
+# Rule: Accessibility First
+
+**Priority**: P0 — Blocks merge if violated.
+
+## Constraints
+
+1. Every interactive element (`button`, `a`, `input`, `select`, custom widget) **must** have an accessible name via `aria-label`, `aria-labelledby`, or visible text content.
+2. Color contrast ratio must be **≥ 4.5:1** for normal text and **≥ 3:1** for large text (WCAG 2.1 AA).
+3. All functionality must be operable via **keyboard only** (Tab, Shift+Tab, Enter, Space, Arrow keys).
+4. Images must have meaningful `alt` attributes; decorative images use `alt=""`.
+5. Dynamic content updates (toasts, modals, form errors) must be announced via `aria-live` regions or focus management.
+6. No `tabindex` values greater than `0` are permitted.
+
+## Verification
+
+The agent must run `axe-core` or `eslint-plugin-jsx-a11y` checks before considering any UI component complete.

package/areas/software/frontend/rules/architecture.md

@@ -0,0 +1,29 @@
+# Rule: Component Architecture
+
+**Priority**: P0 — Structural violations require refactor before shipping.
+
+## Constraints
+
+1. **Atomic Design Boundary**: Atoms have no internal state. Molecules compose atoms. Organisms own local UI state. Pages own data-fetching. Templates are layout-only.
+2. **No Prop Drilling beyond 2 levels**: Pass data via context, state management, or composition — never chain props more than 2 components deep.
+3. **Co-location**: A component's styles, tests, and stories must live in the same directory as the component file.
+4. **Single Responsibility**: One component = one visual responsibility. A component that fetches data AND renders a complex layout must be split into a container and a presentational component.
+5. **No Business Logic in Components**: Domain logic must live in custom hooks (`use*.ts`) or utility modules (`lib/`), not in JSX.
+6. **No Circular Imports**: Module dependency graph must be a DAG.
+
+## Directory Convention
+
+```
+src/
+├── components/        # Atoms, Molecules, Organisms (pure UI)
+├── features/          # Feature slices (container + domain logic)
+│   └── [feature]/
+│       ├── components/
+│       ├── hooks/
+│       ├── store/
+│       └── types.ts
+├── pages/             # Route-level components (data orchestration)
+├── lib/               # Shared utilities, helpers, constants
+├── hooks/             # Shared custom hooks
+└── types/             # Global TypeScript types
+```