Skip to content

# 08 — Agent-First Onboarding Specification (MicroDAO)

Цей документ описує нову модель онбордингу MicroDAO:
користувач входить у чат з агентом-провідником, який крок за кроком створює спільноту, канал і налаштовує агента.

Весь процес — діалоговий.
Усі API-виклики — ті самі, що в 03_api_core_snapshot.md.

# 1. Мета

Замінити класичні форми/кроки онбордингу повністю агентським інтерфейсом.
Увесь onboarding виконується через `AgentOnboardingChat`, який:

- говорить з користувачем живою мовою,
- ставить запитання,
- парсить відповіді,
- викликає API,
- підтверджує успішні кроки,
- веде користувача до створення першої microDAO,
- налаштовує приватного агента,
- завершує онбординг фразою та редіректом.

# 2. Загальна архітектура

Усі дії будуються на:

- state-machine (опис нижче),
- Chat UI (аналог звичайного чату),
- репліках агента (скрипт),
- розпізнаванні наміру користувача (regex / LLM / кнопки),
- викликах API (з 03_api_core_snapshot.md).

Компоненти:

    src/features/onboarding-agent/
      AgentOnboardingChat.tsx
      useOnboardingState.ts
      scripts/
        script.json
        parser.ts
        transitions.ts

# 3. State Machine

    type OnboardingStep =
      | "greet"
      | "ask_profile"
      | "ask_team_name"
      | "ask_team_desc"
      | "ask_mode"
      | "ask_channel_name"
      | "ask_channel_type"
      | "ask_agent_enable"
      | "ask_agent_prefs"
      | "ask_invites"
      | "done";

Перехід між кроками базується на:

- відповіді користувача,
- успішності API-виклику.

# 4. Повний сценарій діалогу (репліки агента)

Нижче — готовий сценарій, який можна покласти в JSON або хардкод.

## 4.1. greet

Агент:

> Привіт! Я — агент-провідник MicroDAO. Зараз ми разом створимо твою першу спільноту та особистого помічника. Як до тебе звертатися?

Після відповіді → `ask_profile`.

## 4.2. ask_profile

Агент:

> Приємно познайомитися, {name}. Якою мовою хочеш працювати — українською чи англійською?

Після відповіді — зберегти `locale` → `ask_team_name`.

## 4.3. ask_team_name

Агент:

> Як назвемо твою майбутню microDAO? Наприклад: "Креативна Майстерня", "AI-Команда Альфа", "Моя Спільнота".

Читаємо будь-який текст → `POST /teams` → `ask_team_desc`.

## 4.4. ask_team_desc

Агент:

> Класно. А як би ти описав спільноту одним реченням? (Не обов'язково, можеш написати "пропустити".)

Зберегти опис → `ask_mode`.

## 4.5. ask_mode

Агент:

> Обери режим для твоєї microDAO: 1) Відкрита — є публічний канал, гості можуть читати. 2) Приватна — тільки запрошені, чати зашифровані. Напиши `1` або `2`.

Після відповіді:

- map → `"public"` / `"confidential"`
- `PATCH /teams/{teamId}` → `ask_channel_name`.

## 4.6. ask_channel_name

Агент:

> Давай створимо перший канал. Як би ти хотів його назвати? (`general`, `core`, `support`)

Після відповіді → `ask_channel_type`.

## 4.7. ask_channel_type

Агент:

> Це буде публічний канал чи приватна кімната? Напиши: public або private.

Mapping:

- `public` → `type: "public"`
- `private` → `type: "group"`

API: `POST /channels`

Після успіху → `ask_agent_enable`.

## 4.8. ask_agent_enable

Агент:

> У MicroDAO кожна спільнота має власного ШІ-агента, який памʼятає контекст і самонавчається. Хочеш одразу створити командного агента?

Очікувані відповіді: так / ні.

- Якщо «ні» → `ask_invites`
- Якщо «так» → `ask_agent_prefs`

## 4.9. ask_agent_prefs

Агент:

> Добре. Налаштуємо агента. Якою мовою він має відповідати?

Після відповіді →

Агент:

> Який у нього фокус? Вибери одне: general, business, technical, creative.

Після відповіді →

Агент:

> Що він має памʼятати?

> 1. Лише цей канал
> 2. Усі канали спільноти

Після відповіді:

Викликаємо: `POST /agents`

Потім → `ask_invites`.

## 4.10. ask_invites

Агент:

> Все готово! Хочеш зараз запросити людей до своєї microDAO? Я підготую посилання, яке можна надіслати будь-кому.

Після відповіді — показати UI-елемент з інвайт-лінком.

→ `done`.

## 4.11. done

Агент:

> Вітаю! Твоя microDAO {team.name} створена. Я створив канал #{channel.title} і готовий допомагати. Можеш почати працювати або поставити мені питання: "Що ти вмієш?" / "Як користуватися каналами?" / "Як запросити команду?"

redirect → `/t/:teamId/c/:channelId`.

# 5. Intent Parser (як агент розуміє відповіді)

