Forms Dev

---
name: forms-dev
description: Воркфлоу разработки @letar/forms — приоритизация задач и обязательный цикл синхронизации из 6 групп
disable-model-invocation: true
---

# Forms Dev - Воркфлоу разработки

## Инициализация

1. Прочитай `.claude/rules/forms.md` для правил работы с формами
2. Прочитай `libs/forms/README.md` для API библиотеки
3. Зарегистрируйся в agent-mail под фиксированным именем `forms-dev`
   (токен — в памяти `agent_fixed_names_tokens.md`, таблица «Приложение → agent_name → registration_token»):

   ```
   macro_start_session(
     human_key: "C:/web/letar",
     program: "claude-code",
     model: "claude-opus-5",
     agent_name: "forms-dev",
     registration_token: "<токен из agent_fixed_names_tokens.md>",
     task_description: "Разработка @letar/forms",
     file_reservation_paths: [
       "libs/forms/**",
       "libs/forms-core/**",      // Фаза 7: dependency-free ядро
       "libs/forms-shadcn/**",    // Фаза 7: shadcn-скин
       "libs/forms-vue/**",       // Фаза 7: Vue-пруф-адаптер (7.8)
       "libs/zenstack-form-plugin/**",
     ],
     file_reservation_reason: "form-components development"
   )
   ```

   ⚠️ **Фаза 7 разбивает библиотеку на несколько пакетов** — резервируй владение ими заранее (даже если
   папки ещё не созданы), чтобы параллельные сессии не разъехались по core/скинам.

4. **Выставь открытую contact policy** — иначе первый запрос от незнакомого агента виснет заявкой
   на подтверждение контакта (см. `.claude/rules/agent-mail.md`):

   ```
   set_contact_policy(
     project_key: "c-web-letar",
     agent_name: "forms-dev",
     policy: "open",
     registration_token: "<тот же токен>"
   )
   ```

5. **Стартуй таймер** `time_start({ app: "forms", ... })` — общий шаблон и правила переключения/
   остановки см. `.claude/rules/app-workflow.md` и `.claude/rules/time-tracking.md`.
6. **Проверь входящие запросы:**
   ```
   fetch_inbox(topic: "form-feature-request", include_bodies: true)
   ```
7. **Очередь задач — `libs/forms/tasks/`.** `Read libs/forms/tasks/README.md` (компас), затем
   `bun scripts/tasks.mjs next forms`. Вызвали с id (`/forms-dev FM-004`) — сразу
   `bun scripts/tasks.mjs show FM-004`. `PLAN.md` (1 МБ) и `PLAN_COMPLETED.md` заморожены и целиком
   не читаются: секцию из `source` задачи открывай через `grep -n` и `Read` с `offset`.
8. Прочитай `apps/form-develop-app/PLAN.md` для текущего состояния задач песочницы.
9. **Приоритизация:** задачи от координатора и входящие запросы > очередь (`next forms`). Новый
   запрос агента, которого нет в очереди, — сразу `bun scripts/tasks.mjs new forms "<заголовок>" --source "<тред>"`.

## Координация (Forms Coordinator)

**Проверяй inbox** на задачи от координатора (topic: `forms-task`):

```
fetch_inbox(project_key: "c-web-letar", agent_name: "<твоё-имя>", topic: "forms-task", include_bodies: true)
```

После завершения задачи от координатора — **отвечай через reply_message** с результатом (сохраняет
тред). Координатор форм — `forms-coordinator-dev` (переименован 2026-08-10 из `forms-coordinator`; старое
kebab-case имя ловило баг сервера agent-mail в `send_message` — см. `.claude/rules/agent-mail.md`,
новое имя этой проблемы не имеет, но `reply_message` для продолжения треда всё равно предпочтительнее).

**⚠️ После добавления поля** — строка в `libs/forms/docs/fields.md` (пропсы вне таблицы — в `libs/form-mcp/src/data/field-props.ts`). Тест `field-code-parity.integration.spec.ts` проверит, что код и доки совпали. MCP-инструменты (`list_fields` и др.) руками не правятся — они читают `fields.md`.

## Действия

После изучения документации:

- Если есть задачи от координатора форм `forms-coordinator-dev` (topic: `forms-task`) — **обработай их первыми**
- Если есть входящие запросы (topic: `form-feature-request`) — обработай следующими
- Иначе — возьми задачу из `bun scripts/tasks.mjs next forms`: `start <ID> --owner forms-dev`, план работ запиши в файл задачи, находки по ходу — `tasks new`
- Предложи план действий

## После завершения задачи

⚠️ **КРИТИЧНО:** Фаза НЕ считается завершённой без полного цикла документации. НЕ коммить, пока все 6 групп не обновлены.

⚠️ **Документация и примеры живут в ОТДЕЛЬНЫХ приложениях, а не в `libs/forms`:**

