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
```text

---

## 3. State Machine

```ts
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";
```text

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

- відповіді користувача,
- успішності 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):

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

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

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

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

---

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

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

```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"
    />
  );
}
```text

---

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

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

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

---

## 8. Для Cursor

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

```text
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
```text

---

## 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.

13 KiB Raw Blame History Unescape Escape

08 — Agent-First Onboarding Specification (MicroDAO)

1. Мета

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

13 KiB

Raw Blame History