---
name: doc-aggregate
description: >-
  Агрегуюча документація за запитом: module-summary на кожен логічний модуль (docs/ARCHITECTURE.md) і доменні доки бізнес-процесів у кореневій docs/ — синтез поверх готових файлових док (doc-files), батч-диспатч субагентів у worktree
version: '1.0'
---

# doc-aggregate — агрегуюча документація (за запитом)

## Мета

Синтезувати документацію вищого рівня поверх **готових файлових док** (їх підтримує
обовʼязковий скіл `doc-files`). Два рівні, строго послідовно:

1. **Tier 2 — module-summary**: `<module_root>/docs/ARCHITECTURE.md`, субагент на модуль.
2. **Tier 3 — доменні доки**: `docs/<домен>.md` у кореневій `docs/`, субагент-синтезатор
   виділяє бізнес-домени й пише файл на кожен домен.

Агрегат ніколи не випереджає джерело: Tier 3 — лише після завершення всього Tier 2.
Цей скіл викликається **за запитом** (не обовʼязковий крок задачі).

## ⚠️ Паралелізм

Tier 2 — батчами **по 5** субагентів одночасно (кожен пише свій файл, гонок немає).
Tier 3 — **один** субагент-синтезатор після завершення всього Tier 2.

## Передумова

- Доступний `npx @7n/rules`.
- Файлові доки мають бути свіжі. Перевір і за потреби онови перед агрегацією:

```bash
npx @7n/rules lint doc-files --no-fix
```

Якщо багато застарілих — спершу прожени `npx @7n/rules lint doc-files` (fix-by-default).

## Крок 1: Tier 2 — module-summary

Зібрати список воркспейсів з кореневого `package.json`:

```bash
node -e "const p=JSON.parse(require('fs').readFileSync('package.json','utf8')); console.log(JSON.stringify(p.workspaces))"
```

Для кожного воркспейсу `<ws>`:

- `relRoot` = `<ws>` (напр. `npm`, `demo`)
- `docPath` = `<ws>/docs/ARCHITECTURE.md`
- `members` — кодові файли (розширення декларують lang-плагіни через `doc-files.extensions`, крім тестів) у `<ws>/`

module-summary **завжди регенерується**. Розбий воркспейси на батчі по 5 і диспатч субагентів.
Промпт кожного (підстав `relRoot`, `docPath`, `members`):

```
Напиши module-summary для одного логічного модуля.

МОДУЛЬ: <relRoot>
ЗАПИСАТИ В: <docPath>
ФАЙЛИ МОДУЛЯ (members): <members>

Кроки:
1. Прочитай файлові доки членів модуля. <member> — sourcePath відносно кореня проєкту
   (= поточний CWD); його файлова дока — <CWD>/<dir>/docs/<stem>.md. За потреби зазирни
   в самі файли.
2. Створи теку для <docPath>, якщо її немає.
3. Запиши markdown у <docPath> за тими ж правилами стилю, що й файлова дока
   (українська, чистий Markdown, контекстна незалежність, без HTML).

Секції module-summary:
## Огляд модуля — призначення модуля <relRoot>, його роль у проєкті.
## Ключові файли — список із кліковими посиланнями (відносними до розташування цього
   ARCHITECTURE.md) на члени модуля та їхні файлові доки.
## Публічний API — що модуль експортує назовні.
## Внутрішній потік — як компоненти модуля взаємодіють.
## Підмодулі — вкладені модулі, якщо є.

Поверни лише підтвердження, що файл <docPath> записано.
```

## Крок 2: Tier 3 — доменні доки

Після завершення **всіх** module-summary диспатч **одного** субагента-синтезатора.
У промпт підстав конкретний перелік шляхів module-summary (`<module_root>/docs/ARCHITECTURE.md`
кожного модуля з виводу `doc-aggregate modules`), а не інструкцію їх шукати. Промпт:

```
Синтезуй доменну документацію бізнес-процесів проєкту.

ДЖЕРЕЛА (module-summary, читай усі): <перелік шляхів ARCHITECTURE.md, підставлений вище>

Кроки:
1. Прочитай усі module-summary.
2. Виділи бізнес-домени та процеси (можуть перетинати межі модулів). Доменів може бути багато.
3. Для КОЖНОГО домену запиши окремий файл docs/<домен>.md у кореневій docs/:
   - назва файлу — короткий kebab-slug домену;
   - не перезаписуй файлові доки кореневих файлів у docs/ (напр. app.md, eslint.config.md):
     якщо слаґ домену збігається з іменем такого файлу — додай суфікс -domain
     (напр. app-domain.md). Інакше пиши docs/<домен>.md як є;
   - опиши бізнес-процес домену з кліковими відносними посиланнями на module-summary, конкретні файли й директорії.

Правила стилю — ті ж (українська, чистий Markdown, контекстна незалежність, без HTML).

Поверни перелік створених файлів docs/<домен>.md.
```

## Крок 3: Підсумок

```
✓ doc-aggregate завершено.
Tier 2 (модулі): <M> module-summary.
Tier 3 (домени): <D> доменних доків у docs/.
```

Перелічи файли з помилками (субагент впав або не записав `docPath`), якщо такі є.
Помилка одного модуля не зупиняє решту.

## Нотатки

- Не комітити автоматично — користувач вирішує, коли комітити згенеровану доку.
- Файлові доки (Tier 1) — окремий обовʼязковий скіл `doc-files`; цей скіл їх не пише, лише агрегує.