- **Документацию** обновляй в **`apps/form-docs`** (Fumadocs MDX, [forms.letar.best](https://forms.letar.best)) — Группа 3.
- **Примеры/showcase** обновляй в **`apps/form-example`** ([forms-example.letar.best](https://forms-example.letar.best)) — Группа 4.
- **Демо для разработки** — в **`apps/form-develop-app`** (песочница, порт 3006) — Группа 2.

Правка кода в `libs/forms` **без** синхронного обновления этих аппов = незавершённая задача. Новое поле,
которого нет в `form-docs`/`form-example`, для внешнего пользователя **не существует**.

### Группа 1: libs/forms

- [ ] `CHANGELOG.md` — запись новой версии
- [ ] `package.json` — увеличь версию (semver)
- [ ] `README.md` — добавь компонент в таблицу полей и секцию описания
- [ ] `docs/form-level.md` — если это form-level компонент (не Field)

### Группа 2: apps/form-develop-app

- [ ] `src/app/<demo-name>/page.tsx` — демо-страница нового компонента
- [ ] `src/app/page.tsx` — ссылка на демо с главной
- [ ] Задача закрыта: `bun scripts/tasks.mjs done <ID> --summary "…"` (итог живёт в файле задачи, `PLAN.md` не трогать)
- [ ] `CHANGELOG.md` — запись об изменениях
- [ ] `PLAN_TESTING.md` — если добавил тесты

### Группа 3: apps/form-docs (документация)

- [ ] `content/docs/guides/<slug>.mdx` — guide MDX страница
- [ ] `content/docs/guides/meta.json` — добавь slug в pages массив
- [ ] `src/app/demo/<category>/page.tsx` — интерактивная демо-страница
- [ ] `content/docs/api/form-component.mdx` — добавь props в API reference

### Группа 4: apps/form-example (showcase)

- [ ] `src/app/examples/<name>/page.tsx` — страница примера
- [ ] `src/components/nav.tsx` — добавь ссылку в навигацию

### Группа 5: Метадокументация

- [ ] `libs/forms/NEW_COMPONENTS.md` — отметь фазу как done

### Группа 6: Ответ агентам (если задача из agent-mail)

- [ ] `reply_message(message_id: <id>, body_md: "Реализовано в v<версия>: <описание>")`

### Порядок работы

1. Реализуй компонент + тесты в libs/forms
2. Обнови Группу 1 (библиотека)
3. Обнови Группу 2 (песочница)
4. Обнови Группу 3 (документация)
5. Обнови Группу 4 (showcase)
6. Обнови Группу 5 (метадокументация)
7. Запусти preview_start для form-develop-app и form-docs — визуально проверь
8. Коммит только после прохождения всех групп

## Проекты экосистемы форм

### form-develop-app (песочница)

**Приложение:** form-develop-app
**Порт:** 3006
**Описание:** Песочница для разработки @letar/forms
**Библиотека:** libs/forms
**Правила:** `.claude/rules/forms.md`

Демо-страницы — `apps/form-develop-app/src/app`, E2E — `apps/form-develop-app-e2e`.

### form-docs (документация)

**Приложение:** form-docs
**Порт:** 3020
**Домен:** [forms.letar.best](https://forms.letar.best)
**Описание:** Документация @letar/forms на базе Fumadocs MDX
**Структура:** `[lang]/docs/[[...slug]]` — мультиязычная документация + `demo/` — интерактивные демо

Демо-страницы: basic, string, number, date, select, specialized, groups, conditional, multi-step, auto-fields, fields-all, validation.

### form-example (showcase)

**Приложение:** form-example
**Порт (dev):** 3027 (production за Traefik — 3022, не связан с dev-портом)
**Домен:** [forms-example.letar.best](https://forms-example.letar.best)
**Описание:** Showcase приложение @letar/forms для внешних пользователей
**Модели:** `schema.zmodel` с `@meta("form.*", value)` директивами (legacy `@form.*`-комментарии убраны в plugin v4.0.0) → `src/generated/form-schemas/`

Страницы: basic, all-fields, validation, conditional, multi-step, groups, auto-fields, zenstack, theming, i18n, offline.

### @letar/forms (библиотека)

**Библиотека:** libs/forms
**Версия:** см. `libs/forms/package.json`
**npm пакет:** @letar/forms
**Описание:** compound component API, Zod v4, offline, i18n, ZenStack интеграция, MCP-сервер
**Стратегия:** open-core, широкий OSS-охват — см. задачу FM-011 и справку `libs/forms/PLAN.md` → Фаза 7 (расслоение core + скины)

### @letar/zenstack-form-plugin (плагин)

**Библиотека:** libs/zenstack-form-plugin
**Версия:** см. `libs/zenstack-form-plugin/package.json`
**Описание:** Генерация Zod form schemas из `schema.zmodel` с `@meta("form.*", value)` директивами (основной синтаксис с Фазы 3; legacy `/// @form.*`-комментарии убраны в v4.0.0)