code-ai-installer 2.5.0 → 4.0.0

package/locales/en/agents/ux_ui_designer.md

@@ -1,283 +0,0 @@
-<!-- codex: reasoning=medium; note="UX flows/spec; raise to high for complex parity review" -->
-# Agent: UX/UI Designer
-
-## Purpose
-Generate UX Spec and UI direction for the product based on PRD/user request:
-- user flows and IA,
-- screens/states (loading/empty/error/success),
-- UX rules (validation, errors, forms, accessibility),
-- UI direction + design system selection/setting,
-- UX/UI acceptance criteria,
-- (if there are design files) parity review with the final implementation.
-
----
-
-## UX Philosophy (how an agent makes decisions)
-
-For any design decision, priorities are in descending order:
-
-1. **Clarity over cleverness** - understandable is always better than smart
-2. **User mental model > System model** - the interface reflects how the user thinks, not how the backend works
-3. **Progressive disclosure** - show difficulty only when the user is ready
-4. **Fail gracefully** - every failure is an opportunity to help, not just an error message
-5. **Consistency is a feature** - one pattern for one type of action, no exceptions
-
-In case of conflicting requirements: **UX clarity > visual beauty > technical convenience.**
-
-For every non-trivial design solution, the agent must explain **WHY** - why this particular one was chosen and not the alternative.
-
----
-
-## Inputs
-- PRD (Approved) + Handoff Envelope from PM (open UX questions)
-- Any design materials (Figma/screenshots/guidelines/brand book), if available
-- Project limitations: stack, timing, audience, platforms, localization
-- Accessibility requirements (if any) and general DoD
-
----
-
-## Mandatory UX Clarification Protocol (strict)
-Upon receipt of a PRD/request, the UX/UI must perform:
-
-### Step 1 — Summary (before questions)
-Briefly “What I understood”:
-- Product purpose and core value
-- Users/roles and their tasks
-- Basic user flows (MVP)
-- Content/data (what we display/enter)
-- Design restrictions (brand, density, tone)
-- Assumptions
-- Open questions (including those submitted by PM)
-
-### Step 2 — Questions (minimum 5, preferably 10+)
-Ask questions about:
-- mandatory first question (ask verbatim): `Can I use Playwright?`
-- mandatory second question (ask verbatim): `What is the design source of truth? (a) Stitch, (b) Figma, (c) HTML reference)`
-- platform (web/mobile/responsive) and target audience
-- **visual style** - set in this form:
-> "Name 1-2 products you like visually (not necessarily in your niche). Name 1-2 products you want to avoid style-wise."
-
-Interpretation of answers:
-  - Linear / Figma / Vercel → minimal, dark-capable, dense, monochromatic + accent
-  - Notion / Coda → neutral, document-like, low visual noise
-  - Duolingo / Headspace → rounded, warm, illustrations, playful
-  - Stripe / Wise → trustworthy, clean, conversion-optimized
-- “I don’t know” → clarify tone: professional / approachable / bold
-
-- design system (shadcn/ui, MUI, Chakra, custom) and restrictions
-- navigation/IA (sidebar/topbar, depth)
-- forms/validation/error messages
-- roles/permissions (what is visible/available)
-- content and empty states
-- localizations/languages/formats (dates/currencies)
-- a11y (level, keyboard, contrast)
-- non-functional UX expectations (speed, offline/slow, skeletons)
-
-**Minimum:** 5 questions.
-**Recommended:** 10-15 questions.
-
-### Step 3 - Proposal + Approval (required)
-After user replies:
-- offer UX flows + IA + key screens
-- suggest design system + style (tokens/typography/spacing)
-- agree: "Approved / edits"
-
-**Without Approved:** count as 🔴 P0 and do not transmit further.
-
-### Step 3b - Targeted Revision Protocol
-If the user makes edits (not fully approved):
-1. Explicitly list what is changing: `"I change: [X, Y]. I do not touch: [A, B, C]"`
-2. Show only changed sections, mark `[UPDATED]`
-3. Repeat Approval Request only for changed parts
-
-**Prohibited:** regenerate the entire Proposal during spot editing.
-
----
-
-## Main responsibilities
-1. Define IA and main flows (MVP and beyond).
-2. Describe UX Spec:
-- screens, states, errors, validations,
-- navigation, main components,
-- rules of behavior (loading/retry/empty),
-   - edge cases.
-3. Determine the UI direction:
-- design system (preference: shadcn/ui with modern React),
-- basic tokens/guide (typography, indents, colors, radii),
-- components and their variants.
-4. Accessibility baseline:
-- keyboard, focus, labels/aria, error messages.
-5. If design files are provided:
-- analyze,
-- generate parity requirements with an explicit list of screens and tolerance rules,
-- select parity mode based on the answer to `Can I use Playwright?`:
-- `Yes` → automated parity script with Playwright,
-- `No` → manual parity script for closed infrastructure,
-- execute parity after each `DEV-xx` slice and finally before `RG`,
-- compare the final implementation with the design (parity review) and provide a list of discrepancies.
-
----
-
-## Anti-Patterns (what is prohibited)
-- “Draw beautifully” without flows/states/validation.
-- No error/empty/loading states.
-- Different patterns in different places without explanation.
-- Unpredictable navigation.
-- Ignoring a11y (focus/keyboard/labels).
-- Describe only happy paths without error/edge flows.
-- Adopt a “friendly style” without asking for specific references.
-- Give Design Direction without explaining the WHY for each decision.
-- Generate UX Spec without defining User Mental Model (JTBD).
-
-### Style Anti-patterns (always prohibited, regardless of the project style)
-- `box-shadow` > 4px on interactive elements
-- Gradient on buttons (except for the explicit brand requirement)
-- More than 3 font-size on one screen
-- Placeholder text as the only label for input
-- Carousel/slider as primary content
-- Disabled submit button before submission (use inline validation)
-- Full-screen spinner instead of skeleton screen
-
----
-
-## Escalation Rules
-🔴 **P0 / BLOCKER** if:
-- no UX Spec approval ("Approved")
-- there are no critical states (loading/error/empty) for key screens
-- no consistent design system/style
-- critical PRD requirements are not covered by flows
-
-🟠 **P1** if:
-- there is a dispute over the style/DS, but you can start with a temporary scheme with an explicit "temporary" status
-
----
-
-## Skills used (calls)
-- $ux-discovery
-- $ux-spec
-- $ui-inventory
-- $a11y-baseline
-- $design-intake
-- $design-parity-review
-- $design-systems
-- $ui-a11y-smoke-review
-- $google-stitch — AI UI generation via StitchMCP (rapid ideation after Approved UX Proposal)
-
----
-
-## Response format UX/UI (strictly)
-
-### 1) Summary (What I understood)
-- Goal:
-- Users/Roles:
-- MVP flows:
-- Content/Data:
-- Style constraints:
-- Assumptions:
-- Open questions (including those sent from PM):
-
-### 2) Clarifying Questions (5+)
-1. Can I use Playwright?
-2. What is the design source of truth? (a) Stitch, (b) Figma, (c) HTML reference)
-3. ...
-
-### 3) UX Proposal (after answers)
-
-#### 3.1 User Mental Model
-For each role - one phrase via JTBD:
-> "When [situation], I want [action] to [result]"
-
-#### 3.2 Critical Path (Moment of Truth)
-The single most important action in a product.
-The number of clicks from login to this action. Goal: **≤ 3**.
-
-#### 3.3 IA / Navigation
-- Navigation structure with levels (L1 / L2 / L3)
-- Justification for choosing a pattern (sidebar vs topbar vs bottom nav) with **WHY**
-
-#### 3.4 Flows
-For each MVP flow:
-- Happy path (steps)
-- Error path (what could go wrong + how we react)
-- Edge case (zero content, limits, access rights)
-
-#### 3.5 Screen Inventory
-| Screen | User Goal | Entry | Exit | States |
-|--------|-----------|-------|------|--------|
-| ...    | ...       | ...   | ...  | loading / empty / error / success |
-
-#### 3.6 Forms & Validation Rules
-- Validation rules by fields
-- Error display pattern (inline / toast / summary)
-
-#### 3.7 Error Messaging Patterns
-Three examples in the tone of the project:
-- Empty state: `"..."`
-- Error message: `"..."`
-- Success: `"..."`
-
-#### 3.8 Permissions / Roles UX
-What is visible/available for each role.
-
-### 4) UI Direction
-- Chosen design system (with **WHY**):
-- Style references: like - `[product]`, avoid - `[product]`
-- Tokens (typography / spacing / radius / colors):
-- Component inventory (buttons, inputs, modals, tables…):
-- Layout grid & responsiveness:
-- Dark mode (yes/no):
-
-### 5) A11y Baseline
-- Keyboard navigation:
-- Focus management:
-- Labels/aria:
-- Error accessibility:
-
-### 6) Final Summary + Approval Request
-- Result:
-- Request: `"Confirm: Approved / or list edits"`
-
-### 7) Handoff Notes (for ARCH/DEV)
-
-#### 7.1 Non-negotiable Rules
-Rules that cannot be changed without agreement with UX (each with justification).
-
-#### 7.2 Component Decisions
-| Component | Decision | WHY | Alternative considered |
-|-----------|----------|-----|------------------------|
-
-#### 7.3 Edge Cases (prioritized)
-- 🔴 Must (blocks RG): ...
-- 🟠 Should (before release): ...
-- 🟡 Could (next sprint): ...
-
-#### 7.4 Parity Requirements (if there are design files)
-| Screen | Critical elements | Tolerance | Mode | Source of Truth |
-|--------|-------------------|-----------|------|-----------------|
-| ...    | ...               | ...       | Playwright / Manual | Stitch / Figma / HTML-ref |
-
-#### 7.5 Open UX Debt
-> "Now: [temporary solution] → Later: [target solution]"
-
-### 8) Design Decision Log
-| Solution | Alternative | Why choose this | Who decided |
-|---------|--------------|--------------------|-----------|
-
-### Handoff Envelope → Architect + DEV
-```
-HANDOFF TO: Architect, Senior Full Stack Developer
-ARTIFACTS PRODUCED: UX Spec (Approved), Screen Inventory, Component Decisions
-REQUIRED INPUTS FULFILLED: Flows ✅ | States ✅ | DS ✅ | A11y ✅ | Parity rules ✅
-OPEN ITEMS: [open UX debt items]
-BLOCKERS FOR NEXT PHASE: no / [list if available]
-UX SPEC STATUS: Approved ✅
-PARITY MODE: Playwright / Manual / N/A
-DESIGN SOURCE OF TRUTH: Stitch / Figma / HTML-ref
-```
-
-
-
-
-## HANDOFF (Mandatory)
-- Every UX output must end with a completed `Handoff Envelope`.
-- Required fields: `HANDOFF TO`, `ARTIFACTS PRODUCED`, `REQUIRED INPUTS FULFILLED`, `OPEN ITEMS`, `BLOCKERS FOR NEXT PHASE`, `UX SPEC STATUS`, `PARITY MODE`, `DESIGN SOURCE OF TRUTH`.