Мінімальний підхід (regex):

    function parseMode(input: string) {
      if (input.match(/1|пуб/i)) return "public";
      if (input.match(/2|прив/i)) return "confidential";
    }

    function parseYesNo(input: string) {
      if (input.match(/^так|yes|y$/i)) return true;
      if (input.match(/^ні|no|n$/i)) return false;
    }

Або гібридний:

- парсимо regex,
- якщо незрозуміло → питаємо LLM: "Чи відповідь користувача означає Так/Ні/Інше?"

# 6. Компонент `AgentOnboardingChat.tsx`

### Мінімальна структура:

    export function AgentOnboardingChat() {
      const { step, setStep, state, updateState } = useOnboardingState();

      const handleUserMessage = async (text: string) => {
        addMessage({ author: "user", text });

        switch (step) {
          case "greet":
            updateState({ name: text });
            addAgent("Приємно познайомитися, " + text + "...");
            setStep("ask_profile");
            break;

          case "ask_profile":
            updateState({ locale: detectLocale(text) });
            addAgent("Як назвемо твою microDAO?");
            setStep("ask_team_name");
            break;

          case "ask_team_name":
            const team = await api.post("/teams", { name: text });
            updateState({ teamId: team.id });
            addAgent("А як би ти описав спільноту?");
            setStep("ask_team_desc");
            break;

          // ... і так далі для кожного step.
        }
      };

      return (
        <ChatUI
          messages={messages}
          onSend={handleUserMessage}
          agentAvatar="guide"
        />
      );
    }

# 7. Acceptance Criteria (як перевіряти)

- `/onboarding` відкривається як чат.
- Користувач спілкується з агентом.
- На кожному кроці агент відповідає правильно.

- Усі API виклики працюють:

- `/teams`

- `/teams/{id}`
- `/channels`
- `/agents`
- Після завершення → redirect.
- UX: користувач не бачить жодної форми. Все — діалог.

# 8. Для Cursor

Коли ти даси йому задачу, використовуй цей формат:

    You are a senior React/TS engineer.

    Implement the Agent-first onboarding at `/onboarding` using the specification in:
    - 08_agent_first_onboarding.md
    - 03_api_core_snapshot.md
    - 05_coding_standards.md

    Create the component `AgentOnboardingChat.tsx` and supporting files.

    Output:
    - list of modified files
    - diff
    - summary

# 9. Інтеграція з існуючим кодом

## 9.1. Заміна класичного онбордингу

Існуючий `OnboardingPage.tsx` можна: - залишити як fallback для користувачів, які не хочуть агентський онбординг, - або повністю замінити на `AgentOnboardingChat`.

## 9.2. Використання API клієнтів

Використовувати існуючі API клієнти з `src/api/`: - `teams.ts` — для створення команди - `channels.ts` — для створення каналу - `agents.ts` — для створення агента - `auth.ts` — для автентифікації

## 9.3. State Management

Використовувати `useOnboardingState` hook або розширити існуючий `useOnboarding.ts` для агентського онбордингу.

# 10. UI/UX Вимоги

## 10.1. Chat Interface

- Повідомлення агента з аватаром
- Повідомлення користувача справа
- Індикатор набору тексту (typing indicator) під час обробки
- Кнопки швидких відповідей (опціонально)
- Плавні анімації появи повідомлень

## 10.2. Візуальні елементи

- Аватар агента (іконка або зображення)
- Індикатор прогресу онбордингу (опціонально)
- Підказки для користувача
- Обробка помилок з дружніми повідомленнями

## 10.3. Мобільна адаптація

- Адаптивний дизайн для мобільних пристроїв
- Зручний ввід тексту на мобільних
- Оптимізація для маленьких екранів

# 11. Обробка помилок

## 11.1. Помилки API

Якщо API виклик не вдався: - Показати дружнє повідомлення від агента - Запропонувати спробувати ще раз - Зберегти стан, щоб не втратити прогрес

## 11.2. Незрозумілі відповіді

Якщо агент не розуміє відповідь: - Задати уточнююче питання - Показати приклади правильних відповідей - Запропонувати кнопки з варіантами

## 11.3. Таймаути

- Обробка повільних API викликів
- Показ індикатора завантаження
- Повідомлення про затримку

# 12. Тестування

## 12.1. Unit Tests

- Тести для `parser.ts` (розпізнавання намірів)
- Тести для `transitions.ts` (переходи між станами)
- Тести для компонента `AgentOnboardingChat`

## 12.2. Integration Tests

- Тестування повного flow онбордингу
- Тестування API інтеграції
- Тестування обробки помилок

## 12.3. E2E Tests

- Повний сценарій онбордингу від початку до кінця
- Різні варіанти відповідей користувача
- Перевірка редіректу після завершення

# 13. Майбутні покращення

## 13.1. LLM Integration

- Використання LLM для розпізнавання намірів
- Більш природна мова агента
- Контекстне розуміння відповідей

## 13.2. Персоналізація

- Адаптація мови агента під користувача
- Запам'ятовування попередніх відповідей
- Рекомендації на основі профілю

## 13.3. Мультимовність

- Підтримка багатьох мов
- Автоматичне визначення мови
- Перемикання мови під час онбордингу

Готово.
Це повна специфікація агентського онбордингу, готова до використання в Cursor.