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

# 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 @nitra/cursor`.
- Файлові доки мають бути свіжі. Перевір і за потреби онови перед агрегацією:

```bash
npx @nitra/cursor lint-doc-files --git
```

Якщо багато застарілих — спершу прожени `npx @nitra/cursor fix-doc-files`.

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

Зібрати список модулів:

```bash
npx @nitra/cursor doc-aggregate modules
```

Команда друкує JSON-масив (усі шляхи абсолютні):

```json
[
  {
    "moduleRoot": "/abs/npm/rules/adr",
    "relRoot": "npm/rules/adr",
    "slug": "npm-rules-adr",
    "docPath": "/abs/npm/rules/adr/docs/ARCHITECTURE.md",
    "members": ["npm/rules/adr/index.mjs"],
    "exists": false
  }
]
```

module-summary **завжди регенерується** (це агрегат — поле `exists` ігноруй). Розбий модулі
на батчі по 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`; цей скіл їх не пише, лише агрегує.