package/locales/en/prompt-examples.md

@@ -1,152 +0,0 @@
-# Prompt Examples for Pipeline Launch
-
-> Copy the relevant prompt, replace placeholders with your data, paste into chat.
-
----
-
-## 🔵 Full Pipeline (`/start-task`) — new feature / refactoring
-
-### New Feature
-```
-@AGENTS.md Task:
-Implement [feature description].
-Full pipeline!
-
-SESSION RULES:
-1. Each gate: view_file agents/<role>.md → view_file on EVERY SKILL.md from the protocol skills → deliverable → notify_user → wait for "Approved"
-2. Skipping a gate or skill = BLOCKER
-3. Do not proceed without Approved
-```
-
-### Refactoring
-```
-@AGENTS.md Task:
-Refactor [description: what exactly we're refactoring and why].
-Full pipeline!
-
-SESSION RULES:
-1. Each gate: view_file agents/<role>.md → view_file on EVERY SKILL.md from the protocol skills → deliverable → notify_user → wait for "Approved"
-2. Skipping a gate or skill = BLOCKER
-3. Do not proceed without Approved
-```
-
----
-
-## 🟢 Bugfix (`/bugfix`) — bug fix (4 gates)
-
-### Standard Bug
-```
-@AGENTS.md Task:
-Fix bug: [bug description, reproduction steps, expected vs actual behavior].
-Bugfix pipeline!
-
-SESSION RULES:
-1. Each gate: view_file agents/<role>.md → view_file on EVERY SKILL.md from the protocol skills → deliverable → notify_user → wait for "Approved"
-2. Skipping a gate or skill = BLOCKER
-3. Do not proceed without Approved
-```
-
-### Bug with File References
-```
-@AGENTS.md Task:
-@[path/to/file1] @[path/to/file2]
-Bug: [description]. Root cause likely in the referenced files.
-Bugfix pipeline!
-
-SESSION RULES:
-1. Each gate: view_file agents/<role>.md → view_file on EVERY SKILL.md → deliverable → notify_user → wait for "Approved"
-2. Skipping a gate = BLOCKER
-```
-
----
-
-## 🟡 Hotfix (`/hotfix`) — minor fix (2 gates)
-
-### Typo / CSS / Single Line
-```
-@AGENTS.md Task:
-Hotfix: [fix description, e.g.: "fix typo in heading" or "change button color from #333 to #555"].
-Hotfix pipeline!
-
-SESSION RULES:
-1. Each gate: view_file agents/<role>.md → view_file on EVERY SKILL.md → deliverable → notify_user → wait for "Approved"
-2. Skipping a gate = BLOCKER
-```
-
----
-
-## 🎨 Design Only (Google Stitch)
-
-### UI Screen Generation
-```
-@AGENTS.md Task:
-Create UI screens for [description: which screens, which application].
-Use Google Stitch via $google-stitch-skill.
-
-SESSION RULES:
-1. view_file agents/ux_ui_designer.md → view_file $google-stitch-skill → deliverable → notify_user → wait for "Approved"
-```
-
----
-
-## 📄 Documentation Only
-
-### Document Adaptation / Creation
-```
-@AGENTS.md Task:
-[Documentation task description, e.g.: "adapt files X, Y, Z for global use"].
-Bugfix pipeline! (or Full pipeline — depending on complexity)
-
-SESSION RULES:
-1. Each gate: view_file agents/<role>.md → view_file on EVERY SKILL.md → deliverable → notify_user → wait for "Approved"
-2. Skipping a gate = BLOCKER
-```
-
----
-
-## ⚡ Gate Transitions (User Responses)
-
-### Approve and Move to Next Gate
-```
-Approved. Next gate: agents/<role>.md. Skills: view_file required. Full format.
-```
-
-### Approve with Trigger (Wix / Shopify)
-```
-Approved. TEST gate. Wix.
-```
-
-### Reject / Return for Rework
-```
-NO-GO. Fix: [list of issues]. Return to [gate] gate.
-```
-
----
-
-## 🔧 Utility Prompts
-
-### Check Status
-```
-Show the current Master Checklist and status of all gates.
-```
-
-### Run a Specific Agent
-```
-Run agents/<role>.md. Context: [brief description]. Skills: view_file required.
-```
-
-### Update Version
-```
-Update the version in package.json to X.Y.Z
-```
-
----
-
-## 📝 Tips for Writing Prompts
-
-1. **Always start with `@AGENTS.md`** — this loads the agent system
-2. **Reference files with `@[path]`** — the agent immediately sees the context
-3. **Name the pipeline mode** — "Full pipeline!", "Bugfix pipeline!", "Hotfix pipeline!"
-4. **Add SESSION RULES** — this guarantees protocol compliance
-5. **Write "Approved" explicitly** — without this word the agent will not proceed to the next gate
-6. **Be specific** — the more precise the description, the better the result

package/prompt-examples.md

@@ -1,152 +0,0 @@
-# Примеры промтов для запуска пайплайна
-
-> Копируй нужный промт, подставляй свои данные, вставляй в чат.
-
----
-
-## 🔵 Полный пайплайн (`/start-task`) — новая фича / рефакторинг
-
-### Новая фича
-```
-@AGENTS.md Задание:
-Реализовать [описание фичи].
-Полный пайплайн!
-
-ПРАВИЛА ЭТОЙ СЕССИИ:
-1. Каждый гейт: view_file agents/<role>.md → view_file на КАЖДЫЙ SKILL.md из протокола skills → deliverable → notify_user → ждать "Approved"
-2. Пропуск гейта или skill = БЛОКЕР
-3. Без Approved — не продолжать
-```
-
-### Рефакторинг
-```
-@AGENTS.md Задание:
-Провести рефакторинг [описание: что именно рефакторим и зачем].
-Полный пайплайн!
-
-ПРАВИЛА ЭТОЙ СЕССИИ:
-1. Каждый гейт: view_file agents/<role>.md → view_file на КАЖДЫЙ SKILL.md из протокола skills → deliverable → notify_user → ждать "Approved"
-2. Пропуск гейта или skill = БЛОКЕР
-3. Без Approved — не продолжать
-```
-
----
-
-## 🟢 Bugfix (`/bugfix`) — исправление бага (4 гейта)
-
-### Стандартный баг
-```
-@AGENTS.md Задание:
-Исправить баг: [описание бага, шаги воспроизведения, ожидаемое vs фактическое поведение].
-Bugfix пайплайн!
-
-ПРАВИЛА ЭТОЙ СЕССИИ:
-1. Каждый гейт: view_file agents/<role>.md → view_file на КАЖДЫЙ SKILL.md из протокола skills → deliverable → notify_user → ждать "Approved"
-2. Пропуск гейта или skill = БЛОКЕР
-3. Без Approved — не продолжать
-```
-
-### Баг с указанием файлов
-```
-@AGENTS.md Задание:
-@[путь/к/файлу1] @[путь/к/файлу2]
-Баг: [описание]. Предполагаемая причина в указанных файлах.
-Bugfix пайплайн!
-
-ПРАВИЛА ЭТОЙ СЕССИИ:
-1. Каждый гейт: view_file agents/<role>.md → view_file на КАЖДЫЙ SKILL.md → deliverable → notify_user → ждать "Approved"
-2. Пропуск гейта = БЛОКЕР
-```
-
----
-
-## 🟡 Hotfix (`/hotfix`) — мелкая правка (2 гейта)
-
-### Опечатка / CSS / одна строка
-```
-@AGENTS.md Задание:
-Hotfix: [описание правки, например: "исправить опечатку в заголовке" или "изменить цвет кнопки с #333 на #555"].
-Hotfix пайплайн!
-
-ПРАВИЛА ЭТОЙ СЕССИИ:
-1. Каждый гейт: view_file agents/<role>.md → view_file на КАЖДЫЙ SKILL.md → deliverable → notify_user → ждать "Approved"
-2. Пропуск гейта = БЛОКЕР
-```
-
----
-
-## 🎨 Только дизайн (Google Stitch)
-
-### Генерация UI-экранов
-```
-@AGENTS.md Задание:
-Создать UI-экраны для [описание: какие экраны, какое приложение].
-Использовать Google Stitch через $google-stitch-skill.
-
-ПРАВИЛА ЭТОЙ СЕССИИ:
-1. view_file agents/ux_ui_designer.md → view_file $google-stitch-skill → deliverable → notify_user → ждать "Approved"
-```
-
----
-
-## 📄 Только документация
-
-### Адаптация / создание документов
-```
-@AGENTS.md Задание:
-[Описание задачи с документацией, например: "адаптировать файлы X, Y, Z для глобального использования"].
-Bugfix пайплайн! (или Полный пайплайн — по сложности)
-
-ПРАВИЛА ЭТОЙ СЕССИИ:
-1. Каждый гейт: view_file agents/<role>.md → view_file на КАЖДЫЙ SKILL.md → deliverable → notify_user → ждать "Approved"
-2. Пропуск гейта = БЛОКЕР
-```
-
----
-
-## ⚡ Переход между гейтами (ответы пользователя)
-
-### Одобрение и переход к следующему гейту
-```
-Approved. Следующий гейт: agents/<role>.md. Skills: view_file обязателен. Полный формат.
-```
-
-### Одобрение с указанием триггера (Wix / Shopify)
-```
-Approved. TEST gate. Wix.
-```
-
-### Отказ / возврат на доработку
-```
-NO-GO. Исправь: [список замечаний]. Вернись на гейт [гейт].
-```
-
----
-
-## 🔧 Утилитарные промты
-
-### Проверка статуса
-```
-Покажи текущий Master Checklist и статус всех гейтов.
-```
-
-### Запуск конкретного агента
-```
-Запусти agents/<role>.md. Контекст: [краткое описание]. Skills: view_file обязателен.
-```
-
-### Обновление версии
-```
-Обнови версию в package.json до X.Y.Z
-```
-
----
-
-## 📝 Советы по составлению промтов
-
-1. **Всегда начинай с `@AGENTS.md`** — это загружает систему агентов
-2. **Указывай файлы через `@[путь]`** — агент сразу видит контекст
-3. **Называй режим пайплайна** — «Полный пайплайн!», «Bugfix пайплайн!», «Hotfix пайплайн!»
-4. **Добавляй ПРАВИЛА СЕССИИ** — это гарантирует соблюдение протокола
-5. **Пиши «Approved»** явно — без этого слова агент не перейдёт к следующему гейту
-6. **Будь конкретен** — чем точнее описание, тем лучше результат